RunReveal Onboarding Guide

Step 1: Create Your Account and Workspace

Sign up at app.runreveal.com, complete account setup, and verify your workspace appears in Settings → Workspace Settings. For now, defer team invitations and API tokens to Step 8.

See Managing Users and Role-Based Access Control for governance details.

Step 2: Connect Your First Source

Start with a source that gets you to value quickly (Okta, CloudTrail, GitHub, or Google Workspace).

1. Go to Sources → Add Source.
2. Pick your source and complete its wizard.
3. For API sources: set credentials, click Test Connection, then Save.

Use least-privilege credentials for all integrations. See Sources and Source Types.

Step 3: Validate Data Flow

Confirm data quality before creating detections:

1. In Sources, check source status.
2. Open Sources → [your source] → Health Checks and verify connectivity + recent receipt timestamps.
3. Run this query in Explore Logs:

SELECT
  sourceType,
  eventName,
  COUNT(*) AS event_count
FROM logs
WHERE sourceType = 'okta' -- adjust for your source
  AND receivedAt > now() - INTERVAL 10 MINUTE
GROUP BY sourceType, eventName
ORDER BY event_count DESC
LIMIT 20

If no rows appear after a few minutes, check Health Checks first.

Step 4: Create Your First Detection

Create a SQL detection on real source data (not synthetic webhook test data).

Example (Okta failed logins by source IP):

SELECT
  actor.email AS user,
  src.ip AS source_ip,
  COUNT(*) AS failed_count,
  MIN(receivedAt) AS first_attempt,
  MAX(receivedAt) AS last_attempt
FROM logs
WHERE sourceType = 'okta'
  AND eventName = 'user.session.start'
  AND eventOutcome = 'FAILURE'
  AND receivedAt BETWEEN {from:DateTime} AND {to:DateTime}
GROUP BY actor.email, src.ip
HAVING COUNT(*) >= 1

Suggested config:

• Name: okta-failed-logins-by-ip
• Schedule: */5 * * * *
• Severity: Medium
• Categories: authentication, brute-force
• Notification Channels: leave empty initially (signals only)

SELECT detectionName, severity, recordsReturned, createdAt
FROM signals
WHERE detectionName = 'okta-failed-logins-by-ip'
ORDER BY createdAt DESC
LIMIT 5

See Writing Detections, Detections Quick Start, and Sigma Streaming.

Step 5: Optional — Trigger a Detection with a Webhook Generic Logs Source

Use this step when you want to force a known-positive match quickly (for demos, validation, or low-volume environments).

1. Go to Sources → Add Source → Webhook Generic Logs and create a source.
2. Copy the webhook URL (and bearer token if enabled).
3. Create a test SQL detection named webhook-suspicious-login-test:

SELECT
  JSONExtractString(rawLog, 'eventName') AS eventName,
  JSONExtractString(rawLog, 'user') AS user,
  JSONExtractString(rawLog, 'srcIP') AS srcIP,
  receivedAt
FROM logs
WHERE sourceType = 'webhook'
  AND JSONExtractString(rawLog, 'eventName') = 'suspicious_login'
  AND receivedAt BETWEEN {from:DateTime} AND {to:DateTime}

4. Send a test event to the webhook:

curl -X POST \
  YOUR_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -d '{
    "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'",
    "eventName": "suspicious_login",
    "user": "test-user",
    "srcIP": "192.168.1.100",
    "severity": "high"
  }'

5. Verify the detection fired:

SELECT detectionName, recordsReturned, createdAt
FROM signals
WHERE detectionName = 'webhook-suspicious-login-test'
ORDER BY createdAt DESC
LIMIT 5

Step 6: Investigate with AI Chat

Now that you have detections configured, use AI Chat to explore data and detection outcomes faster.

1. Configure a model provider in Workspace Settings → AI Model Providers.
2. Open Chat and ask:
   • “What are the most common event types in the last 24 hours?”
   • “Show failed logins from unusual locations.”
   • “Which sources are sending the most volume?”
3. Reuse generated SQL to improve detections and dashboards.

See Native AI Chat and Model Context Protocol.

Step 7: Configure Notifications and Promote Signals to Alerts

Once your detection works, attach channels so matching results become alerts:

1. Go to Notification Channels → Add Channel.
2. Configure Slack, Email, PagerDuty, Jira, Linear, or Webhooks.
3. Edit your detection and attach one or more channels.
4. Save and wait for next run (or trigger manually).

See Notifications Getting Started, Slack, and Templates.

Step 8: Invite Team and Configure Access

Now that you have working ingest + detections, add collaborators:

1. Go to Settings → Workspace Members → Invite User.
2. Assign the right role:
   • Admin: workspace/platform owners
   • Analyst: detection authors and SOC analysts
   • Operator: read-only investigators/reporting
   • CIBot: automation/service account workflows
3. Optional: configure SSO and API tokens.

See Managing Users, RBAC, and Single Sign-on.

Step 9: Connect More Sources and Tune Log Processing

Expand coverage (identity, cloud infra, endpoint, and network), then tune ingestion:

• Pipelines with topic routing
• Transforms to normalize data
• Filtering for reusable noise controls
• Enrichments to add context
• Sampling for high-volume optimization
• Drop for permanent discard of zero-value events
• Destinations to stream data to external storage
• Custom Views for frequently used investigative slices

Step 10: Set Up Investigations and Optional Automated Triage

Use Investigations for structured incident response:

1. Create an investigation manually in Investigations.
2. Add artifacts: query links, alerts, AI chat findings, and notes.
3. Optional: enable AI triage in detections and assign an agent.

See Investigations and Agents.

Step 11: Build Dashboards and Scheduled Agents

Create persistent visibility and recurring analysis:

1. Build a dashboard in Dashboards → Create Dashboard.
2. Add SQL-backed widgets (time series, counters, tables).
3. Configure scheduled agents for daily/weekly summaries and hunting prompts.

See Dashboards, Agents, and Prompts.

Step 12: Adopt Detection-as-Code (Recommended)

Move detections into version control for safer deployment workflows.

# macOS
brew tap runreveal/runreveal
brew install runreveal
 
# Linux
curl -L https://github.com/runreveal/runreveal/releases/latest/download/runreveal-linux-amd64 -o runreveal
chmod +x runreveal && sudo mv runreveal /usr/local/bin/

runreveal init
runreveal config account
runreveal detections export -d ./detections/
runreveal detections test --file ./detections/sql/okta-failed-logins-by-ip.yaml --from "now-24h" --to "now"
runreveal detections sync -d ./detections --dry-run
runreveal detections sync -d ./detections

See Detection as Code, Getting Started, and Deployment.

Step 13: Integrate External Tools (Optional)

Connect RunReveal to your broader tooling: