Metadata-Version: 2.4
Name: ccs-scan-runtime
Version: 1.0.1
Summary: CCS Security Scanner runtime — 部署用包（含 main/mcp_server/scanner_engine）
Author-email: Correctover <wangguigui@correctover.com>
License: Proprietary
Project-URL: Homepage, https://correctover.com
Project-URL: Repository, https://github.com/Correctover/ccs-scan-api
Keywords: mcp,security,agent,scanner,audit,ccs
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0.0
Requires-Dist: pyyaml>=6.0
Dynamic: license-file

# CCS Security Scanner API

<div align="center">

**🛡️ 一键检测 AI Agent / MCP Server 的安全风险，30秒出报告**

[![License](https://img.shields.io/badge/license-Proprietary-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green.svg)](https://fastapi.tiangolo.com/)
[![PyPI](https://img.shields.io/badge/pip_install-ccs--scan-blue.svg)](https://pypi.org/project/ccs-scan/)
[![Live API](https://img.shields.io/badge/Live_API-在线-brightgreen.svg)](https://ccs-scan-production.up.railway.app/api/health)
[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](Dockerfile)

[🚀 快速开始](#-快速开始) · [💻 CLI 工具](#-cli-工具) · [📖 API文档](#-api-文档) · [🔍 检查项说明](#-14-项安全检查规则) · [🐳 部署](#-部署)

</div>

---

## 解决什么问题？

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 一行命令扫描（推荐）

```bash
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 服务部署

```bash
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 一键部署

[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template)

1. Fork 本仓库
2. 在 [Railway](https://railway.app) 中创建项目，关联此仓库
3. 自动检测 `Dockerfile` 并部署
4. 获得公网 URL，即可使用

---

## 📖 API 文档

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

### 健康检查

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

响应示例：
```json
{
  "status": "ok",
  "version": "1.0.0",
  "scanner_checks": 14
}
```

### 扫描 MCP 配置

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

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

响应示例：
```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 仓库

```bash
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 工具

### 安装

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

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

### 使用方法

```bash
# 查看版本
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

```bash
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](https://www.npmjs.com/package/correctover-scan)** — NPM CLI 版本，本地扫描
- **[correctover-mcp-server](https://github.com/Correctover/correctover-mcp-server)** — CCS 原生 MCP Server
- **[correctover-scan-action](https://github.com/Correctover/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](https://datatracker.ietf.org/doc/draft-wang-ccs-runtime-verification/)
- 📦 [DOI: 10.5281/zenodo.21783723](https://doi.org/10.5281/zenodo.21783723)
- 📐 [CCS 标准规范](https://correctover.com)

---

## 📄 License

Proprietary Commercial License. See [LICENSE](LICENSE) for details.

---

<div align="center">

**Correctover — Runtime Verification for Agent Systems**

[Website](https://correctover.com) · [GitHub](https://github.com/Correctover) · [Contact](mailto:wangguigui@correctover.com)

</div>
