Generic SIEM or SOAR
Push detection events as JSON to any HTTP endpoint, with the full payload schema for both event types and a way to test it before pointing it at production.
Stairwell can POST detection events as JSON to any endpoint that accepts them, which is how you integrate with a SIEM, SOAR, or alerting system that has no purpose-built integration. When a configured event fires, Stairwell sends a payload to the webhook URI you provide.
This is also the page to read if you are writing your own integration. Everything the named integrations receive, they receive through this mechanism.
Which events can be sent?
Two:
- AV Scan Match. An object was flagged by one or more antivirus engines.
- YARA Rule Match, reported as Object Seen. A file matching an existing YARA rule was observed on an asset or uploaded by a user.
Every payload carries the object's three hashes, its size, a direct link to it in Stairwell, the environment where it was seen, and details specific to the event type.
How do I configure a webhook?
- Log in to Stairwell.
- Select the Settings icon in the left navigation.
- Open the Environments tab.
- Find the environment you want and select its gear icon.
- Open the Event Notifications tab.
- Select Add New Splunk Integration.
- Paste your webhook URI.
- Select Create.
Step 6 is not a mistake. The control is labelled for Splunk and is used for any generic webhook. If you are looking for a "generic webhook" option, this is it.
The integration is active immediately, and Stairwell POSTs to your URI each time a matching event occurs in that environment.
What does the payload look like?
AV Scan Match
| Field | Description |
|---|---|
match_type | "av_scan_match" |
av_scan_results | Array of objects, each with engine_name and threat_found |
object_sha256 | SHA-256 hash of the detected file |
object_sha1 | SHA-1 hash |
object_md5 | MD5 hash |
object_size | File size in bytes |
object_link | Direct URL to the object in Stairwell |
seen_environment_name | Environment where the object was observed |
seen_environment_id | Environment ID |
triggers_settings | Link to the notification settings that fired this event |
description | Human-readable summary of the event |
YARA Rule Match
Carries every field above except av_scan_results, plus:
| Field | Description |
|---|---|
match_type | "object_seen" |
rule_name | Name of the matching YARA rule |
rule_version | Version number of the rule |
rule_environment_name | Environment where the rule is defined |
rule_environment_id | Rule environment ID |
seen_asset | Hostname of the asset where the file was found |
seen_file_name | File name on disk |
seen_file_path | Full file path on the asset |
Two things about that second table are worth noticing when you build against it.
The rule environment and the seen environment are separate fields. A rule defined in one environment can match a file seen in another, and conflating the two produces attribution that is wrong in exactly the cases you care about. See Environments.
seen_file_name and seen_file_path belong to the sighting, not the file. The same object arrives under different names on different machines, so these describe one observation rather than the file itself. Do not key anything on them. See Sightings.
How do I test it before pointing it at production?
Do this. The failure mode otherwise is a silent one, and you will not notice until an incident.
- Configure a webhook pointing at a request-inspection tool such as webhook.site, or a local listener with
nc -l 8080. - Upload a known-malicious test file, such as the EICAR test file, to the target environment.
- Confirm the JSON arrives within a few minutes.
- Replace the test URI with your production endpoint.
Reading one real payload before you write a parser against the schema above is worth the ten minutes, because it tells you what your particular events actually contain.
What do people use this for?
- SIEM ingestion. Forward detection events to Splunk, Sentinel, Elastic, or Google SecOps for correlation with other log sources.
- SOAR automation. Trigger playbooks in Tines, Torq, XSOAR, or Swimlane to enrich, quarantine, or escalate.
- Alerting. Route to PagerDuty, Slack, or email through lightweight middleware.
- Hunting pipelines. Feed rule match events into your own tooling for bulk triage.
Several of those have a purpose-built integration that will save you the middleware. Check Integrations before building.
What should I read next?
- Event Notifications, for which events fire and why.
- Trigger Silences, for narrowing a webhook that turns out noisy without turning it off.
- REST APIs, if you need to pull data rather than receive it.
Updated 20 days ago