内容
# checkmarx-mcp
[](https://www.npmjs.com/package/@nntndfrk/checkmarx-mcp)
[](https://github.com/nntndfrk/checkmarx-mcp/blob/main/LICENSE)
MCP 服务器为 AI 编码代理提供全程序访问 **Checkmarx One** 安全平台的能力 — 项目、扫描、发现结果以及扫描触发。
## 可用工具
| 工具 | 描述 |
|---|---|
| `health_check` | 验证与 Checkmarx One 的连接 |
| `list_projects` | 列出项目，可选名称过滤 |
| `get_project` | 通过 ID 获取完整项目详情 |
| `list_scans` | 列出按项目、状态筛选的扫描 |
| `get_scan` | 获取扫描详情（用于轮询状态） |
| `trigger_scan_git` | 从 Git 仓库 URL 启动扫描 |
| `trigger_scan_local` | 压缩并上传本地目录进行扫描 |
| `trigger_scan_image` | 按引用扫描任意公共容器镜像（容器安全） |
| `findings_summary` | 严重性分解，重新组织为 `perEngine` + 顶级 `containersCounters` / `scaContainersCounters` |
| `list_findings` | 列出具有严重性/类型/状态筛选的发现结果。支持 `type: ["containers"]`；容器发现结果包括 `imageName`、`imageTag`、`baseImage`、`packageName/Version`、`recommendedImage` 和 CVE/CVSS |
| `get_finding_details` | 完整的发现结果数据流（SAST）或 CVE 链（SCA / 容器） |
所有触发扫描的工具都接受一个 `scanTypes` 数组。有效值为：
`sast`、`sca`、`kics`、`apisec`、`secrets`、`containers`。
默认值仍为 `["sast", "sca", "kics"]` — 容器安全功能需显式开启。
## 设置
### 先决条件
- Node.js >= 18
- 具有 API 密钥的 Checkmarx One 账户
### 配置
复制 `.env.example` 并填写您的凭证：
```bash
cp .env.example .env
```
| 变量 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|
| `CHECKMARX_API_KEY` | 是 | — | IAM 的 API 密钥（刷新令牌） |
| `CHECKMARX_TENANT` | 是 | — | Checkmarx One 租户名称 |
| `CHECKMARX_BASE_URL` | 否 | `https://ast.checkmarx.net` | API 基本 URL（更改为 EU/DEU 区域） |
| `CHECKMARX_IAM_URL` | 否 | `https://iam.checkmarx.net` | IAM URL（更改为 EU/DEU 区域） |
| `CHECKMARX_PROJECT_ID` | 否 | — | 默认项目 UUID（工具接受每次调用的覆盖） |
| `TRANSPORT` | 否 | `stdio` | `stdio` 用于 CLI 客户端或 `http` 用于远程 |
| `PORT` | 否 | `3000` | HTTP 传输端口 |
| `LOG_LEVEL` | 否 | `info` | 日志详细程度（`debug`、`info`、`error`） |
### Claude 代码（npx）
```json
{
"mcpServers": {
"checkmarx": {
"command": "npx",
"args": ["-y", "@nntndfrk/checkmarx-mcp"],
"env": {
"CHECKMARX_API_KEY": "your-api-key",
"CHECKMARX_TENANT": "your-tenant"
}
}
}
}
```
### Cursor（npx）
在工作区中添加到 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"checkmarx": {
"command": "npx",
"args": ["-y", "@nntndfrk/checkmarx-mcp"],
"env": {
"CHECKMARX_API_KEY": "your-api-key",
"CHECKMARX_TENANT": "your-tenant"
}
}
}
}
```
### 从源码构建
如果从本地克隆运行，请将 `npx` 替换为 `node`，并指向编译后的文件：
```json
{
"command": "node",
"args": ["/path/to/checkmarx-mcp/dist/index.js"]
}
```
### Claude Desktop（HTTP 模式）
启动服务器：
```bash
CHECKMARX_API_KEY=your-key CHECKMARX_TENANT=your-tenant TRANSPORT=http node dist/index.js
```
然后配置 Claude Desktop 连接到 `http://localhost:3000/mcp`。
### Docker
```bash
docker build -t checkmarx-mcp .
docker run -p 3000:3000 \
-e CHECKMARX_API_KEY=your-key \
-e CHECKMARX_TENANT=your-tenant \
-e CHECKMARX_BASE_URL=https://eu.ast.checkmarx.net \
-e CHECKMARX_IAM_URL=https://eu.iam.checkmarx.net \
checkmarx-mcp
```
## 开发
```bash
# 安装依赖
npm install
# 以开发模式运行（stdio）
CHECKMARX_API_KEY=your-key CHECKMARX_TENANT=your-tenant npm run dev
# 编译生产环境代码
npm run build
# 运行测试
npm test
# 类型检查
npm run typecheck
# 校验和格式化
npm run lint
npm run format
```
## 示例提示
### 快速安全概览
> "检查 Checkmarx 连接，列出我的项目，并显示最新完成扫描的发现结果摘要。"
### 扫描本地代码
> "使用 Checkmarx 扫描当前目录的漏洞。"
### 扫描 Git 仓库
> "扫描 https://github.com/org/repo 的 main 分支，启用 SAST 和 SCA。"
### 分类关键发现结果
> "显示我的应用项目最新扫描的所有关键和高级发现结果。对于每个 SAST 发现结果，显示数据流。"
### 比较扫描结果
> "比较项目 my-api 的两次最近扫描的发现结果。有什么新的，什么已修复？"
### 修复漏洞
> "获取扫描 ABC 中发现结果 XYZ 的完整数据流，然后根据源和汇建议代码修复。"
### SCA 依赖审计
> "列出最新扫描的所有 SCA 发现结果。按包分组，并显示哪些包有推荐的修复版本。"
### 按状态筛选
> "显示最新扫描中标记为待验证的所有发现结果。帮助我将其分类为已确认或不可利用。"
### 基础设施即代码审查
> "列出最新扫描的所有 KICS 发现结果。按平台（Terraform、Dockerfile、K8s）和严重性分组。"
### 监控扫描进度
> "触发当前目录的仅 SAST 扫描，然后轮询直到它完成并显示结果。"
### 扫描基本镜像的 CVE
> "扫描 nginx:1.27-alpine-slim 并告诉我其中有哪些 CVE。优先显示高和关键级别。"
### 审查仓库中的 Dockerfile 基本镜像
> "扫描此仓库，包括容器安全功能，然后列出按基本镜像分组的容器发现结果，并推荐升级。"
## 容器安全
MCP 公开 Checkmarx One 容器安全引擎，分为两种：
### 基于 Dockerfile（在仓库/本地扫描内）
在触发包含 `Dockerfile` 的代码扫描时，将 `"containers"` 添加到 `scanTypes`。Checkmarx 将解析每个 `FROM` 镜像，提取其包库存，并标记这些基本镜像层中的 CVE。
```text
trigger_scan_local({
directory: "/path/to/app",
scanTypes: ["sast", "sca", "kics", "containers"]
})
```
当请求 `sca` 和 `containers` 时，MCP 会自动在 SCA 引擎上发出 `enableContainersScan: "false"`（根据 Checkmarx 文档），以便两个引擎不会重复报告基本镜像包。
### 仅镜像（无需 Dockerfile）
`trigger_scan_image` 通过合成最小的 Docker 上下文（`FROM <image>`）并上传来扫描任何公共镜像引用。它适用于任何公共注册表 — Docker Hub、GHCR、公共 ECR、Quay。
```text
trigger_scan_image({ image: "nginx:1.27-alpine-slim" })
trigger_scan_image({ image: "ghcr.io/org/app:v1" })
trigger_scan_image({ image: "nginx@sha256:<digest>" })
```
对于 **私有注册表**，请在 Checkmarx One 中配置私有注册表集成。MCP 不使用本地 `docker pull`。
## 故障排除
**启动时“配置无效”** — 检查是否设置了 `CHECKMARX_API_KEY` 和 `CHECKMARX_TENANT`。参见 `.env.example` 获取所有可用选项。
**“身份验证失败：invalid_grant”** — 您的 API 密钥可能已过期。在 Checkmarx One 的 IAM > API 密钥下生成一个新的。
**“健康检查失败”** — 验证 `CHECKMARX_BASE_URL` 是否与您的区域匹配（美国：`ast.checkmarx.net`，欧盟：`eu.ast.checkmarx.net`）。
**扫描卡在“Queued”状态** — 对于大型队列，这是正常的。使用 `get_scan` 进行轮询。扫描通常在几分钟内开始。
## 许可证
MIT
