Getting started with the agent

The Next-Gen WAF agent (formerly known as the Signal Sciences agent) is a small process that provides the interface between your web server and our analysis platform. An inbound web request is passed to the agent, which then decides whether the request should be permitted to continue, blocked, rate limited, or tagged with signals. Depending on your deployment method, the agent is typically installed directly on your web server, or as a sidecar extending your existing deployment.

How the agent works

When a request is made to your web application, the deployment entity detects the request and sends it to the agent for processing. The agent uses your active rules and site alerts (also known as workspace alerts) to determine whether to allow, block, rate limit, or tag the request. Next, the agent performs any tagging decisions and redacts sensitive information from the request. Then the agent relays the request and its decision back to the deployment entity. The deployment entity enacts the agent's decision.

In addition to your deployment entity, the agent communicates asynchronously with our cloud engine every 30 seconds. Specifically, the agent:

• uploads redacted request and response data to the cloud engine per our data storage policy.
• downloads new rules and configurations from the cloud engine.

Threshold counting

For Core WAF and Cloud WAF deployments, the agent has local counters and is immediately able to determine when a request exceeds a site alert (workspace alert) or rate limit threshold. The agent uses aggregation from the cloud engine when multiple agents are deployed.

For information on how threshold counting works for Edge WAF deployments, check out How the Edge WAF works.

Agent reliability

To optimize performance and improve reliability, the Next-Gen WAF architecture is split between the agent and deployment entity. If the agent experiences issues or unavailability, your application will continue to function because your deployment entity fails open if it doesn’t hear back from the agent within a set time limit. The default timeouts vary by module type and are as follows:

If the agent loses the ability to communicate with the cloud engine, the agent will continue to function with the following caveats:

• The agent will continue to detect attacks, anomalies, and any custom rules or signals based on local configurations at time of communication failure.
• The agent will continue to enforce existing blocking decisions.
• For Core WAF and Cloud WAF deployments, the agent's local counters will continue to tally requests that count towards site alert (workspace alert) and rate limit thresholds. When multiple agents are deployed, aggregation will not occur until communication resumes. Edge WAF deployment agents do not have local counters.
• The agent will not queue request logs and there will be an outage of data shown in the control panel. The ability to look at individual requests or aggregate data will be lost until the connection is reestablished.
• The agent will not receive configuration updates made via the control panel and API you have access to.
• The agent will not receive updates for new detections or enforcement decisions.
• The agent will not receive updated geolocation data.

Agent language

The agent is written in Go. We chose Go because of its combination of performance, ease of deployment, and memory safety guarantees. In addition, Go doesn't have the security issues associated with C/C++ (e.g., buffer overflows).

Installing the agent

To install the agent, complete the following steps:

1. Follow the agent installation instructions for your operating system:

2. (Optional) Configure the agent for your environment.

3. (Optional) Set up agent alerts to inform you when:

   • the number of online agents reaches a specified threshold.
   • the average number of requests per second (RPS) for all agents across all sites reaches a specified threshold.

Upgrading the agent

Per our agent end-of-support policy, we support agent versions that are under two years old. On a quarterly cadence, we deprecate and no longer support agent versions that are older than two years. If you want to upgrade your agent to a newer version, you can:

• manually upgrade the agent and then restart the agent.
• enable the agent auto-update service. The agent auto-update service checks at regularly occurring intervals for a new version of the agent and updates the agent when a new version is available.

Using agent configuration management systems

The agent can be managed via various configuration management systems (e.g., Chef, Puppet, and Ansible). To use a configuration management system, construct or expand an agent configuration file (typically agent.conf) or use environment variables. For a list of values that can be configured, check out our Configuring the agent guide.

Agent Start-up Behavior

When the agent starts up, it will send http requests to one or more addresses in order to determine what environment it is running in and optimize for that environment. The addresses are:

• http://169.254.169.254/latest/api/token
• http://169.254.169.254/latest/meta-data/instance-type
• http://metadata.google.internal/computeMetadata/v1/instance/machine-type
• http://169.254.169.254/metadata/instance/compute/vmSize