App

Changelog · — Monocle Assess & Enforce, policy decision logging, health alerts, and Install with AI.

Fastly Integration Workflow

The Fastly integration lets you deploy Monocle without changing your application code.

This is the no-code setup path for customers who serve traffic through Fastly. Once configured, Monocle assesses traffic on the domain you choose and surfaces results in the dashboard.

Blocking is only applied when policy-based enforcement is enabled.

How it works

The Fastly integration deploys a Compute service into your Fastly account, named spur-monocle-<app id>, and moves the protected domain onto it. The service sits in front of your site: every request is assessed, and verified traffic is forwarded to your origin.

Alongside the service, Monocle creates two account-level stores, both named after the app:

  • A Config Store holding the integration's configuration: the assessed and enforced paths, the excluded paths, the block response and the origin settings
  • A Secret Store holding the app's secret key and the cookie-signing secret

Monocle manages all of this through the API token you connect. Configuration changes made in the dashboard are written to the Config Store, which the running service reads live, so most changes apply without a redeploy.

You can use the integration to:

  • Assess traffic without adding code to your site
  • Choose which pages on the domain Monocle assesses, and which it leaves alone
  • Configure a block response
  • Keep your existing Fastly service in the request path (chaining)
  • Redeploy when plugin updates are available
  • Remove the service when it is no longer needed

Before you begin

You need access to:

  • A Fastly account with the domain you want to protect already served by Fastly
  • Permission to create a Fastly API token with the Global scope, from a user with the Engineer or Superuser role
  • An account with Compute enabled (a free trial is available under Account → Products)

Create a Monocle app

To start the Fastly integration:

  1. Create a new Monocle app.
  2. Enter the app name.
  3. Choose Fastly as the integration type.
  4. Continue to the Connect Fastly step.

Connect your Fastly account

In Fastly, go to Account → API tokens → Personal tokens and select Create token.

SettingValue
TypeUser token
ScopeGlobal API access
AccessAll services
ExpirationNever, or a date you will renew before

A user token has the permissions of the user who creates it, so it must belong to a user with the Engineer or Superuser role: Monocle creates a service, stores and domains in your account, which other roles, and read-only or purge-only tokens, cannot do.

Paste the token into Monocle and select Validate token. Monocle checks the token's scope before saving it encrypted. It cannot see the role of the user who created the token: a Global token from a user without the Engineer or Superuser role validates but fails at the first deploy, with a message that names the role it needs.

Choose your domain and origin

Monocle protects one domain per app. Pick it from the domains on your Fastly account, or type it if the list is empty. A classic domain has to be migrated to a versionless one in Fastly first: Monocle attaches domains through Fastly's Domain Management, and setup says so when it finds a classic one.

Monocle then looks up the service currently serving the domain and detects its origin automatically. Depending on what it finds, you choose how verified traffic is forwarded:

  • Forward to your origin copies the origin backend onto the Monocle service, host override, TLS settings and shielding included. Best when your existing service has no custom rules.
  • Keep my existing Fastly setup chains the Monocle service through your existing service, so its VCL, WAF and caching stay in the request path. Monocle adds an internal host to your service and a guard that rejects traffic not signed by Monocle. A VCL service is configured automatically with your authorisation. A Compute service shows you a snippet to add to its code: Monocle checks that your service refuses traffic it did not sign, and only then moves the domain.

A domain that is on your Fastly account but not attached to any service asks you for the origin instead.

When you deploy, the domain moves to the Monocle Compute service. The domain is fixed at setup, as on the other integrations: to protect another domain, create a separate app; to change this one, remove the service from the app's Fastly page, which returns the domain to the service it came from, then set up again.

Choose where Monocle runs

The whole domain moves to the Monocle service, so the Assessment step chooses what happens on it:

  • Assessed paths choose which pages Monocle assesses. Site-wide is recommended: assessment runs in the background on each page load and does not block visitors. Monocle adds its script to the pages it assesses, so no tag has to be added by hand.
  • Excluded paths name paths Monocle must never act on, such as a public API. The Compute service still receives these requests, since the whole domain is on it, but passes them straight to your origin untouched: nothing is assessed, enforced or changed. An excluded path is /path exactly, /path/* for a section, or /path* for everything starting with it.
  • Enforced paths (on the app's Configure Policy page) choose where a Policy block decision is applied. An enforced path cannot sit inside an excluded one; Monocle refuses the combination wherever it is saved.

Assessed and excluded paths can be changed later from the app's Fastly page, and apply to the running service without a redeploy.

Configure the block response

The block response controls what users see when traffic is blocked.

You can configure:

  • Response body
  • Page title
  • HTTP status code (401, 403 or 404)
  • Redirect URL, which must point to a path on the protected domain

The default response status is 403. A redirect can also be applied to blocked background requests, which the Monocle script navigates to the block page.

Deploy the service

Once the token, domain, assessment and block response are configured, select Deploy Service.

Monocle creates the Compute service and stores, writes the configuration, attaches the domain, uploads the Monocle package and activates the service. A new version reaches every Fastly POP within about a minute.

After deployment, Monocle begins testing for traffic on the domain. When traffic is detected, the integration status updates to show that Monocle is assessing traffic.

Check the deployment

The app's Fastly page has a Run check button. It fetches the protected domain as a visitor would and reports whether Monocle is running there: the page carries the Monocle script or the verification screen, and the service's own endpoints answer.

A check that finds a problem names what stopped Monocle, for example a Content-Security-Policy the script cannot be added to, a page served as something other than HTML, or a domain that no longer points at the Monocle service.

WebSockets

Monocle hands a WebSocket connection to Fastly to proxy, which needs WebSocket passthrough enabled on the service in your Fastly account. It is a paid Fastly product and Monocle does not enable it for you. Without it, WebSocket connections to the protected domain fail.

On an enforced path, a WebSocket needs a verdict like any other request: a visitor without one is refused, and a cleared visitor connects. An open connection stays open if the visitor's verdict later changes.

Blocking requires Policy API

The Fastly integration can assess traffic without code changes.

However, assessment is not the same as blocking.

By default, Monocle will allow all traffic unless your policy configuration returns a block decision.

To actively block traffic, you must:

  1. Have access to policy enforcement.
  2. Enable the Policy API.
  3. Select a blocking strategy.
  4. In the policy's Scope, add the paths you want it to protect. These are the enforced paths: a Block decision is applied only on them, and everywhere else the service assesses and lets the visitor through. Connected integrations apply the saved paths at the edge, so a change here needs no redeploy.
  5. Configure the policy rules you want to apply.

An enforced path cannot sit inside an excluded path; Monocle refuses the combination wherever it is saved. If your policy is set to Allow All, or its Scope has no paths, the service continues allowing traffic even though it is deployed.

Assessment logging

Assessment logging is available on the Pro plan and above. When it is on, the Compute service writes one line for every policy decision it makes on an enforced path: the decision, and the visitor's decrypted Monocle assessment, including their IP address and network signals. Each line is a JSON object with a monocle field set to assessment, so it can be told apart from anything else the service logs.

The lines are written to the service's log output. On Fastly that is the live log tail (fastly log-tail or the Compute service's Logs tab), which shows the lines as they happen but does not keep them. To retain or forward them, the service also writes each line to a log endpoint named monocle_assessments, if one exists. Monocle does not create this endpoint: where your logs go, and the credentials for that destination, are yours to choose.

To set it up:

  1. In Fastly, open the Monocle service, spur-monocle-<app id>, and go to Logging.
  2. Create a log endpoint of whichever type you use, such as Amazon S3, Google Cloud Storage, Datadog, Splunk or an HTTPS endpoint. See Fastly's logging endpoints guide for the settings each type needs.
  3. Name the endpoint exactly monocle_assessments. A Compute service sends the endpoint the lines the program writes, so the log format field does not apply.
  4. Activate the new service version.
  5. In Monocle, open the app's Fastly page, turn on Log policy decisions under Assessment Logging, and save.

The endpoint must be on the Monocle service, not on the service that serves your origin. If the name does not match, the lines still reach the log tail but nothing is retained, and no error is shown. Updating the service from the Fastly page keeps the endpoint: a redeploy clones the active version, so logging configuration carries over.

Each line contains the visitor's IP address. Retain and forward the lines in line with your own data protection obligations. Turning the switch off stops the lines with the next request; a plan that no longer includes assessment logging stops them too, without a redeploy.

Plugin version updates

Monocle may release new versions of the Compute plugin.

When a new version is available, the Fastly page shows that an update is available. To update, select Update Service. The service is redeployed with the latest package and your current configuration; traffic keeps flowing during the deploy.

A service deployed with a previous version of the plugin shows a notice on the Fastly page until it is redeployed. Its path rules are replaced by the assessed paths chosen on that page.

Updating an API token

If your Fastly API token is rotated, revoked, or expires, Monocle loses permission to manage the service.

The deployed service keeps running, but Monocle cannot update its configuration, redeploy it, or remove it until a valid token is provided.

If you see an invalid token warning:

  1. Create a new Fastly API token with the same scope.
  2. Update the token in Monocle from the Fastly page.
  3. Validate the token again.

Removing the service

You can remove the Monocle Compute service from the Fastly page.

Removing the service first moves the domain back to the service that served it before Monocle, then undoes any chaining changes made to your existing service and deletes the Monocle service and its stores from your Fastly account. Traffic is no longer assessed.

If the domain cannot be moved back, nothing is removed and your site keeps running through Monocle. Retry the removal, or move the domain in the Fastly dashboard first.

Related