Skip to content

Reduce event volume with the Sekoia Endpoint Agent

The Sekoia Endpoint Agent supports optimization rules that filter events directly on the host, before they are transmitted to the platform. Filtering at the agent level reduces both network bandwidth usage and the volume counted against your license allowance, making it more effective than platform-level optimization rules for endpoint sources.

How agent-level optimization rules differ from platform-level rules

Both the Sekoia Endpoint Agent and the Sekoia platform support optimization rules, but they work at different points in the pipeline:

Agent-level rules Platform-level rules
Where filtering happens On the host, before transmission At the Sekoia intake, after reception
Volume impact Reduces network usage and ingestion volume Reduces storage and detection load only
Configuration method API or agent configuration file API only
Applicable sources Sekoia Endpoint Agent intakes only Any intake
Field availability Parsed fields only Parsed fields only

Use agent-level rules first for endpoint sources

If you are optimizing a Sekoia Endpoint Agent intake, configure agent-level rules before resorting to platform-level optimization rules. The impact on volume and bandwidth is greater.

Prerequisites

  • At least one Sekoia Endpoint Agent deployed and sending events.
    • API access to your Sekoia community if you use the API configuration method. The API key must have the SIC_WRITE_CONF_INTAKES permission.
  • The format_uuid for the Sekoia Endpoint Agent format: 250e4095-fa08-4101-bb02-e72f870fcbd1.

Understand what to filter

Good candidates for agent-level filtering are high-frequency, low-security-value events that the Endpoint Agent generates continuously:

  • Process creation and process end events for known-safe, non-interactive processes (monitoring agents, update services, antivirus scanners).
  • DNS query events for internal resolvers or known-safe domains.
  • File creation events in temporary or cache directories with no security relevance.
  • Network connection events between internal hosts on known management ports.

To find the highest-volume event types, use Events > Search in Sekoia, filter by your endpoint intake, and sort by event count. The investigate overusage playbook describes this process in detail.

Create an agent-level optimization rule

Agent-level optimization rules can be configured through the Sekoia API or an agent configuration file. The following examples use the Sekoia API. The endpoint is:

POST https://api.sekoia.io/v1/sic/conf/intakes/optimization_rules/

Authenticate with your API key in the Authorization header.

Scope options

You can target the rule at three levels of granularity:

Omit intake_uuid and agent_id. The rule applies to all Endpoint Agent intakes in the community.

{
  "format_uuid": "250e4095-fa08-4101-bb02-e72f870fcbd1",
  "community_uuid": "YOUR_COMMUNITY_UUID",
  "description": "Drop monitoring agent process events",
  "action": 1,
  "enabled": true,
  "filters": [
    {
      "field": "process.name",
      "operator": "==",
      "value": "monitoring-agent.exe"
    }
  ]
}

Add intake_uuid to scope the rule to one intake only.

{
  "format_uuid": "250e4095-fa08-4101-bb02-e72f870fcbd1",
  "intake_uuid": "YOUR_INTAKE_UUID",
  "community_uuid": "YOUR_COMMUNITY_UUID",
  "description": "Drop monitoring agent process events on server-intake",
  "action": 1,
  "enabled": true,
  "filters": [
    {
      "field": "process.name",
      "operator": "==",
      "value": "monitoring-agent.exe"
    }
  ]
}

Add agent_id to scope the rule to one individual agent.

{
  "format_uuid": "250e4095-fa08-4101-bb02-e72f870fcbd1",
  "agent_id": "YOUR_AGENT_ID",
  "community_uuid": "YOUR_COMMUNITY_UUID",
  "description": "Drop monitoring agent process events on this host",
  "action": 1,
  "enabled": true,
  "filters": [
    {
      "field": "process.name",
      "operator": "==",
      "value": "monitoring-agent.exe"
    }
  ]
}

Filter multiple conditions

All filters in the filters array are combined with AND logic. An event is dropped only if it matches every condition.

{
  "format_uuid": "250e4095-fa08-4101-bb02-e72f870fcbd1",
  "community_uuid": "YOUR_COMMUNITY_UUID",
  "description": "Drop notepad txt file events",
  "action": 1,
  "enabled": true,
  "filters": [
    {
      "field": "process.name",
      "operator": "==",
      "value": "notepad.exe"
    },
    {
      "field": "file.extension",
      "operator": "==",
      "value": "txt"
    }
  ]
}

Filter a list of values

Use the in operator to match against a list of values in a single filter condition.

{
  "format_uuid": "250e4095-fa08-4101-bb02-e72f870fcbd1",
  "community_uuid": "YOUR_COMMUNITY_UUID",
  "description": "Drop high-volume low-value endpoint action types",
  "action": 1,
  "enabled": true,
  "filters": [
    {
      "field": "action.name",
      "operator": "in",
      "value": [
        "file-created",
        "connected-to",
        "dns-query-result",
        "process-created",
        "process-ended"
      ]
    }
  ]
}

Filter on process-created and process-ended carefully

Dropping all process-created events removes important forensic data. Target this filter at specific, known-safe process names rather than the entire event type.

Known limitation: enriched fields are not available

Optimization rules are evaluated at parsing time, before enrichment runs. Fields added during enrichment, such as sekoiaio.tags.*, are not available when the rule is evaluated. A filter on an enriched field will never match and the rule will have no effect.

Use only fields that appear in the raw parsed event. To check which fields are available at parse time, inspect a raw event in Events > Search before you received it.

Allow the agent to fetch rules

Allow the agent to fetch rules

API-created optimization rules are remote rules. The agent does not fetch these rules unless remote optimization rule fetching is enabled.

Enable remote rule fetching at installation time by passing the --remote-optimization-rules flag:

./agent install --intake-key <INTAKE_KEY> --remote-optimization-rules

For an existing installation, set RemoteOptimizationRules to true in the agent configuration file:

RemoteOptimizationRules: true

Restart the agent after changing the configuration file. A restart is not required for a routine rule update, but it forces an immediate configuration fetch.

Network access

The agent must be able to connect to the Sekoia API server over HTTPS on port 443. For the default server, allow outbound access to api.sekoia.io.

When remote rule fetching is enabled, the agent periodically requests its configuration from the Sekoia API:

GET {server_url}/v1/xdr-agent/agents/config
Sekoia-Agent-ID: <AGENT_ID>
Authorization: IntakeKey <INTAKE_KEY>

The response includes the OptimizationRules assigned to the agent. The agent loads these remote rules together with any optimization rules defined in its local configuration.

Local and remote rules

RemoteOptimizationRules is required only for optimization rules configured through the Sekoia API. Rules defined in the local agent configuration do not require this setting.

To verify that a remote rule loaded successfully, check the agent logs for Optimization rule loaded. If the agent cannot compile a rule, inspect the logs for the corresponding compilation error.

Validate the impact

After creating the rule:

  1. Wait 5 to 10 minutes for the agent to fetch the updated configuration.
  2. In Sekoia, go to Events > Search, filter by the affected intake, and verify that events matching your filter conditions no longer appear.
  3. Go to Home > Settings > Usage and monitor the volume trend for the intake over the next 24 hours.

If matching events are still arriving after 15 minutes, check the agent logs for rule compilation errors. A misconfigured field path generates an error like error getting field accessor for <field>: field <X> is not in a struct, which means the field path is invalid for the parsed event structure.