shivsegv/EdgeShield

# EdgeShield 一个端到端的边缘防御演示，可在恶意流量冲击您的核心服务之前将其拦截。Go 反向代理应用了基于 Redis 的速率限制，FastAPI 摄取管道将每个决策记录在 Postgres 中，而 SOLID 原则构建的 React/MUI 控制台则将遥测数据转化为可操作的洞察。 ## 需求与解决方案 **它解决了什么问题？** 现代 API 饱受撞库、爬取和流量洪水的轰炸。如果放任不管，这些攻击会扭曲指标、消耗资源并困扰客户。 **本项目如何应对？** 边缘代理检查每个请求，对每个 IP 和 API Key 强制执行滑动窗口限制，执行轻量级机器人启发式分析，并发出结构化事件流。运维人员在仪表板中观察趋势，并在恶意流量到达生产后端之前调整策略。 ### 核心功能 - **速率限制与滥用评分：** Redis 中的原子计数器维持确定性的窗口，而请求元数据（方法组合、UA、突发节奏）有助于标记可能的机器人。 - **集中式事件日志记录：** 每个允许/拦截决策都被推送到摄取服务进行存储和下游分析。 - **实时态势感知：** 仪表板显示网络动量、流量分布、热点以及带有搜索和决策过滤器的实时事件流。 - **动态姿态：** 策略更改或节点元数据通过 Redis + 摄取更新即时推出。 ## 架构概览 ``` ┌────────┐ HTTP ┌────────────────────────┐ │ Clients├──────────▶│ Edge proxy (Go + Redis) │ └────────┘ │ • Sliding-window limits │ │ • Prometheus metrics │ └─────────┬───────────────┘ │ ingest events ▼ ┌────────────────────────────┐ │ FastAPI ingest + Postgres │ │ • Persist structured events │ │ • Serve `/v1/events` │ └─────────┬───────────────────┘ │ REST ▼ ┌────────────────────────────┐ │ React/MUI console (nginx) │ │ • Network Momentum │ │ • Traffic Split & Hotspots │ │ • Live event stream │ └────────────────────────────┘ Allowed traffic continues to the bundled `demo-app` backend through the edge proxy. ``` ## 技术栈概览 | 层级 | 技术 | 选择原因 | |-------|------------|-------------------| | 边缘代理 | Go, Redis, Prometheus | 高吞吐量网络 IO，确定性计数器，原生指标 | | 摄取服务 | FastAPI, PostgreSQL | 快速 API 开发，持久化事件存储 | | 演示后端 | Node.js (Express) | 用于允许流量的轻量级目标 | | UI | React 18, MUI, nginx | 具有 SOLID 对齐组件和 hooks 的响应式控制台 | | 工具 | Docker Compose, Python 攻击模拟器 | 一键编排和可重复的流量场景 | ## 仓库布局 ``` EdgeShield/ ├── edge/ # Go proxy with internal packages for config, limiter, events, telemetry, server ├── ingest/ # FastAPI ingest API backed by Postgres ├── ui/ # React operations console (components/hooks/utils extracted for SOLID readability) ├── demo-app/ # Sample upstream service used for allowed traffic ├── infra/ # Docker Compose definition ├── tests/ # Traffic simulator and helper scripts └── README.md ``` ## 前置条件 - Docker 24+ 及 Compose 插件 - Python 3.10+（可选，用于 `tests/attack_sim.py`） - Node.js 18+，如果您想使用 `npm start` 迭代 UI ## 快速开始 ``` git clone https://github.com/shivsegv/EdgeShield.git cd EdgeShield/infra docker compose up --build ``` 当容器稳定后： - UI 仪表板： - 边缘代理： - Prometheus 指标： - 摄取 API： - 演示上游应用（通过边缘）： 使用 `docker compose down` 关闭。添加 `-v` 以删除 Postgres 数据。 ## 运行演示 ### 1. 边缘冒烟测试 ``` curl -i http://localhost:8080/healthz curl -i -H "X-API-KEY: goodkey" http://localhost:8080/api/hello ``` 两次调用都应返回 `200 OK` 并立即显示在仪表板中。 ### 2. 施压限制器 ``` python3 ../tests/attack_sim.py \ --url http://localhost:8080/api/hello \ --api-key botkey \ --rps 300 \ --duration 10 ``` 观察网络动量激增，流量分布向被拦截流量倾斜，以及实时事件流填满决策细节。 ### 3. 探索仪表板 - **Hero tiles：** 确认边缘代理、摄取管道和演示后端的新鲜度。 - **网络动量：** 绘制过去 12 分钟的图表；当数据稀疏时回退到点标记，因此卡片永远不会显得空洞。 - **流量分布与热点：** 环形图加上针对端点、API Key、HTTP 方法和拦截原因的排序列表。 - **实时事件流：** 按 IP、API Key、路径、原因或用户代理搜索；筛选决策以审核拦截与允许。 ## 配置速查表 | 服务 | 变量 | 默认值 | 用途 | |---------|----------|---------|---------| | edge | `REDIS_ADDR` | `redis:6379` | 计数器的 Redis 端点 | | edge | `DEMO_APP_URL` | `http://demo-app:5000` | 上游服务目标 | | edge | `INGEST_SERVICE_URL` | `http://ingest:8081/v1/events` | 遥测端点 | | edge | `EDGE_NODE_NAME` | `edge-1` | 包含在事件中的节点标签 | | ingest | `DATABASE_URL` | `postgresql://postgres:postgres@postgres:5432/postgres` | Postgres DSN | | ingest | `INGEST_API_KEY` | *(空)* | 来自边缘的可选共享密钥 | | ui/nginx | `API_BASE_URL` | `http://edge:8080` | `/v1/events` 的反向代理目标 | 默认限制：每个 IP 100 次请求 / 60 秒，每个 API Key 1000 次 / 60 秒。调整 `edge/internal/limiter` 或扩展策略模块以实现动态配额。 ## 可观测性 - Prometheus 抓取：`http://localhost:8080/metrics`，用于计数器、延迟和摄取结果。 - 结构化事件：Postgres 存储在 `/v1/events` 提供的决策日志。 - 日志：`docker compose logs ` 仍然是端到端追踪代理 → 摄取流程最快的方式。 ## 本地开发 - **UI：** `cd ui && npm install && npm start` - 组件位于 `ui/src/components`，hooks 位于 `ui/src/hooks`，共享助手位于 `ui/src/utils` + `ui/src/constants`。 - **Edge (Go)：** `cd edge && go test ./...` - 内部包（`config`, `limiter`, `events`, `telemetry`, `server`）保持 SOLID 边界。 - **Ingest (FastAPI)：** - `cd ingest && pip install -r requirements.txt` - `uvicorn main:app --reload --port 8081` - **流量工具：** `tests/attack_sim.py --help` 公开了并发、随机路径和用户代理旋钮，用于更丰富的模拟。 ## 演示脚本 1. `cd infra && docker compose up --build -d` 2. 访问 `http://localhost:8080/healthz` 3. 打开 并指出 hero tiles + 动量卡片 4. 使用 `curl` 发起一些允许的请求 5. 启动模拟器以展示限流和拦截原因 6. 通过 `curl http://localhost:8080/metrics | head` 展示 Prometheus 指标

标签：API 安全, AV绕过, CISA项目, DDoS 防护, FastAPI, Go 语言, JSONLines, MITM代理, MUI, PostgreSQL, React, Redis, Syscalls, WAF, Web 应用防火墙, 反向代理, 威胁情报, 安全仪表盘, 密码管理, 开发者工具, 搜索引擎查询, 撞库防护, 日志审计, 机器人检测, 测试用例, 版权保护, 网络流量分析, 自定义脚本, 自定义脚本, 自定义请求头, 边缘计算安全, 逆向工具, 防爬虫, 限流, 零信任