puck-scout: Instructions file for Claude Code

CLAUDE.md — Puck Scout

1. What Puck Is

Puck is an open-source autonomous endpoint investigation tool for security teams. It is an MCP (Model Context Protocol) server that enables Claude Code, Cursor, or any MCP client to perform autonomous, schema-free, read-only investigation of endpoint state during incident response and threat hunting. An IR engineer gets an alert, opens their MCP client, types a natural-language question ("investigate eng-laptop-47 and give me the blast radius"), and Puck autonomously runs read-only commands on the target endpoint, reasons about findings, pivots to related endpoints, and returns a narrative answer with containment recommendations.

Puck has three open-source components: (1) a Rust endpoint agent — a thin, memory-safe, read-only command executor that runs on customer endpoints; (2) a Go MCP server — the routing, orchestration, audit, and cost-control layer between MCP clients and endpoint agents; and (3) a skills library — investigation playbooks as YAML + markdown files that provide Claude with the reasoning context to execute investigations well. Key architectural properties: the agent is strictly read-only (cannot modify endpoint state), investigations are schema-free (commands are generated by AI reasoning at query time, not pre-indexed), the system is MCP-native (no proprietary UI/API), inference is BYO (users bring their own Claude/Bedrock/OpenAI keys), and fan-out to multiple endpoints happens in parallel.

2. Architectural Invariants

These are load-bearing constraints. If you are about to do something that violates any of these, stop immediately and flag the violation instead of proceeding.

1. Read-only agent: The endpoint agent MUST NOT call any file-write, process-termination, or system-modification syscall. This is the core trust story. No exceptions, no "admin mode," no flags that disable it.
2. No persistent state in the agent: The endpoint agent has no database, no cache, no local state beyond ephemeral command execution. It receives a command, executes it, returns the result, and forgets.
3. Bounded commands: Every command executed by the endpoint agent must have an explicit scope limit and a timeout. No unbounded recursion, no open-ended streaming, no commands that run indefinitely.
4. Audit-before-execute: The MCP server MUST log every command sent to every endpoint agent before execution. The audit log is the ground truth for what Puck did to a customer's fleet.
5. No inference keys in repo or logs: API keys for Claude/Bedrock/OpenAI are never committed to the repository and never written to audit logs or application logs. Ever.
6. Agent network isolation: The endpoint agent MUST NOT call any external network service other than the configured MCP server. No DNS lookups to third parties, no telemetry, no update checks.
7. Skills are YAML, not code: Investigation logic lives in skill YAML files, not in Go code in the MCP server. The MCP server loads and interprets skills at runtime. Skills are the source of truth for investigation behavior.
8. Untrusted driving LLM: The MCP client is untrusted. No safety property may depend on the LLM behaving well — it may be weak, hostile, or prompt-injected by content read off an investigated endpoint. Every boundary that prevents harm lives in Go/Rust code, gated by command grammar (policy/policy.toml) or operation type. Skill prose is advice; only the agent + MCP server are safety boundaries. The practical test: if a malicious LLM ignored a rule, could harm occur? If yes, the rule belongs in code, not in a skill.
9. Modular and expandable: Every component is designed for independent development, testing, and extension. Interfaces are explicit. Dependencies flow one direction. Adding a new command, skill, or integration should not require modifying unrelated code.