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
- Click Create or Save
- Copy the webhook URL - it will look like: https://api.runreveal.com/sources/hook/YOUR_WEBHOOK_ID
- You’ll also need to copy the bearer token and pass it in the Authorization header with your webhook’s request. Alternatively, after saving the webhook source, you can edit it and remove the bearer token to allow unauthenticated requests for this webhook.

Step 1: Create Webhook Source

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/31I8bKFd9hxbr3eXJlLiEAFOEKr \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 31I8bOdsVNEBTkZgSJ5E7zvhCXF" \
  -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 2: Send Test Data

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 3: Create a Test Detection Rule

Step 4: Validate and Test Detection using CLI (optional)

Validate Detection Syntax with Lint

Before testing your detection, validate the syntax and format using the lint command. This catches common errors early and ensures your detection will work properly.

For SQL detections:

# Lint your SQL detection file
runreveal lint sql test-suspicious-login.sql

For Sigma detections:

# Lint your Sigma detection file
runreveal lint sigma test-suspicious-login-sigma.yaml

Expected output for successful validation:

$ runreveal lint sql test-suspicious-login.sql
✅ SQL file passed validation
 
$ runreveal lint sigma test-suspicious-login-sigma.yaml
✅ Sigma file passed validation

If validation fails, fix the errors before proceeding:

$ runreveal lint sigma invalid-rule.yaml
❌ Validation failed for invalid-rule.yaml:
   - Missing required field: 'title'
   - Invalid YAML syntax at line 5

Lint Benefits:

Catches syntax errors before testing
Validates required fields and structure
Ensures compliance with Sigma/SQL standards
Saves time by catching issues early in the development process

Test your detection to verify it works:

Install and configure CLI:
1. Install RunReveal CLI:
```
brew install runreveal/tap/runreveal
```
2. 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, using JSONExtractString(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 5: Trigger and Review Detection

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

Send another test event:

curl -X POST https://api.runreveal.com/sources/hook/31I8bKFd9hxbr3eXJlLiEAFOEKr \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 31I8bOdsVNEBTkZgSJ5E7zvhCXF" \
  -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;

SQL Signal Query

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;

SQL Alert Query

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

Collect Nginx Logs Kubernetes Logs