NuGuardAI/nuguard

# NuGuard 开源 NuGuard 是一个专注于 AI 应用安全的开源命令行工具（CLI）。它可以从源代码或 Git 仓库生成 AI 专属的软件物料清单（SBOM），执行静态安全分析、审查认知策略文档、测试在线 AI 应用行为，并使用基于场景的对抗测试对运行的 AI 应用进行红队演练。 ## 功能概述 - 从本地代码库或 Git 仓库生成 AI-SBOM - 分析 SBOM 中的结构性 AI 安全风险与依赖问题 - 将认知策略与 SBOM 进行交叉验证 - 对在线 AI 应用端点执行静态与动态行为测试 - 基于 AI-SBOM 和认知策略对运行中的 AI 应用进行红队演练，包括提示注入、工具滥用、数据外泄等攻击场景，以检验目标系统的各类子代理、工具与能力 - 以文本、JSON、Markdown 和 SARIF 格式导出发现结果 ## 当前 CLI 功能 当前已实现并可直接使用： - `nuguard sbom` - `nuguard analyze` - `nuguard scan` - `nuguard policy` - `nuguard behavior` - `nuguard redteam` 暂存或未实现： - `nuguard seed` - `nuguard report` ## 系统要求 - Python 3.12+ - 本地工作流推荐使用 `uv` 可选的外部工具（部分分析路径会用到）： - `grype` - `checkov` - `trivy` - `semgrep` 若未安装相应工具，相关检查可能会被跳过或标记为不可用，具体取决于执行命令的路径。 ## 安装 生产环境建议从 PyPI 安装： ``` pip install nuguard ``` 以下说明适用于本地开发环境的搭建。建议在需要运行最新代码、贡献项目或使用需要本地环境变量配置的 LLM 辅助功能时使用。 ``` uv sync --dev ``` 运行 CLI： ``` uv run nuguard --help ``` 或通过虚拟环境运行： ``` . .venv/bin/activate nuguard --help ``` ## 快速开始 ### 1. 生成 AI-SBOM ``` nuguard sbom generate --source . --output app.sbom.json ``` 你也可以扫描远程仓库： ``` nuguard sbom generate \ --from-repo https://github.com/org/repo \ --ref main \ --output app.sbom.json ``` ### 2. 运行静态分析 ``` nuguard analyze --sbom app.sbom.json --format markdown ``` 典型输出格式： - `markdown`：供人工审查 - `json`：供自动化处理 - `sarif`：供代码扫描流水线使用 ### 3. 行为测试 ``` nuguard behavior \ --sbom app.sbom.json \ --target http://localhost:3000 \ --format markdown ``` ### 4. 对运行中的应用进行红队演练 ``` nuguard redteam \ --config nuguard.yaml \ --output reports/redteam.md \ --format markdown ``` 如需更全面的红队覆盖，你还可以提供： - 通过 `--policy` 指定认知策略 - 通过 `--canary` 提供金丝雀值 - 通过 `--config` 指定配置文件 ### 5. 运行统一流程 ``` nuguard scan \ --source . \ --output-dir nuguard-reports ``` 这是一次性完成 SBOM 生成与静态分析的最便捷方式。 ## 配置 NuGuard 支持通过 `nuguard.yaml` 进行项目配置。一个可直接编辑的示例文件位于 [`nuguard.yaml.example`](nuguard.yaml.example)。 示例配置的关键区域： - `sbom`：已有 SBOM 文件路径 - `source`：生成 SBOM 的源代码目录 - `policy`：认知策略文件路径 - `llm`：LLM 辅助功能相关的模型设置 - `behavior`：行为测试的目标 URL、端点与测试配置 - `redteam`：目标 URL、端点、金丝雀文件、配置文件、场景过滤、引导对话设置及发现触发控制（`finding_triggers.*`） - `analyze`：最低严重性阈值 - `database`：基于 SQLite 或 Postgres 的存储设置 - `output`：输出格式与失败阈值 CLI 参数具有最高优先级，其次是 `nuguard.yaml`，最后是环境变量与内置默认值。 ## 红队金丝雀 NuGuard 可在动态测试过程中监控预设的金丝雀值，以识别高置信度的数据外泄发现。操作步骤如下： 1. 从 [`canary.example.json`](canary.example.json) 获取模板 2. 创建本地 `canary.json` 3. 将金丝雀值注入目标系统 4. 使用 `--canary` 参数运行 `nuguard redteam` 并指向该文件 更多细节请参考 [`docs/redteam-engine.md`](docs/redteam-engine.md)。 ## 常用命令 ``` nuguard --help nuguard sbom --help nuguard analyze --help nuguard policy --help nuguard behavior --help nuguard redteam --help nuguard scan --help ``` ## 开发 安装开发依赖： ``` make dev ``` 运行测试： ``` make test ``` 运行代码检查与类型验证： ``` make lint ``` 代码格式化： ``` make fmt ``` ## 发布 该仓库包含用于 Trusted Publishing 到 TestPyPI 和 PyPI 的 GitHub Actions 工作流： - [publish-testpypi.yml](.github/workflows/publish-testpypi.yml) - [publish-pypi.yml](.github/workflows/publish-pypi.yml) 在发布前，需为 `nuguard` 项目在 TestPyPI 和 PyPI 中配置 Trusted Publishers： - 组织者：`NuGuardAI` - 仓库：`nuguard` - 工作流文件：`publish-testpypi.yml` 或 `publish-pypi.yml` - 环境：`testpypi` 或 `pypi` 推荐发布流程： 1. 手动触发 TestPyPI 的 GitHub Actions 工作流 2. 验证 TestPyPI 上的包安装与 CLI 行为 3. 创建 GitHub 发布以触发 PyPI 发布工作流 ## 仓库说明 - 示例输出与基准测试固件位于 `tests/output/` 目录下 - 部分红队演练与基准测试为可选功能，需通过环境变量启用 - LLM 辅助功能依赖通过环境变量提供的对应服务商凭证 ## 许可证 许可证信息请查阅 [LICENSE](./LICENSE) 文件。

标签：AI安全, AI物料清单, Chat Copilot, DevSecOps, DNS解析, JSON导出, Markdown导出, Python, SARIF, SBOM, 上游代理, 云安全监控, 动态测试, 安全合规, 安全扫描, 安全报告, 对抗测试, 工具滥用, 开源项目, 提示注入, 文本导出, 无后门, 时序注入, 硬件无关, 策略校验, 网络代理, 行为测试, 跌倒检测, 软件物料清单, 逆向工具, 集群管理, 静态分析