一个用 Rust 编写的快速通用代码安全扫描器。功能齐全：支持 14 种语言、用于分类的 TUI、秘密检测、后量子审计、差异感知扫描等等 𓃥
<p align="center"> <img src="https://raw.githubusercontent.com/0sec-labs/foxguard/main/www/public/foxguard-logo.png" width="128" alt="foxguard" /> </p> <h1 align="center">foxguard</h1> <p align="center"> <strong>针对代码、密钥、依赖项和加密风险的快速本地安全扫描。</strong> <br /> <sub>已集成到 <a href="https://github.com/0sec-labs/0sec">0sec</a>，开源网络安全工具集。</sub> </p> <p align="center"> <a href="https://github.com/0sec-labs/foxguard/actions/workflows/ci.yml"><img src="https://github.com/0sec-labs/foxguard/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <a href="https://github.com/0sec-labs/foxguard"><img src="https://img.shields.io/badge/foxguard-clean-3fb950" alt="foxguard: clean" /></a> <a href="https://crates.io/crates/foxguard"><img src="https://img.shields.io/crates/v/foxguard?color=d97706&label=crates.io" alt="crates.io" /></a> <a href="https://www.npmjs.com/package/foxguard"><img src="https://img.shields.io/npm/v/foxguard?color=d97706&label=npm" alt="npm" /></a> <a href="https://pypi.org/project/foxguard/"><img src="https://img.shields.io/pypi/v/foxguard?color=d97706&label=PyPI" alt="PyPI" /></a> <a href="https://github.com/apps/foxguard-app/installations/new"><img src="https://img.shields.io/badge/GitHub_App-Install-2ea44f?logo=github" alt="Install GitHub App" /></a> </p> ```sh npx foxguard . ``` <p align="center"> <img src="https://assets.kitploit.com/production/public/readmes/13909/2ce579a58299a47cd3e965f13b97bf1c5dcaf020496d4a4eb2141d414ff7bd0c.gif" alt="foxguard scan demo" width="640" /> </p> ## 为什么选择 foxguard - <img height="14" src="https://raw.githubusercontent.com/0sec-labs/.github/main/profile/assets/icons/checklist.png" alt=""> 覆盖 12 种源语言的 200+ 内置规则，以及配置和清单文件检查 - <img height="14" src="https://raw.githubusercontent.com/0sec-labs/.github/main/profile/assets/icons/git-branch.png" alt=""> 支持 14 种语言的污点追踪，并对 Python、JavaScript、Go、Java、Ruby、PHP、C# 和 Kotlin 进行跨文件分析 - <img height="14" src="https://raw.githubusercontent.com/0sec-labs/.github/main/profile/assets/icons/zap.png" alt=""> 快速的本地和 CI 扫描，支持 diff 模式以回答“这个分支新增了什么？” - <img height="14" src="https://raw.githubusercontent.com/0sec-labs/.github/main/profile/assets/icons/key.png" alt=""> 密钥扫描、基于 OSV 的依赖项扫描，以及后量子加密审计 - <img height="14" src="https://raw.githubusercontent.com/0sec-labs/.github/main/profile/assets/icons/plug.png" alt=""> 兼容 Semgrep/OpenGrep 的 YAML 桥接，可加载约 98% 的公共规则库（[覆盖率报告](https://github.com/0sec-labs/foxguard/blob/main/docs/parity/registry-coverage.md)） - <img height="14" src="https://raw.githubusercontent.com/0sec-labs/.github/main/profile/assets/icons/file-code.png" alt=""> 支持终端、JSON、SARIF、CycloneDX 1.6 CBOM 以及兼容 Semgrep 的 JSON 输出 ## 安装 ```sh npx foxguard . # 零安装 pipx install foxguard # 从 PyPI 安装预构建 CLI curl -fsSL https://foxguard.dev/install.sh | sh # 预构建二进制文件（macOS/Linux） cargo install foxguard # 从源码安装 ``` 独立二进制安装程序会根据 `checksums.txt` 验证 GitHub 发布二进制文件。发布二进制文件还会发布 GitHub 工件证明；可使用 `gh attestation verify` 进行手动验证，或参阅[发布来源](https://github.com/0sec-labs/foxguard/blob/main/docs/release-provenance.md)。 PyPI wheel 支持 Python 3.9+，适用于 Linux glibc 2.28+（x86_64/ARM64）、macOS（Intel/Apple Silicon）和 Windows x86_64。在现有 Python 虚拟环境中，请改用 `python -m pip install foxguard`。这些安装方式无需 Rust 编译器或运行时二进制下载即可安装原生 CLI；不提供 Python API。Alpine/musl 用户应使用独立的 Linux 发布二进制文件。 **GitHub Action：** ```yaml - uses: 0sec-labs/foxguard/[email protected] with: path: . severity: medium fail-on-findings: "true" upload-sarif: "true" ``` **pre-commit：** ```yaml repos: - repo: https://github.com/0sec-labs/foxguard rev: v0.14.0 hooks: - id: foxguard ``` 集成：[GitHub App](https://github.com/apps/foxguard-app/installations/new)、[VS Code](https://marketplace.visualstudio.com/items?itemName=peaktwilight.foxguard)、[Claude Code 插件](https://github.com/0sec-labs/foxguard/blob/main/docs/claude-code-integration.md) 和 [MCP 服务器](https://github.com/0sec-labs/foxguard/blob/main/docs/mcp-server.md)。 ### 托管 GitHub App 运维 `foxguard-github-app` 写入以换行符分隔的 JSON 日志。已完成和失败的扫描分别使用 `event=foxguard.scan.completed` 和 `event=foxguard.scan.failed`，并包含投递、安装、仓库、PR、提交、持续时间以及 `usage_scope` 字段以便关联。请将标识符保留为日志字段，而非指标标签。 将 `FOXGUARD_INTERNAL_ACCOUNTS` 设置为您自己的 GitHub 账户和组织的逗号分隔列表。匹配不区分大小写。其他所有者会被归类为 `external`；未设置列表或缺少所有者会产生 `unknown`。外部活动并不能证明是付费客户，扫描也不代表人员。 安装注册表会在启动时以及每小时与 GitHub App 安装 API 的所有页面进行对账。刷新失败会保留现有状态；并发 webhook 优先。稀疏的 webhook 元数据会保留已知账户详细信息和观察到的仓库名称。这些名称并非安装可访问仓库的完整清单。 请将 `FOXGUARD_INSTALLATIONS_PATH` 和 `FOXGUARD_PULL_REQUEST_JOBS_PATH` 持久化到持久存储上。请将 `foxguard.installations.reconcile_failed` 与扫描失败一起监控；`foxguard.installations.reconciled` 会在成功刷新后报告安装总数以及内部/外部/未知安装数量。请根据实测的扫描器峰值内存和容器内存限制来设置 `FOXGUARD_PR_WORKERS`：子进程 OOM 终止可能发生而不会重启托管应用程序。 ## 快速开始 ```sh foxguard . # 扫描所有内容 foxguard diff main . # 仅显示与 main 相比的新发现 foxguard tui . # 交互式终端审查 foxguard secrets . # 泄露的凭据和密钥 foxguard sca . # 来自 OSV 的依赖项漏洞 foxguard pqc . # 后量子加密审计 foxguard --format sarif . > results.sarif foxguard --format semgrep-json . # 兼容 Semgrep CLI 的 JSON ``` 使用 `foxguard --fix src/` 或 `foxguard --fix src/app.py` 就地应用受支持的污点修复。目标会根据规范扫描目录或所选文件进行检查；超出该范围的发现会被跳过。Python 命令注入修复会在需要时添加 `import subprocess`，同时保留模块文档字符串和 future 导入。提交前请审查生成的更改。 原生代码扫描器中的文件读取、元数据和目录遍历失败会以退出码 `2` 退出，而不是生成成功报告或覆盖基线。有意排除以及不支持、二进制或过大的文件仍会被跳过；检查扫描覆盖率时请查看跳过文件通知。 ## 终端审查 运行 `foxguard tui .`，使用方向键或 Tab 选择 **Scan**、**Diff**、**Secrets** 或 **PQC**。在 Diff 模式下，按 Enter 前输入目标分支。宽终端会在发现旁边显示其详细信息；较小的终端使用列表和可展开的详情视图。只要发现提供了源代码上下文、数据流和修复，它们就保持可滚动。 标题栏将扫描统计信息与基线类别分开。选定的源代码范围会内联高亮显示，无需额外的注释行。打开控件保持在实时详情窗格下方，而其内容可滚动，缩短的文件位置会保留其行号和列号后缀。搜索和对话框在激活时拥有各自的快捷键。 如果无法加载源代码上下文，保存的发现片段仍然可用。密钥使用经过脱敏的片段，而不是将原始源代码加载到详情窗格中。 加载卡片显示不确定的活动和实际经过时间，而不是百分比估计。扫描期间按 Ctrl+C 退出。 | 按键 | 操作 | |-----|--------| | `j` / `k`、方向键、Home / End | 在发现之间移动 | | `v` | 展开详情或返回列表/分屏视图 | | PageUp / PageDown | 翻页列表，或滚动可见详情 | | `/`、Enter | 编辑并应用搜索 | | Ctrl+U | 清除正在编辑的搜索 | | Esc | 关闭模态框、取消搜索编辑、离开展开的详情，或清除已应用的过滤器 | | `0`–`4`、`c`、Shift+C | 最低严重性、置信度阈值和排序顺序 | | `f` | 循环 All → Unreviewed → Todo → Reviewed → Ignore | | `i` | 预览并应用分类操作 | | Space、`a`、`x` | 勾选一个发现、切换可见选择，并预览批量操作 | | Shift+F | 保存、加载、替换或删除命名过滤器；恢复审查存储 | | `b` | 在有可用比较时循环基线类别 | | Tab、Enter / `o` | 选择发现/源/汇并在编辑器中打开 | | `w`、`[` / `]` | 显示通知并滚动其历史记录；最新通知最先显示 | | `e` | 导出 CBOM、JSON 或 SARIF | | `?`、`q` / Ctrl+C | 帮助和退出；Ctrl+C 在每个模态框内也可用 | Enter 和 `o` 使用非空白的 `$VISUAL`，然后是 `$EDITOR`。如果两者都未设置，foxguard 会在 `PATH` 中查找 `nvim`、`vim`、`nano` 或 `vi`，然后才考虑可用的桌面打开程序。无头终端不需要 `xdg-open`。例如，运行 `VISUAL="nvim" foxguard tui .` 或设置 `EDITOR='code --wait'`。损坏的显式编辑器设置会被报告，而不是被静默替换；如果没有可用的编辑器，TUI 会保持打开并显示设置指导。受支持的编辑器会跳转到所选发现/源/汇所在行。 审查标记会自动持久化到每用户存储中，作用域为规范项目根目录和扫描模式（在 Diff 模式下包括目标）。使用 Shift+F 加载命名过滤器时，会恢复搜索、严重性、置信度、审查状态、排序和基线类别。它们不会更改仓库扫描配置。列表显示可见/总发现数和审查进度；更改过滤器或排序时，只要同一发现仍然可见，就会保持选中。取消搜索编辑会恢复之前应用的查询。 已勾选的发现会在过滤器更改后保留。`x` 打开批量操作；Enter 显示确切目标、隐藏选择数量、目标和效果范围。只有 `y` 会应用预览；再次按 Enter 不会确认，按 Esc 会取消而不写入。基线操作会添加精确指纹。规则/文件和项目范围的配置操作也可能影响未选中的发现，正如预览所警告的那样。如果配置目标失败，成功的写入会保留并报告结果；该批次不是事务。 存储使用 Linux 上的 `$XDG_STATE_HOME/foxguard/tui`（或 `~/.local/state/foxguard/tui`）、macOS 上的 Application Support，以及 Windows 上的 `%LOCALAPPDATA%`。原子写入和修订检查可防止一个终端静默覆盖另一个终端。存储错误会使本地更改明显处于 **UNSAVED** 状态。在 Shift+F 中，`w` 重试保存，`r` 显式从磁盘重新加载，Shift+R 确认对当前项目/模式进行备份并重置。重新加载/重置可能会丢弃未保存的更改；重置会保留之前的磁盘字节，而不是未保存的标记。审查存储包含指纹和过滤器设置，不包含源代码。 导出包含当前扫描的结果，而不仅仅是可见的过滤行，并写入当前工作目录。现有常规文件需要显式按 `y` 确认；按 Esc 取消。写入是原子的，目标符号链接（包括悬空链接）会被拒绝。 使用 `foxguard tui --baseline .foxguard/baseline.json .` 审查保存的基线比较。与 CLI 抑制不同，终端审查会保留当前发现，并区分 **introduced**、**recurring** 和 **resolved** 条目。Resolved 表示在当前扫描输出中不存在，而非已验证修复：请比较等效的范围、规则和阈值。基线身份包括文件和源位置，因此移动发现可能会显示为 introduced 加 resolved。Resolved 行是只读的历史元数据；仅适用搜索，`v` 会展开其可滚动详情。切换回当前发现类别以分类或导出当前扫描。 Git Diff 仍然是与分支的单独比较。 ## 语言覆盖 | 语言 | 内置规则 | 污点追踪 | 框架感知规则 | |----------|:-:|:-:|---| | JavaScript / TypeScript | 是 | 是 | Express、Next.js | | Python | 是 | 是 | Django、Flask、FastAPI | | Go | 是 | 是 | Gin | | Kotlin | 是 | 是 | Spring | | Java | 是 | 是 | Spring | | Ruby | 是 | 是 | Rails | | PHP | 是 | 是 | Laravel | | Rust | 是 | -- | -- | | C# | 是 | 是 | .NET | | Swift | 是 | 是 | iOS | | Haskell | 是 | -- | Cardano 种子规则 | 污点追踪还覆盖 C、Bash 和 Solidity。配置、清单和外部规则扫描覆盖 Dockerfile、Nginx、Apache、HAProxy、HCL/Terraform、YAML/JSON/XML/HTML、通过 Semgrep YAML/Coccinelle 的 C 等。 ## 安全模式 ```sh foxguard sca . foxguard pqc . foxguard --rules ./semgrep-rules . ``` SCA 支持 `Cargo.lock`、`package-lock.json`、`pnpm-lock.yaml`、`requirements.txt`、`poetry.lock` 和 `Pipfile.lock`。PQC 审计是一个双面记分卡：它会标记量子易受攻击的原语（RSA、ECDSA/DSA、ECDH/DH）并给出 CNSA 2.0 迁移截止日期，同时也会检测已在使用的后量子算法（ML-KEM、ML-DSA、SLH-DSA、FN-DSA、HQC 以及 X25519MLKEM768 等混合算法），将其作为信息性、抗量子清单进行报告——并报告迁移就绪百分比。两侧都会导出为 CycloneDX 1.6 CBOM，其中后量子算法作为抗量子资产而非漏洞出现。 ## 配置 foxguard 会从扫描路径向上自动发现 `.foxguard.yml`。 ```yaml scan: baseline: .foxguard/baseline.json disable_rules: [py/no-eval] secrets: exclude_paths: [fixtures, testdata] ``` 使用 `// foxguard: ignore[rule-id]` 内联抑制已接受的发现。 ## 文档 从[文档索引](https://github.com/0sec-labs/foxguard/blob/main/docs/README.md)开始。关键参考：[架构](https://github.com/0sec-labs/foxguard/blob/main/docs/architecture.md)、[Semgrep/OpenGrep 兼容性](https://github.com/0sec-labs/foxguard/blob/main/docs/compatibility.md) 和[发布运行手册](https://github.com/0sec-labs/foxguard/blob/main/docs/releasing.md)。 ## 基准测试 | 仓库 | 代码行数 | foxguard | Semgrep | 加速比 | |------|-----|----------|---------|---------| | express | 15K JS | 0.28s | 6.09s | **22x** | | flask | 14K Py | 0.33s | 6.51s | **20x** | | gin | 18K Go | 0.50s | 4.95s | **10x** | | sentry | 1.3M Py | 35s | 194s | **5x** | 使用 `./benchmarks/run.sh` 复现；结果因机器而异。参见 [`benchmarks/README.md`](https://github.com/0sec-labs/foxguard/blob/main/benchmarks/README.md)。 ## 贡献 有关规则编写、测试和开发设置，请参见 [`CONTRIBUTING.md`](https://github.com/0sec-labs/foxguard/blob/main/CONTRIBUTING.md)。 ## 许可证 MIT OR Apache-2.0 -- [0sec Labs](https://0sec.ai)
