Skip to content
Puck Docs

Investigations

An investigation is a question you ask Puck — natural language in, structured findings and a narrative report out.

Why it exists

Security telemetry shows you what was logged. An investigation is how you go look for something that wasn’t — a credential in the wrong place, an AI tool running where it shouldn’t be, a persistence mechanism that predates your EDR deployment.

Passive collectors wait for events to arrive. Puck’s agents actively explore: they follow threads, read files, inspect processes, and chain results into follow-up checks. An investigation coordinates that active exploration across your whole fleet and hands you a report with reasoning chains you can follow, not just a raw data dump.

Without investigations, you’d have a fleet of agents with nowhere to direct their curiosity. An investigation is the question that focuses them.

How it works

When you submit a query, the investigation moves through a fixed set of states:

pending → queued → exploring → compiling → executing → analyzing → complete
                                                                  ↘ failed
                                                                  ↘ cancelled

Each state transition produces an artifact you can inspect in the console’s activity feed.

pending / queued — the investigation is created and waiting for the pipeline to pick it up. Your query is preprocessed by a fast-tier LLM (Haiku) to extract a focused brief and any indicators of compromise.

exploring — a pathfinder agent (one per OS) runs a multi-turn conversation with the brain, exploring your question on a single live endpoint. This produces a pathfinder transcript: a record of what the agent found and what it decided to check next.

compiling — the brain assesses whether the pathfinder’s findings warrant checking the rest of the fleet (see blast radius). If yes, it compiles a deterministic signed plan from the pathfinder transcript.

executing — the signed plan is distributed to all connected agents of the target OS. Agents pick it up on their next poll (typically within 2–5 seconds), validate every command against the whitelist, and execute.

analyzing — results are streaming in. The brain presorts them by anomaly score, runs tiered LLM analysis (Haiku for clean and minor results, Sonnet for notable ones), and writes findings to the store with severity bias from any applicable tag policies.

complete — the narrative generator writes a markdown investigation story. The report compiler builds the structured report. A webhook fires with the investigation’s severity.

You can also control three parameters at query time:

  • Mode: auto (use cached pathfinder results if recent), cached (always use cache), or live (always run a fresh pathfinder).
  • Depth: quick, standard, or deep — controls pathfinder iteration budget and plan complexity.
  • Scope: specific agent IDs, a tag-based selector, or all connected agents.

When you’d touch it

There are three natural patterns for investigations:

Incident triage — something happened and you need to know the blast radius. Submit a query like “find evidence of lateral movement from host X” or “look for the credential this alert flagged.” The investigation runs fleet-wide and gives you a narrative of what was found where.

Ambient curiosity — scheduled background investigations that run without you asking. A weekly shadow-IT sweep, a daily prod-credential check. These live in the curiosity queue.

Calibrated detection — after an investigation finds a pattern, you can compile it into a recurring deterministic check that runs without LLM overhead. These are managed in the Calibrated Detection section of the console. (The wire event for promotion is check.graduated for backward-compatibility — see webhooks.)

Most of the time you’re either submitting a query or reading results. The only operational decisions are which mode and depth to use — and those are easy to leave at defaults until you have a reason to change them.