An MCP server your AI uses to investigate. Real credentials. Read-only by design. No signup.
Like osquery — but driven by your AI, and validates what those credentials actually reach.
Day one
Install Puck on a laptop, point your AI at the MCP, ask it to look around. You usually come back with something — a plaintext AWS access key in a shell init file, an OAuth token cached in a .config directory, a long-forgotten id_rsa with no passphrase, a docker daemon listening on every interface. Not because the host is special. Because nobody's looked closely.
# Top hits from first-run sweeps → AWS access keys in ~/.aws/credentials, shell history, and dotfiles → GitHub PATs with org-admin scope in ~/.config/gh/hosts.yml → Cached OAuth tokens for Google, Slack, Notion, Linear → SSH keys without passphrases — and what they reach → Long-lived service-account JSON files, sometimes in ~/Downloads/ → Docker daemons bound to 0.0.0.0 → Plaintext credentials in build scripts and CI cache directories
No agent has to be told what to look for. Your AI walks the host with Puck as its read-only hands.
Install
Two binaries built from source: puck-mcp (Go) and puck-agent (Rust). No daemon, no agent-side state, no kernel driver. Docker quickstart is on the roadmap — until then, build takes about two minutes. For fleet-scale, continuous coverage, and Calibrated Detection that compounds, see Enterprise.
# Clone, then let your coding agent read README + docs/getting-started.md. $ git clone https://github.com/puck-security/puck-oss.git && cd puck-oss $ claude "build puck-mcp + puck-agent, bootstrap the MCP server, enroll this host as an agent, wire the server into my MCP client, run a smoke query"
Your agent reads README.md + docs/getting-started.md, builds both binaries, runs setup-mcp.sh, generates a bootstrap token, runs install-agent.sh, and wires the MCP server into your client config. Drops you back at a prompt with a working install. Step-by-step below if you'd rather drive it yourself.
Or, step-by-step
# MCP server (Go) + endpoint agent (Rust) $ git clone https://github.com/puck-security/puck-oss.git && cd puck-oss $ (cd mcp && go build -o puck-mcp ./cmd/puck-mcp && sudo install -m 0755 puck-mcp /usr/local/bin/) $ (cd agent && cargo build --release && sudo install -m 0755 target/release/puck-agent /usr/local/bin/)
# Generates the embedded CA, server cert, and mcp_token $ ./scripts/setup-mcp.sh --hostname puck-mcp.internal # Per endpoint: issue a single-use, host-bound bootstrap token $ puck-mcp generate-bootstrap-token --hostname eng-laptop-47 --ttl 1h
# On the endpoint — mTLS pinned to your MCP server $ echo "puck-bt-…" > /tmp/bt && \ ./scripts/install-agent.sh --server https://puck-mcp.internal:50281 \ --hostname eng-laptop-47 \ --token-file /tmp/bt && rm /tmp/bt
# Claude Code / Cursor: add the server to your MCP config, then ask away. $ claude "What does eng-laptop-47 actually reach? Look at credentials on disk first."
Architecture
Three components. Your AI lives in any MCP client (Claude Code, Cursor, etc.). The MCP server orchestrates and gates. Endpoint agents validate and execute. The typed allowlist is compiled into both server and agent.
Server-side multi-turn reasoning, cross-fleet hivemind propagation, Ed25519-signed plan distribution, blast-radius graph, and a web console live in Enterprise. OSS is one AI client, one MCP server, read-only across your hosts.
How it works
Five investigation stages, all driven by your AI through MCP tools. No web console, no daemon — your client picks the skill, calls the tools, and reads the structured results back.
puck_list_skills returns the available playbooks (credential exposure, AWS blast radius, CVE exposure, IR triage, shadow AI, schema). Your AI picks one or composes its own approach.puck_investigate starts on one host first to learn the environment. The skill defines the objective, the pathfinder strategy, and the iteration criteria — your AI calls puck_run_check for individual commands based on what it sees.puck_query_fleet fans the same checks across matching hosts in parallel. Every command validated twice — server first, then agent — against the typed allowlist.puck_get_skill_section for follow-up strategy, pivots to affected hosts, and runs targeted checks. puck_continue extends the command budget when a thread is worth pulling.puck_save_analysis writes a markdown report — findings, evidence, containment recommendations — to investigations/. Optional outbound integrations post the case to TheHive or Tines.Use it for
Every query below is a real investigation Puck can run against your fleet today. Click through for the full write-up with methodology, what Puck checks, and what the results look like.
Surfaces credentials on disk, validates which still authenticate, and traces what each one reaches — AWS SSO sessions, Vault tokens, kubectl contexts, SSH keys to prod hosts. Read-only, audited per command. Often turns a one-host alert into a fleet question.
Read the write-up →Puck identifies every endpoint with AWS admin credentials, maps what each can reach — S3 buckets, RDS instances, Lambda functions, IAM role chains — and ranks by blast radius. 12 endpoints with paths to production data.
14 credentials still present. 4 AWS keys never rotated. 1 GitHub PAT still grants admin:org. SSH key to prod-db still authenticates.
Puck maps every user's endpoint credentials and traces what they reach. jsmith: 4 AWS accounts, kubectl admin on prod, SSH to 11 hosts, GitHub org admin. mchen: Stripe live keys + prod DB conn string on a laptop with no disk encryption.
7 endpoints with keys for 3 unknown AWS accounts. 2 are contractor personal accounts with S3 write access. 1 is a former employer's account still in ~/.aws/credentials. Potential data exfiltration paths.
3 archives flagged. 2.4 GB pg_dump in ~/backup with rclone configured to personal Google Drive. 340 MB CSV export with PII columns. Finance laptop with M&A docs on USB.
47 installs, 3 modified binaries beaconing. Chain: CI runner → artifact-writer role → prod deploy. 23 static-linked customs invisible to package scans.
147 of 2,847 hosts returned HTTP 200 from ot-int.factory.timecard.co. 23 hosts can SSH into the PCI environment. 4 with working keys. Segmentation has holes.
Local Ollama instances (which are network-exposed), MCP servers wired to databases, custom scripts calling LLM APIs, repos with committed API keys, LLM tools running on Finance laptops. Ships as a skill — see skills/shadow-ai.
67 endpoints with AWS keys, 43 with DB conn strings, 12 with Stripe live keys, 234 SSH keys without passphrases. 44 of 67 AWS keys are still live.
89 endpoints. 14 outside Engineering. One on a USB drive owned by a marketing contractor, with production Stripe keys in .env.production.
7 cron jobs, 3 launch agents, 2 systemd services with outbound connections. 1 matched a known C2 pattern. 4 others connecting to IPs not in any internal DNS.
vs the tools you know
Fleet-query tools — osquery, Velociraptor, GRR — give you the power to ask anything. They also assume you know the right question, the right query, and which result is worth chasing.
Puck moves the expert work to your AI: ask in plain language, watch it explore, follow the thread across hosts, and surface what each finding actually reaches. No packs. No detection engineering. No expert-on-call required.
And vs the other categories
MCP-native
When Claude, Cursor, or any MCP client needs to know what's actually true on an endpoint — process tree, credentials, blast radius — Puck is the MCP that retrieves ground truth. Read-only. Schema-free. Real-time.
puck.investigate
Plug Puck into your existing AI agent surfaces. Your AI calls puck_investigate, Puck investigates the fleet, the structured result flows back through MCP. No new dashboards, no new query language.
puck_investigate, puck_list_skills, puck_get_skill_section, puck_run_check, puck_query_fleet, puck_save_analysis, puck_continue.puck_save_analysis writes the report. Outbound case-creation playbooks ship for TheHive and Tines.The trust boundary
Your AI generates commands. Puck validates each one twice — at the MCP server before dispatch, and again at the agent before execution — against the same typed allowlist compiled into both binaries. Anything not in the grammar is rejected and logged. See security.md and ADR-022.
policy/policy.toml baked into both binaries. A per-host overrides file can disable compiled-in entries; it cannot author new grammar.bash -c are not in the grammar.OSS is on-demand by design — your AI drives one investigation at a time. Enterprise adds always-on coverage with a server-side reasoning loop, hivemind propagation across teams, Ed25519-signed plan distribution, Calibrated Detection compiled to your environment, a web console, SSO, and managed inference. Single-tenant in your AWS account, SOC2-ready by design.