Tracehound

Trace every input to its sink, then try to prove yourself wrong.

Tracehound is a security-audit skill: a portable methodology that a capable coding agent follows to perform a deep, reproducible security review of a code repository. It clones the target locally, traces untrusted input through the call graph to dangerous sinks, reviews authentication and authorization, checks configuration and dependencies, and produces a Markdown report with cautious proofs-of-concept and redacted secrets.

The skill is a single SKILL.md of instructions. Its goal is to make an agent audit the way a careful human reviewer would rather than a pattern matcher, and to stay honest about the difference between what it proved and what it merely suspects.

What it does

• Clone and triage: pins the commit, maps languages, entry points, and dependency manifests.
• Input-to-sink tracing: walks user-controlled sources (HTTP params, bodies, headers, uploads, webhooks) to dangerous sinks (code exec, shell, SQL/NoSQL, DOM, filesystem, SSRF, deserialization, templates, redirects).
• Auth review: missing middleware, broken object-level authorization (IDOR/BOLA), admin gating, multi-tenant isolation.
• Secrets: in code and across full git history. Values are always redacted (PREFIX****).
• Configuration, CI/CD, and IaC: debug flags, permissive CORS/TLS, GitHub Actions injection (pull_request_target, ${{ github.event }}, unpinned actions), Dockerfile/K8s/Terraform misconfig.
• Dependency audit: runs native auditors (npm audit, pip-audit, osv-scanner, and so on) when available, and cross-checks against OSV.
• Exploitability scoring and attack-path synthesis: chains individual findings into end-to-end paths that can be worse than any single link.
• Diagrams: every serious finding ships a source-to-sink flow diagram, and the report includes an attack-path graph (Mermaid, with an ASCII fallback).
• Reproducible output: a Markdown report plus a machine-readable SARIF/JSON sidecar pinned to the analyzed commit.

What makes it different

Many automated security reviews optimize for the number of findings. Tracehound optimizes for how much you can trust each finding.

• Evidence tiers (SUSPECTED, CONFIRMED, PROVEN). A pattern match is never "confirmed." A finding is CONFIRMED only after the data flow is traced by hand or by a semantic engine, and PROVEN only after a sandboxed reproduction.
• Adversarial self-refutation. Before any finding ships as CONFIRMED, a dedicated pass tries to disprove it by looking for the sanitizer, the upstream guard, or the unreachable path. Survivors ship; the rest are downgraded with the reason recorded.
• Framework-aware reasoning. It reasons against what the framework already guarantees (ORM parameterization, template auto-escaping) so it does not cry wolf on safe house style, and it flags the dangerous opt-outs (dangerouslySetInnerHTML, .raw(), | safe).
• Honesty about tools. If an auditor did not run, dependency findings are labeled "unverified, version heuristic" and kept separate from tool-verified results.

Using it

Tracehound runs inside any agent harness that supports skills, or it can be pasted as system instructions.

1. Place the tracehound/ folder where your agent discovers skills (for example a skills/ directory), or hand the agent SKILL.md directly.
2. Ask for an audit and provide one of:
   • a full URL: https://github.com/owner/repo
   • a shortcut: owner/repo
   • a local path: /path/to/repo
   • optionally a branch or tag (defaults to the repo's default branch)

Audit https://github.com/owner/repo for security issues.

If the repo is private or cannot be cloned, Tracehound says so and offers to audit a local path or pasted files instead.

A full sanitized sample report is in examples/sample-report.md (Mermaid diagrams render on GitHub).

Example output (excerpt)

### [C-1] CONFIRMED: OS command injection, RCE (src/server.js:297, CWE-78)
- Source: req.body.outputName (POST /admin/products/:id/image)
- Sink:   exec(`cp ${sourcePath} ${outputPath}`)
- Trace:  req.body.outputName (293) -> path.join (295) -> command (297) -> exec (298)
- Refutation (1h): no upstream auth, no sanitizer, not execFile; survives
- Impact: arbitrary command execution as the server process
- Fix:    use fs.copyFile; if a command is required use execFile with an arg array; add admin authz

flowchart TD
  A(["SOURCE: req.body.outputName (server.js:293)"]) --> B["path.join(uploadDir, outputName) (server.js:295)"]
  B --> C["command = cp ... (server.js:297)"]
  C --> D[["SINK: exec(command) (server.js:298, CWE-78)"]]

Loading

Requirements and dependencies

Hard requirements (all you need): a shell, git, and a capable agent's reasoning. ripgrep is recommended; plain grep works.

Everything else is an optional accelerator that improves recall and precision on the exhaustive, deterministic work that reasoning does less reliably. When a tool is absent, Tracehound falls back to reasoning and records the gap under "Coverage and blind spots." It never blocks.

Optional tool	What it adds
tokei / cloc	faster, accurate language and size triage
gitleaks / trufflehog	secret scanning across full git history
semgrep / ast-grep / CodeQL	machine-verified source-to-sink reachability
npm audit / pip-audit / govulncheck / cargo audit / osv-scanner	authoritative dependency CVEs, including the transitive tree
docker / podman	sandboxed PoC execution to reach the PROVEN tier

Why the optional auditors matter: an agent reasoning from memory sees only top-level manifest pins and recalls a stale, partial CVE set. A real auditor walks the full resolved dependency tree against a live database. In testing on a sample app, hand reasoning found about 4 likely issues while npm audit found 11 (including 5 transitive ones reasoning was blind to). Tools do exhaustive recall; the agent does reachability judgment. Use both.

Scope and ethics

• Read-only by default. Tracehound audits; it changes files only if you also ask for fixes.
• Concrete PoCs only for code you own or are authorized to test. For third-party code it describes the vector and impact rather than producing a ready-to-run exploit, and it never validates a discovered secret against a live service.
• Secrets are always redacted in output (PREFIX****).
• No exfiltration. It quotes the minimum lines needed to substantiate a finding and removes the local clone when done.

Limitations

Output quality depends on the agent running it and on which optional tools are present. With nothing installed it is a careful, reasoning-driven audit; with the optional engines it gains machine-verified reachability and exhaustive dependency and secret coverage. It does not replace a human security review. It makes one faster and harder to fool.

License

Apache License 2.0. See LICENSE.