Investigations

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.

Check out our blog: For a deeper look at how investigations fit into incident response and automated triage—including walkthroughs and real-world workflows—see our post Introducing RunReveal’s Autonomous Security Operations Agent.

Investigations List View

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?

  • Track incidents from initial alert through resolution
  • Document root cause analysis with timestamped notes
  • Link related detections and queries for evidence preservation

Common Use Cases

Incident Response
→Alert fires for suspicious login activity
→Create investigation, add alert as artifact
→Use AI Chat to analyze patterns, link the conversation
→Document findings, close with resolution
Threat Hunting
→Hypothesis: Lateral movement after compromised credential
→Create investigation to track hunting session
→Add queries as you pivot through data
→Document techniques and IOCs discovered
Compliance
→Auditor requests evidence of incident response
→Export investigation timeline
→All artifacts, timestamps, and actions documented
→Complete audit trail in one place

Setup Guide

Navigate to Investigations

Go to Investigations in the sidebar and click Open Investigation.

Configure Investigation Details

Provide the following:

  • Title: Descriptive name (required, 1-100 characters)
  • Description: Context for what you’re investigating
  • Severity: low, medium, high, or critical
  • Status: open (default), investigating, or closed
  • Tags: Custom labels for categorization and filtering

Start Investigating

Click Create Investigation. An initial status artifact is automatically added to the timeline. Begin adding artifacts as you work through the incident.

Investigation Properties

PropertyValuesDescription
Statusopen, agent-triage, investigating, closedCurrent investigation state (agent-triage used by AI auto-triage)
Severitylow, medium, high, criticalPriority level for triage
TagsCustom stringsFlexible labels for filtering
ResolutionFree textRequired when closing; documents outcome

Artifact Types

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

TypeDescriptionHow to Add
NoteText comments and observationsAdd Comment section on investigation page
QueryLinks to specific queries”Add to Investigation” from query results
Query ResultCaptured query results with field filtering”Add to Investigation” from query results
AlertSecurity alerts related to the investigation”Add to Investigation” from alert detail
ChatAI Chat conversations”Add to Investigation” from chat interface
Chat MessageSpecific messages from chat conversations”Add to Investigation” from chat interface
LinkExternal URLs and resourcesLinks sidebar on investigation page
GraphVisual graph representations”Add to Investigation” from graph view

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

Investigation Detail View

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 create and triage investigations when detection alerts fire, reducing manual work and accelerating incident response. You enable this per detection by turning on AI Triage and optionally choosing an Agent Configuration.

Automated Investigations

How Automated Investigations Work

When a detection alert fires and AI Triage is enabled for that detection:

  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 (inherited from detection)
    • Tags including auto-created, alert
    • Status set to open

  2. AI-Powered Auto-Triage: 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

AI triage in action

Setting Up Automated Investigations

Enable AI Triage on a Detection

  1. Go to Detections and open the detection you want to automate.
  2. Edit Detection or Edit Subscribe to open the subscription form.
  3. Find the AI Triage section, turn AI Triage on, and under Agent Configuration choose an agent (or leave Default Triage Agent for the built-in agent). This connects the detection to the agent channel.
  4. Save the detection (subscribe or update subscription).

When this detection fires an alert, RunReveal will create an investigation and run the selected agent to triage it.

Automated Investigation Flow

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

Detection configuration:

  • AI Triage: On
  • Agent Configuration: Default Triage Agent (or a custom agent)

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: from detection
    • Tags: auto-created, alert
    • Alert artifact: Links to the triggering alert

  3. AI agent triages:

    • Status changes to agent-triage
    • Agent analyzes the alert data
    • Queries additional context: e.g. “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”

Auto-Triage Behavior: When AI Triage is enabled, the AI agent focuses only on the specific alert that triggered the investigation. It does not search for or link additional alerts, keeping the investigation scope focused.

Example: Alert Investigation Agent (create with these settings)

An agent that triages detection alerts by parsing key fields, gathering log context, enriching indicators, and producing a risk assessment with recommended actions. Use it as the AI Triage agent on detections to automate investigation creation and initial analysis.

Expand: Agent configuration to create

Use the following when creating a new agent in Agents (e.g. for Agent Configuration in a detection’s AI Triage section).

SettingValue
NameAlert Investigation Agent
DescriptionAn agent that triages detection alerts by parsing key fields, gathering log context, enriching indicators, and producing a risk assessment with recommended actions. Use it as the AI Triage agent on detections to automate investigation creation and initial analysis.
AI Prompt1. Triage — Parse the alert for key fields (user, IP, action, timestamp, resource). Categorize the alert type and check for known false positive patterns.

2. Gather Context — Query logs to establish baseline behavior. What’s normal for this user/system? What happened immediately before and after the alert?

3. Enrich Indicators — For any IPs, domains, or hashes, check reputation and whether they appear elsewhere in your environment.

4. Assess Risk — Weigh asset criticality, user privilege level, action severity, timing, and whether this behavior has been seen before. Use your judgment.

5. Conclude — Classify as: true positive (critical/high/medium), benign but suspicious, false positive, or insufficient data.

6. Report — Provide a brief summary, timeline of events, key evidence, and recommended actions. Use mermaid diagrams to visualize attack flows or timelines when helpful.

Be direct. Lead with conclusions but don’t assume something is malicious unless it is for sure malicious. Quantify observations. If you can’t determine the answer, state exactly what additional data you need and provide next steps.

If the detection / finding is bad, make recommendations for how to tune the alert.
Tools NeededAdd Investigation Artifact, Get Table Schema, Investigation Get, List Tables, Logs Query V3, Source List
Cron schedule0 9 * * * (9am daily, or your desired timeframe)
Scheduled EnabledON
Skip PermissionsON

Quick steps to attach to a detection (so the agent runs when the detection fires):

  1. Create the agent in Agents using the table above, then save.
  2. Go to Detections and open the detection you want to triage automatically.
  3. Edit Detection or Edit Subscribe to enable AI Triage for the detection and connect it to the agent channel.
  4. In the AI Triage section, turn AI Triage on and under Agent Configuration select Alert Investigation Agent (or the name you gave the agent).
  5. Save the detection (subscribe or update subscription).

When this detection fires an alert, RunReveal creates an investigation and runs the selected agent to triage it.

Type of response and artifact

The agent adds a Note artifact to the investigation timeline with a structured triage analysis. The note typically includes:

  • Summary & conclusion — Classification (e.g. true positive, false positive, benign, or insufficient data) and a short narrative.
  • Alert details — Detection name, severity, actor, event time, source IP, and related context.
  • Baseline / context — What’s normal for the user or system and how this event compares.
  • Risk assessment — Factors (actor, timing, pattern, etc.) and overall risk level.
  • Recommendations — Suggested next steps and, when the alert is noisy, detection tuning ideas. The agent may include mermaid diagrams for timelines or flow.

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

Writing DetectionsNotifications