Nox
**具有一流 AI 应用安全能力的语言无关安全扫描器。**
Nox 生成标准工件（SARIF, SBOM）并显式建模 AI 应用安全风险。它设计为可由人工、CI 系统和 AI 代理（通过 MCP）调用。
- **确定性** —— 相同的输入产生相同的输出，无隐藏状态
- **离线优先** —— 零外部服务依赖
- **默认安全** —— 从不上传源代码，从不执行不可信代码，从不自动应用修复
- **代理原生** —— 可通过 Model Context Protocol (MCP) 安全调用
## 快速演示
在一分钟内安装并扫描一个项目：
```
# 安装
brew tap felixgeelhaar/tap && brew install nox
# 或：go install github.com/nox-hq/nox/cli@latest
# 扫描当前目录
nox scan .
# 输出：
# nox dev -- scanning .
# [results] 12 findings, 47 dependencies, 3 AI components
# [done]
```
Nox 将 `findings.json` 写入当前目录。要一次性生成所有输出格式：
```
nox scan . --format all --output reports/
```
这将生成：
```
reports/
findings.json # Nox canonical findings
results.sarif # SARIF 2.1.0 (GitHub Code Scanning)
sbom.cdx.json # CycloneDX SBOM with vulnerability enrichment
sbom.spdx.json # SPDX SBOM with security references
report.html # Standalone HTML report
ai.inventory.json # AI component inventory (if detected)
```
### 在 CI 中使用 (GitHub Action)
```
# .github/workflows/security.yml
- uses: nox-hq/nox@24c7f00916ad15e99b6c44cdda8e55f05b869e43 # v0.4.2
with:
path: '.'
format: sarif
annotate: 'true' # Post inline PR comments (default: true)
- uses: github/codeql-action/upload-sarif@33119e582d3ab4ed79c2610af108cb08ff983917 # v3
if: always()
with:
sarif_file: nox-results/results.sarif
```
### 与 AI 代理一起使用 (MCP)
```
nox serve --allowed-paths /path/to/project
```
这将在 stdio 上启动一个包含 10 个只读工具和 5 个资源的 MCP 服务器。详情请参阅 [MCP Server](#mcp-server)。
## 安装
### Homebrew (macOS/Linux)
```
brew tap felixgeelhaar/tap
brew install nox
```
### Go
```
go install github.com/nox-hq/nox/cli@latest
```
### 从源码构建
```
git clone https://github.com/nox-hq/nox.git
cd nox
make build
./nox scan .
```
## Nox 检测内容
Nox 内置 **1506 条规则**，分为五个分析器套件：
### Secrets (938 条规则)
检测 **25+ 个类别** 的硬编码密钥、API 密钥、令牌和凭据（共 938 条规则，与 TruffleHog 相当）：
| Category | Rules | Examples |
|----------|-------|---------|
| 云服务商 | SEC-001 -- SEC-015 | AWS, GCP, Azure, DigitalOcean, Heroku, Alibaba, IBM, Databricks |
| 源代码控制 | SEC-003, SEC-016 -- SEC-022 | GitHub PAT/fine-grained/app tokens, GitLab, Bitbucket |
| 通讯 | SEC-023 -- SEC-029 | Slack, Discord, Telegram, Microsoft Teams |
| 支付 | SEC-030 -- SEC-038 | Stripe, Square, Shopify, PayPal/Braintree |
| AI/ML 提供商 | SEC-039 -- SEC-044 | OpenAI, Anthropic, HuggingFace, Replicate, Cohere |
| DevOps & CI/CD | SEC-045 -- SEC-056 | NPM, PyPI, Docker Hub, Terraform, Vault, Grafana |
| SaaS & APIs | SEC-057 -- SEC-072 | Twilio, SendGrid, Datadog, PagerDuty, Linear, Okta |
| 数据库 & 基础设施 | SEC-073 -- SEC-076 | 连接字符串 (Postgres, MongoDB, Redis), Firebase |
| 加密 & 密钥 | SEC-004, SEC-077 -- SEC-079 | PEM 私钥, Age, PGP, PKCS12 |
| 通用模式 | SEC-005, SEC-080 -- SEC-086 | 密码, 密钥, Bearer/Basic auth, JWT, 带凭据的 URL |
**密钥检测功能：**
- **香农熵分析**，用于高熵字符串（API 密钥、令牌），支持配置阈值
- **上下文感知检测** —— 当同一行出现暗示密钥的关键词（`password`, `secret`, `token`, `key` 等）时，降低熵阈值
- **误报加固** —— 自动过滤 git SHA、版本字符串、文件路径、驼峰式标识符、十六进制校验和及其他非密钥模式
- **文件模式范围界定** —— 熵规则仅扫描类源文件（非 lockfile、校验和或 vendor 代码）
- **通过 `.nox.yaml` 配置** —— 按规则覆盖熵阈值（见 [Entropy Configuration](#entropy-configuration)）
- Git 历史扫描，查找过往提交中的密钥
- 通过 YAML 定义文件添加自定义规则（`--rules path/to/rules/`）
### AI 安全 (50 条规则)
检测与 **OWASP LLM Top 10** 一致的 AI/ML 应用安全风险：
| Category | Rules | OWASP LLM | Examples |
|----------|-------|-----------|---------|
| 提示词注入 | AI-001 -- AI-003, AI-010 | LLM01 | 边界违规, RAG 注入, 间接注入 |
| 工具/代理安全 | AI-004, AI-005, AI-011 | LLM06 | MCP 写入工具, 通配符白名单, 无限制代理 |
| 不安全日志 | AI-006, AI-007 | LLM02 | 提示词/响应日志记录, API 密钥泄露 |
| 输出处理 | AI-009, AI-012, AI-015, AI-018 | LLM05 | eval()/exec(), SQL 注入, XSS, 路径遍历 |
| 信息泄露 | AI-013, AI-016 | LLM02, LLM07 | 响应中的堆栈跟踪, 系统提示词泄露 |
| 供应链 | AI-008, AI-014 | LLM03 | 未固定模型, 不安全的 HTTP 模型下载 |
| 资源管理 | AI-017 | LLM10 | 无限制 token 限制 |
### 基础设施即代码 (500 条规则)
检测 **7 个 IaC 类别** 中的配置错误：
| Category | Rules | Examples |
|----------|-------|---------|
| Dockerfile | IAC-001 -- IAC-003, IAC-022 -- IAC-025 | Root 用户, 未固定镜像, ARG 中的密钥, curl-pipe-sh |
| Terraform/Cloud | IAC-004 -- IAC-006, IAC-036 -- IAC-045 | 公网访问, 禁用加密, 通配符 IAM, 公开 S3 |
| Kubernetes | IAC-007 -- IAC-010, IAC-026 -- IAC-035 | 特权 Pod, 主机命名空间, 危险 capabilities, cluster-admin |
| GitHub Actions | IAC-011 -- IAC-018 | pull_request_target, 脚本注入, 可变 action 标签, write-all |
| Docker Compose | IAC-019 -- IAC-021, IAC-049 | 特权模式, 主机网络, Docker socket 挂载 |
| Helm | IAC-046 -- IAC-048 | Tiller 部署, 硬编码密码, 禁用 RBAC |
| CI/CD 通用 | IAC-050 | 禁用安全检查 |
### 依赖项 & SCA (6 条规则)
解析来自 **8 个生态系统**（Go, npm, PyPI, RubyGems, Cargo, Maven, Gradle, NuGet）的 lockfile，并查询 [OSV.dev](https://osv.dev) 数据库以查找已知漏洞：
| Rule | Description |
|------|-------------|
| VULN-001 | 依赖项中的已知漏洞（严重性映射自 CVSS） |
- 批量查询 OSV.dev API（每次请求最多 1000 个包）
- CVSS 分数映射到 nox 严重性级别（Critical/High/Medium/Low/Info）
- 网络错误时优雅降级（离线优先）
- 使用 `--no-osv` 标志或 `.nox.yaml` 中的 `scan.osv.disabled: true` 禁用
- 漏洞数据丰富 CycloneDX 和 SPDX SBOM 输出
### 数据保护 (12 条规则)
检测代码和配置中的个人身份信息 (PII) 及敏感数据模式：
| Category | Rules | Examples |
|----------|-------|---------|
| 联系信息 | DATA-001, DATA-004 | 电子邮件地址, 美国电话号码 |
| 金融 | DATA-003, DATA-007 | 信用卡号 (Visa/MC/Amex/Discover), IBAN |
| 政府证件 | DATA-002, DATA-008 -- DATA-012 | SSN, 英国国民保险号, 税号, 驾照, 护照 |
| 健康 | DATA-010 | 健康记录标识符 (MRN, patient_id) |
| 基础设施 | DATA-005 | 硬编码公网 IP 地址 |
| 个人 | DATA-006 | 出生日期字段 |
## 配置
在项目根目录创建 `.nox.yaml` 以自定义扫描行为：
```
scan:
exclude:
- "vendor/"
- "testdata/"
- "*.test.js"
osv:
disabled: false # Set true to skip OSV lookups (offline mode)
rules:
disable:
- "AI-008" # Unpinned model refs OK here
severity_override:
SEC-005: low # Downgrade for this project
output:
format: sarif # Default output format
directory: reports # Default output directory
policy:
fail_on: high # Only fail on high+ severity (critical, high)
warn_on: medium # Warn on medium findings
baseline_mode: warn # warn | strict | off
baseline_path: "" # Default: .nox/baseline.json
explain:
api_key_env: OPENAI_API_KEY # Env var to read API key from
model: gpt-4o # LLM model name
base_url: "" # Custom OpenAI-compatible endpoint
timeout: 2m # Per-request timeout
batch_size: 10 # Findings per LLM request
output: explanations.json # Output file path
```
CLI 标志始终优先于配置文件中的值。
### 熵值配置
通过 `.nox.yaml` 微调基于熵的密钥检测阈值：
```
scan:
entropy:
threshold: 5.0 # General entropy threshold (default: 5.0)
hex_threshold: 4.5 # Threshold for hex strings (default: rule-specific)
base64_threshold: 5.2 # Threshold for base64 strings (default: rule-specific)
require_context: true # Only flag when secret keyword is present (default: false)
```
- **`threshold`** —— 标记候选字符串所需的最小香农熵（每字符比特数）。较高的值可减少误报；较低的值能发现更多密钥。
- **`require_context`** —— 当为 `true` 时，仅标记包含暗示密钥关键词（`password`, `secret`, `key`, `token`, `credential`, `api_key`, `private`）的行上的高熵字符串。有助于减少包含许多看起来随机的常量的代码库中的噪音。
- **上下文提升** —— 当同一行出现密钥关键词时，有效阈值自动降低 0.5 比特，从而在关键位置提高敏感度。
### 基线管理
管理已知发现以跟踪进度并抑制已接受的风险：
```
# 从当前所有 findings 创建 baseline
nox baseline write .
# 写入特定文件
nox baseline write . --output my-baseline.json
# 更新 baseline（添加新的，移除过时的）
nox baseline update .
nox baseline update . --baseline my-baseline.json
# 显示 baseline 统计信息
nox baseline show .
```
### 内联抑制
直接在源代码中抑制特定发现：
```
// nox:ignore SEC-001 -- false positive in test
var testKey = "AKIAEXAMPLEFAKEKEY"
var apiKey = "test" // nox:ignore SEC-005
```
支持所有注释风格：`//`, `#`, `--`, `/*`, `