RunReveal Onboarding Guide

Create Your Account

Navigate to app.runreveal.com and create your account:

1. Click Sign Up and enter your email address
2. Check your email for the verification link
3. Complete account setup with your name and company information

Your workspace is automatically created with default settings:

• Workspace name: your-email's Workspace
• Admin role: Automatically assigned
• Default email notifications: Pre-configured

Verify Workspace Setup

Verify workspace configuration:

1. Go to Settings → Workspace Settings in your dashboard
2. Check workspace name and admin role
3. Note your workspace ID for CLI usage (Optional)

Expected workspace structure:

• Admin access enabled
• Default notification channel active
• API tokens available under Settings → API Tokens

Verify notification channels:

1. Go to Notification Channels in your dashboard
2. Confirm default email channel is active
3. Test notification delivery

Default email notifications include:

• Detection alerts
• System health notifications
• Source connection status

Generate API token for CLI access (Optional):

1. Go to Settings → API Tokens
2. Click “Create Token”
3. Name: “CLI Access”
4. Copy token for later use

Store your API token securely - you’ll need it for:

• RunReveal CLI operations
• CI/CD integrations
• API-based automation

Invite Team Members

Invite team members through the dashboard:

1. Navigate to Settings → Workspace Members
2. Click Invite User
3. Enter email address and select appropriate role
4. Click Send Invitation

Invited users receive an email with signup instructions. You’ll see their status update from “Pending” to “Active” once they accept.

Role Capabilities:

Choose Integration Type

RunReveal supports three primary ingestion methods:

• API Polling: Okta, GitHub, Office 365
• Object Storage: S3, R2, GCS, Azure Blob
• Webhooks: Vector, Fluent Bit, custom

Configure Okta Integration

Get Okta API Token:

1. Log into Okta Admin Console
2. Navigate to Security → API → Tokens
3. Click Create Token
4. Name: RunReveal Integration
5. Copy the token (starts with SSWS-)

Configure in RunReveal:

1. Go to Sources in your dashboard
2. Click Add Source → Okta
3. Enter configuration:
   • Domain: company.okta.com
   • API Token: Your SSWS token
   • Log Types: System logs, User events, Authentication events
4. Click Test Connection
5. Click Save

Expected result: Logs start flowing within 60-120 seconds.

Verify Data Flow:

-- Check for Okta logs
SELECT 
  eventName,
  COUNT(*) as event_count
FROM logs 
WHERE sourceType = 'okta'
  AND receivedAt > now() - INTERVAL 5 MINUTE
GROUP BY eventName
ORDER BY event_count DESC

Navigate to Sources → Okta → Recent Events to view live log data.

Configure AWS CloudTrail

Deploy CloudFormation Stack:

1. Use RunReveal’s pre-built template from the AWS Console
2. Stack name: RunRevealSetup
3. Parameters: Accept defaults
4. Capabilities: Acknowledge IAM resource creation
5. Wait for stack creation (2-3 minutes)

Add Source in RunReveal:

1. Go to Sources → Add Source → AWS CloudTrail
2. Enter configuration:
   • S3 Bucket: Your CloudTrail bucket name
   • Region: Your AWS region
   • Role ARN: (leave blank for CloudFormation setup)
3. Click Save

Verify CloudTrail logs:

-- Check for AWS CloudTrail events
SELECT 
  eventName,
  userIdentity.type,
  COUNT(*) as event_count
FROM logs 
WHERE sourceType = 'aws-cloudtrail'
  AND receivedAt > now() - INTERVAL 1 HOUR
GROUP BY eventName, userIdentity.type
ORDER BY event_count DESC
LIMIT 10

Configure Generic Webhook

Create Webhook Source:

1. Go to Sources → Add Source → Webhook
2. Configure webhook name and description
3. Copy your webhook URL

Test Webhook:

Send test event using curl:

curl -X POST \
  https://api.runreveal.com/sources/hook/YOUR_SOURCE_ID \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "'$(date -Iseconds)'",
    "level": "info",
    "message": "Test webhook log",
    "service": "test-app"
  }'

Verify in RunReveal:

-- Check for webhook logs
SELECT *
FROM logs
WHERE sourceType = 'generic-webhook'
  AND receivedAt > now() - INTERVAL 5 MINUTE
ORDER BY receivedAt DESC
LIMIT 10

Create Your First Detection

Navigate to Detections → Create Detection:

Example: Failed Login Attempts

name: Failed Login Attempts
description: Alert on multiple failed login attempts from same IP
severity: medium
schedule: "*/15 * * * *"  # Every 15 minutes

Query:

SELECT 
  actor.email as user,
  src.ip as source_ip,
  COUNT(*) as failed_attempts,
  MIN(receivedAt) as first_attempt,
  MAX(receivedAt) as last_attempt
FROM logs 
WHERE eventName = 'user.session.start'
  AND outcome.result = 'FAILURE'
  AND receivedAt BETWEEN {from:DateTime} AND {to:DateTime}
GROUP BY actor.email, src.ip
HAVING failed_attempts >= 5
ORDER BY failed_attempts DESC

Configure Notification Channels

Set Up Slack Integration:

1. Go to Notification Channels → Add Channel → Slack
2. Click Authorize Slack
3. Select your Slack workspace
4. Choose channel: #security-alerts
5. Test notification
6. Click Save

Configure Email Notifications:

Email channel is pre-configured by default. Customize recipients:

1. Go to Notification Channels → Email Channel
2. Add recipients
3. Configure email format
4. Click Save

Set Up PagerDuty Integration:

1. Create PagerDuty Integration in PagerDuty console
2. Copy Integration Key
3. Go to Notification Channels → Add Channel → PagerDuty in RunReveal
4. Paste Integration Key
5. Configure incident severity mapping
6. Test integration

Enable and Monitor Detections

After creating your detection:

1. Click Test Detection to verify query returns results
2. Review notification channel configuration
3. Click Save and Enable

Navigate to Detections dashboard to view:

• Active detections count
• Detection success rate
• Recent alerts generated
• Average execution time

Run SQL Queries

Navigate to Explorer or Search and try these queries:

Most Common Events (24 hours):

SELECT 
  eventName,
  sourceType,
  COUNT(*) as event_count,
  COUNT(DISTINCT src.ip) as unique_ips
FROM logs 
WHERE receivedAt > now() - INTERVAL 24 HOUR
GROUP BY eventName, sourceType
ORDER BY event_count DESC
LIMIT 20

Top Active Users:

SELECT 
  actor.email as user,
  COUNT(*) as total_events,
  COUNT(DISTINCT eventName) as unique_actions,
  MIN(receivedAt) as first_seen,
  MAX(receivedAt) as last_seen
FROM logs 
WHERE actor.email != ''
  AND receivedAt > now() - INTERVAL 7 DAY
GROUP BY actor.email
ORDER BY total_events DESC
LIMIT 50

Use AI Chat

Enable AI Chat:

1. Go to Settings → AI Settings
2. Configure AI provider (AWS Bedrock, OpenAI, or Azure OpenAI)
3. Enter your API credentials
4. Click Test Connection then Save

Try AI Chat:

Navigate to Chat and try prompts like:

• “What are the most common event types in the last 24 hours?”
• “Show me any failed login attempts from unusual locations”
• “Write a detection for AWS IAM policy changes”

Set Up Dashboards

Create Custom Dashboard:

1. Go to Dashboards → Create Dashboard
2. Dashboard name: Security Overview
3. Description: Real-time security metrics and alerts
4. Click Create

Add Dashboard Widgets:

Available widget types include Time Series Charts, Counter Widgets, and Table Widgets. Each widget is powered by SQL queries.

Share Dashboard:

1. Open your dashboard
2. Click Share button
3. Configure access settings
4. Copy share link
5. Distribute to team members

Install RunReveal CLI (Optional)

Install via Homebrew (macOS):

brew tap runreveal/runreveal
brew install runreveal

Install Binary (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/

Configure CLI:

# Authenticate with API token
runreveal config set api-token YOUR_API_TOKEN
 
# Set default workspace
runreveal config set workspace YOUR_WORKSPACE_ID
 
# Verify configuration
runreveal config list

Common CLI Commands:

# List all detections
runreveal detections list
 
# Create new detection
runreveal detections create --file detection.yaml
 
# Test detection locally
runreveal detections test --name "Failed Logins"
 
# Export detections to YAML
runreveal detections export --output ./detections/
 
# View recent logs
runreveal logs query "SELECT * FROM logs LIMIT 10"