A security layer for AI coding agents like Claude Code and Cursor, enforcing YAML policy rules and local SQLite audit trails for authorized developers and security teams.
| Tool | safedep/gryph — a local security and audit layer that hooks into AI coding agents |
| Category | Agent security / host audit tooling (Go, Apache-2.0) |
| Primary Use | Enforcing block/warn/guide policies on agent tool calls and replaying every file_read, file_write, and exec action via gryph logs and gryph query |
| Safe Use | Defensive tooling for authorized professionals: securing your own development machines, reviewing agent behavior in CI, and exporting audit events to a SIEM during authorized security assessments |
| Telemetry Note | Purely defensive and local: events land in an on-device SQLite database with no cloud or telemetry; sensitive file contents are never stored, only flagged |
AI coding agents have quietly become one of the most powerful and least governed components of the modern developer workstation. Claude Code, Cursor, Windsurf, Gemini CLI, OpenCode, Codex, Devin CLI, Pi Agent, and Command Code can all read arbitrary files, write anywhere the user can, and execute shell commands — dozens of times per session — with no built-in boundary and no durable record of what happened. gryph, from safedep/gryph, is a Go-based, Apache-2.0-licensed answer to that gap: it installs hooks into these agents, evaluates every tool call against a YAML policy, and persists a complete event stream to a local SQLite database. The framing is blunt — everyone runs YOLO mode, and this project builds the missing guardrail.
The architectural insight is that most agents already expose hook surfaces, and gryph standardizes across them. A single command, gryph install, detects every supported agent on the machine and wires in the appropriate hooks — PreToolUse and PostToolUse for Claude Code and Codex, BeforeTool/AfterTool for Gemini CLI, tool.execute for OpenCode, and equivalents for the rest. Because the interception happens on both sides of the tool call, the daemon captures the full lifecycle of each action: what the agent wanted to do, what the policy decided, and what actually resulted. Events are emitted as JSON from the hook into gryph's local store, which is what makes session replay possible.
The problem the README leads with is post-hoc forensics. When an agent runs forty-seven tool calls in ninety seconds and the tests subsequently fail, git diff only shows the net change — it cannot tell you which files the agent read before editing, whether it ran unexpected shell commands, whether it touched CI pipeline configs or secrets, or what a file looked like before and after an intermediate write-and-revert. gryph logs answers exactly those questions, and gryph logs --follow streams the event feed live while the agent works, turning an opaque autonomous session into an observable one.
The query interface is where the tool earns its keep for incident review. gryph query --action exec --since "1w" surfaces every shell command the agent executed — including side-effecting operations like npm install, curl, or rm that leave no trace in version control. Path-scoped queries such as gryph query --file "src/auth/**" --action file_write reconstruct write histories to sensitive code paths, and --session, --command, --today, and --count filters let an operator slice the corpus by session or pattern. For structured analysis, gryph export emits JSONL validated against a published event.schema.json, with a metadata export profile that reduces events to labels and digests — a thoughtful touch for teams that must audit behavior without shipping source code or secrets off-box.
Policy enforcement goes beyond logging. Rules are authored in YAML and can block, warn, guide, or allow actions based on action type, file path, command pattern, tool name, agent, project, and CEL expressions evaluated over per-session counters — which enables rate-based controls, not just pattern matching. Blocked actions never reach the agent's tool, while guide decisions deliver policy text back to the agent as stderr, nudging the model's behavior mid-session rather than simply killing the call. Every decision is persisted, so the policy engine itself generates an auditable record of what was permitted and why. The workflow is well scaffolded: gryph policy init, gryph policy edit, gryph policy validate, and a dry-run simulator in gryph policy test --action file_write --path ./secrets/db.env.
Secrets hygiene receives explicit design attention, which matters because agents routinely wander into credential material while exploring a repository. Files matching .env, *.pem, *.key, *secret*, .ssh/**, and .aws/** are automatically flagged as sensitive: actions against them are logged, but their contents are never stored. By default the export pipeline also drops secret content and represents prompts as keyed digests, so even the audit artifact is sanitized before it leaves the database. Logging is tiered through minimal, standard, and full levels, with full adding file diffs, raw events, and conversation context — the operator explicitly opts into heavier capture.
Operationally, the CLI is unusually complete for a young project. gryph install --dry-run previews hook installation, gryph uninstall --restore-backup reverts original agent configurations from backup, and gryph doctor diagnoses setup problems. gryph diff <event-id> shows what a write event actually changed, gryph session <id> --show-diff replays a whole session with diffs, and gryph stats renders an interactive TUI dashboard with --since and --agent filters. Retention management via gryph retention status and gryph retention cleanup --dry-run keeps the local database from growing unbounded, and gryph self-log gives the tool its own audit trail — a detail that signals the authors understood they were building a control plane, not just a logger.
For enterprise consumption, the README points at an OpenSearch observability example under examples/ai-coding-observability/ for centralized dashboards and threat-detection alerts, and the JSONL export format makes SIEM ingestion straightforward. There is also per-session token usage and cost tracking across models and agents, plus agent-comparison workflows — filtering by --agent to see which coding assistant reads more, executes more commands, or burns more budget on the same task. That dual security-plus-cost framing is honest about why teams adopt observability in practice. The README also documents real integration quirks, such as Codex requiring the codex_hooks feature flag in ~/.codex/config.toml, and Devin CLI double-emitting claude-code events unless read_config_from.claude is disabled — evidence of genuine field testing rather than aspirational docs.
Privacy posture is the strongest selling point for security-conscious shops: all data stays on the local machine, with no cloud component, no telemetry, and no tracking. The project ships with CodeQL in its CI, carries an A+ Go report card, and is at roughly 171 stars, reflecting early but genuine community traction. Installation is flexible: curl -fsSL https://raw.githubusercontent.com/safedep/gryph/main/install.sh | sh, brew install safedep/tap/gryph, npm install -g @safedep/gryph, or go install github.com/safedep/gryph/cmd/gryph@latest, with pre-built binaries for macOS, Linux, and Windows on the releases page.
The defensive relevance here is hard to overstate. Prompt-injection research has repeatedly shown that agentic coding tools are a credible vehicle for arbitrary command execution on developer machines, and gryph addresses both halves of that risk: prevention through pre-execution policy enforcement, and detection through complete, queryable telemetry. For purple teams running authorized assessments against agentic CI pipelines, the event schema provides a ready-made detection source; for defenders, sensitive-file access flags and exec event streams are exactly the signals an agent-abuse detection rule set would consume. gryph is the rare tool that is simultaneously a hardening control and an observation instrument, and it is well worth a look before your organization's next agent-driven incident answers the question of why nobody was watching.
safedep/gryph.Educational analysis for authorized security professionals. Use only in controlled, authorized environments.
Related coverage
0 comentários:
Post a Comment
Note: Only a member of this blog may post a comment.