Getting started with the agent
Last updated 2023-10-19
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 entity for your particular deployment method (e.g., module or Fastly VCL Service) 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. The agent then performs any tagging decisions and redacts sensitive information from the request. Next, 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 with our cloud-hosted collection and analysis system. 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.
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. Additionally, agent communication with the Signal Sciences backend is asynchronous, so should the agent lose the ability to communicate with the Signal Sciences cloud backend, the agent will continue to function with the following caveats:
- The agent will continue to detect attacks, anomalies, and any custom rules or signals.
- The agent will continue to enforce existing blocking decisions.
- 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 updates for new detections or enforcement decisions.
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.