Investigations

Investigations provide a centralized workspace for tracking security incidents within RunReveal. Each investigation collects related artifacts—queries, alerts, chat conversations, and notes—into a single timeline, enabling teams to collaborate on complex incidents and maintain a comprehensive audit trail.

Why Investigations?

• Centralized evidence: Link queries, alerts, AI chat sessions, and notes to a single investigation timeline
• Audit trail: Every status change and artifact addition is automatically tracked with timestamps and user attribution
• Collaborative workflow: Share investigation links with team members; everyone sees the same context
• Persistent context: Investigations persist across sessions, enabling multi-day incident response

What Can You Do with Investigations?

Common Use Cases

Setup Guide

Investigation Properties

Artifact Types

Investigations support 10 artifact types that can be added to the timeline:

Working with Investigations

Adding Artifacts

Most RunReveal interfaces include an Add to Investigation action:

1. From query results, alert details, chat sessions, or graphs, click Add to Investigation
2. Select an existing investigation or create a new one
3. Add an optional comment explaining relevance
4. Click Add

Managing the Timeline

The investigation detail page provides:

• Header: Title, status, severity, duration, metadata
• Description: Editable investigation context
• Comment Section: Add notes directly to the timeline
• Artifact Timeline: Chronological view of all linked items
• Details Sidebar: Status/severity controls, tag management
• Links Sidebar: Quick links to external resources

Filtering and Starring

• Filter by type: Show only specific artifact types (alerts, queries, notes)
• Filter by starred: Surface important findings quickly
• Text search: Search across artifact comments and content
• Star artifacts: Hover over any artifact and click the star icon to highlight key findings

Closing Investigations

When changing status to closed:

1. A resolution modal appears
2. Enter resolution details (recommended)
3. Click Close Investigation

A resolution artifact is automatically added to the timeline.

Automated Investigations

Automated investigations automatically create and triage investigations when detection alerts fire, reducing manual work and accelerating incident response.

How Automated Investigations Work

When a detection alert fires and has an investigation automation configured:

1. Investigation Creation: RunReveal automatically creates a new investigation with:

   • Title based on the detection name (with unique identifier)
   • Alert artifact linking to the triggering alert
   • Default severity (from automation settings or inherited from detection)
   • Tags including auto-created, alert, and any custom tags
   • Status set to open

2. AI-Powered Auto-Triage (optional): If enabled, an AI agent analyzes the alert:

   • Updates status to agent-triage while analyzing
   • Reviews the alert data and queries additional context if needed
   • Adds analysis notes to the investigation timeline
   • Updates severity if the initial assessment was incorrect
   • Makes a decision:
     • Genuine threat: Updates status to investigating for human review
     • False positive: Automatically closes the investigation with resolution notes

Setting Up Automated Investigations

Example: Automated Investigation Flow

Scenario: A detection for “Multiple Failed Login Attempts” fires an alert.

Automation Configuration:

• Name: “Authentication Anomalies”
• Default severity: high
• Tags: authentication, brute-force
• Auto-triage: Enabled

What Happens:

1. Alert fires → Detection triggers for user [email protected] with 15 failed logins from IP 203.0.113.45

2. Investigation created:

   • Title: “Multiple Failed Login Attempts (a1b2c3d4)”
   • Status: open
   • Severity: high
   • Tags: authentication, brute-force, auto-created, alert
   • Alert artifact: Links to the triggering alert

3. AI agent triages (auto-triage enabled):

   • Status changes to agent-triage
   • Agent analyzes the alert data
   • Queries additional context: “Show all login attempts for [email protected] in last 24 hours”
   • Adds note: “Analysis: 15 failed attempts from IP 203.0.113.45 (previously unknown). No successful logins. Pattern suggests brute-force attack. Recommend blocking IP and reviewing account security.”
   • Updates status to investigating (requires human review)

4. Analyst reviews:

   • Opens investigation, sees AI analysis
   • Reviews query results added by agent
   • Takes action: Blocks IP, resets password
   • Closes investigation with resolution: “IP blocked, password reset, account secured”

CLI Reference

# List all investigations
runreveal investigations list
 
# Create investigation
runreveal investigations create \
  --title "Suspicious Login Activity" \
  --description "Multiple failed login attempts from unusual IP ranges" \
  --severity high \
  --status open \
  --tags "authentication,brute-force"
 
# Get investigation details
runreveal investigations get --id <investigation-id>
 
# Update investigation field
runreveal investigations update \
  --id <investigation-id> \
  --field status \
  --value investigating
 
# Delete investigation
runreveal investigations delete --id <investigation-id>

Best Practices

Investigation Organization

• Descriptive titles: Use specific names like “2024-01-15 Brute Force from IP Range 192.168.x.x” rather than “Login Issue”
• Tag consistently: Establish team conventions for tags (e.g., authentication, malware, insider-threat)
• Update status promptly: Move from open → investigating → closed as work progresses
• Document resolution: Always provide resolution details when closing

Artifact Management

• Add context: Include comments when adding artifacts explaining why they’re relevant
• Star key findings: Use starring to highlight critical evidence
• Link comprehensively: Add all related queries, alerts, and chats to build complete context
• Use notes for analysis: Document your reasoning and hypotheses as you investigate

Related Documentation

• Detections — Create detection rules that can trigger investigations
• Native AI Chat — Use AI to analyze data and add insights to investigations
• Explore Logs — Run queries and add results to investigations
• Notifications — Configure alerts that link to investigations