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.

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