Monocle by Spur

Easily deploy a Cloudflare Worker with Monocle that will automatically protect your site from residential proxies, malware proxies, or other commercial anonymity services.

Description

Monocle can detect a user session coming from a residential proxy, malware proxy, or other endpoint based proxy network. By detecting this at the session level, you can take action on abusive users without impacting legitimate ones.

Monocle Docs FAQ Demo Blog

This Cloudflare Worker will automatically force a Monocle assessment on new users before allowing them access to your site. Authentic users will not be negatively impacted. The cookie this plugin sets is valid for one hour or until the user changes IP address.

Help and Support

support@spur.us

---

Deployment

Terraform

Use our official Terraform module to quickly integrate the Monocle Cloudflare worker into your Terraform-enabled project.

Wrangler Setup

Install Wrangler CLI

Wrangler is the Cloudflare CLI tool that allows you to manage your Cloudflare Workers. In order to install the Monocle worker make sure you have wrangler installed globally.

npm install -g wrangler

Make sure you are logged in to your Cloudflare account with Wrangler.

wrangler login

Fork this repository

In order to deploy this worker, you will need to fork this repository to your own GitHub account. This will allow you to make changes to the worker and deploy it to your own Cloudflare account.

1. Navigate to the GitHub repository for this worker.
2. In the top-right corner of the page, click the Fork button.
3. You will now have a copy of this repository in your own GitHub account.
4. You can clone this repository to your local machine by running the following command:

git clone git@github.com:${YOUR_USERNAME_HERE}/monocle-plugin-cloudflare.git
cd monocle-plugin-cloudflare
npm install # Install dependencies

Configure the worker

You will need to create a wrangler.toml file and set your account_id and route.

1. Open the wrangler.toml file in your text editor.
2. Copy the example below and paste it into the wrangler.toml file.
3. Update the compatibility_date field with the current date. This value must be greater than 2024-11-11.
4. Add nodejs_compat to compatibility_flags.
5. Update the account_id field with your Cloudflare account ID.
6. Update the route field with the route you want to deploy the worker to.
7. Update the zone_id field with the zone you want to deploy the worker to.
8. Save the file.

name = "monocle"
main = "src/index.ts"
compatibility_date = "${TODAYS_DATE}"
compatibility_flags = [ "nodejs_compat" ]
account_id = "${YOUR_ACCOUNT_ID}"
workers_dev = false # Set to false to deploy to custom domain
route = { pattern = "${YOUR_ROUTE}", zone_id = "${YOUR_ZONE}" }

Set up your secrets

wrangler secret put PUBLISHABLE_KEY
wrangler secret put SECRET_KEY
# The cookie secret must be 32 bytes "openssl rand -hex 32"
wrangler secret put COOKIE_SECRET_VALUE

To use manual decryption set the PRIVATE_KEY secret. This is feature is only available to customers with Enterprise plans.

wrangler secret put PRIVATE_KEY

Opt in to the Policy API

If you want to use Spur's Policy API for assessment decisions instead of the default local decryption path, set the following secret:

# Set to true to use the Monocle policy API instead of local assessment decryption.
wrangler secret put USE_POLICY_API   # set value to: true

When USE_POLICY_API=true:

• The worker calls Spur's Policy API to evaluate each session
• If you have the relevant Policy blocking entitlements and a policy is configured, traffic that fails the policy check will be blocked
• If no policy is configured or the account does not have blocking entitlements, traffic is allowed through automatically

Optionally configure a custom response for blocked requests:

wrangler secret put BLOCK_RESPONSE_TYPE   # html or redirect

For html — customise the block page:

wrangler secret put BLOCK_STATUS_CODE     # e.g. 403
wrangler secret put BLOCK_PAGE_TITLE      # browser tab title
wrangler secret put BLOCK_RESPONSE_BODY   # message text shown on the block page

For redirect — send blocked users elsewhere:

wrangler secret put BLOCK_REDIRECT_URL    # URL to redirect to

If BLOCK_RESPONSE_TYPE is not set, blocked requests receive a plain 403 response.

Deploy the worker

wrangler deploy

---

Environment Variables Reference

Variable	Required	Description
PUBLISHABLE_KEY	Yes	Your Monocle publishable key
SECRET_KEY	Yes	Your Monocle secret key
COOKIE_SECRET_VALUE	Yes	32-byte hex string for cookie signing
PRIVATE_KEY	No	PEM private key for local decryption (Enterprise only)
USE_POLICY_API	No	Set to true to use the Policy API instead of local decryption
EXEMPTED_SERVICES	No	JSON array of service names to exempt from blocking (default: ["WARP_VPN","ICLOUD_RELAY_PROXY"])
BLOCK_RESPONSE_TYPE	No	html or redirect — customises the response for blocked requests
BLOCK_STATUS_CODE	No	HTTP status code for HTML block responses (default: 403)
BLOCK_PAGE_TITLE	No	Browser tab title for HTML block responses
BLOCK_RESPONSE_BODY	No	Message text shown on the block page
BLOCK_REDIRECT_URL	No	URL to redirect blocked users to (required when BLOCK_RESPONSE_TYPE=redirect)