Monocle Assessment

Monocle can be used exclusively as a passive means of gathering statistics about your users' connections, requiring no backend integration.

In addition, you can also choose to implement real-time actions based on the contents of the Monocle Assessment on your backend. Here are a couple of scenarios:

• Blocking risky form submissions from anonymizing VPNs
• Logging the anonymizing status of newly created accounts
• Reducing user friction for known-good Zero Trust networks like ZScaler and Netskope
• Flagging in your database logins and account creation from residential proxies

By default, the Monocle Assessment appends itself as a hidden field (named monocle) to any <form> elements present on the page.

This allows the backend server to log and/or take action using the Monocle Assessment.

Because the Monocle Assessment is encrypted (to prevent viewing and tampering by the client), it must first be decrypted in one of two ways:

1. Using your Monocle Secret Key to authenticate with the Monocle Decryption API.
2. Using your Monocle Private Key to decrypt the Monocle Assessment directly on the backend.

Either method will provide you with the decrypted Monocle Assessment, whose schema is outlined in the section below.

The Monocle Assessment object

{
  "vpn": true,
  "proxied": false,
  "anon": true,
  "rdp": false,
  "dch": false,
  "cc": "US",
  "ip": "198.51.23.210",
  "ipv6": "2001:db8:e214:9f67:711:f03e:a141:3871",
  "ts": "2022-10-17T14:03:19-04:00",
  "complete": true,
  "id": "580f12c9-8030-4d49-b39f-35dfe560fa9e",
  "sid": "example-sign-up-form",
  "service": "MULLVAD_VPN"
}

Monocle Assessment Verification

Because Monocle is stateless, verifying the veracity of an incoming Monocle Assessment is the responsibility of the integrating user.

The client cannot modify the decrypted contents of the Monocle Assessment, but they could tamper with it (thereby breaking its ability to be decrypted) or replay it in subsequent requests.

Spur recommends the following methods for validating a Monocle Assessment:

• Verify that the Monocle Assessment is included (if tied to a form submission).
• Verify that the Monocle Assessment successfully decrypts, indicating it has not been modified.
• Verify that ip matches the IP address of the form submission request.
• Verify that ts is within an acceptable range of the current datetime. We suggest ~5 minutes or a time frame commensurate with your use case.
• Check the value of complete. Under normal operation, this will be true. A false value indicates Monocle was unable to complete its evaluation, suggesting a higher possibility of false positives or negatives.

As with the interpretation of the Monocle Assessment, how you handle verification errors depends on your use case. This could range from accepting the form submission anyway, returning a validation error requiring the user to retry the form, logging the event in a backend database, or rejecting the form submission outright.

Common Scenarios

The primary value of Monocle is delivered in the first three fields: vpn, proxied, and anon.

In the matrix below, we've provided a few possible scenarios covering different combinations of values for these flags.