Sophos Central Integration

Poll the Sophos Central SIEM API with ilagent and turn Sophos endpoint alerts into ilert alerts that notify on-call teams.

Sophos Central is the cloud console that manages Sophos endpoint, server, and firewall protection and collects the alerts they raise, such as malware detections, blocked threats, and tamper attempts. Integrating Sophos Central with ilert routes those alerts to the right on-call team through SMS, phone calls, and push notifications.

Sophos Central has no webhook for this. Instead, the pull connector of ilagent polls the Sophos SIEM API, turns each Sophos alert into an ilert event, and sends it to your alert source:

Sophos Central SIEM API  ◄── polls every 60s ──  ilagent  ── events ──►  ilert

Before you start, you need:

• admin access to Sophos Central
• permission to create alert sources in ilert
• an always-on host that can reach *.sophos.com and api.ilert.com, with Docker or the ilagent binary installed

The pull connector requires ilagent 0.12.0 or later. Check with ilagent --version.

In ilert: Create a Sophos alert source

1. Go to Alert sources → Alert sources and click Create new alert source.
2. Search for Sophos in the search field, click the Sophos tile, and click Next.
3. Give your alert source a name such as Sophos Central, optionally assign teams, and click Next.
4. Select an escalation policy by creating a new one or assigning an existing one.
5. Select your alert grouping preference and click Continue setup. You may click Do not group alerts for now and change it later.
6. The next page shows additional settings, such as custom alert templates or notification priority. Click Finish setup for now.
7. On the final page, copy the Integration key. You pass it to ilagent as --event_key. ilagent does not use the Sophos URL shown below it.

   

   Copy the Integration key from the Settings tab of the alert source

Treat the integration key like a password. Anyone who has it can create alerts in your account.

In Sophos Central: Create API credentials

1. Click the gear icon in the top bar to open Global Settings, then go to Access Control → API Credentials.

   

   API Credentials is under Access Control in Global Settings
2. Click Add Credential. Enter ilagent as the Credential name, set Role to Service Principal Read-Only, and click Add. ilagent only reads from Sophos, so it needs no broader role.

   

   Set Role to Service Principal Read-Only, not the Service Principal Super Admin shown here
3. Copy the Client ID and the Client Secret. Sophos displays the secret only once.

Sophos API credentials expire after 36 months. When yours expires, create a new credential and restart ilagent with the new client ID and secret.

On any machine: Look up your tenant ID and region host

Sophos serves each tenant from a regional host, and every SIEM request needs your tenant ID. Neither changes, so you look them up once. Run this anywhere curl and jq are installed:

CID='YOUR_CLIENT_ID'
SECRET='YOUR_CLIENT_SECRET'

TOKEN=$(curl -s -X POST https://id.sophos.com/api/v2/oauth2/token \
  -d "grant_type=client_credentials&scope=token&client_id=$CID&client_secret=$SECRET" \
  | jq -r .access_token)

curl -s -H "Authorization: Bearer $TOKEN" https://api.central.sophos.com/whoami/v1 | jq

The response looks like this:

{
  "id": "1a2b3c4d-...",
  "idType": "tenant",
  "apiHosts": {
    "global": "https://api.central.sophos.com",
    "dataRegion": "https://api-eu01.central.sophos.com"
  }
}

Note down id, which is your tenant ID, and apiHosts.dataRegion, which is your region host. If TOKEN is null, the client ID or secret is wrong.

If idType is partner or organization rather than tenant, the credential covers several tenants. This guide covers a single tenant, so create the credential inside the tenant you want to monitor instead.

On the host: Run ilagent

Replace YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_TENANT_ID, YOUR_REGION_HOST, and YOUR_INTEGRATION_KEY, then start the agent.

Docker (recommended)

docker run -d --name ilagent-sophos --restart unless-stopped \
  -v ilagent-sophos:/data \
  -p 8977:8977 \
  -e ILERT_PULL_CLIENT_SECRET='YOUR_CLIENT_SECRET' \
  ilert/ilagent daemon -v -v \
  --file /data/ilagent.db3 \
  --port 8977 \
  --max_retries 0 \
  --pull_url 'YOUR_REGION_HOST/siem/v1/alerts?limit=1000' \
  --pull_name sophos-alerts \
  --pull_interval 60 \
  --pull_header 'X-Tenant-ID=YOUR_TENANT_ID' \
  --pull_items_path items \
  --pull_auth oauth2 \
  --pull_token_url https://id.sophos.com/api/v2/oauth2/token \
  --pull_client_id 'YOUR_CLIENT_ID' \
  --pull_scope token \
  --pull_cursor_mode token \
  --pull_cursor_path next_cursor \
  --pull_cursor_param cursor \
  --pull_dedup_key id \
  --event_key 'YOUR_INTEGRATION_KEY' \
  --map_key_summary description \
  --map_key_alert_key id \
  --map_key_severity severity \
  --map_val_severity 'critical=1' \
  --map_val_severity 'high=2' \
  --map_val_severity 'medium=3' \
  --map_val_severity 'low=4' \
  --forward_message_payload \
  --label 'source=sophos'

Keep the volume. It holds ilagent's SQLite database: the position in the Sophos feed, the IDs of alerts already sent, and any events still waiting for delivery. Without the volume, every container restart loses all three.

Binary

ILERT_PULL_CLIENT_SECRET='YOUR_CLIENT_SECRET' ilagent daemon -v -v \
  --file /var/lib/ilagent/ilagent.db3 \
  --port 8977 \
  --max_retries 0 \
  --pull_url 'YOUR_REGION_HOST/siem/v1/alerts?limit=1000' \
  --pull_name sophos-alerts \
  --pull_interval 60 \
  --pull_header 'X-Tenant-ID=YOUR_TENANT_ID' \
  --pull_items_path items \
  --pull_auth oauth2 \
  --pull_token_url https://id.sophos.com/api/v2/oauth2/token \
  --pull_client_id 'YOUR_CLIENT_ID' \
  --pull_scope token \
  --pull_cursor_mode token \
  --pull_cursor_path next_cursor \
  --pull_cursor_param cursor \
  --pull_dedup_key id \
  --event_key 'YOUR_INTEGRATION_KEY' \
  --map_key_summary description \
  --map_key_alert_key id \
  --map_key_severity severity \
  --map_val_severity 'critical=1' \
  --map_val_severity 'high=2' \
  --map_val_severity 'medium=3' \
  --map_val_severity 'low=4' \
  --forward_message_payload \
  --label 'source=sophos'

Run it under systemd or another supervisor so that it restarts after a failure or a reboot.

Both variants pass the client secret in the ILERT_PULL_CLIENT_SECRET environment variable rather than as a flag, so it stays out of the process list.

Flag	What it does
-v -v	Logs at info level, so you see a line whenever new Sophos alerts are queued. With one -v or none, ilagent logs only warnings and errors.
--max_retries 0	Retries undelivered events until ilert accepts them. The default of 100 drops an event after about 100 failed attempts, which an ilert or network outage of roughly 1.5 hours can use up.
--pull_url …/siem/v1/alerts?limit=1000	Polls the Sophos alerts feed, up to 1000 alerts per page.
--pull_name sophos-alerts	Names this source in ilagent's database. Do not change it later, or ilagent loses its place in the feed.
--pull_header X-Tenant-ID=…	Sends the tenant ID, which Sophos requires on every request.
--pull_auth oauth2, --pull_token_url, --pull_client_id, --pull_scope token	Logs in with the API credential. ilagent renews the token automatically.
--pull_cursor_mode token, --pull_cursor_path next_cursor, --pull_cursor_param cursor	Sophos returns a next_cursor with each page. ilagent stores it and sends it back, so each poll fetches only new alerts.
--pull_dedup_key id	Remembers Sophos alert IDs for 7 days, so no Sophos alert is sent twice.
--map_key_summary description	Uses the Sophos alert description as the ilert alert summary.
--map_key_alert_key id	Sets the alert key. ilert groups events that share an alert key into one alert.
--map_key_severity, --map_val_severity	Translates the Sophos severity words to ilert's 1 to 5.
--forward_message_payload	Copies the full Sophos alert, including type, endpoint, threat, and file path, into the custom details of the ilert alert.
--label source=sophos	Adds a source=sophos label to every event, for filtering and routing in ilert.

For every flag the pull connector supports, see the pull connector reference.

Run one agent per Sophos feed. Two agents polling the same feed both send an event for every Sophos alert.

Verify the integration

1. Follow the logs:

   docker logs -f ilagent-sophos

   The agent starts without errors. Whenever a poll finds new Sophos alerts, it logs Pull source 'sophos-alerts' enqueued N events. Polls that find nothing new log nothing; to log every poll, use -v -v -v instead of -v -v.
2. Check the health endpoint. It returns 204 No Content once a poll has succeeded. Until then, or after a failed poll, it returns 503 with a body such as {"component":"pull","polling":true,"error":"..."}. The error field is empty before the first poll finishes.

   curl -i http://localhost:8977/ready

3. Trigger a real alert. On a machine protected by Sophos, download the EICAR test file. It is harmless, and every antivirus product detects it as malware. Within a few minutes, an alert appears in Sophos Central and then in ilert, with the source=sophos label and the full Sophos record in its custom details.

On its first poll, ilagent picks up every alert that Sophos still serves, which covers roughly the last 24 hours. If your tenant had recent alerts, expect a burst of them in ilert right away.

Troubleshooting

Log message	Cause and fix
oauth token request returned status 400 or 401	Wrong client ID or secret, or the credential was deleted or has expired in Sophos Central. Create a new one.
unauthorized (401) — check pull credentials	Sophos rejected the token for this tenant. Check the tenant ID and region host: look them up again and compare.
pull request returned status 403	Wrong region host or tenant ID. Look them up again and compare.
pull request returned status 400 after downtime	The stored cursor has expired. See Reset the cursor after downtime.
pull request returned status 429	Sophos is rate limiting the agent. Raise --pull_interval.
Alerts reach ilert without a severity	Sophos sent a severity word the mapping does not cover. Add another --map_val_severity.
Nothing in ilert, no errors in the logs	There were no new Sophos alerts. Trigger one with the EICAR test file.

Reset the cursor after downtime

Sophos cursors stay valid for about 24 hours. If the agent was stopped for longer, every poll then fails with pull request returned status 400. Clear the stored cursor and restart the agent. Alerts that ilagent already sent are not sent again, because the dedup IDs are kept:

docker stop ilagent-sophos
docker run --rm -v ilagent-sophos:/data alpine sh -c \
  "apk add -q sqlite && sqlite3 /data/ilagent.db3 \"DELETE FROM ilagent WHERE key='pull_cursor:sophos-alerts'\""
docker start ilagent-sophos

FAQ

Will alerts in ilert be resolved automatically?

No. The Sophos SIEM feed carries new alerts, not their closure, so ilagent never sends a resolve event. Resolve the alert in ilert once it is handled in Sophos Central.

Will alerts in ilert be accepted automatically?

No. Sophos has no acknowledged state that ilagent could forward.

What happens if ilert cannot be reached?

ilagent keeps undelivered events in its local database and retries them, backing off to one attempt per minute. With --max_retries 0, as in the commands above, it retries until ilert accepts them. Without it, ilagent drops an event after 100 failed attempts. The queue lives in the SQLite database, which is why the Docker volume matters.

While more than 5000 events wait for delivery, ilagent skips its Sophos polls. If ilert stays unreachable for more than about 24 hours, the stored cursor expires, and you need to reset the cursor once ilert is back.

Can I forward Sophos events as well as alerts?

Yes. Sophos also has an events feed, /siem/v1/events, with much more detail, such as update successes and policy changes. It is usually too noisy to page on. To forward it, run a second agent with its own volume, a different --pull_name such as sophos-events, and --map_key_summary name. Add --filter_key type and --filter_val with the one Sophos event type you want to page on. The filter matches a single value, so forwarding several event types takes one agent per type.

Can I reduce the number of alerts that reach ilert?

Yes, either in ilagent or in ilert. --filter_key and --filter_val make ilagent send only the Sophos alerts whose top-level field equals exactly one value, and drop all others. For example, --filter_key severity --filter_val high sends only high-severity alerts. The filter cannot exclude specific alerts or match several values. In ilert, event grouping and support hours on the alert source control how many of the events turn into notifications.