<p align="center"> <img src="assets/mascot.png" alt="HoneyBadger — kicking snakes, protecting your claw runtimes" width="600"> </p>

HoneyBadger

Security scanner for skills, tools, and MCP servers used by AI assistant runtimes.

HoneyBadger don't care. HoneyBadger checks anyway.

What it does

Before anything gets installed on a family home server running AI assistants, HoneyBadger checks it. HoneyBadger performs static analysis only -- it reads source code and metadata but never executes the scanned code.

Install

# Go install (requires Go 1.22+)
go install github.com/famclaw/honeybadger/cmd/honeybadger@latest

# Binary download (Linux amd64)
curl -fsSL https://github.com/famclaw/honeybadger/releases/latest/download/honeybadger-linux-amd64 \
  -o honeybadger && chmod +x honeybadger

# Docker
docker pull ghcr.io/famclaw/honeybadger:latest

Secure Installation Note

For secure installation, we recommend downloading the binary first, inspecting it, and then executing it:

# Download the binary
curl -fsSL https://github.com/famclaw/honeybadger/releases/latest/download/honeybadger-linux-amd64 -o honeybadger

# Inspect the downloaded file (optional but recommended)
ls -la honeybadger

# Make it executable
chmod +x honeybadger

All platforms: Releases — Linux (amd64, arm64, armv7), macOS (arm64, amd64). Verify downloads: see SECURITY.md.

Usage

CLI

honeybadger scan <repo-url> [flags]
where <repo-url> supports HTTPS, SSH/git@ (e.g., git@github.com:user/repo), and local paths.

Flags:
  --paranoia string      off|minimal|family|strict|paranoid (default: family)
  --format string        ndjson|text|sarif (default: ndjson)
  --llm string           LLM endpoint override
  --db string            Path to audit trail file
  --installed-sha string SHA256 of installed version
  --installed-tool-hash  SHA256 of installed MCP tool definitions
  --tool-manifest string  Path to MCP tools/list JSON for tool-definition analysis
  --tool-baseline string  Path to approved tools/list JSON for rug-pull diffing
  --force                Skip scan, exit 0
  --offline              Skip network calls, scan local only
  --path string          Subdirectory within repo to scan
    See [docs/sarif-output.md] for details on SARIF output.

MCP Server

honeybadger --mcp-server

Speaks MCP JSON-RPC over stdio. Exposes honeybadger_scan tool.

Piped input

cat SKILL.md | honeybadger scan -

Reads from stdin and scans it as a single file (SKILL.md by default). Input is capped at 10 MB.

SARIF Output

HoneyBadger now supports generating SARIF (Static Analysis Results Interchange Format) 2.1.0 output for integration with security tools and CI/CD pipelines:

honeybadger scan <repo-url> --format sarif

This format is compatible with various security platforms and CI/CD systems. The SARIF output includes detailed information about each finding, including rule IDs, severity levels, file locations, and additional metadata.

Example Usage

honeybadger scan https://github.com/example/repo --format sarif

SARIF Output Structure

The SARIF output includes:

• Version: "2.1.0"
• Schema: "https://json.schemastore.org/sarif-2.1.0-rtm.5.json"
• Tool: honeybadger driver with name and version
• Results: Each finding becomes a SARIF result with:
  • ruleId: The rule identifier
  • level: Severity mapping (error, warning, note)
  • message.text: Finding message
  • locations.physicalLocation.artifactLocation.uri: File path
  • locations.physicalLocation.region.startLine: Line number
  • properties: Additional metadata including rule_id, more_info_url, references, package, version, ecosystem, cve_id, fixed_in

Severity Mapping

| HoneyBadger Severity | SARIF Level | |---------------------|-------------| | CRITICAL | error | | HIGH | error | | MEDIUM | warning | | LOW | note | | INFO | note |

Rules CLI

HoneyBadger now supports listing and explaining detection rules:

honeybadger rules list
honeybadger rules explain <rule-id>

This feature allows users to inspect the available detection rules, see their details, and understand what threats they are designed to catch.

Example Usage

# List all available rules
honeybadger rules list

# Explain a specific rule
honeybadger rules explain SECRET_IN_CODE

SSH/git@ Clone URLs

HoneyBadger now supports scanning repositories using SSH/git@ clone URLs:

honeybadger scan git@github.com:user/repo.git

This enables scanning private repositories or repositories that are only accessible via SSH without requiring token authentication.

Example Usage

honeybadger scan git@github.com:user/repo.git

Suppressing findings

Place a .honeybadgerignore file in your repository root. Each line suppresses findings by rule ID, optionally constrained by a glob pattern or snippet SHA256:

# Suppress all findings for a rule
SECRET_IN_CODE

# Suppress only in test fixtures
SECRET_IN_CODE *.test.yaml

# Suppress a specific snippet by SHA256
SECRET_IN_CODE sha256:<64-hex-digit-sha256-of-the-snippet>

Suppressed findings are excluded from the verdict. A suppression_summary NDJSON event is emitted when findings are suppressed. In text mode, a summary line is printed after the verdict.

Rules CLI

honeybadger rules list
honeybadger rules explain <rule-id>

What it checks

| Check | Scanner | Description | |-------|---------|-------------| | Secrets | gitleaks v8 | 800+ credential patterns, noise reduction for test files | | CVEs | osv.dev | Batch API across Go, npm, PyPI, Rust, Ruby, Maven (8 lockfile formats) | | curl|bash | supplychain | Downloads and executes remote scripts | | eval remote | supplychain | Evaluates remotely fetched code | | Reverse shell | supplychain | nc/netcat/bash reverse shell patterns | | Crypto mining | supplychain | Coinhive, xmrig, stratum+tcp patterns | | Data exfil | supplychain | Webhook/requestbin exfiltration endpoints | | Typosquat | supplychain | Edit-distance check against popular package names | | SKILL.md fields | meta | Required fields and format validation | | Capability drift | capability | Declared requires.* vs actual code: network/filesystem/bins/env reads (family+) | | Build provenance | attestation | GitHub Attestation API + workflow check (strict+) | | Cosign/SHA256 | attestation | Cosign signatures and checksum files present (strict+) | | Prompt injection | skillsafety | Override phrases in 11 languages, across SKILL.md and any referenced text files (family+) | | Homoglyphs | skillsafety | Mixed-script words (Latin+Cyrillic/Greek/Armenian) (family+) | | Zero-width chars | skillsafety | Hidden Unicode characters in skill content (family+) | | RTL override | skillsafety | Right-to-left text direction manipulation (family+) | | Data exfil intent | skillsafety | Sensitive paths + external/webhook URLs correlation (family+) | | Multi-language hiding | skillsafety | Unexpected script blocks in primary-language skills (family+) | | MCP tool injection | mcptool | Prompt injection in MCP tool/param descriptions, titles, defaults, enums, and the SKILL.md body (family+) | | MCP read-from-other-file | mcptool | SKILL.md directing the agent to read/see/consult a separate instruction file (family+) | | MCP tool obfuscation | mcptool | Zero-width / homoglyph / RTL / Tags-block chars in tool definitions (family+) | | MCP cross-tool shadowing | mcptool | One tool's description redefining another tool's behavior (family+) | | MCP capability mismatch | mcptool | Tool declares readOnlyHint but params/source show writes (family+) | | MCP rug pull | mcptool | Tool definitions changed since the approved baseline (family+) |

Binary Detection

HoneyBadger implements robust binary file detection to prevent scanning of non-text content. Two approaches are used:

1. Null-byte detection - Checks for null bytes (0x00) in the first 512 bytes of file content
2. UTF-8 validation - Ensures content is valid UTF-8 encoded text

Binary files are automatically skipped during scanning to avoid processing executables, libraries, or compiled code that wouldn't benefit from security scanning rules.

Why HoneyBadger

HoneyBadger analyzes MCP tool definitions from a caller-supplied manifest and never executes the server, unlike scanners that call tools/list on a live server.

| | HoneyBadger | Cisco MCP Scanner | Snyk agent-scan | Proximity | |---|:-:|:-:|:-:|:-:| | Single binary | Go | Python | Python | Python | | Offline mode | yes | partial (static) | no | partial (local Ollama) | | MCP server mode | yes (JSON-RPC) | scans MCP servers | scans MCP servers | scans MCP servers | | Paranoia levels | 5 tiers | no | no | no | | SKILL.md scanning | yes | no | yes | yes | | CVE scanning | 8 lockfile formats | no | no | no | | Secrets detection | gitleaks 800+ | Yara | yes (skills mode) | yes (skill scanning) | | Supply chain | yes | no | no | no | | Attestation | yes | no | no | no | | No cloud dependency | yes | partial | no (needs Snyk API) | partial (Ollama ok) | | Runs on ARM/RPi | yes | no | no | no | | Audit trail | JSONL | no | no | no |

Integrations

| Platform | Type | Guide | |----------|------|-------| | Claude Code | Skill + MCP + Hook | docs/CLAUDE_CODE.md | | OpenAI Codex CLI | Hook | docs/integrations/codex-cli.md | | FamClaw | Built-in pipeline | docs/INSTALLATION.md | | OpenClaw | Skill | docs/INSTALLATION.md | | PicoClaw | Skill | docs/INSTALLATION.md | | NanoBot | Skill | docs/INSTALLATION.md | | CI/CD | CLI | docs/EXAMPLES.md | | MCP | JSON-RPC stdio | docs/EXAMPLES.md |

Paranoia levels

| Level | Scanners | LLM | Blocks on | |-------|----------|-----|-----------| | off | None | No | Nothing | | minimal | secrets, cve | No | CRITICAL | | family | secrets, cve, supplychain, meta, capability, skillsafety | Yes | HIGH+ | | strict | family + attestation | Yes | MEDIUM+ (WARN=FAIL) | | paranoid | family + attestation + allowlist | Yes | LOW+ |

Output

Newline-delimited JSON streamed to stdout. Events: progress, finding, cve, health, attestation, sandbox, suppression_summary, result.

Findings include rule metadata when available: rule_id, more_info_url, and references from the source YAML rule. In text mode, the severity tag shows [SEVERITY rule_id] and a → url line links to further documentation.

CVE severity is graded from the CVSS v3/v4 score, fetching the full osv.dev record when the batch response omits it. When no CVSS score is available, severity falls back to MEDIUM and the finding carries reason: severity_unknown so a fallback MEDIUM is distinguishable from a graded one.

Exit codes: 0=PASS, 1=WARN, 2=FAIL, 3=error.

Project structure

honeybadger/
├── cmd/honeybadger/
│   ├── main.go              # CLI entry point — full pipeline wiring
│   ├── mcp.go               # MCP server mode — JSON-RPC over stdio
│   ├── mcp_test.go          # MCP server tests via in-process client
│   ├── integration_test.go  # CLI + MCP integration tests (build tag: integration)
│   └── e2e_test.go          # E2E stdio MCP server subprocess tests
├── internal/
│   ├── engine/
│   │   ├── engine.go        # Verdict computation, tier/sandbox detection, scanner list builder
│   │   └── engine_test.go
│   ├── fetch/
│   │   ├── fetch.go         # Repo type, Route(), Fetcher interface
│   │   ├── fetch_test.go
│   │   ├── github.go        # GitHub