Bommalimallesu/api-security-observatory
GitHub: Bommalimallesu/api-security-observatory
一个融合 Kong 网关防护、API 风险评分与 Grafana 可观测性技术栈的防御性 API 安全实验室。
Stars: 0 | Forks: 0
# API 安全观测台
### 主动 API 拦截、API 风险评分与 SOC 风格可观测性实验室
一个使用 Kong Gateway、Flask、Prometheus、Loki、Promtail 和 Grafana 构建的防御性 API 安全实验室。
## 概述
**API Security Observatory** 是一个基于本地 Docker 的网络安全项目，演示了如何使用现代网关和可观测性技术栈来保护、监控、评分、记录和调查 API 流量。
该项目将 **Kong API Gateway** 部署在 Flask API 的前端，对受保护的路由应用 API 密钥认证，在网关层拦截可疑的请求模式，生成 API 风险评分，并使用 **Grafana、Loki、Promtail 和 Prometheus** 将日志和指标发送到 SOC 风格的监控工作流中。
本仓库旨在作为一个专业的作品集实验室，专注于 API 安全、检测工程和 DevSecOps 风格的验证。
## 核心能力
| 领域 | 能力 |
| -------------------- | ---------------------------------------------------------------------- |
| API 网关安全 | Kong 路由、API 密钥认证、限流、请求过滤 |
| 主动拦截 | 针对可疑 payload 特征的网关层拦截 |
| API 风险评分 | 基于规则的传入 API 请求风险评分 |
| 可观测性 | 集中式日志、指标和仪表盘可见性 |
| SOC 监控 | 拦截攻击源、调查工作流和告警逻辑 |
| 验证证据 | Curl、Burp Suite 和 OWASP ZAP 风格的验证文档 |
| 合规性支持 | 基于证据的报告和安全控制文档 |
| 项目审计 | 仓库清理、编码检查、链接检查和质量审查 |
## 本地验证行为
| 验证测试 | 结果 |
| ------------------------------------------------ | -------- |
| Docker 技术栈成功启动 | 已验证 |
| Kong Gateway 运行健康 | 已验证 |
| 公开 `/health` 路由无需 API 密钥即可访问 | 已验证 |
| 受保护的 `/api/echo` 路由需要 API 密钥 | 已验证 |
| 有效的 API 密钥成功到达 Flask API | 已验证 |
| 正常请求返回 LOW 风险评分 | 已验证 |
| SQL 注入关键字 `UNION` 被 Kong 拦截 | 已验证 |
| 可观测性技术栈容器成功运行 | 已验证 |
## 架构
GitHub 架构图像的推荐视觉比例为：**1:1.618**，大约为 **3:5**。
建议的 Banner 尺寸：
```
1200 x 742 px
1500 x 927 px
```
```
flowchart LR
Client["Client / Tester"] --> Kong["Kong API Gateway"]
Kong --> Route["Route Matching"]
Route --> Auth["API Key Authentication"]
Auth --> RateLimit["Rate Limiting"]
RateLimit --> Blocker["Active Blocking Logic"]
Blocker -->|Allowed Request| API["Flask API Service"]
Blocker -->|Blocked Request| Deny["403 Blocked Response"]
API --> Risk["Risk Scoring Engine"]
Risk --> Response["JSON Response"]
Kong --> KongLogs["Kong Logs"]
API --> AppLogs["Application Logs"]
KongLogs --> Promtail["Promtail"]
AppLogs --> Promtail
Promtail --> Loki["Loki"]
Kong --> Metrics["Gateway Metrics"]
Metrics --> Prometheus["Prometheus"]
Loki --> Grafana["Grafana Dashboards"]
Prometheus --> Grafana
Grafana --> SOC["SOC-Style Monitoring View"]
```
## 安全事件流
```
sequenceDiagram
participant Client as Client
participant Kong as Kong Gateway
participant Blocker as Blocking Logic
participant API as Flask API
participant Risk as Risk Engine
participant Logs as Loki / Grafana
Client->>Kong: Send HTTP request
Kong->>Kong: Match route
alt Public health route
Kong-->>Client: Health response
else Protected API route
Kong->>Kong: Validate API key
Kong->>Blocker: Inspect request payload
alt Suspicious pattern detected
Blocker-->>Client: 403 blocked response
Blocker->>Logs: Store blocked attack event
else Request allowed
Kong->>API: Forward request
API->>Risk: Calculate risk score
Risk-->>API: Return risk result
API-->>Client: JSON response
API->>Logs: Store API event
end
end
```
## 技术栈
| 层级 | 技术 |
| ---------------- | ----------------------------------------- |
| API 网关 | Kong Gateway |
| 后端 API | Python Flask |
| 风险引擎 | 自定义基于规则的 Python 引擎 |
| 指标 | Prometheus |
| 日志 | Loki |
| 日志收集 | Promtail |
| 可视化 | Grafana |
| 容器化 | Docker Compose |
| 验证 | Curl、Burp Suite、OWASP ZAP 风格测试 |
| 文档 | Markdown |
## 仓库结构
```
api-security-observatory/
|-- README.md
|-- PROJECT-OVERVIEW.md
|-- ARCHITECTURE.md
|-- QUICK-START-GUIDE.md
|-- SECURITY-DISCLAIMER.md
|-- CONTRIBUTING.md
|-- LICENSE
|-- docker-compose.yml
|-- .env.example
|-- .gitignore
|
|-- 01-INFRASTRUCTURE/
|-- 02-API-SERVICE/
|-- 03-KONG-GATEWAY/
|-- 04-OWASP-API-TOP-10-DETECTION/
|-- 05-OBSERVABILITY-STACK/
|-- 06-DETECTION-ENGINEERING/
|-- 07-GRAFANA-DASHBOARDS/
|-- 08-SECURITY-VALIDATION/
|-- 09-COMPLIANCE-REPORTING/
|-- 10-EVIDENCE-VAULT/
|-- 11-AUTOMATION-SCRIPTS/
|-- 12-OPERATIONS-RUNBOOKS/
|-- 13-PROJECT-DOCUMENTATION/
|-- 14-ARCHITECTURE-ASSETS/
|-- 15-TOOLS-VERSION-REFERENCE/
|-- 16-ROADMAP/
`-- 17-PROJECT-AUDIT/
```
## 核心组件
### Kong API Gateway
Kong 作为 API 服务的前端安全层。
它负责处理：
* API 路由
* API 密钥认证
* 限流
* 网关层请求检查
* 主动拦截
* 安全事件记录
当前路由行为：
| 路由 | 行为 |
| ---------------------------- | ------------------------ |
| `/health` | 公开健康检查 |
| `/api/*` | 受 API 密钥保护 |
| 可疑的 `/api/*` payload | 在网关层被拦截 |
### 2. Flask API 服务
Flask API 提供：
* 健康检查 endpoint
* 回显 endpoint
* 请求元数据可见性
* 风险评分集成
* JSON 响应输出
主要测试 endpoint：
```
/api/echo
```
### 3. 风险评分引擎
风险引擎使用透明的基于规则的逻辑来评估 API 请求。
它考虑的因素包括：
* HTTP 方法
* 查询字符串
* 请求体
* 认证上下文
* 可疑关键字
* OWASP 风格的类别映射
风险响应示例：
```
{
"risk": {
"risk_level": "LOW",
"risk_score": 5,
"reasons": [
"Normal GET request baseline risk",
"Authenticated request context present"
],
"owasp_categories": []
}
}
```
### 4. 主动拦截逻辑
网关会在可疑请求特征到达后端 API 之前将其拦截。
| 模式 | 检测含义 |
| ------------- | -------------------------------- |
| `UNION` | SQL 注入关键字 |
| `