ContextHound

静态分析工具，扫描你的代码库以发现 LLM 提示注入和多模态安全漏洞。离线运行，无需 API 调用。

---

ContextHound 生态系统

ContextHound 覆盖你整个开发和浏览工作流：

工具	功能	安装
CLI / npm 包	扫描你的代码库以发现提示注入漏洞。集成 GitHub Actions，输出 SARIF、JSON、HTML 等格式。	npm install -g context-hound
VS Code 扩展	编码时内联显示发现结果、代码操作、输出通道、状态栏。	VS Code Marketplace
浏览器扩展	在任何 AI 聊天界面上实时显示扫描胶囊，DevTools 面板监控 LLM API 流量，弹窗扫描器。支持 Chrome 和 Firefox。	Firefox：免费安装 · Chrome：等待审核 · 源码

---

☕ 支持本项目

---

为什么选择 ContextHound？

随着 LLM 驱动的应用在生产代码库中日益普及，提示注入已成为最易被利用的攻击面之一；而大多数安全扫描器对此毫无察觉。

ContextHound 将静态分析引入你的提示层：

• 在注入路径到达模型之前将其捕获
• 标记嵌入提示中的泄露凭据和内部基础设施
• 检测系统提示中易受越狱影响的措辞
• 识别可能被武器化的不受约束的智能体工具使用
• 检测 RAG 语料库投毒以及作为系统指令注入的检索内容
• 捕获基于编码的走私（绕过字符串过滤器的 Base64 指令）
• 标记不安全的 LLM 输出消费：未经模式验证的 JSON 和未经净化的 Markdown
• 检测多模态攻击面：用户提供的图像 URL 传入视觉 API、通过视觉消息文件读取进行路径遍历、转录输出被送入提示，以及 OCR 文本被注入系统指令
• 标记智能体风险：无界智能体循环、未验证的内存写入、计划注入，以及工具参数接收系统提示内容
• 奖励良好的安全实践：提示中的缓解措施会降低你的评分

它可以作为 CLI 命令、npm 脚本、pre-commit 钩子或 GitHub Action 融入你现有的工作流。它不进行任何网络调用，仅有四个小型运行时依赖。

---

功能特性

122 条安全规则	覆盖 15 个家族：注入、数据外泄、越狱、不安全工具使用、命令注入、RAG 投毒、编码与隐藏内容、输出处理、多模态、智能体技能、智能体、MCP、供应链、资源消耗、持久化
OWASP 映射	每条规则都带有 OWASP Top 10 for LLM Applications (2025) 和 Agentic Applications (2026) ID，显示在 hound explain、--verbose、SARIF 标签和所有报告中
数值风险评分 (0-100)	归一化的仓库级评分，具有低、中、高和严重阈值
缓解检测	提示中的明确安全措辞会降低你的评分
9 种输出格式	Console、JSON、SARIF、GitHub Annotations、Markdown、JSONL 流式、交互式 HTML、CSV 和 JUnit XML
内置 GitHub Action	在风险变更时使 CI 失败，将 SARIF 上传到 Code Scanning，并可在拉取请求上保留摘要评论
自动修复	hound fix 预览并移除隐藏的 Unicode 字符（ENC-002 至 ENC-005）
多语言扫描	检测 Python、Go、Rust、Java、C#、PHP、Ruby、Swift、Kotlin、Vue 和 Bash 中的 LLM API 使用，而不仅仅是 TypeScript 和 JavaScript
规则过滤	excludeRules/includeRules 支持前缀通配符语法（CMD-*）；minConfidence 过滤器
增量缓存	.hound-cache.json 在重新运行时跳过未更改的文件；--no-cache 可禁用
遵循 .gitignore	git 忽略的文件会被跳过；.houndignore 以相同语法添加排除项
插件系统	通过配置中的 "plugins": ["./my-rule.js"] 从本地 .js 文件加载自定义规则
基线 / 差异模式	--baseline results.json 仅报告并使先前扫描中不存在的发现失败；--diff 仅扫描更改的文件
监视模式	--watch 在文件更改时重新扫描并显示增量发现
并行扫描	并发文件处理（--concurrency <n>，默认 8）
完全离线	无 API 调用，无遥测

---

安装

全局安装会将 hound 命令添加到你的 PATH：

npm install -g context-hound

按项目安装 限定于单个仓库，通过 npx hound 或 npm 脚本运行：

npm install --save-dev context-hound

无需安装，npx 会获取并运行该包：

npx context-hound scan --dir .

---

快速开始

# Scaffold a config file
hound init

# Scan your project
hound scan --dir ./my-ai-project

# Or via npm script (scans current directory)
npm run hound

# Verbose output, shows remediations and confidence levels
hound scan --verbose

# Fail the build on any critical finding
hound scan --fail-on critical

# Export JSON and SARIF reports
hound scan --format console,json,sarif --out results

# GitHub Annotations (for CI step summaries)
hound scan --format github-annotations

# Markdown report with findings tables
hound scan --format markdown --out report

# Stream findings as JSONL (one JSON object per line)
hound scan --format jsonl | jq '.severity'

# List all rules
hound scan --list-rules

# Explain a rule (or a rule family by prefix)
hound explain INJ-001
hound explain PST --format json

# Fast PR gate: scan only files changed vs. origin/main
hound scan --diff

# Interactive HTML report (self-contained, open in browser)
hound scan --format html --out report

# Re-scan on file changes
hound scan --watch

# Parallel scanning (default is 8; tune for your machine)
hound scan --concurrency 16

# Disable incremental cache for a clean run
hound scan --no-cache

# Also scan files that git ignores (skipped by default)
hound scan --no-gitignore

# Preview, then remove, hidden Unicode characters flagged by ENC-002 to ENC-005
hound fix
hound fix --write

# Baseline mode: only report findings new since the last saved scan
hound scan --format json --out baseline          # save a baseline
hound scan --baseline baseline.json             # compare future scans against it

# Load a custom rule from a local plugin file
hound scan  # plugin declared in .contexthoundrc.json "plugins" field

# Only run high-confidence rules
hound scan --config .contexthoundrc.json  # set minConfidence: "high"

# Fail if any single file scores >= 40
hound scan --fail-file-threshold 40

# Scan files up to 5 MB (default limit is 1 MiB; 0 = no limit)
hound scan --max-file-size 5242880

退出码：

代码	含义
0	通过：评分低于阈值且无 failOn 违规
1	未处理的错误或参数错误
2	阈值被突破：仓库评分达到或超过阈值，或某个文件超过 failFileThreshold
3	--fail-on 违规：存在达到或超过该严重级别的发现

---

GitHub Actions

使用 ContextHound Action 在每次推送和拉取请求时进行扫描，将发现上传到 GitHub Code Scanning，并在有风险的更改上阻止合并：

# .github/workflows/contexthound.yml
name: Prompt Audit

on: [push, pull_request]

jobs:
  hound:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write   # SARIF upload to Code Scanning

    steps:
      - uses: actions/checkout@v7

      - uses: IulianVOStrut/ContextHound@v2
        with:
          fail-on: high

发现会显示在仓库的 Security > Code scanning 标签页中，并作为拉取请求上的注解出现。

输入	默认值	描述
version	与 Action 匹配的发布版本	要运行的精确 context-hound npm 版本
dir	.	要扫描的目录
config		.contexthoundrc.json 的路径
threshold	配置值或 60	当仓库评分达到或超过此值时失败
fail-on		当发现任何达到或超过此严重级别的问题时失败：critical、high、medium
min-confidence		仅报告达到或超过 low、medium 或 high 置信度的规则
diff		仅扫描与此 git ref 相比发生更改的文件，例如 origin/${{ github.base_ref }}（需要在 checkout 时设置 fetch-depth: 0）
preset		逗号分隔的规则预设，例如 owasp-llm-top10
sarif-out	results.sarif	SARIF 报告的写入位置
upload-sarif	true	将报告上传到 Code Scanning
node-version		先设置此 Node.js 版本（默认：使用运行器的 Node.js）
comment	false	在拉取请求上发布摘要评论，并在后续运行时更新它（需要 pull-requests: write）
github-token	github.token	用于拉取请求评论的令牌

输出：score、findings、passed 和 sarif-file，供后续步骤使用。

拉取请求评论。 使用 comment: true 时，该 Action 会在拉取请求上保持一条 ContextHound 评论为最新状态：通过或失败、评分、各严重级别的计数，以及一个链接到 head commit 精确行的发现表格。将其与 diff 结合使用，评论就只会列出拉取请求所更改的内容：

    permissions:
      contents: read
      security-events: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: IulianVOStrut/ContextHound@v2
        with:
          diff: origin/${{ github.base_ref }}
          comment: true
          fail-on: high

扫描内容（路径、证据）以代码形式呈现，因此恶意拉取请求无法向评论中注入链接、HTML 或 @提及。只有由 github-actions[bot] 发布的评论才会被编辑。来自 fork 的拉取请求获得只读令牌，因此在这种情况下 Action 会记录警告而不是发表评论。

为了更严格的供应链卫生，请将 Action 固定到发布提交 SHA，而不是 @v2。

不使用 Action 时，直接安装 CLI：

    steps:
      - uses: actions/checkout@v7