OpenSearch Integration¶

Deploy WitFoo detection rules and dashboards to OpenSearch or OpenSearch Dashboards.

Downloads¶

OpenSearch DQL rules (.dql)

All 55 detection rules as DQL/Lucene queries. Also available:

• Index template — index_template.json: field mappings for the witfoo-* indices.
• Dashboards — the opensearch/dashboards/ directory (5 NDJSON saved-object files).
• Sigma source — sigma_rules.zip: all 68 platform-agnostic Sigma rules.

Prerequisites¶

• OpenSearch 2.x+ with OpenSearch Dashboards
• WitFoo Conductor with artifact-exporter configured to send to OpenSearch
• Admin access to manage index templates and saved objects

Architecture¶

graph LR
    A[WitFoo<br/>Conductor] -->|REST API| B[OpenSearch<br/>Cluster]
    B --> C[witfoo-* indices]
    C --> D[Alerting<br/>55 monitors]
    C --> E[Dashboards<br/>5 NDJSON]

The artifact-exporter sends JSON documents to OpenSearch indices matching the witfoo-* pattern (e.g., witfoo-2026.02.21). All fields use camelCase naming.

Step 1: Apply Index Template¶

Apply the index template to ensure correct field mappings:

PUT _index_template/witfoo
// Paste contents of opensearch/index_template.json

curl -X PUT "https://opensearch:9200/_index_template/witfoo" \
  -H "Content-Type: application/json" \
  -d @opensearch/index_template.json

The template maps key fields with appropriate types:

• clientIP, serverIP → ip type (enables CIDR queries)
• totalBytes, clientBytes, serverBytes → long type
• startTimeUTC → date type (used as time field)
• streamName, severity → keyword type
• artifactName → text + keyword (full-text + exact match)

Step 2: Import Dashboards¶

Import the 5 NDJSON dashboard files via OpenSearch Dashboards:

1. Navigate to Stack Management → Saved Objects
2. Click Import
3. Select each .ndjson file from opensearch/dashboards/:

Each NDJSON file includes:

• An index pattern for witfoo-*
• The dashboard saved object
• All visualization saved objects referenced by the dashboard

Step 3: Create Alerting Monitors¶

Convert the 55 DQL rule files into OpenSearch alerting monitors:

# Example: create a monitor from a DQL file
for f in opensearch/rules/*.dql; do
  NAME=$(basename "$f" .dql)
  QUERY=$(cat "$f")
  curl -X POST "https://opensearch:9200/_plugins/_alerting/monitors" \
    -H "Content-Type: application/json" \
    -d "{
      \"name\": \"WitFoo - $NAME\",
      \"type\": \"monitor\",
      \"enabled\": false,
      \"schedule\": {\"period\": {\"interval\": 15, \"unit\": \"MINUTES\"}},
      \"inputs\": [{\"search\": {\"indices\": [\"witfoo-*\"], \"query\": {\"query_string\": {\"query\": \"$QUERY\"}}}}],
      \"triggers\": [{\"name\": \"Alert\", \"severity\": \"3\", \"condition\": {\"script\": {\"source\": \"ctx.results[0].hits.total.value > 0\"}}}]
    }"
done

Field Reference¶

Troubleshooting¶

GET witfoo-*/_count