ryanHwH20/oss-hawkeye-agent
GitHub: ryanHwH20/oss-hawkeye-agent
Hawkeye Agent 是一个企业级、AI 原生的软件供应链安全护栏工具，可在毫秒级内评估开源包的许可证合规性、漏洞风险、项目健康度及深层传递依赖。
Stars: 5 | Forks: 2
# 🎾 Hawkeye Agent
**为您的软件供应链提供无可争议的高精度司线裁判。**
[](https://www.npmjs.com/package/oss-hawkeye-agent)
[](https://github.com/ryanHwHH20/oss-hawkeye-agent/blob/main/LICENSE)
[](https://github.com/ryanHwH20/oss-hawkeye-agent/actions)
[](https://scorecard.dev/viewer/?uri=github.com/ryanHwH20/oss-hawkeye-agent)
[](http://makeapullrequest.com)
在职业网球比赛中，Hawk-Eye 系统提供毫米级高精度的、无可争议的判定，裁决球是界内还是界外。在现代软件供应链中，开发者同样需要一个权威的系统，来判断一个开源依赖项是“安全可用”还是“越界（违规）”。
**Hawkeye Agent** 是一个企业级、AI 原生的安全护栏，可在毫秒级时间内评估开源包。它为您提供关于许可证合规性、已知漏洞 (CVE/CVSS)、OpenSSF Scorecard 健康度以及深层传递依赖 (SBOM) 的明确判定。
当 Hawkeye 判定一个包**“OUT（出界）”**时，它不仅会进行拦截，还会提供即时的、AI 引导的自动修复建议，让您的工作得以持续推进。
## ✨ 功能
- 🎾 **毫米级高精度司线** — 瞬间拦截高风险漏洞和违规许可证，并返回标准的退出代码 (`0`/`1`)。
- 🗣️ **询问优先的安全工作流** — 开发者使用自然语言提问，Hawkeye 会返回一份集成的审计报告，包含策略判定和修复指导。
- 🔍 **深度 SBOM 传递扫描** — 通过 [deps.dev](https://deps.dev) 分析完整的依赖关系图，捕捉标准清单扫描器遗漏的“影子漏洞”。
- 💡 **AI 驱动的修复** — 当包被拦截时，Hawkeye 会生成升级代码片段、`overrides` 块，或者委托给您的 AI 助手以动态推荐合规的替代方案。
- 🤖 **技能驱动的工作流** — 结合工作区技能和本地 CLI 执行，让您的 AI 助手在执行安装操作前强制进行安全检查。
- 🌐 **7 大生态系统** — NPM、PyPI、Cargo、Go、RubyGems、NuGet、Maven — 尽在一个工具。
- 🏛️ **策略即代码** — 在您的仓库中放置一个 `.audit-agent.yaml` 文件，以强制执行组织特定的合规规则。
## ✅ 环境要求
在设置之前，请确保您的本地环境满足以下条件：
- Node.js 18+（推荐使用 Node.js 20+）
- npm 9+
- 能访问 `https://api.osv.dev` 的网络连接
- 能访问 `https://api.deps.dev` 的网络连接
- 能访问 `https://osv.dev` 的网络连接
- 能访问 `https://deps.dev` 的网络连接
- 安装了 Copilot Chat 的 VS Code（用于对话式技能工作流）
## 🚀 快速开始
### 1. 从源码构建
通过克隆仓库从源码运行 Hawkeye：
```
git clone https://github.com/ryanHwH20/oss-hawkeye-agent.git
cd oss-hawkeye-agent
npm install
npm run build
```
### 2. 一次性开发者配置（推荐）
为了让新的 Copilot 会话稳定使用 Hawkeye 技能 + CLI SOP，请在每台机器上完成一次此操作：
1. 构建项目：
```
npm install
npm run build
```
2. 保留工作区技能和指令文件：
- `.github/skills/hawkeye-agent/SKILL.md`
- `.github/copilot-instructions.md`
3. 重新加载 VS Code 窗口。
4. 从项目根目录运行设置检查：
```
npm run check:setup
npm run check:smoke
```
如果两项测试均通过，新会话在执行安装命令时应能可靠地触发 Hawkeye 流程。
### 3. 单一包审计 (CLI)
您可以直接运行构建好的 CLI，获取完整的企业级安全报告：
```
node dist/cli.js NPM express 4.16.0
node dist/cli.js PYPI requests 2.31.0
node dist/cli.js MAVEN org.springframework.boot:spring-boot 3.5.8
```
### 示例输出
```
# Package Audit: express@4.16.0 (NPM)
> ### ❌ BLOCKED — Security Policy Violation
## 快速参考
| Category | Status |
| :--- | :--- |
| 📜 License | ✅ MIT — Compliant |
| 🐛 Vulnerabilities | ❌ 2 Vulns (1 High) |
| 📊 OpenSSF Scorecard | 🟢 7.5/10 |
## 🚀 自动化修复
> 💡 Official patches are available. Upgrade to `4.21.2`:
npm install express@4.21.2
```
### 机器可读输出与 CI
对于流水线，请输出结构化数据，而不是 Markdown 报告：
```
node dist/cli.js NPM express 4.16.0 --json # structured CheckResult
node dist/cli.js NPM express 4.16.0 --sarif # SARIF 2.1.0 for GitHub Code Scanning
```
退出代码是确定性的，因此 CI 门禁只需一行代码：
- `0` — 通过
- `1` — 被策略拦截 **或** 无法验证（失败即拒绝）
- `2` — 工具本身运行失败（用法/意外错误）
```
# .github/workflows/security.yml (示例)
- name: Audit a dependency with Hawkeye
run: node dist/cli.js NPM express 4.16.0 --sarif > hawkeye.sarif
- name: Upload to GitHub Code Scanning
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: hawkeye.sarif
```
### 全项目扫描
一次性审计项目清单中声明的每个依赖项：
```
node dist/cli.js scan . # scan the current directory
node dist/cli.js scan ./my-app # scan a specific path
node dist/cli.js scan . --sarif > hawkeye.sarif
```
`scan` 会自动检测 `package.json` (NPM) 和 `requirements.txt` (PyPI)，对每个依赖项进行审计，并返回汇总判定结果以及相同的失败即拒绝退出代码 (`0` / `1` / `2`)。`--json` 和 `--sarif` 在这里同样适用。
## 🤖 技能 + CLI 集成
Hawkeye 旨在作为本地 CLI 审计器运行，同时 AI 助手的行为由工作区技能指令控制。
### CLI 命令
直接使用构建好的 CLI 进行确定性安全检查：
```
node dist/cli.js NPM lodash
node dist/cli.js PYPI requests 2.31.0
node dist/cli.js GO github.com/gin-gonic/gin
```
### 💬 对话式 UX 与两步护栏
连接完成后，请将您的工作区技能保留在 [.github/skills/hawkeye-agent/SKILL.md](.github/skills/hawkeye-agent/SKILL.md)。这会将您的 LLM 转化为 **Hawkeye**，一位企业级安全专家。
### 演示 GIF（提问 -> 集成报告）
下面的演示展示了核心体验：提出一个问题，获得一份集成的安全报告。
Hawkeye 的主要交互模式是一种**两步式对话护栏**，专为真实的开发者对话而构建：
1. **第一步：拦截与审计：** 当您尝试安装包或询问相关信息时，Hawkeye 会拦截该意图，运行 CLI 审计流程，并返回全面的安全报告。**此时它还不会安装该包。**
2. **第二步：批准与执行：** 如果该包已获批准，只需重复命令或告诉 Hawkeye “继续”。Hawkeye 会识别出该包是安全的，并实际执行安装。
### 为什么这是核心体验
大多数工具要求开发者拼凑多个输出结果。Hawkeye 针对的是“一个问题对应一份集成报告”的优化：
- 在单次响应中结合许可证、漏洞、scorecard、SBOM、策略判定和修复建议
- 在执行任何安装操作前，给出明确的通过/拦截决定
- 保持确定性的自然语言交互（由 CLI 支撑的检查）
### 示例对话流
```
Developer: Is lodash safe for our project?
Hawkeye: [returns full integrated audit report]
Developer: npm install lodash
Hawkeye: Choose mode -> (1) Security report first (2) Direct install now
Developer: 1
Hawkeye: [returns full integrated audit report with policy verdict and remediation]
```
**您可以要求 Hawkeye：**
- **安装前审计：** `npm install express`
- **检查包安全性：** “lodash 安全吗？”，“requests 有漏洞吗？”
- **查询许可证信息：** “这个包的许可证是什么？”，“我们可以使用 GPL 的包吗？”
- **寻找安全的替代方案：** “moment 有哪些安全的替代品？”
- **检查企业策略：** “公司的开源策略是什么？”
## 🏛️ 策略配置
Hawkeye 使用工作目录中的 `.audit-agent.yaml` 文件来强制执行合规性。如果未找到，则会回退到内置的 `policy.json`。
```
policy:
organizationName: "Your Organization"
blockedLicenses:
- "GPL-2.0-only"
- "GPL-3.0-only"
- "AGPL-3.0-only"
- "SSPL-1.0"
- "BUSL-1.1"
minScorecardScore: 4.0
blockVulnerabilities: true
minBlockingSeverity: "MEDIUM" # CRITICAL | HIGH | MEDIUM | LOW — lowest severity that blocks (default MEDIUM)
blockDeprecated: true
exceptionFormUrl: "https://your-org.com/oss-exception-request"
```
## 🗺️ 路线图
我们的战略和定位详见 **[docs/VISION.md](docs/VISION.md)**；实时的、与 issue 关联的路线图在 **[docs/ROADMAP.md](docs/ROADMAP.md)** 中。概览如下：
| 里程碑 | 重点 | 状态 |
| :--- | :--- | :--- |
| **v1.1 — 可信核心** | 失败即拒绝的 `SAFE` / `BLOCKED` / `UNKNOWN` 判定、请求超时与重试、独立的退出代码、有界并发 + OSV 批处理、36 项测试套件 | ✅ 已发布 |
| **v1.2 — 适配 CI 的集成** | `--json` / `--sarif` 输出，支持 SPDX 的许可证匹配，可配置的严重性阈值 | 🔜 进行中 |
| **v1.3 — 贴近开发者** | `hawkeye scan`（整个仓库），官方 GitHub Action + PR 评论机器人，无缝的 `npx` / Docker / pre-commit | 🚀 计划中 |
| **v2.0 — AI-Agent 护栏** | MCP 强制执行门禁，AI 辅助的修复 PR，恶意软件/域名抢注检测，共享策略注册表 | 🔮 计划中 |
## 🏆 为什么选择 Hawkeye？
| 能力 | Hawkeye | Snyk | Socket | npm audit | OSV-Scanner |
| :--- | :---: | :---: | :---: | :---: | :---: |
| 许可证扫描 | ✅ | ✅ | ✅ | ❌ | ❌ |
| 漏洞扫描 | ✅ | ✅ | ✅ | ✅ | ✅ |
| SBOM 分析 | ✅ | ✅ | ✅ | ❌ | ❌ |
| OpenSSF Scorecard | ✅ | ❌ | ❌ | ❌ | ❌ |
| AI 原生 (技能 + CLI) | ✅ ⭐ | ❌ | ❌ | ❌ | ❌ |
| 策略即代码 | ✅ | ✅ | ✅ | ❌ | ❌ |
| 免费且开源 | ✅ | 免费增值模式 | 免费增值模式 | ✅ | ✅ |
## 📄 许可证
[Apache-2.0](LICENSE)
*Hawkeye Agent：为您的软件供应链提供无可争议的高精度司线裁判。* 🎾
Hawkeye 的主要交互模式是一种**两步式对话护栏**，专为真实的开发者对话而构建：
1. **第一步：拦截与审计：** 当您尝试安装包或询问相关信息时，Hawkeye 会拦截该意图，运行 CLI 审计流程，并返回全面的安全报告。**此时它还不会安装该包。**
2. **第二步：批准与执行：** 如果该包已获批准，只需重复命令或告诉 Hawkeye “继续”。Hawkeye 会识别出该包是安全的，并实际执行安装。
### 为什么这是核心体验
大多数工具要求开发者拼凑多个输出结果。Hawkeye 针对的是“一个问题对应一份集成报告”的优化：
- 在单次响应中结合许可证、漏洞、scorecard、SBOM、策略判定和修复建议
- 在执行任何安装操作前，给出明确的通过/拦截决定
- 保持确定性的自然语言交互（由 CLI 支撑的检查）
### 示例对话流
```
Developer: Is lodash safe for our project?
Hawkeye: [returns full integrated audit report]
Developer: npm install lodash
Hawkeye: Choose mode -> (1) Security report first (2) Direct install now
Developer: 1
Hawkeye: [returns full integrated audit report with policy verdict and remediation]
```
**您可以要求 Hawkeye：**
- **安装前审计：** `npm install express`
- **检查包安全性：** “lodash 安全吗？”，“requests 有漏洞吗？”
- **查询许可证信息：** “这个包的许可证是什么？”，“我们可以使用 GPL 的包吗？”
- **寻找安全的替代方案：** “moment 有哪些安全的替代品？”
- **检查企业策略：** “公司的开源策略是什么？”
## 🏛️ 策略配置
Hawkeye 使用工作目录中的 `.audit-agent.yaml` 文件来强制执行合规性。如果未找到，则会回退到内置的 `policy.json`。
```
policy:
organizationName: "Your Organization"
blockedLicenses:
- "GPL-2.0-only"
- "GPL-3.0-only"
- "AGPL-3.0-only"
- "SSPL-1.0"
- "BUSL-1.1"
minScorecardScore: 4.0
blockVulnerabilities: true
minBlockingSeverity: "MEDIUM" # CRITICAL | HIGH | MEDIUM | LOW — lowest severity that blocks (default MEDIUM)
blockDeprecated: true
exceptionFormUrl: "https://your-org.com/oss-exception-request"
```
## 🗺️ 路线图
我们的战略和定位详见 **[docs/VISION.md](docs/VISION.md)**；实时的、与 issue 关联的路线图在 **[docs/ROADMAP.md](docs/ROADMAP.md)** 中。概览如下：
| 里程碑 | 重点 | 状态 |
| :--- | :--- | :--- |
| **v1.1 — 可信核心** | 失败即拒绝的 `SAFE` / `BLOCKED` / `UNKNOWN` 判定、请求超时与重试、独立的退出代码、有界并发 + OSV 批处理、36 项测试套件 | ✅ 已发布 |
| **v1.2 — 适配 CI 的集成** | `--json` / `--sarif` 输出，支持 SPDX 的许可证匹配，可配置的严重性阈值 | 🔜 进行中 |
| **v1.3 — 贴近开发者** | `hawkeye scan`（整个仓库），官方 GitHub Action + PR 评论机器人，无缝的 `npx` / Docker / pre-commit | 🚀 计划中 |
| **v2.0 — AI-Agent 护栏** | MCP 强制执行门禁，AI 辅助的修复 PR，恶意软件/域名抢注检测，共享策略注册表 | 🔮 计划中 |
## 🏆 为什么选择 Hawkeye？
| 能力 | Hawkeye | Snyk | Socket | npm audit | OSV-Scanner |
| :--- | :---: | :---: | :---: | :---: | :---: |
| 许可证扫描 | ✅ | ✅ | ✅ | ❌ | ❌ |
| 漏洞扫描 | ✅ | ✅ | ✅ | ✅ | ✅ |
| SBOM 分析 | ✅ | ✅ | ✅ | ❌ | ❌ |
| OpenSSF Scorecard | ✅ | ❌ | ❌ | ❌ | ❌ |
| AI 原生 (技能 + CLI) | ✅ ⭐ | ❌ | ❌ | ❌ | ❌ |
| 策略即代码 | ✅ | ✅ | ✅ | ❌ | ❌ |
| 免费且开源 | ✅ | 免费增值模式 | 免费增值模式 | ✅ | ✅ |
## 📄 许可证
[Apache-2.0](LICENSE)
*Hawkeye Agent：为您的软件供应链提供无可争议的高精度司线裁判。* 🎾标签：MITM代理, SBOM, 开源组件分析, 暗色界面, 硬件无关, 自动化攻击, 许可证合规, 软件供应链安全, 远程方法调用