ContextHound

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

---

ContextHound 生态系统

ContextHound 可贯穿你的整个开发和浏览工作流：

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

---

☕ 支持项目

---

为什么使用 ContextHound？

随着基于 LLM 的应用在生产代码库中变得常见，提示注入已成为最具可攻击性的攻击面之一；而大多数安全扫描工具对此并无感知。

ContextHound 为你的提示层带来静态分析：

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

它可以作为 CLI 命令、npm 脚本或 GitHub Action 融入你现有的工作流，且没有任何外部依赖。

---

特性

95 条安全规则	涵盖 14 个类别：注入、数据外泄、越狱、不安全工具使用、命令注入、RAG 投毒、编码、输出处理、多模态、技能市场、智能体、MCP、供应链、拒绝服务
数值风险评分（0-100）	标准化的仓库级评分，带有低、中、高和严重阈值
缓解措施检测	提示中的显式安全用语会降低你的评分
7 种输出格式	控制台、JSON、SARIF、GitHub 注解、Markdown、JSONL 流式输出以及交互式 HTML
内含 GitHub Action	在风险高时使 CI 失败，并自动上传 SARIF 结果
多语言扫描	检测 Python、Go、Rust、Java、C#、PHP、Ruby、Swift、Kotlin、Vue、Bash 中的 LLM API 使用——不仅限于 TypeScript/JavaScript
规则过滤	使用前缀 glob 语法（CMD-*）进行 excludeRules/includeRules；minConfidence 过滤器
增量缓存	.hound-cache.json 在重新运行时跳过未更改的文件；--no-cache 禁用
插件系统	通过配置中的 "plugins": ["./my-rule.js"] 从本地 .js 文件加载自定义规则
基线 / 差异模式	--baseline results.json —— 仅报告并失败于先前扫描中不存在的发现
观察模式	--watch 在文件变更时重新扫描并显示差异发现
并行扫描	并发文件处理（--concurrency <n>，默认 8）
完全离线	无 API 调用、无遥测、无付费依赖

---

安装

全局安装 —— 将 hound 命令添加到你的 PATH：```bash npm install -g context-hound

**项目级安装** — 限定于单个仓库，通过 `npx hound` 或 npm 脚本运行：```bash
npm install --save-dev context-hound

Zero-install — 无需安装，直接使用缓存的npm注册表副本：```bash npx context-hound scan --dir .

## 快速开始```bash
# 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

# 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

退出码：

代码	含义
0	通过 — 分数低于阈值，无 failOn 违规
1	未处理的错误或参数错误
2	阈值被突破 — 仓库分数 ≥ 阈值，或文件阈值超出
3	--fail-on 违规 — 发现指定严重级别的结果

---

GitHub Actions

添加到你的工作流中，当提示风险过高时阻止合并：```yaml

.github/workflows/context-hound.yml

name: Prompt Audit

on: [push, pull_request]

jobs: hound: runs-on: ubuntu-latest permissions: contents: read security-events: write

steps:
  - uses: actions/checkout@v4

  - uses: actions/setup-node@v4
    with:
      node-version: '20'

  - run: npm install -g context-hound

  - run: hound scan --format console,sarif,github-annotations --out results.sarif

  - name: Upload to GitHub Code Scanning
    if: always()
    uses: github/codeql-action/upload-sarif@v3
    with:
      sarif_file: results.sarif

发现结果将显示在你的仓库的 **Security > Code scanning** 标签页中。`github-annotations` 格式会在 PR 中发布内联评论，并将摘要表格写入 GitHub 步骤摘要。

---

## 配置

运行 `hound init` 来生成一个 `.contexthoundrc.json` 文件，或手动创建一个：```json
{
  "include": ["**/*.ts", "**/*.js", "**/*.py", "**/*.go", "**/*.rs", "**/*.md", "**/*.txt", "**/*.yaml"],
  "exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/tests/**",
    "**/attacks/**"
  ],
  "threshold": 60,
  "formats": ["console", "sarif"],
  "out": "results",
  "verbose": false,
  "failOn": "critical",
  "maxFindings": 50,
  "excludeRules": ["JBK-002"],
  "includeRules": [],
  "minConfidence": "medium",
  "failFileThreshold": 80,
  "concurrency": 8,
  "cache": true,
  "plugins": ["./rules/my-custom-rule.js"],
  "baseline": "./baseline.json"
}

选项	默认值	描述
include	**/*.{ts,tsx,js,jsx,py,go,rs,java,kt,cs,php,rb,swift,vue,sh,bash,hs,md,txt,yaml,yml,json}	要扫描的 Glob 模式
exclude	**/node_modules/**, **/dist/** 等	要忽略的 Glob 模式
threshold	60	仓库评分达到或超过此值时失败（退出码 2）
formats	["console"]	输出格式：console, json, sarif, github-annotations, markdown, jsonl, html
out	自动	文件输出的基础路径
verbose	false	显示每个发现项的修复建议和置信度
failOn	未设置	在首次发现 critical、high 或 medium 级别时退出码 3
maxFindings	未设置	在发现 N 个项后停止
excludeRules	[]	跳过指定规则 ID 或前缀 glob（例如 "CMD-*", "JBK-002")
includeRules	[]	仅运行这些规则 ID（空数组 = 运行所有规则）
minConfidence	未设置	跳过低于此置信度的规则：low、medium 或 high
failFileThreshold	未设置	任何单个文件评分达到或超过此值时失败（退出码 2）
concurrency	8	最多并行处理的文件数
cache	true	启用增量扫描缓存（.hound-cache.json）；设置为 false 或使用 --no-cache 可禁用
plugins	[]	本地 .js 规则插件的路径；每个插件必须导出 Rule 或 Rule[]
baseline	未设置	旧 JSON 报告的路径；仅报告基线中不存在的发现项

环境变量覆盖

所有关键设置都可以在运行时覆盖，无需编辑配置文件：

变量	覆盖项
HOUND_THRESHOLD	threshold
HOUND_FAIL_ON	failOn
HOUND_MIN_CONFIDENCE	minConfidence
HOUND_VERBOSE	verbose（真值：1、true、yes)
HOUND_CONFIG	配置文件路径

.houndignore

在项目根目录放置一个 .houndignore 文件，无需编辑 .contexthoundrc.json 即可添加排除模式。遵循相同的 glob 语法；以 # 开头的行是注释。

内联抑制