内容
# ShipSafe
为快速交付的开发者提供的安全扫描服务。
[](https://www.npmjs.com/package/@shipsafe/cli)
[](https://shipsafe.org)
## 它能做什么
ShipSafe 在代码进入生产环境之前，捕获漏洞、硬编码的秘密和危险的依赖项。它自带 1,266 个检测规则（1,062 个漏洞 + 174 个秘密 + 30 个环境威胁模式），无需配置，即可与 Claude Code、Cursor、Windsurf、Copilot、Cline 等任何 AI 编码工具配合使用。每次扫描都在纯 TypeScript 环境中运行，无需外部二进制依赖。
## 快速开始
```bash
npm install -g @shipsafe/cli
```
就这样。一条命令即可安装 CLI、AI 助手的 MCP 服务器，并自动注册 Claude Code。在任何项目中运行 `shipsafe init`，即可安装 Git 钩子，并将 AI 指令写入编辑器配置文件。
ShipSafe 专为活跃的开发过程设计 - 它在您编写代码时捕获问题，而不是事后才发现。对于现有的代码库，运行 `shipsafe baseline` 即可快照当前发现的问题，从此只显示新增问题。
## 它能捕获什么
- **1,062 个漏洞模式** -- SQL 注入、提示注入、XSS、命令注入、路径遍历、SSRF、CSRF、原型污染、不安全加密、不安全反序列化、身份验证问题等
- **174 个秘密模式** -- AWS 密钥、GCP 服务账户、Azure令牌、GitHub PAT、Stripe 密钥、数据库 URL、JWT、私钥、OAuth 机密等 - 通过 Shannon 熵验证以减少误报
- **30 个环境威胁模式** --CLAUDE.md 中的提示注入、恶意的 MCP 服务器配置、危险的钩子、技能文件操纵、混淆指令、凭证盗窃、反弹 shell
- **依赖漏洞** -- 废弃的软件包、已知的 CVE、 typosquatting 检测、维护状态检查
## 它是如何工作的
ShipSafe 通过三个层次保护您的代码：
1. **Git 钩子** （pre-commit 和 pre-push）-- 在第一次扫描时自动安装，它们会阻止包含关键或高严重性发现的提交和推送。与任何编辑器、任何工作流配合使用。
2. **MCP 服务器** -- 通过 stdio 传输暴露 8 种工具，以便 AI 编码助手可以实时扫描、修复和查询项目的 security 状态。
3. **CLI** -- 直接用于扫描、基准现有发现、检查安装前软件包、以及管理配置的命令。
## CLI 命令
| 命令 | 描述 |
|---------|-------------|
| `shipsafe scan` | 扫描项目漏洞。选项： `--scope staged\|all\|file:<path>`， `--fix`， `--json` |
| `shipsafe init` | 在项目中初始化 ShipSafe。安装钩子，写入 AI 配置文件（CLAUDE.md，.cursorrules 等），注册 MCP 服务器 |
| `shipsafe setup` | 注册 MCP 服务器与 Claude Code、Cursor 等编辑器 |
| `shipsafe baseline` | 快照当前发现的问题，以便只报告新增问题。选项： `--show`， `--clear` |
| `shipsafe activate <key>` | 激活 Pro 或 Team 许可证密钥 |
| `shipsafe config list` | 查看当前配置 |
| `shipsafe config set <key> <value>` | 设置配置值。添加 `--global` 以进行全局设置 |
| `shipsafe audit <url>` | 审核远程 GitHub/GitLab 仓库在安装前。检查漏洞、秘密、恶意模式、混淆、安装后威胁和环境风险。选项： `--json` |
| `shipsafe scan-environment` | 扫描 Claude Code 环境中的恶意 MCP 服务器、钩子、技能和 CLAUDE.md 中的提示注入。选项： `--json` |
| `shipsafe status` | 显示项目安全状态、钩子状态和可用引擎 |
| `shipsafe connect` | 连接项目到 ShipSafe 云以进行监控 |
| `shipsafe upload-sourcemaps` | 上传源映射以进行生产错误解析 |
| `shipsafe mcp-server` | 启动 MCP 服务器（stdio 传输，由 AI 助手使用） |
## .shipsafeignore
在项目根目录中创建 `.shipsafeignore` 文件，以排除文件和目录进行扫描。使用 gitignore 样式的语法：
```gitignore
# 排除测试fixtures
tests/fixtures/
# 排除生成的文件
src/generated/
# 排除特定文件
config/legacy-secrets.ts
```
ShipSafe 还会尊重您的 `.gitignore`，默认情况下始终跳过 `node_modules`、`dist`、`.git` 和 `coverage`。
## 配置
ShipSafe 使用两个配置文件，合并后（项目覆盖全局）：
- **全局**： `~/.shipsafe/config.json`
- **项目**： `shipsafe.config.json`
```bash
# 查看当前配置
shipsafe config list
# 设置项目级配置
shipsafe config set scan.severity_threshold medium
# 设置全局配置
shipsafe config set licenseKey SS-PRO-abc123 --global
```
### 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `SHIPSAFE_API_URL` | API 端点覆盖 | `https://shipsafe-m9nc6.ondigitalocean.app` |
| `SHIPSAFE_DB_PATH` | SQLite 数据库路径（API） | `~/.shipsafe/shipsafe.db` |
## MCP 工具
ShipSafe 通过 [Model Context Protocol](https://modelcontextprotocol.io) 为 AI 编码助手暴露 8 种工具：
| 工具 | 描述 |
|------|-------------|
| `shipsafe_scan` | 对项目目录运行安全扫描 |
| `shipsafe_status` | 获取项目安全状态、钩子状态和扫描器可用性 |
| `shipsafe_check_package` | 验证 npm 软件包在安装前（typosquatting、CVE、维护） |
| `shipsafe_fix` | 为发现的问题应用自动修复（将秘密移动到 .env，建议代码修复） |
| `shipsafe_graph_query` | 查询知识图谱以获取调用者、被调用者、攻击路径、爆炸半径 |
| `shipsafe_production_errors` | 获取生产错误及其堆栈跟踪和建议的修复 |
| `shipsafe_verify_resolution` | 检查生产错误是否已解决 |
MCP 服务器在 `shipsafe init` 或 `shipsafe setup` 期间自动注册。要手动配置：
```json
{
"mcpServers": {
"shipsafe": {
"command": "npx",
"args": ["-y", "shipsafe", "mcp-server"]
}
}
}
```
## 定价
| | 免费 | Pro ($19/mo) | Team ($49/mo) |
|--|------|-------------|---------------|
| 漏洞 + 秘密扫描 | 是 | 是 | 是 |
| Git 钩子（pre-commit、pre-push） | 是 | 是 | 是 |
| 项目 | 1 | 5 | 20 |
| 知识图谱引擎 | -- | 是 | 是 |
| 自动修复（秘密到 .env） | -- | 是 | 是 |
| 生产错误监控 | -- | 是 | 是 |
| MCP 服务器工具 | -- | 是 | 是 |
| GitHub 应用（PR 检查） | -- | -- | 是 |
| 源映射解析 | -- | -- | 是 |
```bash
shipsafe activate SS-PRO-yourkeyhere
```
## 开发
需要 Node.js >= 20。
```bash
# 安装依赖
npm install
# 构建
npm run build
# 在本地运行 CLI（无需构建）
npm run dev -- scan
npm run dev -- init
npm run dev -- setup
# 运行测试
npm test
# 在监视模式下运行测试
npm run test:watch
# 类型检查不发出
npm run lint
# 在本地运行云 API
cd packages/api && npm run dev
```
### 架构
```
bin/shipsafe.ts CLI 入口点（Commander.js）
src/
engines/
builtin/ 纯 TS 模式 + 秘密 + 依赖扫描器
pattern/ 扫描器编排（Semgrep、Gitleaks、Trivy 包装器）
graph/ Tree-sitter + KuzuDB 知识图谱
cli/ CLI 命令（scan、init、activate、config、baseline 等）
mcp/ MCP 服务器 + 8 种工具（stdio 传输）
autofix/ 自动修复引擎（秘密修复、脚手架、PR 生成）
github/ GitHub 应用（webhooks、PR 扫描器、检查 API）
hooks/ Git 钩子安装程序（pre-commit、pre-push）
config/ 全局 + 项目配置管理器
claude-md/ CLAUDE.md / .cursorrules 注入管理器
packages/
api/ Hono 云 API 与 SQLite 持久性
monitor/ @shipsafe/monitor 客户端错误捕获代码段
```
### 约定
- TypeScript 严格模式，ESM 模块
- Vitest 用于测试
- 没有类 -- 普通函数和类型
- 错误作为类型化错误抛出，绝不静默吞噬
## 许可证
UNLICENSED -- ShipSafe 的专有软件。
`@shipsafe/monitor` 采用 MIT 许可证。
---
[shipsafe.org](https://shipsafe.org)
