NSK-394/Vigil-AI

# Vigil AI — 自动化 API 滥用检测       Vigil 在无需人工干预的情况下检测并响应 API 滥用：四个 agent (**Monitor → Detection → Decision → Response**) 运行着连续的 观察–推理–决策–行动循环，将 Isolation Forest 异常分数与规则引擎相结合，在系统重启后依然会记住每个 API key 的行为基线，并且在执行拦截或限速操作时，为每一个判定结果附带完整的推理轨迹。 已在 Product Hunt 发布 · [落地页](https://vigil-landing-page.vercel.app)  ## 架构 ``` ┌─────────────────────────────────────────────────────────────────┐ │ AGENT LOOP (Observe → Reason → Decide → Act) │ │ │ │ ┌──────────────┐ ┌─────────────────┐ ┌──────────────┐ │ │ │ MONITOR │ │ DETECTION │ │ DECISION │ │ │ │ log ingest +│───▶│ rule engine ∥ │───▶│ confidence- │ │ │ │ memory │ │ IsolationForest│ │ weighted │ │ │ │ enrichment │ │ (parallel) │ │ fusion │ │ │ └──────┬───────┘ └────────┬────────┘ └──────┬───────┘ │ │ ▼ ▼ ▼ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ SHARED MEMORY BUS │ │ │ │ short-term: deque, last 10 cycles per key (velocity) │ │ │ │ long-term: rolling EMA baseline per key (JSON, │ │ │ │ atomic writes, survives restarts) │ │ │ └──────────────────────────┬───────────────────────────────┘ │ │ ▼ │ │ ┌───────────────────┐ │ │ │ RESPONSE AGENT │◀── feedback loop │ │ │ BLOCK/RATE_LIMIT │ (updates long-term │ │ │ /ALERT/LOG │ memory each cycle) │ │ └───────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` | Agent | 阶段 | 职责 | |---|---|---| | [MonitorAgent](src/agents/monitor_agent.py) | 观察 | 摄取日志，提取基于 key 的特征，注入 5 个源自记忆的信号（速率、基线偏差、累犯标记、历史平均值、先前观测值） | | [DetectionAgent](src/agents/detection_agent.py) | 推理 | **并行**运行规则引擎和 Isolation Forest；每个引擎输出的是置信度，而不仅仅是分数 | | [DecisionAgent](src/agents/decision_agent.py) | 决策 | 基于置信度加权的融合，动作选择（BLOCK > RATE_LIMIT > ALERT > LOG），每次判定附带完整推理轨迹 | | [ResponseAgent](src/agents/response_agent.py) | 行动 | 执行动作，触发 Slack/电子邮件警报，将结果写回长期记忆 | ## 检测机制说明 1. **基于 API key 的特征** — 请求量、endpoint 多样性、方差 — 结合从记忆中提取的该 key 自身的历史数据进行了丰富。 2. **双引擎并行** — 启发式规则引擎 (0–100) 和用于评估统计异常程度的 [Isolation Forest](src/detector.py)。 3. **置信度加权** ([src/core/confidence.py](src/core/confidence.py)) — 接近 50 的分数代表引擎在表示“我不知道”，因此它的权重接近于零； 接近 0 或 100 的分数则具有全部权重。模棱两可的引擎实际上会**弃权**，而不是将融合后的分数强行拉向中间值。 4. **记忆加成** — 累犯加 18 分（先前有 3 次及以上的 HIGH 判定），速率激增加 12 分，偏离该 key 自身 EMA 基线 60% 以上加 10 分。 5. **决策与反馈** — 融合分数 ≥65 → HIGH（一律 BLOCK），≥35 → MEDIUM；累犯会自动从 MEDIUM 升级为 BLOCK。每次判定结果都会更新 EMA 基线，因此系统能够跨会话进行学习。 每次判定都会附带可审计的推理轨迹： ``` [HIGH | conf=95% | fused=97.6] — rule engine: high-volume/low-diversity (score 95); ML: statistical outlier (anomaly 91.2); short-term memory: velocity spike +70; long-term memory: >=3 prior HIGH verdicts (repeat offender). ``` ## 已解决的核心难题 - **融合两个意见相左的引擎** — 朴素的平均值会让不确定的引擎 否决确定的引擎（规则引擎 95，ML 50 → 72.5，导致对真实攻击的拦截不足）。 解决方法是根据每个投票*距离模糊区域的远近*进行加权，这 同时也会形成一个已知的对抗面（攻击者会潜伏在分数约为 50 的区域），而记忆加成机制的存在正是为了对抗这一点。 - **不会损坏的持久化行为记忆** — 长期记忆是以 JSON 格式存储的、基于 key 的 EMA 基线，通过临时文件 + `os.replace()` 写入，因此写入过程中的崩溃 不会损坏存储 ([src/memory/long_term.py](src/memory/long_term.py))。 - **跨进程摄取** — 真实流量经由 middleware → 摄取服务器 → agent 循环流动，通过 SQLite WAL 队列 ([src/live_queue.py](src/live_queue.py)）；发现并修复了并发的 `push()`/`drain()` 和 `queue_size()` 之间的竞态条件，方法是保持进程锁。摄取服务器还对 `request_count` 设置了上限，以防止通过伪造的 payload 操纵分数，并且仪表盘会对所有受攻击者控制的字符串进行 HTML 转义（在真实流量模式下，API key 可能会携带 XSS payload）。 ## 快速开始 ``` git clone https://github.com/NSK-394/Vigil-AI.git && cd Vigil-AI python -m venv .venv && .venv/Scripts/activate # source .venv/bin/activate on Unix pip install -r requirements.txt python -m streamlit run src/dashboard.py # SOC dashboard → localhost:8501 python run_agent.py --mode attack --cycles 10 # or headless CLI agent ``` 仪表盘模拟了四种流量画像（正常、暴力破解、爬虫抓取、DDoS） 可通过顶部栏实时切换。 ## 监控真实 API 即插即用的 middleware 可将实时 HTTP 流量流式传输到检测 pipeline 中： ``` # FastAPI — 2 行 from src.middleware.fastapi_middleware import VigilMiddleware app.add_middleware(VigilMiddleware, vigil_url="http://localhost:9000/ingest") ``` ``` // Express — built-in modules only, no npm install const { createVigilMiddleware } = require('./src/middleware/express_middleware'); app.use(createVigilMiddleware({ vigilUrl: 'http://localhost:9000/ingest' })); ``` 运行摄取服务器（`uvicorn src.middleware.ingest_server:app --port 9000`），并且 BLOCK 判定会在后台线程中触发 Slack webhook + Gmail 警报（通过 `.env` 配置，详见 [.env.example](.env.example))。 ## 生产环境对标 | Vigil 组件 | 企业级对标 | |---|---| | DetectionAgent | SIEM 关联引擎 (QRadar, Sentinel) | | DecisionAgent | SOAR 剧本引擎 (XSOAR, Splunk SOAR) | | ResponseAgent | WAF 执行 (AWS WAF, Cloudflare) | | 长期记忆 | 威胁情报数据库 (MISP) | | 推理轨迹 | SOC 分析师审计追踪 |

标签：AI智能体, API安全, AppImage, AV绕过, CISA项目, FastAPI, JSON输出, Kubernetes, Python, scikit-learn, Web应用防火墙, 异常检测, 无后门, 自动化响应, 逆向工具, 配置错误