CCS Security Scanner API

---

解决什么问题？

AI Agent 和 MCP Server 正在被大规模部署，但90% 以上的配置存在安全风险。一个错误的 URL scheme、一行硬编码的 API Key、一个缺失的鉴权机制，就可能导致：

风险类型	后果	我们的检查
🔴 凭证泄露	API Key / Token 被盗用，产生巨额费用	credential_exposure
🔴 中间人攻击	使用 HTTP 而非 HTTPS，数据被截获	tls_required
🔴 SSRF 攻击	恶意 Server 访问内网资源（169.254.169.254 等）	ssrf_protection
🟡 权限逃逸	缺少沙箱/文件系统保护，Agent 可执行任意代码	sandbox_isolation
🟡 鉴权缺失	任何人可调用你的 MCP Server	auth_required
🟡 成本失控	未设置 token/cost 限制，账单爆炸	cost_controls

CCS Security Scanner 通过 14 项自动化检查规则，覆盖 TLS、凭证、SSRF、鉴权、沙箱、错误处理、最小权限等维度，对 MCP 配置文件进行全量安全审计，输出结构化的风险评估报告。

核心特性

• ✅ 14 项安全检查：3 Critical + 3 High + 6 Medium + 2 Low，覆盖 Agent 安全全维度
• ✅ 智能评分：100 分制，自动计算安全等级（A/B/C/D/F）
• ✅ 双模式扫描：
  • config — 粘贴 MCP 配置，30秒出报告
  • repo — 输入 GitHub 仓库 URL，自动发现配置文件并深度扫描
• ✅ 结构化报告：每项发现含 severity / detail / fix / aisvs（AI 安全漏洞严重性评分）
• ✅ 生产就绪：Docker 支持、健康检查端点、OpenAPI 文档、CORS 配置
• ✅ 零依赖外部服务：纯 Python 实现，无需第三方 API

---

💎 免费使用 + 深度审计引流

本 API 免费开放基础扫描（/api/scan/config、/api/scan/repo），适合快速验证与 CI 集成。 需要完整深度审计报告（全量规则库、逐条修复建议、AI 辅助研判）时，可使用 CCS Rating 按次付费：

套餐	价格
10 次包	¥7
50 次包	¥35
200 次包	¥140

👉 前往 CCS Rating 购买：https://license-api-neuralbridge-edouhcvhbo.cn-hangzhou.fcapp.run

---

🚀 快速开始

方式一：CLI 一行命令扫描（推荐）

pip install ccs-scan

# 扫描本地 MCP 配置文件
ccs-scan ~/.config/claude/claude_desktop_config.json

# 扫描 GitHub 仓库
ccs-scan https://github.com/user/mcp-server

# JSON 输出（供程序集成）
ccs-scan config.json --json

安装完成后即有动态终端界面：实时进度条、颜色分级、分数仪表盘、风险详情面板，一目了然。

方式二：API 服务部署

git clone https://github.com/Correctover/ccs-scan-api.git
cd ccs-scan-api

# Docker 部署（推荐）
docker build -t ccs-scan-api .
docker run -d -p 8000:8000 --name ccs-scanner ccs-scan-api

# 或本地运行
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000

方式三：Railway 一键部署

1. Fork 本仓库
2. 在 Railway 中创建项目，关联此仓库
3. 自动检测 Dockerfile 并部署
4. 获得公网 URL，即可使用

---

📖 API 文档

公网 API 地址: https://ccs-scan-production.up.railway.app

健康检查

curl https://ccs-scan-production.up.railway.app/api/health

响应示例：

{
  "status": "ok",
  "version": "1.0.0",
  "scanner_checks": 14
}

扫描 MCP 配置

POST /api/scan/config
Content-Type: application/json

{
  "config_text": "你的 MCP 配置 JSON 内容",
  "format": "json"
}

响应示例：

{
  "total_checks": 14,
  "passed": 10,
  "warnings": 2,
  "failed": 2,
  "score": 60,
  "grade": "C",
  "findings": [
    {
      "id": "tls_required",
      "name": "TLS/HTTPS Required",
      "severity": "critical",
      "status": "fail",
      "detail": "URL uses plaintext HTTP: http://example.com → All data transmitted in cleartext",
      "fix": "Change URL to use HTTPS: https://example.com",
      "aisvs": 8.5
    }
  ]
}

扫描 GitHub 仓库

POST /api/scan/repo
Content-Type: application/json

{
  "repo_url": "https://github.com/user/mcp-server",
  "branch": "main",
  "scan_depth": "standard"
}

自动扫描仓库中的 mcp.json、.mcp/config.json、claude_desktop_config.json 等常见配置文件。

交互式 API 文档

启动服务后访问：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

---

💻 CLI 工具

安装

# 从 PyPI 安装（推荐）
pip install ccs-scan

# 从源码安装
git clone https://github.com/Correctover/ccs-scan-api.git
cd ccs-scan-api
pip install -e .

使用方法

# 查看版本
ccs-scan --version

# 扫描本地 MCP 配置文件
ccs-scan /path/to/claude_desktop_config.json

# 扫描 GitHub 仓库（自动克隆并查找配置文件）
ccs-scan https://github.com/user/mcp-server

# 指定分支
ccs-scan https://github.com/user/mcp-server --branch develop

# JSON 输出（供程序集成）
ccs-scan config.json --json

# 从 stdin 读取
cat config.json | ccs-scan -

# 交互式菜单（无参数时自动进入）
ccs-scan

CLI 输出示例

╭─────────────────────────────────────────────────────────╮
│     ____ ____ ____   ____                               │
│    / ___|  _ \ \ \ / /                                   │
│   | |   | |_) | \ V /                                   │
│   | |___|  _ <   | |                                   │
│    \____|_| \_\  |_|                                   │
│                                                          │
│    Security Scanner v1.0.0                               │
│    CCS Runtime Verification Framework                    │
╰─────────────────────────────────────────────────────────╯

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 🔍 Starting CCS Security Scan...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 Input: /path/to/config.json
 Mode: Local File

 ╭──────────────────────────────────────────────────────╮
 │ tls_required                ████████████░░░  85%    │
 │ credential_exposure         ████████░░░░░░░  53%    │
 │ ssrf_protection             ████████████████ 100%    │
 │ auth_required               ████████████░░░  75%    │
 └──────────────────────────────────────────────────────╯

 ╭─ 📊 Security Score ─────────────────────────────────╮
 │ ████████████░░░░░░░ 60/100  Grade: C                │
 ╰──────────────────────────────────────────────────────╯

 🔴 CRITICAL Findings (2)
 ├─ credential_exposure: API Key exposed (AKIA...)
 │  Fix: Use environment variables
 └─ tls_required: HTTP URL detected
    Fix: Change to HTTPS

CLI 参数说明

参数	说明	默认值
<input>	配置文件路径、GitHub URL 或 -（stdin）	-
--json	JSON 格式输出	false
--branch	指定 Git 分支	main
--format	输出格式：json / yaml / auto	auto
--version	显示版本号	-

---

🔍 14 项安全检查规则

🔴 Critical（致命）

#	检查项	说明
1	tls_required	所有 URL 必须使用 HTTPS，禁止 HTTP 明文传输
2	credential_exposure	配置中不得硬编码 API Key、Token、密码等敏感凭证
3	ssrf_protection	禁止访问内网地址（127.0.0.1、169.254.169.254 等元数据端点）

🟡 High（高危）

#	检查项	说明
4	auth_required	MCP Server 必须配置鉴权机制（OAuth 2.1 / API Key Header）
5	sandbox_isolation	文件系统操作需有明确的目录白名单限制
6	error_handling	必须配置错误处理策略，防止敏感信息泄露

🔵 Medium（中等）

#	检查项	说明
7	input_validation	工具参数需有类型约束和输入校验
8	logging_security	日志配置不得记录敏感数据（token、password 等）
9	timeout_config	需设置合理的超时时间，防止资源耗尽
10	cors_policy	CORS 策略不得配置为 * 通配符
11	dependency_pin	依赖版本需固定，防止供应链攻击
12	env_var_security	环境变量引用不得暴露敏感值

⚪ Low（低风险）

#	检查项	说明
13	version_spec	配置应指定版本号，确保可复现性
14	documentation	工具应包含 description 字段，便于审计追溯

---

📊 评分体系

等级	分数范围	含义
A	90-100	优秀，生产就绪
B	75-89	良好，少量改进项
C	60-74	及格，存在中等风险
D	40-59	不及格，存在高危漏洞
F	<40	危险，存在致命安全缺陷

扣分规则：Critical -20 / High -10 / Medium -5 / Low -2（warn 状态减半）

---

🐳 部署

Docker

docker build -t ccs-scan-api .
docker run -d -p 8000:8000 ccs-scan-api

Dockerfile 内置健康检查：每 30 秒访问 /api/health，连续 3 次失败则重启容器。

环境变量

变量	说明	默认值
PORT	服务端口	8000
ALLOWED_ORIGINS	CORS 允许的源，逗号分隔	*
GITHUB_TOKEN	GitHub PAT（可选，用于扫描私有仓库）	-
MAX_REPO_SIZE_MB	仓库克隆最大体积	100
SCAN_TIMEOUT_SEC	单次扫描超时	60
SCAN_API_KEY	最小鉴权密钥（设置后 /api/scan/* 需携带 Authorization: Bearer <key>；未设置则保持开放，默认兼容）	-

平台部署指南

平台	方式	预计费用
Railway	关联 GitHub 仓库，自动构建部署	免费额度 $5/月
Render	Docker 部署，自动 HTTPS	免费（ spins down after 15min）
阿里云	ECS + Docker	~¥50/月起
Vercel	需适配 Serverless 函数	免费额度

---

🔗 生态集成

• correctover-scan — NPM CLI 版本，本地扫描
• correctover-mcp-server — CCS 原生 MCP Server
• correctover-scan-action — GitHub Action CI/CD 集成
• correctover-scan-vscode — VS Code 扩展，编辑器内实时检查

---

📜 标准与合规

CCS Security Scanner 的检查规则基于 CCS（Component Compatibility Specification） 运行时验证标准：

• 📄 IETF Internet-Draft: CCS Runtime Verification
• 📦 DOI: 10.5281/zenodo.21783723
• 📐 CCS 标准规范

---

📄 License

Proprietary Commercial License. See LICENSE for details.

---