famclaw/honeybadger
GitHub: famclaw/honeybadger
一款面向AI技能与MCP服务器的静态安全扫描器，通过预安装门禁防止密钥泄露与供应链攻击。
Stars: 0 | Forks: 0
# HoneyBadger
用于 AI 助手运行时所使用技能、工具和 MCP 服务器的安全扫描器。
**HoneyBadger don't care. HoneyBadger checks anyway.**
## 功能
在任何东西被安装到运行 AI 助手的家庭服务器之前，HoneyBadger 都会对其进行检查。
HoneyBadger 仅执行静态分析——它只读取源代码和元数据，但永远不会执行被扫描的代码。
## 安装
```
# Go install (requires Go 1.22+)
go install github.com/famclaw/honeybadger/cmd/honeybadger@latest
# 二进制下载（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
```
所有平台：[发行版](https://github.com/famclaw/honeybadger/releases/latest) —
Linux（amd64、arm64、armv7）、macOS（arm64、amd64）。
验证下载：请查看 [SECURITY.md](SECURITY.md)。
## 用法
### CLI
```
honeybadger scan
[flags]
Flags:
--paranoia string off|minimal|family|strict|paranoid (default: family)
--format string ndjson|text (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
--force Skip scan, exit 0
--offline Skip network calls, scan local only
--path string Subdirectory within repo to scan
```
### MCP 服务器
```
honeybadger --mcp-server
```
通过 stdio 协议传输 MCP JSON-RPC。暴露 `honeybadger_scan` 工具。
### 管道输入
```
cat SKILL.md | honeybadger scan -
```
从标准输入读取并将其作为单个文件（默认为 `SKILL.md`）进行扫描。
输入大小上限为 10 MB。
### 抑制发现结果
在仓库根目录放置一个 `.honeybadgerignore` 文件。每行可通过规则 ID 抑制
发现结果，可选地通过 glob 模式或片段 SHA256 进行约束：
```
# 抑制规则的所有发现
SECRET_IN_CODE
# 仅抑制测试 fixtures 中的发现
SECRET_IN_CODE *.test.yaml
# 通过 SHA256 抑制特定代码片段
SECRET_IN_CODE sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```
被抑制的发现结果将从判决中排除。当发现结果被抑制时，会发出 `suppression_summary`
NDJSON 事件。在文本模式下，判决后会打印摘要行。
## 检查内容
| 检查 | 扫描器 | 描述 |
|-------|---------|-------------|
| 密钥 | gitleaks v8 | 800+ 凭证模式，对测试文件进行噪声降低 |
| CVE | osv.dev | 在 Go、npm、PyPI、Rust、Ruby、Maven 上通过批处理 API 进行跨平台检测（8 种锁文件格式） |
| curl\|bash | supplychain | 下载并执行远程脚本 |
| eval remote | supplychain | 执行远程获取的代码 |
| 反向 shell | supplychain | nc/netcat/bash 反向 shell 模式 |
| 加密货币挖矿 | supplychain | Coinhive、xmrig、stratum+tcp 模式 |
| 数据外泄 | supplychain | Webhook/requestbin 外泄端点 |
| 仿冒包名 | supplychain | 基于编辑距离检查热门包名 |
| SKILL.md 字段 | meta | 必需字段和格式验证 |
| 权限不匹配 | meta | 声明与实际的网络/文件系统/执行权限对比 |
| 构建来源证明 | attestation | GitHub Attestation API + 工作流检查（严格+） |
| Cosign/SHA256 | attestation | Cosign 签名和校验和文件存在性检查（严格+） |
| 提示注入 | skillsafety | 覆盖短语（支持 11 种语言，含家庭场景） |
| 同形异义字 | skillsafety | 混合脚本单词（拉丁文/西里尔文/希腊文/亚美尼亚文）(family+) |
| 零宽字符 | skillsafety | 技能内容中的隐藏 Unicode 字符 (family+) |
| 双向文本覆盖 | skillsafety | 右到左文本方向操控 (family+) |
| 数据外泄意图 | skillsafety | 敏感路径 + 外部/网络钩子 URL 相关性 (family+) |
| 多语言隐藏 | skillsafety | 主语言技能中意外的脚本块 (family+) |
## 为何选择 HoneyBadger
| | HoneyBadger | Cisco MCP Scanner | Snyk agent-scan | Proximity |
|---|:-:|:-:|:-:|:-:|
| **单一二进制文件** | Go | Python | Python | Python |
| **离线模式** | 是 | 部分（静态） | 否 | 部分（本地 Ollama） |
| **MCP 服务器模式** | 是（JSON-RPC） | 扫描 MCP 服务器 | 扫描 MCP 服务器 | 扫描 MCP 服务器 |
| **偏执等级** | 5 级 | 无 | 无 | 无 |
| **SKILL.md 扫描** | 是 | 否 | 是 | 是 |
| **CVE 扫描** | 8 种锁文件格式 | 否 | 否 | 否 |
| **密钥检测** | gitleaks 800+ | Yara | 是（技能模式） | 是（技能扫描） |
| **供应链攻击** | 是 | 否 | 否 | 否 |
| **来源证明** | 是 | 否 | 否 | 否 |
| **无需云端依赖** | 是 | 部分 | 否（需要 Snyk API） | 部分（Ollama 可用） |
| **ARM/RPi 运行支持** | 是 | 否 | 否 | 否 |
| **审计追踪** | JSONL | 否 | 否 | 否 |
## 集成
| 平台 | 类型 | 指南 |
|----------|------|-------|
| Claude Code | 技能 + MCP + 钩子 | [docs/CLAUDE_CODE.md](docs/CLAUDE_CODE.md) |
| OpenAI Codex CLI | 钩子 | [docs/integrations/codex-cli.md](docs/integrations/codex-cli.md) |
| FamClaw | 内置流水线 | [docs/INSTALLATION.md](docs/INSTALLATION.md) |
| OpenClaw | 技能 | [docs/INSTALLATION.md](docs/INSTALLATION.md) |
| PicoClaw | 技能 | [docs/INSTALLATION.md](docs/INSTALLATION.md) |
| NanoBot | 技能 | [docs/INSTALLATION.md](docs/INSTALLATION.md) |
| CI/CD | CLI | [docs/EXAMPLES.md](docs/EXAMPLES.md) |
| MCP | JSON-RPC stdio | [docs/EXAMPLES.md](docs/EXAMPLES.md) |
## 偏执等级
| 等级 | 扫描器 | LLM | 阻止条件 |
|-------|----------|-----|-----------|
| off | 无 | 否 | 什么都不阻止 |
| minimal | 密钥、CVE | 否 | CRITICAL |
| family | 密钥、CVE、供应链、meta | 是 | HIGH+ |
| strict | 全部 + 来源证明 | 是 | MEDIUM+（WARN=FAIL） |
| paranoid | 全部 + 允许列表 | 是 | LOW+ |
## 输出
以换行符分隔的 JSON 流输出到标准输出。事件包括：progress、finding、cve、health、attestation、sandbox、suppression_summary、result。
发现结果在可用时包含规则元数据：`rule_id`、`more_info_url` 和来源 YAML 规则中的 `references`。
在文本模式下，严重性标签显示为 `[SEVERITY rule_id]`，`→ url` 行链接到更多文档。
退出代码：0=通过，1=警告，2=失败，3=错误。
## 项目结构
```
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 fetcher
│ │ ├── gitlab.go # GitLab fetcher
│ │ ├── stdin.go # Stdin fetcher (piped input via -)
│ │ ├── stdin_test.go
│ │ └── tarball.go # Tarball fetcher
│ ├── ignore/
│ │ ├── ignore.go # .honeybadgerignore parser and finding filter
│ │ └── ignore_test.go
│ ├── report/
│ │ ├── types.go # Emitter interface
│ │ ├── ndjson.go # NDJSON streaming emitter
│ │ ├── ndjson_test.go
│ │ ├── text.go # Human-readable text emitter
│ │ ├── text_test.go
│ │ ├── llm.go # LLM prompt assembly + verdict calling
│ │ └── llm_test.go
│ ├── scan/
│ │ ├── finding.go # Finding struct, severity constants, ParanoiaLevel, Options
│ │ ├── finding_test.go
│ │ ├── scan.go # ScanFunc type, RunAll (concurrent runner with fan-in)
│ │ ├── scan_test.go
│ │ └── helpers.go # WalkCode, IsPlaceholder, Redact, EditDistance, IsBinaryFile
│ ├── scanner/
│ │ ├── secrets/
│ │ │ ├── secrets.go # Secrets scanner (gitleaks-powered)
│ │ │ └── secrets_test.go
│ │ ├── supplychain/
│ │ │ ├── supplychain.go # Supply chain risk patterns + typosquat detection
│ │ │ └── supplychain_test.go
│ │ ├── cve/
│ │ │ ├── cve.go # CVE scanner via osv.dev API
│ │ │ ├── deps.go # Dependency parser (8 lockfile formats)
│ │ │ ├── cve_test.go
│ │ │ └── deps_test.go
│ │ ├── meta/
│ │ │ ├── meta.go # SKILL.md meta scanner
│ │ │ └── meta_test.go
│ │ └── attestation/
│ │ ├── attestation.go # Attestation verification scanner
│ │ └── attestation_test.go
│ ├── store/
│ │ ├── audit.go # JSONL audit trail writer
│ │ └── audit_test.go
│ └── testfixture/
│ ├── fixtures.go # Builder functions returning *fetch.Repo with in-memory files
│ ├── fixtures_test.go # Smoke tests for all fixtures
│ └── mock_osv.go # Mock osv.dev server for testing CVE scanner
├── .github/
│ ├── dependabot.yml
│ └── workflows/
│ ├── ci.yml
│ ├── codeql.yml
│ └── release.yml
├── docs/
│ ├── INSTALLATION.md # Installation guide for all runtimes
│ ├── CLAUDE_CODE.md # Claude Code integration guide (MCP config, hooks)
│ ├── EXAMPLES.md # CLI and MCP usage examples
│ └── docs_test.go # Doc validation tests (11 functions, 35 checks)
├── .gitignore
├── .goreleaser.yml # GoReleaser config: builds, signing, Docker, SBOM, changelog
├── Dockerfile # Multi-stage distroless image (local dev)
├── Dockerfile.goreleaser # GoReleaser Docker image (pre-built binary)
├── go.mod
├── go.sum
├── Makefile
├── README.md
├── SECURITY.md
└── SKILL.md # AgentSkills manifest for skill registries
```
## 状态
**v0.1.0 发布** — [下载二进制文件](https://github.com/famclaw/honeybadger/releases/tag/v0.1.0)
所有核心扫描器均已实现并测试。二进制文件使用 Sigstore cosign 签名，
每个发行版都附带 SPDX SBOM。通过标准输入进行输入（`scan -`）和
`.honeybadgerignore` 抑制功能已实现（尚未发布）。
请查看 [CHANGELOG.md](CHANGELOG.md) 获取版本历史。
## 构建
```
make build # current platform
make cross # all 5 targets (linux arm64/armv7/amd64, darwin arm64/amd64)
make test # run all tests
make self-check # scan ourselves at strict paranoia (requires prior release)
make self-check-bootstrap # scan at minimal paranoia (for initial releases only)
make release-dry # test GoReleaser locally (snapshot, no publish)
```
## 通过自定义规则扩展
检测规则是嵌入在二进制文件中的 YAML 文件。可以在
运行时通过将 `.yaml` 文件放入 `~/.honeybadger/rules/`（或设置
`HONEYBADGER_RULES_DIR`）来添加自定义规则：
```
mkdir -p ~/.honeybadger/rules/custom
cat > ~/.honeybadger/rules/custom/my-rule.yaml << 'EOF'
id: my_custom_check
kind: pattern
scanner: supplychain
category: custom
severity: HIGH
signal: file_content
patterns:
- regex: 'SOME_DANGEROUS_PATTERN'
description: "My custom detection"
message: "Custom rule matched"
EOF
honeybadger scan ./my-project # custom rule will fire
```
请参考 [rules/README.md](rules/README.md) 获取完整格式规范。
## 发布清单
1. `make self-check` 在严格偏执等级下通过（或首次发布时使用 `self-check-bootstrap`）
2. 打标签：`git tagX.Y.Z && git push origin vX.Y.Z`
3. GoReleaser 构建、签名并通过 `.github/workflows/release.yml` 发布
4. 验证发布：请查看 [SECURITY.md](SECURITY.md#verifying-release-artifacts)
5. 设置 GitHub 主题：`security`、`mcp`、`supply-chain`、`scanner`、`agentskills`、`golang`
## 许可证
[MIT](./LICENSE)标签：AI 技能, Claude Code, CLI 工具, CVE 扫描, Docker, EVTX分析, Go 语言, LLM 安全, MCP 服务器, MIT 许可, SKILL.md, 云安全监控, 安全扫描, 安全防御评估, 提示注入, 日志审计, 时序注入, 运行时保护, 集群管理, 零日漏洞检测, 静态分析, 预安装校验