famclawfamclaw/honeybadger/AGENTS.md

honeybadger

AGENTS.md4 starsChanged 4 months agoMITView on GitHub

What this is Go security scanner for AI agent skills and MCP servers. Scans for hardcoded secrets, CVEs, supply-chain risk, and build provenance before install. CLI + MCP server modes. MIT licensed. Code structure - Scanners in internal/scanner/: secrets, supplychain, cve, meta, capability, skillsafety, mcptool, attestation - Core types in internal/scan/: Finding, Options, helpers - Engine in internal/engine/: scanner list, verdict logic - Entry points: cmd/honeybadger/main.go (CLI), cmd/honeybadger/mcp.go (MCP) Coding rules - Go language only - Every scanner change requires…

Reads credentials

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,700 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- honeybadger-devSkill
- honeybadgerSkill

The file

We split this AGENTS.md into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Every scanner change requires matching test fixture
line 14
Very specific:
Run make self-check before submitting (HoneyBadger scans itself)
line 16

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

HoneyBadger Agent Instructions

What this is
Go security scanner for AI agent skills and MCP servers. Scans for hardcoded secrets, CVEs, supply-chain risk, and build provenance before install. CLI + MCP server modes. MIT licensed.

Code structure

Scanners in internal/scanner/: secrets, supplychain, cve, meta, capability, skillsafety, mcptool, attestation
Core types in internal/scan/: Finding, Options, helpers
Engine in internal/engine/: scanner list, verdict logic
Entry points: cmd/honeybadger/main.go (CLI), cmd/honeybadger/mcp.go (MCP)

Coding rules

Go language only
Every scanner change requires matching test fixture
Fixtures must build secrets at runtime (not hardcoded) to avoid GitHub push protection
Run make self-check before submitting (HoneyBadger scans itself)

Build & test

make build
make test
make self-check
Integration tests: go test -tags integration ./...

Module path
github.com/famclaw/honeybadger

Codebase orientation

Purpose

HoneyBadger is a Go security scanner that analyzes AI agent skills and MCP servers for hardcoded secrets, CVEs, supply-chain risks, and build provenance before installation. It performs static analysis only — it reads source code and metadata but never executes the scanned code.

Runtime shape

The process starts with cmd/honeybadger/main.go parsing flags and routing to either CLI or MCP server mode. The scan pipeline runs in internal/scan/scan.go using concurrent RunAll with fan-in. Input is fetched via internal/fetch (GitHub, GitLab, stdin, tarball, local path). Findings are emitted as NDJSON or text via internal/report. Configuration comes from flags, env vars, and ~/.honeybadger/rules/. MCP server mode runs honeybadger --mcp-server and speaks JSON-RPC over stdio.

Package map (internal/)

Package	Responsibility	Key types / entry points	Depends on (other internal/)
engine	Verdict logic, tier/sandbox detection, scanner list builder	`BuildScannerList`, `ComputeVerdict`	scan, report, fetch, scanner
fetch	Repo routing and fetching	`Route`, `Fetcher`, `Repo`	—
ignore	.honeybadgerignore parser, trust-boundary policy, and suppression	`Parse`, `LoadPolicyFromContent`, `Apply`, `Policy`	scan
report	Output formatting (NDJSON, text, LLM)	`NewNDJSONEmitter`, `NewTextEmitter`, `CallLLM`	scan, fetch
rules	Embedded + user YAML rule loading and compilation	`Load`, `RuleSet`, `Rule`	—
scan	Core types, finding struct, severity constants	`Finding`, `ScanFunc`, `RunAll`	fetch, rules
scanner	Individual scanners (8 total)	`Run` functions	scan, fetch, rules
store	Audit trail writer	`WriteAudit`	—
testfixture	In-memory repo builders for testing	`fixtures.go`	fetch

Scanners

Scanner	What it detects	Rule source (YAML dir? code? both?)	Severity range
secrets	Hardcoded credentials (gitleaks v8)	YAML (800+ patterns)	High to Critical
cve	Known vulnerabilities in dependencies	osv.dev API (8 lockfile formats)	Low to Critical
supplychain	Remote script execution, typosquatting, reverse shells	YAML (patterns/dictionaries)	Low to Critical
meta	SKILL.md frontmatter validation	Code (YAML parsing)	Low to High
capability	Drift between declared permissions and code usage	Code (frontmatter vs source)	Info to High
skillsafety	Prompt injection, Unicode obfuscation, data exfiltration intent	YAML + code (7 scripts, 8 checks)	Medium to Critical
mcptool	MCP tool injection (tool fields + SKILL.md body), read-from-other-file references, shadowing, capability mismatch, rug-pull	YAML (concealment, threat-framing, silent-redirect) + code (`mcp-read-from-other-file`)	Info to High
attestation	Build provenance, Cosign signatures, SHA256SUMS	Code (GitHub API, file checks)	Info to High

Entry points

Binary	File	What it does
honeybadger	cmd/honeybadger/main.go	CLI entry point with scan, mcp-server, and flags
honeybadger	cmd/honeybadger/mcp.go	MCP server mode (JSON-RPC over stdio)

Rules (YAML)

Rules live in rules/ at repo root (rules/supplychain/, rules/skillsafety/, rules/mcptool/). They load via internal/rules/ with Load(dir) and merge embedded rules with ~/.honeybadger/rules/ (or HONEYBADGER_RULES_DIR). .honeybadgerignore suppresses findings by rule ID, glob, or SHA256 — but a target's own .honeybadgerignore is untrusted by default (trust boundary; see the "Trust Boundary" section in README.md). Suppressions are loaded via ignore.LoadPolicyFromContent and applied via ignore.Apply.

Configuration

Config loaded from CLI flags, env vars (HONEYBADGER_LLM, GITHUB_TOKEN), and ~/.honeybadger/rules/. Paranoia tiers: off, minimal, family, strict, paranoid.

Reports

internal/report/ handles output formats: NDJSON (default), text, and LLM verdict via CallLLM. Findings include rule metadata (ID, URL, references). LLM verdict path uses AssembleLLMPrompt and CallLLM with JSON response parsing.

Testing conventions

Tests live in each package's _test.go file. internal/testfixture provides in-memory repos (CleanRepo, SecretsRepo, etc.) and a mock osv.dev server (NewMockOSVServer); fixtures build secrets at runtime to avoid push protection. integration_test.go and e2e_test.go handle CLI + MCP integration.

"Where does X live?" — quick index

Where does a scan start? → internal/scan or cmd/honeybadger/main.go
Where is the CVE scanner? → internal/scanner/cve/
Where is the LLM verdict parsed? → internal/report/llm.go
Where are YAML rules stored? → rules/
Where is file-role classification? → internal/scan/fileclass.go
Where is the MCP server implemented? → cmd/honeybadger/mcp.go
Where is rule loading? → internal/rules/
Where are test fixtures? → internal/testfixture/
Where is the output emitter? → internal/report/
Where is suppression logic? → internal/ignore/
Where is the build provenance check? → internal/scanner/attestation/
Where is capability drift detected? → internal/scanner/capability/
Where is supply-chain risk analyzed? → internal/scanner/supplychain/
Where is the scan pipeline? → internal/scan/scan.go
Where is the runtime error handling? → internal/scan/scan.go

Notable sharp edges

File-role classification drops findings in test fixtures and rule corpus (not just test files)
LLM prompt receives the --paranoia level (and other scan context) as input; the actual WARN→FAIL escalation happens in ComputeVerdict, not the LLM path
MCP-server mode optionally accepts --rules-dir via CLI, else falls back to HONEYBADGER_RULES_DIR / default
YAML rule loading is the sole code path — hardcoded Go patterns were removed in v0.3.0
RunAll returns a channel of Event (Finding or RuntimeError) for concurrent fan-in
isBinaryContent skips binary files using null-byte detection
CheckToolHash uses regex to extract tool names from source code
ComputeVerdict never lets INFO findings escalate the verdict (they can still be the reported key finding) and escalates WARN to FAIL in strict/paranoid tiers
parseGitHubURL strips the scheme, github.com/ prefix, .git suffix, and trailing slash to extract owner/repo (no SSH/git@ handling)
buildSourceBlock prioritizes dependency files, build scripts, and files with findings
extractDependencyNames parses package.json and requirements.txt for typosquatting
detectShadowing uses the injection hit set from detectInjectionWithHits for cross-tool analysis

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free