Quick Start Guide: Detections, Signals, and Alerts
This guide walks you through RunReveal’s detection system using hands-on examples. We will go over adding a webhook to send test logs to via curl to test detections and see how Detections, Signals, and Alerts work together.
Detections, Signals, and Alerts are all classified as detection results and are part of the Detections table. Signals are detection results without notifications (for analysis/tuning). Alerts are detection results that trigger notifications.
Detections | Signals | Alerts | |
---|---|---|---|
What it is | Automated rules that analyze logs | Detection results without notifications | Detection results with notifications |
Purpose | Continuous monitoring and analysis | Pattern recognition and tuning | Immediate awareness and response |
Filtering | detections table | signals table | alerts table |
Notifications | None | None | Email, Slack, PagerDuty, etc. |
Use Case | Security policy enforcement | Threat hunting and analysis | Incident response workflows |
Getting Started
This guide walks you through the complete workflow for setting up detections, signals, and alerts in RunReveal:
- Create Webhook Source - Set up a data source to receive test events (Either a Structured Webhook or Generic Webhook Source in UI)
- Send Test Data - Generate sample security events for testing
- Create Detection Rule - Build a SQL-based detection that analyzes your data
- Trigger and Review - Manually run the detection and check results
- Compare Signal vs Alert - Convert to alerts and see the difference
Step 1: Create Webhook Source
First, create a webhook source in RunReveal to receive test data:
- In RunReveal UI:
- Navigate to Sources in the left sidebar
- Click Connect a new source
- Select Webhook from the source types
- Configure the webhook:
- Name:
test-webhook-source
- Description:
Test webhook for detection guide
- Name:
- Click Create or Save
- Copy the webhook URL - it will look like:
https://api.runreveal.com/sources/hook/YOUR_WEBHOOK_ID
Step 2: Send Test Data
Now send a test security event using your webhook URL:
-
Test Event:
curl -X POST https://api.runreveal.com/sources/hook/30pw8Fynw5W7PzjbnRyxnfMsID2 \ -H "Content-Type: application/json" \ -d '{ "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "source": "test-system", "eventName": "suspicious_login", "severity": "high", "user": "test-user", "srcIP": "192.168.1.100", "action": "login_attempt", "result": "success", "user_agent": "curl-test", "metadata": { "login_method": "ssh", "session_id": "test-123" } }'
-
Verify ingestion to logs table:
SELECT receivedAt, sourceType, JSONExtractString(rawLog, 'eventName') as eventName, JSONExtractString(rawLog, 'user') as user, JSONExtractString(rawLog, 'srcIP') as srcIP, rawLog FROM logs WHERE sourceType = 'structured-webhook' AND JSONExtractString(rawLog, 'eventName') = 'suspicious_login' ORDER BY receivedAt DESC LIMIT 5;
Step 3: Create a Test Detection Rule
Create a SQL detection that will trigger a signal from your test logs:
-
In RunReveal UI:
- Go to Detections > Create Detection
- Name:
test-suspicious-login
- Type: SQL
- Query:
SELECT JSONExtractString(rawLog, 'eventName') as eventName, JSONExtractString(rawLog, 'user') as user, JSONExtractString(rawLog, 'srcIP') as srcIP, JSONExtractString(rawLog, 'user_agent') as user_agent, JSONExtractString(rawLog, 'severity') as severity, receivedAt FROM logs WHERE sourceType = 'structured-webhook' AND JSONExtractString(rawLog, 'eventName') = 'suspicious_login' AND JSONExtractString(rawLog, 'srcIP') = '192.168.1.100' AND receivedAt BETWEEN {from:DateTime} AND {to:DateTime}
- Schedule:
*/5 * * * *
(every 5 minutes) - Severity: Medium
- Categories:
["authentication", "test"]
- Save (Signal will be generated as a notification channel was not configured)
Step 4: Test Detection using CLI (optional)
Test your detection to verify it works:
-
Install and configure CLI:
-
Install RunReveal CLI:
brew install runreveal/tap/runreveal
-
Connect to your workspace:
runreveal init
Follow the prompts to authenticate and select your workspace
For complete CLI reference, see CLI Documentation.
-
-
For SQL detections (queries workspace data):
-
Create SQL detection configuration file:
Create file:
test-suspicious-login.yaml
name: test-suspicious-login displayName: Test Suspicious Login Detection description: Detects suspicious login attempts from specific IPs type: sql file: test-suspicious-login.sql categories: - authentication - test sourceTypes: - structured-webhook schedule: "*/5 * * * *" severity: medium riskScore: 50
-
Create SQL query file:
Create file:
test-suspicious-login.sql
SELECT JSONExtractString(rawLog, 'eventName') as eventName, JSONExtractString(rawLog, 'user') as user, JSONExtractString(rawLog, 'srcIP') as srcIP, JSONExtractString(rawLog, 'user_agent') as user_agent, JSONExtractString(rawLog, 'severity') as severity, receivedAt FROM logs WHERE sourceType = 'structured-webhook' AND JSONExtractString(rawLog, 'eventName') = 'suspicious_login' AND JSONExtractString(rawLog, 'srcIP') = '192.168.1.100' AND receivedAt >= now() - INTERVAL 2 HOUR LIMIT 10
-
Test the SQL detection:
# Test against actual data in your workspace runreveal detections test --file test-suspicious-login.yaml --from "now-1h" --to "now"
Note: SQL detections must query real workspace data. Make sure you’ve sent test events via webhook (Step 2) before running this command.
-
-
For Sigma detections (tests with local samples):
-
Create Sigma detection file:
Create file:
test-suspicious-login-sigma.yaml
title: Test Suspicious Login id: 12345678-1234-1234-1234-123456789abc status: test description: Detects suspicious login attempts author: security-team date: 2024/01/01 tags: - authentication - test logsource: product: custom service: webhook detection: selection: eventName: suspicious_login srcIP: 192.168.1.100 condition: selection level: medium riskscore: 50
-
Create sample data file:
Create file:
sample-events.ndjson
Important: NDJSON format requires one JSON object per line with NO commas between lines and NO array brackets.
{"eventName": "suspicious_login", "user": "test-user", "srcIP": "192.168.1.100", "severity": "high", "timestamp": "2024-01-01T12:00:00Z"} {"eventName": "suspicious_login", "user": "test-user-2", "srcIP": "192.168.1.100", "severity": "high", "timestamp": "2024-01-01T12:01:00Z"} {"eventName": "normal_login", "user": "admin", "srcIP": "10.0.0.1", "severity": "low", "timestamp": "2024-01-01T12:02:00Z"}
-
Test the Sigma detection:
# Test against local sample file runreveal detections run --file test-suspicious-login-sigma.yaml --input sample-events.ndjson
✓ Shows which events in the sample file would trigger the detection
-
Expected output for successful detection test:
line 1 matches detection Test Suspicious Login line 2 matches detection Test Suspicious Login line 3 does not match detection Test Suspicious Login
-
Understanding Detection Data Flow
- SQL Detections: Query the raw
logs
table directly, usingJSONExtractString(rawLog, 'field')
to extract values - Sigma Detections (CLI testing): Expect normalized/extracted fields as they would appear after processing
When creating sample data for Sigma CLI testing, provide the fields as if they’ve already been extracted from rawLog.
Step 5: Trigger and Review Detection
-
Manual Execution:
- Navigate to Detections
- Find your
test-suspicious-login
detection - Click Run Detection to execute it manually
- Wait a few seconds for execution to complete which will generate a signal
-
Check signals view:
SELECT detectionName, severity, recordsReturned, categories, receivedAt FROM signals WHERE detectionName = 'test-suspicious-login' ORDER BY receivedAt DESC LIMIT 5;
Step 6: Compare Signal vs Alert
Now convert your detection to an alert:
-
Add notification channel:
- First, add a Notification Channel (email, Slack, etc.) in RunReveal UI
-
Edit detection:
- Edit
test-suspicious-login
detection - Attach the notification channel to the detection
- Save changes
- Edit
-
Send another test event:
curl -X POST https://api.runreveal.com/sources/hook/30pw8Fynw5W7PzjbnRyxnfMsID2 \ -H "Content-Type: application/json" \ -d '{ "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'", "source": "test-system", "eventName": "suspicious_login", "severity": "high", "user": "test-user-2", "srcIP": "192.168.1.100", "action": "login_attempt", "result": "success" }'
-
Wait 5 minutes, then compare the signal results:
-- View signals for the detection SELECT detectionName, severity, recordsReturned, categories, receivedAt, results as raw_results FROM signals WHERE detectionName = 'test-suspicious-login' ORDER BY receivedAt DESC LIMIT 5;
-
To the alerts results:
-- View alerts for the detection SELECT detectionName, severity, recordsReturned, id, receivedAt, -- Extract user from results (simplified) results as raw_results FROM alerts WHERE detectionName = 'test-suspicious-login' ORDER BY receivedAt DESC LIMIT 5;
-
Compare in RunReveal UI:
- Navigate to the Alerts page in RunReveal UI
- Use the dropdown filter to switch between All, Alerts, and Signals
- Compare the results:
- Signals: Shows detection results without notifications
- Alerts: Shows detection results that triggered notifications
- All: Shows both signals and alerts together
Suggested Workflow
- Start with Signals → Validate detection logic without noise
- Tune the rule → Adjust query logic and thresholds
- Convert to Alert → Add notifications when ready for production
- Monitor performance → Track execution times and match rates
Next Steps
Now that you have detections, signals, and alerts set up, explore the detailed configuration guides:
- Detections - Create and manage security detection rules
- Sigma Streaming - Use Sigma rules for standardized threat detection
- Detection as Code - Manage detections through code and version control
- Sources - Set up data collection from your systems
- Pipelines - Configure data processing workflows
- Notifications Getting Started - Set up alerting and notification channels
- AI Chat - Use AI-powered analysis for threat hunting and investigation
- Enrichments - Add context and metadata to your security events