Getting started with the agent
Last updated 2023-12-21
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.
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 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-hosted collection and analysis system every 30 seconds. Specifically, the agent:
- uploads redacted request and response data to the collection and analysis system per our data storage policy.
- downloads new rules and configurations from the collection and analysis system.
For Core and Cloud WAF deployments, the agent has local counters and is immediately able to determine when a request exceeds a site alert or rate limit threshold. The agent uses aggregation from the collection and analysis system when multiple agents are deployed.
For edge deployments, the agent relies on the collection and analysis system to tell it when an IP address is flagged.
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:
|All other modules
If the agent loses the ability to communicate with the collection and analysis system, 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 and Cloud WAF deployments, the agent's local counters will continue to tally requests that count towards site alert and rate limit thresholds. When multiple agents are deployed, aggregation will not occur until communication resumes. Edge 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 console. 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 web interface or API.
- The agent will not receive updates for new detections or enforcement decisions.
- The agent will not receive updated geolocation data.
The monitoring 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).
To install the agent, complete the following steps:
Follow the agent installation instructions for your operating system:
We only support ARM processors on agent v4.27.0 and higher. Dedicated agent packages are only available for Alpine, Ubuntu, Debian, CentOS, and Red Hat Enterprise.
(Optional) Configure the agent for your environment.
(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.
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.
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.