Skip to content

What does it do

  1. Handle WAF functionality from local webserver
  2. Periodically send data back up to the The Collector
  3. Periodically poll for new rule updates

WAF Functionality

Flow 1 - Standard

  1. Data is sent from webserver once all data and post data is read in. This is RPCMsgIn.
  2. Agent returns a status 200 (let request pass), and no request ID using RPCMsgOut
  3. Webserver processes request without error.
  4. Done.

Flow 2 - Standard with Error

  1. Data is sent from webserver, RPCMsgIn
  2. Agent returns a status 200, and no request ID using AgentMsgOut
  3. Webserver processes request but has a 400 or 500- error.
  4. Module resends all data to Agent from step 1 (RPCMsgIn) but also includes the following:
  5. Webserver response code
  6. Webserver response size
  7. Done. (no reply from Agent)

Flow 3 - Allow but Send More Information

  1. Data is sent from webserver, RPCMsgIn
  2. Agent returns a status code 200, and a Request ID using AgentMsgOut
  3. Webserver proceeds normally.
  4. At the of request, module sends back using AgentMsgIn2
  5. Webserver response code
  6. Webserver response size
  7. Request ID.
  8. Done

Flow 4 - Blocking

NOTE: it is somewhat difficult to trigger a non-200 request at the moment.

  1. Data is sent from webserver, RPCMsgIn
  2. Agent returns a status code that is NOT 200, and a Request ID using RPCMsgOut
  3. Module halts request
  4. TBD.. does it also do a followup request like in Flow 3

Upload data

Periodically The Agent uploads data to the collector.

  • It is a HTTPS POST
  • The data is HMACd using a shared secret key, and in a JSON JOSE format.
  • Data transmission is using TLS

Download rules

Periodically The Agent polls for new rule updates.

  • The file is stored on S3, and retrievable using standard HTTPS
  • The file is publicly accessible (i.e. no access control for reads), assuming one knows the exact URL
  • The file is compressed using zlib, and encrypted using a shared secret key using AES128-GCM using the JSON JOSE format.
  • Note that the file is encrypted since its at rest and publicly available, AND it is retrieved via HTTPS / TLS.
  • As of v4.30.0 the file will be fetched from the Fastly CDN before connecting to S3 directly

The rules format is subject story.

RPC Test Harness Mode

The RPC Test Harness mode (aka fakeagent) causes the agent to execute in a mode for testing modules (or general RPC functionality). In this mode, the agent will interpret some HTTP request headers as commands for testing purposes. Enabling this mode will also cause the agent to run in standalone mode, which will not communicate with the cloud (no download or upload functionality).

This mode should NEVER be used in production

Use the -debug-rpc-test-harness option to start in this mode. Note that this will also cause -debug-standalone=3 to be used. In addition to this mode, the -debug-log-rpc-data=[file] will allow logging all raw RPC data to a log file for further diagnostics.

Special Command HTTP Request Headers

The following headers present in the HTTP request will have special meaning to the agent and allow controlling how the agent processes the transaction. Note that any interpreted header will be removed from the original request after it is processed (e.g., it will not be recorded as part of the request).

  • X-Ss-Prerequest-Senderror: true: Agent will cause an error to be generated in the decision processing.
  • X-Ss-Prerequest-Delay: [time-in-ms]: Agent will introduce a delay in decision processing.
  • X-Ss-Prerequest-Panic: true: Agent will cause a panic to be generated during decision processing.
  • X-Ss-Prerequest-Requestid: [id]: Agent will use the given ID as the request ID.
  • X-Ss-Prerequest-Respond: [status-code]: Agent will respond with the given status code in the RPC response.
  • X-Ss-Prerequest-Response-Header: [Name]=[value]: Agent will add the given header to the RPC response.
  • X-Ss-Prerequest-Add-Signal: [type],[location],[value],[detector]: Agent will cause the given signal to be generated. Notes, that you can specify multiple signals by prepending a "-N" to the header name, such as "X-Ss-Prerequest-Add-Signal-1: type,location,value,detector".

In the above, Prerequest can be replaced by "Postrequest" in all cases. Additionally, Prerequest can be replaced with "Updaterequest" in all cases EXCEPT where it adds to the response, as RPC.UpdateRequest calls have no response since no inspection is performed.

License

Proprietary and Confidential

© 2025 Fastly Inc. All Rights Reserved.