rjvareed/ai_soc_assistant

# ai_soc_assistant 一个 Python 的概念验证工具，能将威胁报告、博客文章和应急响应记录转化为结构化的分析师报告。它将确定性的 regex 分析与 Claude AI 相结合，以提取 IOC，映射 MITRE ATT&CK 技术，并起草 Sigma 风格的检测规则。 **所有 AI 输出均为草稿。每一项发现都需要在采取行动前经过分析师的审核。** ## 它的功能 1. **接收**基于文本的威胁报告（最大 500 KB） 2. **安全检查** — 在文本到达 LLM 之前，检测 prompt injection 尝试和敏感数据 3. **Regex IOC 提取** — 确定性地查找 IPv4、domain、URL、hash (MD5/SHA1/SHA256) 和 email 4. **LLM 分析** — 将报告发送给 Claude (`claude-opus-4-8`) 以获取执行摘要、攻击者行为、额外的 IOC 候选项、MITRE ATT&CK 建议、检测假设和不确定性 5. **合并** regex 和 LLM 提取的 IOC；分配置信度（HIGH = regex 确认，MEDIUM = LLM + regex 验证有效，LOW = 仅 LLM） 6. **MITRE 映射** — 关键词字典 + LLM 候选项，去重并进行置信度评分 7. **起草检测规则** — 针对 IOC 类型和 MITRE 技术的 Sigma 风格 YAML 规则，以及 LLM 假设的存根 8. **Markdown 报告** — 包含 IOC 表格、MITRE 表格、检测规则和强制性分析师审核清单的结构化输出 ## 项目结构 ``` ai_soc_assistant/ ├── main.py # CLI entrypoint ├── schemas.py # Pydantic data models ├── ingest.py # File loading and text normalization ├── safety.py # Prompt injection + sensitive data detection ├── ioc_extract.py # Regex IOC extraction and LLM merge ├── mitre_mapper.py # Keyword-to-ATT&CK mapping + LLM merge ├── detection_generator.py # Draft Sigma-style rule generation ├── report_writer.py # Markdown report renderer ├── llm_client.py # Claude API integration ├── requirements.txt ├── .env.example # API key template ├── sample_reports/ # Example threat reports for testing └── outputs/ # Generated reports go here ``` ## 安装说明 ``` # 需要 Python 3.11+ pip install -r requirements.txt ``` ### API key 复制示例 env 文件，并从 [console.anthropic.com](https://console.anthropic.com) → API Keys 添加你的 key： ``` cp .env.example .env # 编辑 .env 并将占位符替换为你的真实密钥 ``` `.env` 内容： ``` ANTHROPIC_API_KEY=sk-ant-api03-your-key-here ``` 该工具在启动时会通过 `python-dotenv` 自动加载 `.env`。该文件已在 `.gitignore` 中列出，不会被提交。 或者，直接在你的 shell 环境中设置 key： ``` export ANTHROPIC_API_KEY=sk-ant-... ``` ## 运行说明 ``` python main.py --input sample_reports/report.txt --output outputs/report.md --verbose ``` **选项：** | Flag | 描述 | |------|-------------| | `--input FILE` | 输入威胁报告的路径 | | `--output FILE` | 输出 Markdown 报告的路径 | | `--model MODEL` | 要使用的 Claude 模型 ID（默认：`claude-opus-4-8`） | | `--skip-llm` | 仅本地模式（无 API 调用） — 用于在没有 API key 的情况下进行测试 | | `--verbose` | 将进度输出到 stderr | ### 选择模型 默认使用 `claude-opus-4-8`，它能产生最详尽的 IOC 提取和 MITRE 映射。`claude-haiku-4-5-20251001` 在质量仅有微小下降的情况下，速度更快且成本大幅降低 —— 适合大批量分类或初步筛选。 ``` # 完整质量（默认） python main.py --input report.txt --output out.md # 更快且更便宜 python main.py --input report.txt --output out.md --model claude-haiku-4-5-20251001 # 显式 Opus python main.py --input report.txt --output out.md --model claude-opus-4-8 ``` 在 8 份测试报告中观察到的质量差异（无论使用哪种模型，仅通过 regex 提取的 IOC 都是相同的）： | | Opus 4.8 | Haiku 4.5 | |---|---|---| | LLM 发现的额外 IOC | 更完整 —— 能提取文件名、工具名、间接指标 | 较少 —— 更容易遗漏上下文 IOC | | MITRE 映射 | 保守、准确 | 略有过度生成；需审核是否存在误报 | | Prompt injection 抵抗力 | 通过 | 通过 | ## 仅本地测试（无需 API key） ``` python main.py --input sample_reports/report.txt --output outputs/report.md --skip-llm --verbose ``` 运行 regex IOC 提取，并在不包含 LLM 摘要、行为或 MITRE 建议的情况下生成报告。 ## 置信度级别 | 级别 | 含义 | |-------|---------| | HIGH | 经 regex 模式确认；同时出现在 regex 和（可选）LLM 输出中 | | MEDIUM | LLM 建议且通过 regex 验证，但未在原始文本中被 regex 发现 | | LOW | LLM 建议；未通过 regex 验证 —— 分析师必须手动核实 | ## 安全模型 - **Prompt injection**：14 种 regex 模式可检测报告中嵌入的试图覆盖 LLM 指令的行为（例如：“ignore all previous instructions”、system-tag 注入、persona 覆盖）。报告仍会被处理，但发现的结果会被标记。 - **敏感数据**：9 种模式可检测凭据、API key、私钥、AWS 凭据和 SSN。匹配到的值在报告摘录中会被脱敏处理。 - **LLM 加固**：system prompt 明确指示 Claude 将所有报告内容视为不受信任的，并且不遵循其中嵌入的任何指令。 ## 安全态势 这是一个**概念验证**。在生产环境使用之前： - 在 API 边界添加速率限制和输入清理 - 将 API key 存储在 secrets manager 中，而不是环境变量中 - 在沙箱环境中运行，除 Anthropic API 外不具有任何网络访问权限 - 为所有 LLM 调用和分析师操作添加审计日志 - 如果是多用户环境，请实施身份验证和访问控制 - 在任何部署之前，让检测工程师审核检测规则 ## 依赖项 - `anthropic` — Anthropic Python SDK - `pydantic` — 数据验证和 schema 强制执行 - `python-dotenv` — 在启动时从 `.env` 加载 `ANTHROPIC_API_KEY` ## 示例报告和记录的输出 `sample_reports/` 中包含了八份示例报告。每份报告都通过完整的 pipeline 分别使用 `claude-opus-4-8` (Opus) 和 `claude-haiku-4-5-20251001` (Haiku) 进行了处理，输出结果保存在 `outputs/` 中。除非另有说明，以下结果均来自 Opus 的运行记录。 ### `report.txt` — Operation Rusty Anchor **场景：** 金融服务公司通过鱼叉式网络钓鱼 ISO 附件遭到入侵。 | | Opus 4.8 | Haiku 4.5 | |---|---|---| | IOC | 32 | 16 | | MITRE 候选项 | 17 | 15 | | 检测规则 | 17 | 16 | | 安全标记 | 0 | 0 | ### `ransomware_healthcare.txt` — BlackMatter Affiliate / 医疗勒索软件 **场景：** 针对医院和制药公司的多受害者勒索软件活动。 | | Opus 4.8 | Haiku 4.5 | |---|---|---| | IOC | 20 | 19 | | MITRE 候选项 | 19 | 23 | | 检测规则 | 18 | 19 | | 安全标记 | 0 | 0 | ### `web_app_attack.txt` — 电商 SQL Injection + Web Shell **场景：** 面向公众的 Web 应用程序通过 SQLi 遭到利用；DNS 隧道数据渗出。 | | Opus 4.8 | Haiku 4.5 | |---|---|---| | IOC | 28 | 21 | | MITRE 候选项 | 11 | 12 | | 检测规则 | 13 | 13 | | 安全标记 | 0 | 0 | ### `apt_espionage.txt` — APT29 / Cozy Bear 智库活动 **场景：** 通过滥用 OAuth 和 Microsoft Graph API C2 进行的国家级间谍活动。 | | Opus 4.8 | Haiku 4.5 | |---|---|---| | IOC | 23 | 12 | | MITRE 候选项 | 16 | 15 | | 检测规则 | 10 | 11 | | 安全标记 | 3（在“OAuth token”上出现 bearer-token 误报） | 3 | 此报告中的三个安全标记属于误报 —— `bearer-token` 模式匹配到了描述性文字中的短语“OAuth token”。分析师在审核后应将其忽略。 ### `volt_typhoon.txt` — Volt Typhoon / 中国关键基础设施 **场景：** 中国国家行为者利用 LOLBins 和 SOHO 设备代理在美国关键基础设施中进行预先布局。基于公开的 Microsoft MSTIC 披露（2023 年 5 月）。 | | Opus 4.8 | Haiku 4.5 | |---|---|---| | IOC | 19 | 19 | | MITRE 候选项 | 19 | 18 | | 检测规则 | 10 | 14 | | 安全标记 | 0 | 0 | 注意：由于大量 SHA256 hash，Opus 的运行最初在 4096 个 token 处因 JSON 截断错误而失败。这促使我们在 `llm_client.py` 中将 `max_tokens` 提高到了 8192。 ### `salt_typhoon_telecom.txt` — Salt Typhoon / 美国电信间谍活动 **场景：**与中国 MSS 有关的攻击者入侵美国运营商 CALEA 合法拦截系统。基于公开的 CISA/FBI 联合公告（2024 年 12 月）。 | | Opus 4.8 | Haiku 4.5 | |---|---|---| | IOC | 19 | 12 | | MITRE 候选项 | 17 | 30 | | 检测规则 | 15 | 20 | | 安全标记 | 0 | 0 | 在此报告中，Haiku 生成了 30 个 MITRE 候选项，而 Opus 生成了 17 个 —— 数量较多反映了过度推断。分析师在审核此报告的 Haiku 输出时应更加彻底。 ### `scattered_spider.txt` — Scattered Spider / 社会工程学 + 勒索软件 **场景：**通过帮助台 vishing 绕过 MFA、滥用 Okta、ALPHV 附属机构勒索软件。基于公开的 CISA/FBI 联合公告（2023 年 10 月）。 | | Opus 4.8 | Haiku 4.5 | |---|---|---| | IOC | 17 | 9 | | MITRE 候选项 | 19 | 22 | | 检测规则 | 12 | 18 | | 安全标记 | 0 | 0 | 巨大的 IOC 差距（17 对 9）反映了 Opus 能够提取 Haiku 遗漏的工具名称、攻击者控制的 domain 模式以及程序性 artifacts。 ### `prompt_injection_test.txt` — 恶意 npm 包（包含嵌入式注入尝试） **场景：**通过受损的 npm package 发起的供应链攻击。该报告故意包含了四次 prompt injection 尝试，以测试安全加固情况。 | | Opus 4.8 | Haiku 4.5 | |---|---|---| | IOC | 14 | 9 | | MITRE 候选项 | 9 | 9 | | 检测规则 | 9 | 10 | | 安全标记 | **4** | **4** | 所有四次注入尝试在到达 LLM 之前都被安全检查器捕获： - `ignore-instructions` — “IGNORE ALL PREVIOUS INSTRUCTIONS” - `system-prompt-injection` — “New system prompt:” - `system-tag-injection` — `` XML tag - `instruction-tag-injection` — `[INST]` tag 两个模型都正确忽略了注入内容，并针对实际威胁生成了一份有价值的报告。

标签：AI辅助分析, IOC提取, IP 地址批量处理, Python, Sigma规则, 威胁情报, 安全运营, 开发者工具, 扫描框架, 无后门, 目标导入, 网络信息收集, 自动化报告, 逆向工具