rvong65/simple-autonomous-security-agent
GitHub: rvong65/simple-autonomous-security-agent
一款透明的 SOC 告警分诊自主安全智能体，通过 ReAct 循环与只读调查工具自动生成结构化风险报告。
Stars: 1 | Forks: 0
# 简易自主安全智能体 (SASA)
一款专为 SOC 分析师和安全学习者设计的轻量级、透明**自主安全调查智能体**。只需粘贴可疑日志、IP、域名或告警 —— SASA 便会运行 **ReAct 循环**（思考 → 行动 → 观察），调用只读调查工具，展示其完整的思维链，并生成包含建议的结构化风险报告。
## 🎯 问题与动机
安全分析师花费大量时间对嘈杂的告警进行分诊：关联日志模式、检查 IP 信誉，以及判断事件是良性还是需要采取行动。手动收集上下文缓慢，且不透明的“黑盒” AI 工具削弱了人们对 SOC 工作流的信任。
**SASA** 通过以下方式解决此问题：
- **自主调查**事件，并带有可见的 ReAct 推理循环
- **强制执行只读护栏** —— 不进行漏洞利用、阻断或处理偏离主题的请求
- **通过确定性的风险底线将风险评级建立在工具证据之上**（LLM 无法对黑名单命中进行低评）
- **支持混合部署** —— 使用 Groq 进行云端演示，使用 Ollama 进行离线操作
## 🛠️ 技术栈
| 层级 | 技术 |
|-------|------------|
| UI | Streamlit |
| Agent | 自定义 ReAct 循环 (`agent.py`) |
| LLM | Groq (`llama-3.1-8b-instant`) 或通过直接 HTTP 连接的 Ollama (`gemma3:4b`) |
| 验证 | Pydantic 模型, 护栏, 风险评分器 |
| 测试 | `unittest` — 64 个离线测试 + 集成质量门禁 |
## 📊 数据来源与归属
| 来源 | 使用方 | 备注 |
|--------|---------|-------|
| **演示事件** | `demo/example_events.json` | 合成 SOC 场景（SSH 暴力破解、SQLi 等） |
| **本地黑名单 / 启发式规则** | `threat_intel` | 演示 Tor/扫描器 IP；可疑的 TLD 模式 |
| **[AbuseIPDB](https://www.abuseipdb.com/)** | `threat_intel` (可选) | 设置 `ABUSEIPDB_API_KEY` 时的实时 IP 信誉查询 |
| **[ipapi.co](https://ipapi.co/)** | `ip_lookup` | 针对公网 IP 的免费层级地理定位 / ASN 查询 |
| **python-whois** | `whois_lookup` | 域名注册元数据 |
| **正则签名** | `log_pattern_match` | 内置针对暴力破解、SQLi、扫描器和路径遍历的模式 |
本项目不包含任何专有数据集。外部 API 均为可选且受速率限制。
## 🏗️ 架构与设计选择
```
flowchart TB
subgraph Client["Client Layer"]
U[Analyst / Demo user]
UI[Streamlit UI
app.py] end subgraph Guard["Safety Layer"] IG[Input guard
scope & attack refusal] TG[Tool guard
whitelist · private IP blocks] RL[Rate limits
per investigation] end subgraph Agent["Agent Layer — agent.py"] BOOT[Log bootstrap
auto log_pattern_match] REACT[ReAct loop
Thought → Action → Observation] PARSE[Response parser
+ format retry] RF[Risk floor merge
utils/risk_scorer.py] RPT[Investigation report
Low / Medium / High] end subgraph Tools["Tool Layer — tools/"] LOG[log_pattern_match
regex signatures] TI[threat_intel
heuristics + AbuseIPDB] IP[ip_lookup
ipapi.co] WHO[whois_lookup
python-whois] end subgraph Models["Model Layer — utils/llm.py"] GROQ[Groq API
llama-3.1-8b-instant] OLL[Ollama API
local models] TGT[Together API
optional fallback] end U --> UI UI --> IG IG -->|allowed| BOOT BOOT --> LOG BOOT --> REACT REACT --> GROQ REACT --> OLL REACT --> TGT REACT --> TG TG --> LOG TG --> TI TG --> IP TG --> WHO LOG --> REACT TI --> REACT IP --> REACT WHO --> REACT REACT --> PARSE PARSE --> RF RF --> RPT RPT --> UI IG -->|refused| UI RL --> REACT ``` **关键设计决策：** - **直接使用 HTTP 连接 LLM** —— 极简依赖，对 Windows 友好的安装体验 - **工具风险底线** —— 报告风险 = max(LLM 评级, 工具证据)；黑名单的高风险（High）不能变为低风险（Low） - **自动日志扫描（步骤 0）** —— 类日志事件在进入 LLM 循环前会先进行 `log_pattern_match` 匹配 - **结构化的护栏观察结果** —— 私有 IP / 无效的查询错误以 JSON 格式返回，以便智能体对其进行推理 - **显式的 `LLM_PROVIDER`** —— 不会仅凭密钥的存在就自动选择 Groq - **服务端 API 密钥** —— Groq/Together 凭据仅存在于环境变量/机密配置中；绝不发送至浏览器或导出文件 ### 开发历程 ``` flowchart LR A[ReAct agent
4 read-only tools] --> B[Guardrails
input + tool whitelist] B --> C[Risk floor
blocklist / log severity] C --> D[Streamlit UI
chain-of-thought + custom theme] D --> E[Quality gates
6 demo integration tests] E --> F[Groq profile
llama-3.1-8b-instant] F --> G[LLM error UX
429 · auth · timeout] G --> H[64 offline tests
+ GitHub Actions CI] H --> I[GitHub + Streamlit deploy
MVP] ``` ## 🚀 在线演示 **[▶ 在 Streamlit Cloud 中打开在线应用](https://simple-autonomous-security-agent.streamlit.app/)** **截图：**  *截图来自使用 Groq (`llama-3.1-8b-instant`) 的运行过程。工具证据和风险评级基于确定性检查；LLM 生成的叙述文本可能因提供商、模型和具体运行情况而异。* 本地演示：`streamlit run app.py` → 在侧边栏加载演示事件 → **调查**。 ## 快速开始 ### 前置条件 - Python 3.10+ - **Groq**（默认）：在 [console.groq.com](https://console.groq.com) 获取免费 API 密钥 - **或 Ollama**（本地）：[ollama.com](https://ollama.com) + `ollama pull gemma3:4b` ### 安装说明 ``` git clone https://github.com/rvong65/simple-autonomous-security-agent.git cd simple-autonomous-security-agent python -m venv .venv # Windows .\.venv\Scripts\Activate.ps1 # macOS / Linux # source .venv/bin/activate pip install -r requirements.txt cp .env.example .env # 编辑 .env — 添加 GROQ_API_KEY（或在 .env.example 中切换到 Ollama block） streamlit run app.py ``` 配置参考：请参阅 `.env.example`（本地）和 `.streamlit/secrets.toml.example`（Streamlit Cloud）。 **Groq 批量测试**（全部 6 个演示 —— 使用延迟以避免 HTTP 429 错误）： ``` python scripts/run_demo_investigations.py --delay 15 ``` ## ✨ 功能 - **自主 ReAct 循环** —— 最多 8 个步骤，完全透明 - **4 种调查工具** —— 日志模式、威胁情报、IP 查询、WHOIS（均为只读） - **风险底线强制执行** —— 工具证据设定了报告的最低严重性限制 - **输入与工具护栏** —— 拒绝攻击/偏离主题的请求；阻止对私有 IP 的外部查询 - **网络安全 UI** —— 自定义主题，IBM Plex Sans + JetBrains Mono 字体，“工作原理”侧边栏 - **分析师导出功能** —— 可下载的 JSON 调查报告和纯文本摘要 (.txt) - **友好的 LLM 错误提示** —— 速率限制 (429)、身份验证、超时，并提供可选的技术详情 - **混合 LLM** —— Groq（云端默认）或 Ollama（本地）；Together 作为可选的备用方案 ## 🛡️ 安全注意事项 | 原则 | 实现方式 | |-----------|----------------| | 只读操作 | 无阻断、删除或漏洞利用工具 | | 输入拒绝 | `check_input()` 拒绝攻击/偏离主题的提示词 | | 工具白名单 | 仅限 4 个指定工具；拒绝未知工具 | | 私有 IP 保护 | 针对 RFC1918/保留 IP 阻止外部情报 / 地理位置查询 | | 速率限制 | 限制每个会话的最大工具调用次数和调查频率 | | 风险底线 | `compute_tool_risk_floor()` 防止对黑名单命中进行低评 | | API 密钥管理 | Groq/Together 密钥仅从服务器端环境变量读取 —— 绝不出现在 UI、导出文件或浏览器中 | | 分析师免责声明 | UI + README：在采取行动前，请与内部遥测数据进行关联确认 | ## 🔄 CI/CD GitHub Actions 会在每次向 `main` / `master` 分支推送代码和发起 Pull Request 时运行： - **工作流:** `.github/workflows/tests.yml` - **范围:** 64 个离线单元测试（工具、护栏、解析、演示、风险评分器、LLM 错误、导出格式、密钥处理） - **所需 API 密钥:** **无** —— CI 不会调用 Groq、Ollama 或外部威胁 API - **集成测试**（`tests.test_integration_investigate`）仅在配置了 LLM 时于本地运行或手动触发 这是一个用于保障回归安全的 **CI 流水线**；**CD**（持续部署）由 Streamlit Cloud 在代码合并到默认分支时处理。 ## 📈 项目状态与构建日志 | 步骤 | 重点 | 状态 | |------|-------|--------| | 1 | ReAct 智能体 + 4 个工具 | ✅ | | 2 | 护栏 + 演示事件 | ✅ | | 3 | 风险评分器 + 质量门禁 | ✅ | | 4 | Streamlit UI + 自定义主题 | ✅ | | 5 | Groq 集成 + 错误用户体验 | ✅ | | 6 | 64 个离线测试 + 集成测试环境 | ✅ | | 7 | GitHub Actions CI | ✅ | | 8 | Streamlit Cloud 部署 | ✅ | **当前状态:** ✅ MVP 完成 —— 可随时进行公开演示部署 ## 📁 仓库结构 ``` ├── app.py # Streamlit UI ├── agent.py # ReAct investigation loop ├── config/settings.py # LLM provider, limits, secrets loading ├── tools/ # ip_lookup, whois, log_matcher, threat_intel ├── utils/ │ ├── guardrails.py # Input/tool safety │ ├── llm.py # Ollama / Groq / Together HTTP client │ ├── llm_errors.py # Friendly error mapping │ ├── risk_scorer.py # Tool evidence risk floor │ ├── export_format.py # JSON + plain-text report exports │ └── secrets.py # API key presence checks (no values exposed) ├── docs/screenshots/ # README demo images ├── demo/example_events.json # 6 SOC demo scenarios ├── scripts/run_demo_investigations.py ├── tests/ # Unit + integration tests ├── .github/workflows/tests.yml # CI pipeline ├── .streamlit/config.toml # Custom theme defaults ├── .env.example # Local config template (Groq default) └── requirements.txt ``` ## 📄 许可证 **MIT 许可证** —— 详见 [LICENSE](LICENSE)。 ## 🤝 联系方式 / 后续计划 欢迎提供反馈、建议以及与项目目标一致的协作。 **未来可能的探索方向** *(不对时间表做任何承诺)*: - 针对日志匹配结果进行 MITRE ATT&CK 技术映射 - 调查历史持久化存储（数据库 / 导出归档） - 在长时间调查过程中显示实时的步骤进度 - 面向生产环境的 AbuseIPDB 优先威胁情报配置 - PDF / 可分享的分析师报告导出 - 更多工具集成（Passive DNS、VirusTotal）
app.py] end subgraph Guard["Safety Layer"] IG[Input guard
scope & attack refusal] TG[Tool guard
whitelist · private IP blocks] RL[Rate limits
per investigation] end subgraph Agent["Agent Layer — agent.py"] BOOT[Log bootstrap
auto log_pattern_match] REACT[ReAct loop
Thought → Action → Observation] PARSE[Response parser
+ format retry] RF[Risk floor merge
utils/risk_scorer.py] RPT[Investigation report
Low / Medium / High] end subgraph Tools["Tool Layer — tools/"] LOG[log_pattern_match
regex signatures] TI[threat_intel
heuristics + AbuseIPDB] IP[ip_lookup
ipapi.co] WHO[whois_lookup
python-whois] end subgraph Models["Model Layer — utils/llm.py"] GROQ[Groq API
llama-3.1-8b-instant] OLL[Ollama API
local models] TGT[Together API
optional fallback] end U --> UI UI --> IG IG -->|allowed| BOOT BOOT --> LOG BOOT --> REACT REACT --> GROQ REACT --> OLL REACT --> TGT REACT --> TG TG --> LOG TG --> TI TG --> IP TG --> WHO LOG --> REACT TI --> REACT IP --> REACT WHO --> REACT REACT --> PARSE PARSE --> RF RF --> RPT RPT --> UI IG -->|refused| UI RL --> REACT ``` **关键设计决策：** - **直接使用 HTTP 连接 LLM** —— 极简依赖，对 Windows 友好的安装体验 - **工具风险底线** —— 报告风险 = max(LLM 评级, 工具证据)；黑名单的高风险（High）不能变为低风险（Low） - **自动日志扫描（步骤 0）** —— 类日志事件在进入 LLM 循环前会先进行 `log_pattern_match` 匹配 - **结构化的护栏观察结果** —— 私有 IP / 无效的查询错误以 JSON 格式返回，以便智能体对其进行推理 - **显式的 `LLM_PROVIDER`** —— 不会仅凭密钥的存在就自动选择 Groq - **服务端 API 密钥** —— Groq/Together 凭据仅存在于环境变量/机密配置中；绝不发送至浏览器或导出文件 ### 开发历程 ``` flowchart LR A[ReAct agent
4 read-only tools] --> B[Guardrails
input + tool whitelist] B --> C[Risk floor
blocklist / log severity] C --> D[Streamlit UI
chain-of-thought + custom theme] D --> E[Quality gates
6 demo integration tests] E --> F[Groq profile
llama-3.1-8b-instant] F --> G[LLM error UX
429 · auth · timeout] G --> H[64 offline tests
+ GitHub Actions CI] H --> I[GitHub + Streamlit deploy
MVP] ``` ## 🚀 在线演示 **[▶ 在 Streamlit Cloud 中打开在线应用](https://simple-autonomous-security-agent.streamlit.app/)** **截图：**  *截图来自使用 Groq (`llama-3.1-8b-instant`) 的运行过程。工具证据和风险评级基于确定性检查；LLM 生成的叙述文本可能因提供商、模型和具体运行情况而异。* 本地演示：`streamlit run app.py` → 在侧边栏加载演示事件 → **调查**。 ## 快速开始 ### 前置条件 - Python 3.10+ - **Groq**（默认）：在 [console.groq.com](https://console.groq.com) 获取免费 API 密钥 - **或 Ollama**（本地）：[ollama.com](https://ollama.com) + `ollama pull gemma3:4b` ### 安装说明 ``` git clone https://github.com/rvong65/simple-autonomous-security-agent.git cd simple-autonomous-security-agent python -m venv .venv # Windows .\.venv\Scripts\Activate.ps1 # macOS / Linux # source .venv/bin/activate pip install -r requirements.txt cp .env.example .env # 编辑 .env — 添加 GROQ_API_KEY（或在 .env.example 中切换到 Ollama block） streamlit run app.py ``` 配置参考：请参阅 `.env.example`（本地）和 `.streamlit/secrets.toml.example`（Streamlit Cloud）。 **Groq 批量测试**（全部 6 个演示 —— 使用延迟以避免 HTTP 429 错误）： ``` python scripts/run_demo_investigations.py --delay 15 ``` ## ✨ 功能 - **自主 ReAct 循环** —— 最多 8 个步骤，完全透明 - **4 种调查工具** —— 日志模式、威胁情报、IP 查询、WHOIS（均为只读） - **风险底线强制执行** —— 工具证据设定了报告的最低严重性限制 - **输入与工具护栏** —— 拒绝攻击/偏离主题的请求；阻止对私有 IP 的外部查询 - **网络安全 UI** —— 自定义主题，IBM Plex Sans + JetBrains Mono 字体，“工作原理”侧边栏 - **分析师导出功能** —— 可下载的 JSON 调查报告和纯文本摘要 (.txt) - **友好的 LLM 错误提示** —— 速率限制 (429)、身份验证、超时，并提供可选的技术详情 - **混合 LLM** —— Groq（云端默认）或 Ollama（本地）；Together 作为可选的备用方案 ## 🛡️ 安全注意事项 | 原则 | 实现方式 | |-----------|----------------| | 只读操作 | 无阻断、删除或漏洞利用工具 | | 输入拒绝 | `check_input()` 拒绝攻击/偏离主题的提示词 | | 工具白名单 | 仅限 4 个指定工具；拒绝未知工具 | | 私有 IP 保护 | 针对 RFC1918/保留 IP 阻止外部情报 / 地理位置查询 | | 速率限制 | 限制每个会话的最大工具调用次数和调查频率 | | 风险底线 | `compute_tool_risk_floor()` 防止对黑名单命中进行低评 | | API 密钥管理 | Groq/Together 密钥仅从服务器端环境变量读取 —— 绝不出现在 UI、导出文件或浏览器中 | | 分析师免责声明 | UI + README：在采取行动前，请与内部遥测数据进行关联确认 | ## 🔄 CI/CD GitHub Actions 会在每次向 `main` / `master` 分支推送代码和发起 Pull Request 时运行： - **工作流:** `.github/workflows/tests.yml` - **范围:** 64 个离线单元测试（工具、护栏、解析、演示、风险评分器、LLM 错误、导出格式、密钥处理） - **所需 API 密钥:** **无** —— CI 不会调用 Groq、Ollama 或外部威胁 API - **集成测试**（`tests.test_integration_investigate`）仅在配置了 LLM 时于本地运行或手动触发 这是一个用于保障回归安全的 **CI 流水线**；**CD**（持续部署）由 Streamlit Cloud 在代码合并到默认分支时处理。 ## 📈 项目状态与构建日志 | 步骤 | 重点 | 状态 | |------|-------|--------| | 1 | ReAct 智能体 + 4 个工具 | ✅ | | 2 | 护栏 + 演示事件 | ✅ | | 3 | 风险评分器 + 质量门禁 | ✅ | | 4 | Streamlit UI + 自定义主题 | ✅ | | 5 | Groq 集成 + 错误用户体验 | ✅ | | 6 | 64 个离线测试 + 集成测试环境 | ✅ | | 7 | GitHub Actions CI | ✅ | | 8 | Streamlit Cloud 部署 | ✅ | **当前状态:** ✅ MVP 完成 —— 可随时进行公开演示部署 ## 📁 仓库结构 ``` ├── app.py # Streamlit UI ├── agent.py # ReAct investigation loop ├── config/settings.py # LLM provider, limits, secrets loading ├── tools/ # ip_lookup, whois, log_matcher, threat_intel ├── utils/ │ ├── guardrails.py # Input/tool safety │ ├── llm.py # Ollama / Groq / Together HTTP client │ ├── llm_errors.py # Friendly error mapping │ ├── risk_scorer.py # Tool evidence risk floor │ ├── export_format.py # JSON + plain-text report exports │ └── secrets.py # API key presence checks (no values exposed) ├── docs/screenshots/ # README demo images ├── demo/example_events.json # 6 SOC demo scenarios ├── scripts/run_demo_investigations.py ├── tests/ # Unit + integration tests ├── .github/workflows/tests.yml # CI pipeline ├── .streamlit/config.toml # Custom theme defaults ├── .env.example # Local config template (Groq default) └── requirements.txt ``` ## 📄 许可证 **MIT 许可证** —— 详见 [LICENSE](LICENSE)。 ## 🤝 联系方式 / 后续计划 欢迎提供反馈、建议以及与项目目标一致的协作。 **未来可能的探索方向** *(不对时间表做任何承诺)*: - 针对日志匹配结果进行 MITRE ATT&CK 技术映射 - 调查历史持久化存储（数据库 / 导出归档） - 在长时间调查过程中显示实时的步骤进度 - 面向生产环境的 AbuseIPDB 优先威胁情报配置 - PDF / 可分享的分析师报告导出 - 更多工具集成（Passive DNS、VirusTotal）
标签：AI风险缓解, Kubernetes, Python, ReAct框架, SOC分析, 告警分诊, 威胁情报, 安全智能体, 开发者工具, 无后门, 逆向工具