sairintechnologycom/pkgsafe
GitHub: sairintechnologycom/pkgsafe
一款面向 AI 编程代理与开发者的本地优先供应链防火墙，在安装前校验软件包的安全风险并输出拦截决策。
Stars: 0 | Forks: 0
# PkgSafe
**面向 AI 编程代理——及其开发者——的供应链防火墙。**
编程代理现在会自行运行 `npm install` 和 `pip install`，并且
“slopsquatting”（攻击者提前注册了 LLM 幻觉产生的包名）是一种真实的攻击手段。PkgSafe 会在安装包*之前*对其进行检查——对照 OSV 安全通告、生命周期脚本分析、域名抢注启发式检测以及你的策略——并返回明确的 **allow / warn / block** 决定。它在本地运行并使用 **MCP** 协议，因此你的代理必须先询问 PkgSafe。
## 快速开始
安装——单一静态二进制文件，无 CGo，无运行时依赖：
```
curl -fsSL https://raw.githubusercontent.com/sairintechnologycom/pkgsafe/main/scripts/install-remote.sh | bash
```
安装程序会下载适合你 OS/架构 的已签名发行版，并验证其 SHA-256 校验和。想手动安装或进行完整的签名验证？请参阅下方的[安装](#install)。
在安装前扫描包：
```
pkgsafe scan-npm-package axios
```
捕获运行可疑安装钩子的包：
```
$ pkgsafe scan-local-npm ./testdata/npm/postinstall-curl --mode block
Decision: BLOCK
Package: npm/postinstall-curl-example@1.0.0
Risk Score: 65/100
Reasons:
- [medium +20] lifecycle_script_present: Package defines a postinstall script
- [high +30] network_command_in_lifecycle: Lifecycle script uses curl
Recommended Action: Do not install this package.
```
保护 AI 代理——在 Claude Code 或 Cursor 中将 PkgSafe 添加为 MCP 服务器：
```
{
"mcpServers": {
"pkgsafe": { "command": "pkgsafe", "args": ["mcp", "serve"] }
}
}
```
代理现在必须在安装任何内容之前调用 `validate_package_install`：
`BLOCK` 表示禁止安装，`WARN` 表示先询问人类。
## 安装
PkgSafe 是一个单一的静态二进制文件（无 CGo）。npm 和 PyPI 包及 lockfile 扫描属于 GA 生产范围；Go 和 Cargo 仍处于预览覆盖阶段，尚未达到 GA 同等水平。
安装已发布的发行版：
```
VERSION=1.6.0
OS=linux
ARCH=amd64
curl -LO "https://github.com/sairintechnologycom/pkgsafe/releases/download/v${VERSION}/pkgsafe_${VERSION}_${OS}_${ARCH}.tar.gz"
tar -xzf "pkgsafe_${VERSION}_${OS}_${ARCH}.tar.gz"
sudo mv pkgsafe /usr/local/bin/
pkgsafe version
pkgsafe doctor
```
有关 macOS arm64、macOS amd64、Linux amd64 和 Windows zip 的示例，请参阅 [docs/install.md](docs/install.md)。
发行版压缩包会附带 `checksums.txt`、cosign 签名、GitHub Artifact Attestations 以及每个压缩包的 SBOM。在信任二进制文件之前，请先进行验证：
```
curl -LO "https://github.com/sairintechnologycom/pkgsafe/releases/download/v${VERSION}/checksums.txt"
curl -LO "https://github.com/sairintechnologycom/pkgsafe/releases/download/v${VERSION}/checksums.txt.sig"
curl -LO "https://github.com/sairintechnologycom/pkgsafe/releases/download/v${VERSION}/checksums.txt.pem"
sha256sum -c checksums.txt
cosign verify-blob \
--certificate checksums.txt.pem --signature checksums.txt.sig \
--certificate-identity-regexp 'https://github.com/.*/pkgsafe/.*' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
checksums.txt
gh attestation verify "pkgsafe_${VERSION}_${OS}_${ARCH}.tar.gz" --repo sairintechnologycom/pkgsafe
```
完整的发行版检查记录在
[docs/release-verification.md](docs/release-verification.md) 中。
**从源码构建**（Go 1.25+）：
```
go install github.com/sairintechnologycom/pkgsafe/cmd/pkgsafe@latest
# 或者，从 clone 中运行，并在其中内置 version metadata：
make build && ./dist/pkgsafe version
```
## 命令
```
pkgsafe scan-local-npm ./testdata/npm/safe-package
pkgsafe scan-npm-package axios
pkgsafe scan-npm-package lodash --json
pkgsafe scan-npm-package some-package --version 1.2.3
pkgsafe scan-npm-package axios --policy ./default-policy.yaml
pkgsafe scan-npm-package axios --mode audit
pkgsafe scan-npm-package axios --mode warn
pkgsafe scan-npm-package axios --mode block
pkgsafe scan-lockfile ./package-lock.json
pkgsafe explain axios
pkgsafe npm-install axios --mode warn
pkgsafe mcp serve
```
`scan-npm-package` 会从 npm registry 获取元数据，在未提供版本时解析 `latest`，将选定的 tarball 下载到本地缓存中，在存在时验证 npm 的完整性/shasum 元数据，安全地提取 `package/package.json`，并复用 npm 静态分析器。
## 决定
PkgSafe 会返回以下结果之一：
- `allow`：低风险
- `warn`：有可疑信号，建议开发者确认
- `block`：严重行为，例如访问凭证路径、已知恶意软件或有强烈的数据外泄迹象
## 策略与模式
省略 `--policy` 时，PkgSafe 会使用内置的默认策略。你可以通过 YAML 策略调整阈值、受信任和被阻止的 npm 包、受保护的凭证路径以及每条规则的评分：
```
pkgsafe scan-npm-package axios --policy ./default-policy.yaml
pkgsafe scan-local-npm ./testdata/npm/postinstall-curl --policy ./default-policy.yaml --mode audit
```
模式用于控制执行措辞，但不会隐藏底层的风险判定：
- `audit`：报告决定，但从不强制阻止
- `warn`：默认模式；对可疑包发出警告，并阻止严重发现
- `block`：严格模式；达到或超过阻止阈值的包不应被安装
人类可读的输出示例：
```
Decision: WARN
Mode: WARN
Enforcement: User review recommended
Package: npm/example-package@1.2.3
Risk Score: 62/100
Reasons:
- [medium +20] lifecycle_script_present: Package defines a postinstall script
- [high +30] network_command_in_lifecycle: Lifecycle script uses curl
Recommended Action:
Review package before installing.
```
## 构建
```
make test
make build
make package
```
构建产物将写入 `dist/`。
## MCP 工具
启动兼容 MCP 的 stdio 服务器：
```
pkgsafe mcp serve
```
PkgSafe 使用标准 MCP：`initialize`，然后通过 `tools/list` 发现工具，接着通过 `tools/call` 调用其中一个。包安全工具通过 `tools/call` 暴露（而不是作为顶级的 JSON-RPC 方法）。
示例：询问 PkgSafe AI 代理是否应该安装某个包：
```
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"validate_package_install","arguments":{"ecosystem":"npm","name":"axios","requested_by":"ai_agent"}}}
```
可用的 MCP 工具包括 `validate_package_install`、
`validate_install_command`（验证完整的 `npm install …` / `pip install …` 字符串）、`suggest_safe_alternative`（针对有风险、未知或幻觉产生的包名）、`explain_package_risk`、`score_lockfile` 以及治理/审计报告。运行 `tools/list` 可获取完整的、自描述的 schema。
CLI JSON 输出使用稳定的扫描契约：
```
{
"ecosystem": "npm",
"package": "example-package",
"version": "1.2.3",
"mode": "warn",
"decision": "warn",
"risk_score": 62,
"thresholds": {
"allow_max_score": 29,
"warn_max_score": 69,
"block_min_score": 70
},
"reasons": [
{
"rule_id": "lifecycle_script_present",
"severity": "medium",
"score": 20,
"message": "Package defines a postinstall script"
}
],
"recommended_action": "Review package before installing."
}
```
## 能力矩阵
PkgSafe GA 版本涵盖了 npm 和 PyPI。不同生态系统和覆盖面的成熟度有所差异：
| 生态系统 | 元数据 + OSV | Lockfile 解析 | 产物/内容分析 |
|-----------|:--:|:--:|:--:|
| **npm** | 生产就绪的 GA v1 范围 | ✅ `package-lock.json` | ✅ tarball + 生命周期启发式检测 |
| **PyPI** | GA（pip 平级的解析、大型产物上限、真实仓库验证） | ✅ `requirements.txt`（包含 `--hash`）、`pyproject.toml`、`poetry.lock`、`uv.lock`、`Pipfile`、`Pipfile.lock` 并带有清单去重（conda 为占位实现） | ⚠️ wheel + sdist 静态分析（RECORD、字节码、构建后端）；无行为分析 |
| **Go** | 预览版 | ✅ `go.mod`/`go.sum` | ❌ 仅元数据 |
| **Cargo** | 预览版 | ✅ `Cargo.lock` | ❌ 仅元数据 |
覆盖面：CLI、REST API、MCP stdio 服务器、GitHub Action、策略引擎、离线情报包以及本地证据包。
## 运维说明
**本地优先，但参考数据需要网络。** OSV 安全通告数据在线获取并缓存在本地 SQLite DB 中。`pkgsafe update-db --ecosystem all`
会执行真正的 OSV 批量同步，以便你随后可以进行离线扫描；在某个包被同步/缓存之前，对其进行 `--offline` 扫描将会失败或发出警告，而不是静默放行。OSV 查询**采用失败封闭原则** —— 网络/速率限制错误会显式暴露 `vulnerability_data_unavailable` 状态，而不是将包评为无风险。
对于物理隔离环境，可以通过 `pkgsafe db export-bundle`、`pkgsafe db verify-bundle` 和
`pkgsafe db import-bundle` 导出、验证并导入已签名的安全通告包；请参阅
[docs/offline-intelligence-bundle.md](docs/offline-intelligence-bundle.md)。
**行为分析默认禁用，必须显式请求才能使用。**
仅在可丢弃的环境中使用 `--behavior heuristic`：它会在宿主机上运行生命周期脚本，且**没有 OS 隔离**；检测基于模式/金丝雀机制，并且不强制执行 `network_mode`。`--behavior isolated` 通过 bubblewrap 在 Linux user/mount/pid/ipc/uts/network namespace 中运行生命周期脚本，且**默认禁用网络（强制执行）**；它需要 `bwrap` 和非特权用户 namespace，否则会报告不可用，并且绝对不会回退到宿主机执行。隔离减少了宿主机的暴露风险，但仍会共享宿主机内核。请勿将启发式模式称为沙箱或容器化。请参阅
[docs/behavior-analysis.md](docs/behavior-analysis.md)。
**真实的仓库验证是 GA 发布的关卡。** 使用
`pkgsafe test benchmark --repo-list benchmarks/real-repos.json --json` 以及
`pkgsafe report beta-evidence --repo-list benchmarks/real-repos.json` 或
`pkgsafe report ga-evidence --repo-list benchmarks/real-repos.json --output pkgsafe-ga-evidence.zip`
来构建证据。当真实仓库验证、发行版签名、出处、SBOM 或校验和验证低于阈值时，生产就绪报告会明确指出 GA 阻碍项。
**REST API 默认仅限回环接口且无需身份验证。** 它绑定到 localhost，旨在用于本地工具。目前没有 TLS、请求速率限制或正文大小上限——在服务加固里程碑达成之前，**请勿在非回环接口上暴露它**。即使在 localhost 上，也要设置 bearer token（`--token`）以实现深度防御。
**依赖项。** 纯 Go 编写，无 CGo 构建。使用少量经过审查的外部模块（例如 `modernc.org/sqlite`、`gopkg.in/yaml.v3`）；详见 `go.mod`。
标签：AI代码助手, DevSecOps, EVTX分析, Go, MCP, Ruby工具, 上游代理, 依赖安全, 域名收集, 搜索语句（dork）, 日志审计