Elastic

Elasticsearch is a log management, SIEM, and observability platform, most often deployed as the ELK stack: Elasticsearch for storage and search, Logstash for input and output, and Kibana for dashboards.

This integration sends Stairwell trigger notifications into Elasticsearch by way of Logstash. Stairwell posts a webhook, Logstash receives it on an HTTP port, and the events land in an index you can search and dashboard alongside everything else.

What do I need before I start?

• A webhook URI from Elastic, which is the Logstash HTTP input you are about to configure.
• Write access to the Stairwell environment you are configuring.

How do I configure Logstash?

Logstash sits between your data sources and Elasticsearch. This integration uses its HTTP input plugin: Logstash listens on a port, and Stairwell sends its trigger webhooks there.

input {
  http {
    port => 10228
  }
}

filter {
  json {
    source => "message"
  }

  # Rename 'query', which Elasticsearch uses itself, and rename 'matches'
  # to 'match' to make clear these are single matches after the split below.
  mutate {
    rename => {"query" => "queryCEL"}
    rename => {"matches" => "match"}
  }

  # Trigger notifications arrive with an array of matches. Splitting it
  # produces one document per match rather than one per notification.
  split {
    field => "match"
  }
}

output {
  elasticsearch {
    hosts => ["localhost:9200"]
    manage_template => false
    index => "%{+YYYY.MM.dd}"
  }
}

Three parts of that config are doing real work and are worth understanding rather than pasting.

The query rename. Elasticsearch uses query for its own purposes, so a field of that name in an incoming document causes trouble. Stairwell's notification carries the CEL query that produced the match, hence queryCEL.

The split. A single trigger notification can carry many matches. Without the split you get one Elasticsearch document holding an array, which is awkward to search and worse to dashboard. With it you get one document per match, which is almost always what you want.

The daily index. %{+YYYY.MM.dd} writes to a date-stamped index, which is the conventional ELK pattern and keeps retention manageable. Change it if your cluster has its own naming convention.

How do I configure Stairwell?

1. Select the settings icon.
2. Open the Environments tab.
3. Find the environment you are configuring and select the cog.
4. Open the Event Notifications tab.
5. Choose Add New Elastic Integration.
6. Paste the webhook URI from Elastic.
7. Select Create.

What actually gets sent?

Whatever your triggers decide, which means this integration is only as useful as the triggers behind it. A trigger that fires on every verdict change will fill an index and teach your team to ignore it.

Configure the triggers first and the integration second. See Event Notifications for what a notification contains and Trigger Silences for narrowing one that turns out noisy.

Where do I get help?

[email protected].

What should I read next?

• Event Notifications, which decides what this integration receives.
• Generic SIEM or SOAR, which is the same webhook mechanism for any other destination.
• Integrations, for what else is available.