# API 安全扫描器
一个开源、零依赖的基于 Python 的 **API 安全扫描器**，通过全面的静态分析来发现、审计和报告 **REST、GraphQL、gRPC、OpenAPI 规范和 API 网关配置** 中的 API 安全漏洞和配置错误 —— 映射到 **OWASP API Security Top 10 (2023)**。
**无需外部依赖** —— 在 Windows、macOS 和 Linux 上运行纯 Python 3.10+ 标准库。
## 为什么需要 API 安全？
传统的应用程序扫描器会遗漏 API 特有的威胁。本扫描器通过检测以下问题填补了这一空白：
- **失效的对象级别授权 (BOLA)** — 无所有权检查的直接 ID 引用、顺序 ID
- **失效的身份认证** — 硬编码的 JWT 密钥、弱算法、禁用验证、URL 中的 API 密钥
- **批量赋值** — 请求体直接解包到模型中、过度的数据暴露
- **不受限制的资源消耗** — 缺少速率限制、无分页、无限制上传
- **失效的功能级别授权** — 无角色检查的管理员端点、权限提升
- **敏感业务流滥用** — 登录时无 CAPTCHA、未受保护的支付流程
- **服务端请求伪造 (SSRF)** — 服务器请求中的用户可控 URL、Webhook 滥用
- **安全配置错误** — CORS 通配符、调试模式、冗长错误、TLS 问题
- **不当的资产管理** — 影子 API、已弃用的端点、暴露的文档
- **不安全的 API 消费** — 未验证的第三方响应、无超时或熔断器
- **注入** — SQL、NoSQL、命令注入、XXE、路径遍历、LDAP 注入
- **敏感信息泄露** — 硬编码的 API 密钥、密码、私钥、数据库连接字符串
- **GraphQL 风险** — 启用内省、无深度限制、批量攻击、Mutation 缺少认证
- **gRPC 风险** — 不安全通道、启用反射、无限消息大小
- **API 网关配置错误** — 无速率限制或认证的 Nginx、Kong、Envoy、AWS API Gateway
## 功能特性
- 跨 22 个类别的 **100+ 安全规则**
- **5 种合规框架** — OWASP API Top 10、PCI-DSS v4.0、GDPR、HIPAA、DORA
- **API 资产发现** — 自动检测框架、协议、认证方法、网关、数据库
- **多协议** — REST、GraphQL、gRPC、OpenAPI/Swagger、Protobuf
- **多语言** — Python、JavaScript/TypeScript、Java、Go、Ruby、PHP
- **网关配置扫描** — Nginx、Kong、Envoy、AWS API Gateway
- **K8s API 安全** — Ingress TLS、LoadBalancer 限制、NetworkPolicy、Secrets 挂载
- **3 种输出格式** — 彩色控制台、JSON、交互式 HTML
- **退出代码** — 如果存在 CRITICAL 或 HIGH 发现则返回 `1`，否则返回 `0`（对 CI/CD 友好）
- **单文件** — 整个扫描器是一个可移植的 Python 文件，无需 pip 安装
## 安全检查组 (100+ 规则)
| # | 类别 | 规则 ID | OWASP | 关键检查 |
|---|----------|----------|-------|------------|
| 1 | **BOLA** | API1-001 至 006 | API1 | 直接对象 ID 访问、无认证的路径参数、顺序 ID |
| 2 | **Broken Authentication** | API2-001 至 010 | API2 | 缺少认证装饰器、JWT 硬编码/弱/未验证、URL 中的 API 密钥、CSRF 禁用、OAuth 隐式 |
| 3 | **Property Level Auth** | API3-001 至 005 | API3 | 批量赋值、过度数据暴露、响应中的敏感字段、GraphQL 字段暴露 |
| 4 | **Resource Consumption** | API4-001 至 006 | API4 | 无速率限制、无分页、无限制上传、无超时、GraphQL 深度/复杂度 |
| 5 | **BFLA** | API5-001 至 004 | API5 | 无 RBAC 的管理员端点、权限提升、方法覆盖、未受保护的 DELETE |
| 6 | **Business Flow** | API6-001 至 003 | API6 | 登录无 CAPTCHA、未受保护的支付/结账、密码重置滥用 |
| 7 | **SSRF** | API7-001 至 004 | API7 | 服务器请求中的用户 URL、开放重定向、Webhook SSRF、文件导入 SSRF |
| 8 | **Misconfiguration** | API8-001 至 010 | API8 | CORS 通配符、调试模式、冗长错误、缺少标头、HTTP 服务、TLS 验证禁用 |
| 9 | **Inventory Management** | API9-001 至 004 | API9 | 多版本、暴露的 Swagger/文档、已弃用端点、调试端点 |
| 10 | **Unsafe Consumption** | API10-001 至 004 | API10 | 未验证的响应、无超时、无熔断器、盲目跟随重定向 |
| 11 | **Input Validation** | API-INJ-001 至 007 | — | SQL 注入、NoSQL 注入、命令注入、XSS、LDAP 注入、XXE、路径遍历 |
| 12 | **Secrets** | API-SEC-001 至 006 | — | 硬编码的 API 密钥、密码、私钥、AWS 凭证、DB 连接字符串、Bearer Token |
| 13 | **Transport / TLS** | API-TLS-001 至 004 | — | HTTP 端点、弱 TLS 版本、弱加密套件、缺少 HSTS |
| 14 | **Logging** | API-LOG-001 至 003 | — | 日志中的敏感数据、禁用日志、记录完整请求体 |
| 15 | **GraphQL** | API-GQL-001 至 005 | — | 内省、无深度限制、批量、未认证 Mutation、缺少字段认证 |
| 16 | **gRPC** | API-GRPC-001 至 004 | — | 不安全通道、反射、无认证拦截器、无限消息大小 |
| 17 | **API Gateway** | API-GW-001 至 005 | — | 无速率限制或认证的 Nginx/Kong/Envoy/AWS |
| 18 | **Environment Secrets** | API-ENV-001 至 006 | — | .env 中的 API 密钥、DB 密码、JWT 密钥、OAuth 密钥、调试模式 |
| 19 | **Container Security** | API-DOCKER-001 至 004 | — | Root 用户、Dockerfile 中的密钥、未版本化的基础镜像、暴露 HTTP 端口 |
| 20 | **K8s API Security** | API-K8S-001 至 005 | — | Ingress 无 TLS、LoadBalancer 开放、无 NetworkPolicy、无限制、Secret 作为环境变量 |
| 21 | **OpenAPI Spec** | API-SPEC-001 至 005 | — | 无安全方案、查询中的 API 密钥、缺少响应模式、HTTP 服务器 URL |
| 22 | **Protobuf** | API-PROTO-001 至 002 | — | 敏感字段无注解、RPC 无认证 |
## 合规框架
每个发现都映射到适用的合规框架：
| 框架 | 范围 |
|-----------|-------|
| **OWASP API Top 10 (2023)** | API1 至 API10 — API 安全的行业标准 |
| **PCI-DSS v4.0** | 支付卡数据保护 |
| **GDPR** | 欧盟数据隐私法规 |
| **HIPAA** | 医疗数据保护 |
| **DORA** | 数字运营弹性（金融领域） |
## 前置条件
- **Python 3.10 或更高版本** — 使用 `python --version` 或 `python3 --version` 检查
- **无需 pip 安装** — 仅需 Python 标准库
## 安装
### 选项 1：克隆仓库
```
git clone https://github.com/Krishcalin/API-Security.git
cd API-Security
```
### 选项 2：下载扫描器文件
```
curl -O https://raw.githubusercontent.com/Krishcalin/API-Security/main/api_security_scanner.py
```
### 验证是否正常工作
```
python api_security_scanner.py --version
# API Security Scanner v1.0.0
```
## 快速开始
### 1. 扫描您的 API 项目
```
# 扫描整个项目目录
python api_security_scanner.py /path/to/your/api-project
# 扫描单个文件
python api_security_scanner.py /path/to/your/app.py
```
### 2. 生成报告
```
# JSON 报告（机器可解析，用于 CI/CD）
python api_security_scanner.py ./my-api --json report.json
# HTML 报告（交互式，用于利益相关者）
python api_security_scanner.py ./my-api --html report.html
# 同时生成两种报告
python api_security_scanner.py ./my-api --json report.json --html report.html
```
### 3. 按严重程度筛选
```
# 仅 CRITICAL 和 HIGH
python api_security_scanner.py ./my-api --severity HIGH
# 仅 CRITICAL
python api_security_scanner.py ./my-api --severity CRITICAL
```
### 4. 详细模式
```
python api_security_scanner.py ./my-api --verbose
```
## 使用方法
### CLI 参考
```
usage: api_security_scanner.py [-h] [--json FILE] [--html FILE]
[--severity {CRITICAL,HIGH,MEDIUM,LOW,INFO}]
[-v] [--version]
target
positional arguments:
target File or directory to scan
options:
-h, --help Show help message and exit
--json FILE Save JSON report to FILE
--html FILE Save HTML report to FILE
--severity SEV Minimum severity (CRITICAL, HIGH, MEDIUM, LOW, INFO)
-v, --verbose Show files being scanned
--version Show scanner version
```
### 示例
```
# 扫描当前目录
python api_security_scanner.py .
# 扫描 Flask/FastAPI 应用
python api_security_scanner.py src/api/
# 扫描 OpenAPI spec
python api_security_scanner.py openapi.yaml
# 扫描 GraphQL schema
python api_security_scanner.py schema.graphql
# 扫描 protobuf 服务定义
python api_security_scanner.py service.proto
# 扫描 Nginx API gateway 配置
python api_security_scanner.py nginx.conf
# 扫描 .env 以查找暴露的 API secrets
python api_security_scanner.py .env
# 扫描 K8s API deployment
python api_security_scanner.py k8s/api-deploy.yaml
# 包含所有输出的完整扫描
python api_security_scanner.py ./my-api --json report.json --html report.html --severity MEDIUM --verbose
```
## 扫描的文件类型
| 文件类型 | 扩展名 / 名称 | 检查内容 |
|-----------|-------------------|-----------------|
| **Python** | `.py`, `.pyw` | 所有 OWASP API T10 规则 + 注入 + 密钥 + 日志|
| **JavaScript / TypeScript** | `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` | 相同规则|
| **Java / Go / Ruby / PHP** | `.java`, `.go`, `.rb`, `.php` | 所有源代码规则|
| **GraphQL schemas** | `.graphql`, `.gql` | 5 条 GraphQL 特定规则 + BOLA + 属性认证 |
| **Protobuf** | `.proto` | 2 条 Protobuf 规则 + gRPC 安全 |
| **OpenAPI / Swagger** | `.yaml`, `.yml`, `.json` | 5 条 OpenAPI 规范规则（通过内容自动检测） |
| **Nginx / Gateway configs** | `nginx.conf`, `*.conf` | 5 条网关规则 + 配置错误 + TLS |
| **Environment files** | `.env`, `.env.*` | 6 条关于 API 密钥、DB 密码、JWT 密钥、调试模式的规则 |
| **Dockerfiles** | `Dockerfile`, `*.dockerfile` | 4 条容器安全规则 |
| **K8s manifests** | `.yaml`, `.yml` | 5 条 K8s API 规则|
## API 资产发现
扫描器会自动发现并报告代码库中的 API 组件：
| 类别 | 检测项 |
|----------|----------------|
| **Frameworks** | Flask, FastAPI, Django, Express, NestJS, Koa, Hapi, Spring Boot, Gin, Echo, Fiber, Actix, Rails, Laravel, Phoenix, Graphene, Strawberry, Apollo, Ariadne, Nexus |
| **Protocols** | REST, GraphQL, gRPC, SOAP, WebSocket, SSE, Protobuf, OpenAPI, Swagger |
| **Auth Methods** | JWT, OAuth2, Basic Auth, API Key, Bearer Token, SAML, mTLS, OpenID Connect, Passport.js, Auth0, Cognito, Keycloak |
| **API Gateways** | Nginx, Kong, Envoy, Traefik, Apigee, AWS API Gateway, Azure APIM, Istio |
| **Databases** | PostgreSQL, MySQL, MongoDB, Redis, Elasticsearch, DynamoDB, SQLite, Cassandra, Neo4j |
## CI/CD 集成
如果存在 CRITICAL 或 HIGH 发现，扫描器将返回退出代码 `1`：
### GitHub Actions
```
name: API Security Scan
on: [push, pull_request]
jobs:
api-security:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Run API Security Scanner
run: python api_security_scanner.py . --severity HIGH --json report.json --html report.html
- name: Upload Report
if: always()
uses: actions/upload-artifact@v4
with:
name: api-security-report
path: |
report.json
report.html
```
### GitLab CI
```
api-security-scan:
stage: test
image: python:3.12-slim
script:
- python api_security_scanner.py . --severity HIGH --json report.json --html report.html
artifacts:
paths: [report.json, report.html]
when: always
```
## 使用示例文件进行测试
```
# 针对所有测试样本运行（预期 190+ findings）
python api_security_scanner.py tests/samples/ --verbose
# 生成完整报告
python api_security_scanner.py tests/samples/ --html test-report.html --json test-report.json
```
### 测试示例文件
| 文件 | 用途 | 预期发现 |
|------|---------|-------------------|
| `vulnerable_api.py` | 不安全的 Flask API（BOLA、认证、SSRF、注入、密钥） | 100+ |
| `vulnerable_api.js` | 不安全的 Express.js API | 40+ |
| `vulnerable_openapi.yaml` | 不安全的 OpenAPI 3.x 规范 | 10+ |
| `vulnerable_api.graphql` | 不安全的 GraphQL Schema | 5+ |
| `vulnerable_api.proto` | 不安全的 gRPC protobuf | 10+ |
| `.env.api` | 暴露的 API 密钥和调试模式 | 15+ |
| `Dockerfile.api` | 不安全的 API 容器 | 5+ |
| `nginx_api.conf` | 不安全的 Nginx API 代理 | 5+ |
| `k8s_api_deploy.yaml` | 不安全的 K8s API 部署 | 5+ |
## 项目结构
```
API-Security/
├── api_security_scanner.py # Main scanner (single file, no dependencies)
├── banner.svg # Project banner
├── CLAUDE.md # Claude Code project instructions
├── LICENSE # MIT License
├── README.md # This file
├── .gitignore # Python gitignore
└── tests/
└── samples/ # Intentionally vulnerable test files
├── vulnerable_api.py
├── vulnerable_api.js
├── vulnerable_openapi.yaml
├── vulnerable_api.graphql
├── vulnerable_api.proto
├── .env.api
├── Dockerfile.api
├── nginx_api.conf
└── k8s_api_deploy.yaml
```
## 贡献
1. 在 `api_security_scanner.py` 中将规则字典添加到相应的 `*_RULES` 列表中
2. 遵循 ID 模式：`API{N}-{NNN}` (OWASP) 或 `API-{CATEGORY}-{NNN}`
3. 每条规则必须包含：`id`、`category`、`severity`、``、`pattern`、`description`、`cwe`、`recommendation`、`compliance`
4. 将测试用例添加到触发新规则的 `tests/samples/` 中
5. 运行 `python api_security_scanner.py tests/samples/ --verbose` 进行验证
## 许可证
本项目采用 MIT 许可证授权 —— 详情请参阅 [LICENSE](LICENSE) 文件。