Jaisurya2823/security-autopilot-agent

# Security Autopilot Agent **一个自主的 AI 安全平台，用于告警分诊、威胁建模、 供应链分析、钓鱼/诈骗调查、攻击路径 推理，以及人工批准的修复。** 它不是扫描器，而是一个调查员。将它指向一个安全告警、一个 GitHub 仓库或 ZIP 文件、一个依赖清单，或一条可疑消息，它就会 对发现进行推理，将证据串联成一个现实的攻击 故事，评估风险，并推荐后续步骤 —— 在发生任何破坏性操作之前暂停等待人类的 批准。 完整的设计 和流程图请参阅 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)，关于所有四项功能的 5 分钟演练请参阅 [`docs/DEMO_SCRIPT.md`](docs/DEMO_SCRIPT.md)，关于定位/面向评委的推介请参阅 [`docs/PITCH.md`](docs/PITCH.md)。 ## 它的功能 | 功能 | 输入 | 输出 | |---|---|---| | **告警分诊** | 原始安全告警 (EDR/SIEM/firewall/IOC) | 严重程度、修复计划、人工控制的执行 | | **威胁建模** | GitHub 仓库 URL 或 ZIP 上传 | STRIDE 威胁、信任边界、入口点、风险评分 | | **攻击路径发现** | （从威胁模型中链式推导） | 从初始访问到造成影响的有序攻击者路径 | | **供应链安全** | `requirements.txt` / `package.json` | 真实的 OSV.dev 漏洞匹配、域名仿冒检测、信任评分 | | **钓鱼/诈骗调查** | 电子邮件/短信/聊天文本 | URL 危险信号分析、语言模式启发式分析、LLM 判定 + 置信度 | 每项功能都会产生相同形式的回答：一份执行 摘要、一个风险评分、背后的证据，以及一个推荐的后续 步骤 —— 实时显示在 `/` 的仪表板中。 ## 为什么这是一个平台，而不是五个独立的工具 所有五项功能共享一个安全主干： - **Human-in-the-loop gate** (`src/graph.py`) —— 破坏性修复 操作（`block_ip`、`quarantine_host`、`disable_account`）在代码中通过 `src/models.py` 中的 `DESTRUCTIVE_ACTIONS` 进行严格拦截，而 不是交由 LLM 自行判断。一个真正的 LangGraph `interrupt()` 会暂停 执行；批准可以来自几分钟后另一个完全不同的 HTTP 请求，并且图会从它上次中断的地方准确恢复执行。 - **仅追加的审计日志** (`src/audit_log.py`) —— 每个节点都会写入一条带有 时间戳的记录，说明它看到了什么以及做出了什么决定。 - **基于事实的推理，而非幻觉** —— 本项目中的每个 LLM prompt (`src/groq_client.py`) 都被明确指示，只能根据提供给它的发现进行推理，绝不捏造静态分析实际上并未发现的 endpoint、 secret 或漏洞。 威胁建模和攻击路径的 prompt 明确说明了这一点。 - **真实数据，而非模拟结果** —— 供应链检查会请求 OSV.dev 的实际漏洞数据库；仓库分析是真实的静态 分析（针对磁盘上的实际文件内容进行 regex/AST 级别的模式匹配），而不是预先编排的演示。 ## 设置 ``` python -m venv venv . venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt cp .env.example .env # then fill in GROQ_API_KEY ``` 从 [Groq console](https://console.groq.com/keys) 获取 Groq API key。 供应链 agent 的 OSV.dev 查找（公共 API）不需要 key。 ## 运行仪表板 + API ``` python app.py # 打开 http://localhost:8080 ``` 四个选项卡：**Alert Triage**（通过表单提交真实告警，外加 待批准/决策账本视图）、**Repo Investigation**、 **Supply Chain**、**Phishing/Scam**。每个选项卡都接受真实输入 —— 粘贴/上传 —— 并实时呈现结果。 你也可以通过 curl 直接驱动每项功能： ``` # Alert triage curl -X POST localhost:8080/alerts \ -H "Content-Type: application/json" \ -d '{"description":"outbound connection to known C2","asset_id":"WKS-114","asset_ip":"185.220.101.7","raw_log":"..."}' curl localhost:8080/pending curl localhost:8080/history curl -X POST localhost:8080/approve/ -H "Content-Type: application/json" -d '{"approved": true}' # Repo 调查（GitHub URL 或 ZIP 上传） curl -X POST localhost:8080/investigate/repo \ -H "Content-Type: application/json" -d '{"repo_url":"https://github.com/owner/repo"}' curl -X POST localhost:8080/investigate/repo -F "zip=@/path/to/repo.zip" # 供应链 curl -X POST localhost:8080/investigate/dependencies \ -H "Content-Type: application/json" \ -d '{"filename":"requirements.txt","content":"flask==3.0.0\npsycopg2==2.9.9\n"}' # 钓鱼/诈骗 curl -X POST localhost:8080/investigate/phishing \ -H "Content-Type: application/json" -d '{"text":"URGENT: verify your account now: http://paypa1.com/signin"}' ``` ## 运行测试 ``` pip install pytest python -m pytest -q ``` 162 个测试，全部通过。每个 LLM 调用 (Groq) 和每个外部网络 调用 (OSV.dev、GitHub 的 codeload) 都在传输边界进行了 mock —— 绝不是伪造的安全*结果*，而仅仅是网络往返 —— 因此该 测试套件在不需要 API key 和网络访问的情况下运行。包含基于真实 fixture 仓库构建的真实 回归测试，针对每个路由使用格式错误/超大/类型错误的输入进行的真实压力 测试，以及 真实的恶意 zip payload（包括 zip-slip 路径遍历和 真正的 zip bomb —— 将 5MB 压缩为 ~KB，在超过限制的任何字节 触及磁盘之前被正确拒绝），而不仅仅是 mock 单元 —— 请参阅 `tests/test_repo_intel.py`、`tests/test_orchestrator.py` 和 `tests/test_app_routes.py`。 ## 使用 Docker 运行 ``` docker build -t security-autopilot-agent . docker run -p 8080:8080 --env-file .env security-autopilot-agent ``` 由 gunicorn (`--workers 1 --threads 4`) 提供服务，而不是 Flask 开发 服务器 —— 关于为什么它是一个带有多个线程的 worker 进程而不是多个 进程的原因，请参阅 Dockerfile 和 `app.py` 的模块 docstring。 ## 部署到 Render 将此仓库推送到 GitHub，然后任选其一： - **Blueprint 部署**：在 Render 仪表板中，“New +” → “Blueprint”， 将其指向此仓库 —— 位于仓库根目录的 `render.yaml` 会自动定义 服务、健康检查和环境变量。 - **手动**：“New +” → “Web Service” → 连接该仓库 → Render 检测到 `Dockerfile` 并直接从中构建。 无论哪种方式，都要在 Render 仪表板的环境变量中设置 `GROQ_API_KEY`（不提交 —— `render.yaml` 特意将其标记为 `sync: false`，因此它不会被提交）。 ## 已知局限性（公开声明，而非隐瞒） - **仓库分析**是基于 regex/模式的静态分析，而不是真正的 AST 解析 —— 动态构建的路由和不符合格式的 secret 将被遗漏。endpoint 上的 `requires_auth` 是尽力而为的，在无法确定时为 `None`（而不是错误的 `True`/`False`）。 - **告警分诊**将已知的恶意 IP 与真实的实时信息源 （FireHOL 的 `level1` netset —— Spamhaus DROP、DShield Top 攻击者、 fullbogons）进行匹配，而不是硬编码的列表 —— 但它仍然是众多 信息源之一；它无法捕获恶意但 尚未出现在任何 FireHOL 源列表中的 IP。修复执行（`block_ip`、 `quarantine_host`、`disable_account`、`open_ticket`）是失败即停止（fail-closed）的： 如果未将 `REMEDIATION_WEBHOOK_URL` 配置为指向你真实的 SOAR/firewall/EDR/IdP，这些操作会如实报告 `FAILED: not executed` ，而不是捏造成功 —— 请参阅下文的“真实可用 vs. 需要你的配置”。 - **供应链**仅解析 `requirements.txt` 和 `package.json` —— `Cargo.toml`/`pyproject.toml`/lockfile 会引发明确的错误，而不会 静默失效。域名仿冒检测使用一个小型的精选参考 列表，而不是实时的流行度数据源。CVSS v3.0/v3.1 vector 会进行真实评分 （`src/cvss.py`，官方的基础评分公式，已针对 著名的 Log4Shell 参考分数进行了验证）；CVSS v2 vector 使用了未实现的另一个公式，因此那些 vector 仍然 报告 `"unknown"`，而不是给出错误的评分。 - **钓鱼/诈骗**没有实时的黑名单检查（PhishTank/OpenPhish/Safe Browsing） —— 仅包含结构和语言分析，不包括域名声誉或 注册年龄。没有截图/QR 图像分析（仅限文本/URL 输入）。 - **此处的任何内容都不会执行攻击或触及真实的目标系统** —— 攻击路径输出是基于真实的 发现得出的调查叙述，而不是自主的渗透测试。 请参阅 [roadmap](#roadmap) 了解接下来如何填补这些空白。 ## 路线图 - 真正的渗透测试集成 —— 仅进行只读侦查，绝不进行主动利用 - 跨告警的长期事件关联 / 知识图谱 - 截图/QR 钓鱼分析（图像 pipeline） - 多仓库 / 组织范围的供应链仪表板 - SOAR 集成 —— 真实的 EDR/SIEM webhook，而不是手动粘贴 - 用于钓鱼 agent 的实时域名声誉/黑名单数据源 - CVSS v2 vector 评分（与 v3 的公式不同，尚未实现） - 实时/可刷新的域名仿冒流行度数据（PyPI BigQuery dataset / npm registry download API），取代当前的静态入门列表 ## 项目结构 ``` app.py Flask API + dashboard host (all 4 routes) cli.py CLI alert-triage runner (real alert JSON, file or stdin) render.yaml Render deployment config Dockerfile Container build static/index.html Live dashboard — 4 tabs, one per capability src/ models.py All data models (alert/triage/remediation, repo intel, threat model, attack path, supply chain, phishing) + safety floors config.py Env-var config (Groq, OSV.dev, IOC feed, webhook) groq_client.py All LLM prompts (triage, remediation, threat model, attack path, phishing) graph.py LangGraph alert-triage flow + human gate + severity-based approval floor threat_intel.py Real live IOC feed + NVD CVE enrichment ioc_feed.py FireHOL blocklist fetch/cache/CIDR matching remediation.py Fail-closed webhook-based action executors audit_log.py Append-only structured decision log repo_intel.py Static analysis (lang/framework/ endpoint/secret/CI detection) manifest_parser.py requirements.txt / package.json parsing supply_chain.py OSV.dev vulnerability + typosquat + trust scoring cvss.py Real CVSS v3.0/v3.1 base-score calculator threat_model.py Deterministic STRIDE rules + LLM augmentation attack_path.py Chains threats into an attacker path phishing.py URL/keyword heuristics + LLM classification orchestrator.py GitHub fetch / ZIP extraction (zip-slip AND zip-bomb safe) + repo-investigation pipeline wiring tests/ 162 tests across all of the above docs/ARCHITECTURE.md Design doc + flow diagram docs/DEMO_SCRIPT.md 5-minute walkthrough script docs/PITCH.md Positioning / judge-facing pitch ``` ## 真实可用 vs. 需要你的配置 预先说明哪些部分是开箱即用完全真实的，而 哪些部分需要你将它们指向你拥有的内容： | 功能 | 状态 | |---|---| | 威胁情报 (IOC matching) | **完全真实，零配置** —— 实时的 FireHOL 黑名单 | | 供应链 (OSV.dev) | **完全真实，零配置** —— 实时的公共漏洞数据库 | | 仓库静态分析 | **完全真实，零配置** —— 读取磁盘上的实际文件 | | CVSS 评分 | **完全真实，零配置** —— 官方公式 | | LLM 推理（所有 agent） | **完全真实** —— 需要 `GROQ_API_KEY` | | 修复执行 | **真实，配置前为失败即停止（fail-closed）** —— 需要将指向你的 SOAR/firewall/EDR/IdP 的 `REMEDIATION_WEBHOOK_URL` 进行配置。如果没有它，破坏性操作将如实报告 `FAILED: not executed`，而不是捏造成功。 | | 待处理的人工控制决策 | **完全真实，零配置** —— 基于 SQLite 的 checkpointing (`GRAPH_CHECKPOINT_PATH`)，可在进程重启后保留。具体到 Render 上，这意味着在崩溃/重启后可以保留，但不一定在重新部署后保留 —— 请参阅 `render.yaml` 中关于附加持久磁盘的说明。 | | 钓鱼黑名单声誉 | **未实现** —— 仅限结构/语言分析（请参阅上文的局限性） | ## 许可证 MIT —— 请参阅 [LICENSE](LICENSE)。

标签：DNS 反向解析, LLM, PB级数据处理, Sysdig, Unmanaged PE, 人工智能, 威胁建模, 安全运维, 文档安全, 用户模式Hook绕过, 自动化响应, 请求拦截, 逆向工具, 钓鱼检测