How To GuidesQuick Start: Detections, Signals, and Alerts

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.

DetectionsSignalsAlerts
What it isAutomated rules that analyze logsDetection results without notificationsDetection results with notifications
PurposeContinuous monitoring and analysisPattern recognition and tuningImmediate awareness and response
Filteringdetections tablesignals tablealerts table
NotificationsNoneNoneEmail, Slack, PagerDuty, etc.
Use CaseSecurity policy enforcementThreat hunting and analysisIncident response workflows

Getting Started

This guide walks you through the complete workflow for setting up detections, signals, and alerts in RunReveal:

  1. Create Webhook Source - Set up a data source to receive test events (Either a Structured Webhook or Generic Webhook Source in UI)
  2. Send Test Data - Generate sample security events for testing
  3. Create Detection Rule - Build a SQL-based detection that analyzes your data
  4. Trigger and Review - Manually run the detection and check results
  5. 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:

  1. 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

Step 1: Create Webhook Source

Step 2: Send Test Data

Now send a test security event using your webhook URL:

  1. 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"
        }
      }'
  2. 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:

  1. 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: Test Detection using CLI (optional)

Test your detection to verify it works:

  1. 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.

  2. For SQL detections (queries workspace data):

    1. 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
    2. 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
    3. 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.

  3. For Sigma detections (tests with local samples):

    1. 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
    2. 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"}
    3. 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

    4. 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

  1. 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
  2. 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:

  1. Add notification channel:

  2. Edit detection:

    • Edit test-suspicious-login detection
    • Attach the notification channel to the detection
    • Save changes
  3. 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"
      }'
  4. 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

  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;

    SQL Alert Query

  6. 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

    Step 6: Compare Signal vs Alert UI


Suggested Workflow

  1. Start with Signals → Validate detection logic without noise
  2. Tune the rule → Adjust query logic and thresholds
  3. Convert to Alert → Add notifications when ready for production
  4. 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: