Investigations

Investigations provide a centralized workspace for tracking security incidents within RunReveal. Each investigation collects related artifacts—queries, alerts, chat conversations, notes, and indicators—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 11 artifact types that can be added to the timeline:

---

Notes

Notes are timeline artifacts with type note. The text you enter is stored in the artifact comment field and rendered on the timeline with Markdown support (headings, lists, code blocks, and links).

How notes work

• Use Add Note on the investigation detail page to post analysis, hypotheses, or handoff context.
• Notes are user-deletable (unlike system-generated investigation updates and resolutions).
• Notes do not carry structured metadata—everything lives in the comment text.

How notes and context reach the AI agent

Investigation notes are not pasted into the agent’s system prompt automatically. Agents read them the same way analysts do: by loading the full investigation when they need it.

Auto-triage (AI Triage on a detection)

When an alert opens an investigation, the triage agent starts with a fixed workflow prompt (alert ID, detection name, investigation ID). It is instructed to call InvestigationGet early in the run. That response includes:

• Investigation fields such as title, description, summary, status, severity, and classification
• The full timeline of artifacts in chronological order, including every note (comment text), linked alerts, queries, and system updates

So context you add in a timeline note or the investigation Description is available to the agent after it calls InvestigationGet. It is not guaranteed to be considered on the very first model turn before that tool runs.

Detection notes are separate from investigation notes. They are author guidance on the detection (for example, “check CloudTrail for AssumeRole from this principal”) and are injected into the triage agent’s initial prompt when AI Triage runs. They do not appear as timeline notes. See Detection as Code (notes field) or the detection editor in the app.

Manual AI chat from an investigation

Actions such as Query Related or Auto-tune Detection open AI Chat with a seeded prompt that references the investigation ID. The chat does not embed your note text in that first message. The agent is expected to use investigation tools (especially InvestigationGet) to read notes, description, and artifacts before acting.

Practical tips

• Add Description or notes with playbook context before triage finishes (or before you retry a failed triage) if you want the agent to weigh that context during its first pass.
• Notes added after triage has completed are visible to later agent runs (retry triage, a new chat, or a custom agent with InvestigationGet) but do not change an investigation that was already classified and closed.
• For facts you want future investigations to find automatically, use indicators (structured IOCs), not note prose alone—IOC lookup does not search note text.

Notes vs indicators

When AI triage runs, it typically documents IOC correlation findings in a note (for example, prior investigations that used the same IP) and adds indicators separately when the alert is classified as a true positive, so those values can be found automatically in future cases.

---

Indicators and IOC correlation

Indicators let you record pivotable entities (IPs, users, domains, hashes, files, processes, URLs, and other free-form types) as structured data. Other investigations—and the AI triage agent—can then search for matching indicator values across your workspace.

Adding and managing indicators

On the investigation detail page, open the Indicators section in the sidebar:

1. Click + to add an indicator.
2. Enter a type (for example, ip, user, domain, hash) and value.
3. Edit or remove indicators from the same section.

Indicators appear in the sidebar for quick reference; they are not duplicated in the main artifact timeline (timeline filtering excludes indicators artifacts from the default stream).

Multiple indicators can be stored in a single indicators artifact. Editing one indicator in a shared artifact updates that artifact’s indicator list.

How correlation works

Cross-investigation correlation is powered by the IOC lookup API (GET /investigations/ioc/lookup), which searches all indicators artifacts in the workspace:

• Match by IOC type (exact, for example ip)
• Match by IOC value (partial, case-insensitive)
• Optionally filter by parent investigation classification (true_positive, false_positive, inconclusive)

Each result includes the investigation title, status, severity, classification, and when the indicator was recorded—so you can see whether the same entity appeared in earlier true positives or false positives.

Automated triage and correlation

When AI Triage is enabled on a detection, the triage agent generally:

1. Analyzes the triggering alert and queries logs for context.
2. Calls InvestigationIocLookup for suspicious entities (IP, user, domain, hash, and so on) to find prior investigations that tracked the same values.
3. Adds a note summarizing the analysis, including any relevant prior-investigation context from step 2.
4. For true positive classifications only, adds indicators for pivotable IOCs an analyst would search on later (not routine contextual fields such as generic internal IPs unless they matter to the alert).

---

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, classification, duration, metadata
• Description: Editable investigation context
• Add Note: Post Markdown-formatted notes to the timeline
• Indicators: Add, edit, and remove structured IOCs in the sidebar for cross-investigation correlation
• Artifact Timeline: Chronological view of all linked items
• Details Sidebar: Status, severity, classification, assignee, and tag management
• Links Sidebar: Quick links to external resources

Filtering and Starring

• Filter by type: Show only specific artifact types (alerts, queries, notes). Indicators are managed in the sidebar, not the main timeline filter list.
• 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

Classification

Investigations can be classified to record whether the triggering alert was a genuine threat or not. Classification can be set at any time from the investigation sidebar, or when closing an investigation via the resolution modal.

Classification is available as a filter on the investigations list page, making it easy to track detection accuracy over time and identify detections that need tuning.

Time to Respond (MTTR)

Time to Respond (MTTR) and the value delivered by the AI triage agent - broken down by detection, response, investigation, and resolution stages.

This gives you a real-time view of how fast threats are being triaged and resolved, and quantifies the time savings the agent is delivering for your team.

Closing Investigations

When changing status to closed:

1. A resolution modal appears
2. Select a classification (true positive, false positive, or inconclusive)
3. Optionally enter resolution details
4. Click Close Investigation

The classification and resolution are saved on the investigation, and 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.

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
   • Loads the investigation via InvestigationGet (alert, description, and any existing timeline notes)
   • 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 a classification and resolution notes

Setting Up Automated Investigations

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"
   • Checks IOC correlation: searches workspace indicators for entities from the alert (for example, whether 203.0.113.45 appeared in prior investigations)
   • Adds note: documents analysis and any prior-investigation context from IOC lookup
   • Adds indicators (true positives only): structured IOCs such as the source IP for future correlation
   • 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
   • Classifies as true positive and closes with resolution: "IP blocked, password reset, account secured"

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).

Setting	Value
Name	Alert Investigation Agent
Description	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.
AI Prompt	1. 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 Needed	Add Investigation Artifact, Get Table Schema, Investigation Get, List Tables, Logs Query V3, Source List
Cron schedule	0 9 * * * (9am daily, or your desired timeframe)
Scheduled Enabled	ON
Skip Permissions	ON

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.
• IOC correlation — Prior investigations that tracked the same indicators, when found via IOC lookup.
• 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.

For true positive alerts, the agent may also add Indicators artifacts so key entities are searchable in future investigations.

---

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
• Classify on close: Always set a classification when closing to track detection accuracy
• Document resolution: Provide resolution details when closing for future reference

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; mention prior cases in prose when helpful
• Add indicators for pivotable IOCs: Use the sidebar so entities are findable via IOC lookup in future investigations—not only described in note text

---

Related Documentation

• Agents — Create and schedule AI agents, including for automated investigation triage
• 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
• Introducing RunReveal's Autonomous Security Operations Agent (blog) — AI agent for security operations, auto-triage, and incident response