内容
# 自主响应与守护统一安全
**一个多代理的SOC副驾驶，检测、丰富、调查和报告网络入侵 - 使用谷歌ADK、真正的MCP服务器和每层的安全设计构建。**
这是ARGUS的顶级工作区文档和使用指南。
## 🏗️ 架构与流程
ARGUS协调多个专门的代理角色来处理警报分类和调查：
```mermaid
flowchart TD
IN[输入流 + 可选PCAP / IOC] --> TRI[分类代理]
TRI --> PAR{{并行代理}}
PAR --> ENR[丰富代理]
PAR --> FOR[取证代理]
ENR --> REM[修复代理<br/>仅提案]
FOR --> REM
REM --> REP[报告代理<br/>零工具]
REP --> OUT[事件报告]
TRI & ENR & FOR & REM -. MCP .-> MCP[(ARGUS MCP 服务器)]
MCP --> RF[RF 流分类器]
MCP --> ATT[MITRE ATT&CK 映射]
MCP --> VT[IOC 丰富]
MCP --> PCAP[PCAP 取证]
```
## 🚀 快速开始（零设置）
ARGUS设计为开箱即用。Gemini API密钥嵌入在 [config.py](file:///c:/Users/suzum/Downloads/argus-soc-agent/argus/config.py) 中，包含自我修复的模型备用链和速率限制重试逻辑。
### 1. 设置环境
在仓库中激活预配置的虚拟环境：
**在 Windows 上（PowerShell）：**
```powershell
.\venv\Scripts\Activate.ps1
```
**在 Windows 上（CMD）：**
```cmd
.\venv\Scripts\activate.bat
```
**在 Linux/macOS 上：**
```bash
source venv/bin/activate
```
### 2. 安装依赖
从仓库根目录以可编辑模式安装 `argus` 包：
```bash
pip install -e ./argus
```
### 3. 生成样本数据和训练机器学习模型
生成一个合成网络捕获文件（PCAP）并训练随机森林流分类器：
```bash
# 在 argus/data/ 中生成 sample_portscan.pcap
python argus/scripts/make_sample_pcap.py
# 训练随机森林模型（运行网格搜索调优）
python argus/scripts/train_model.py
```
*（提示：您可以使用 `python argus/scripts/train_model.py --fast` 跳过超参数调优并立即训练。）*
## 🖥️ 运行 Web 仪表盘
Web 仪表盘提供了一个完整的用户界面，用于运行确定性离线调查和实时 Gemini 多代理流。
启动 FastAPI/Uvicorn 服务器：
```bash
uvicorn argus.dashboard.app:app --reload --port 8000
```
在浏览器中打开 **[http://localhost:8000](http://localhost:8000)**。
从标题栏中，您可以切换到：
- ⚡ **离线管道** — 即时、确定性、零 API 调用。
- 🧠 **实时代理（Gemini）** — 真正的 ADK 多代理流运行于 Gemini。
## 🛠️ 命令行界面和代理技能
SOC 调查管道的每个阶段都作为一个独立的、可脚本化的“代理技能”通过 `argus` 命令行界面公开。
```bash
# 训练流分类器
argus train
# 分类一个随机的合成流
argus detect --random
# 查询威胁情报（VirusTotal 丰富模拟）以获取 IP 地址
argus enrich 185.220.101.45
# 总结 PCAP 文件的流量
argus forensics argus/data/sample_portscan.pcap
# 查找 MITRE ATT&CK 技术以获取标签
argus attack DDoS
# 提出修复剧本
argus playbook DDoS --confidence 0.95
# 运行完整的离线管道调查
argus investigate --random --pcap argus/data/sample_portscan.pcap --ip 185.220.101.45
# 运行完整的实时多代理 Gemini 调查
argus investigate --random --live
# 验证审计日志的加密链完整性
argus audit verify
```
## 🧪 运行测试
要验证包完整性，请运行单元测试套件：
```bash
pytest -q argus
```
所有 22 个单元测试都在离线运行，测试流检测器、MITRE 映射、安全防护、审计日志和仪表盘端点。
## 📁 仓库目录布局
* [argus/agents/](file:///c:/Users/suzum/Downloads/argus-soc-agent/argus/agents/) - 多代理系统编排（谷歌 ADK）。
* [argus/cli/](file:///c:/Users/suzum/Downloads/argus-soc-agent/argus/cli/) - 命令行界面定义。
* [argus/dashboard/](file:///c:/Users/suzum/Downloads/argus-soc-agent/argus/dashboard/) - FastAPI 后端和静态 HTML/CSS 前端仪表盘。
* [argus/mcp_server/](file:///c:/Users/suzum/Downloads/argus-soc-agent/argus/mcp_server/) - FastMCP 服务器公开工具（PCAP 分析、威胁情报、MITRE 映射）。
* [argus/ml/](file:///c:/Users/suzum/Downloads/argus-soc-agent/argus/ml/) - 合成特征生成器和随机森林模型代码。
* [argus/security/](file:///c:/Users/suzum/Downloads/argus-soc-agent/argus/security/) - PII 删减、工具允许列表、提示注入检查和哈希链审计日志。
* [argus/scripts/](file:///c:/Users/suzum/Downloads/argus-soc-agent/argus/scripts/) - 模型训练和 PCAP 生成器脚本。
* [argus/tests/](file:///c:/Users/suzum/Downloads/argus-soc-agent/argus/tests/) - 全面的离线测试套件。
* [argus/deploy/](file:///c:/Users/suzum/Downloads/argus-soc-agent/argus/deploy/) - Docker 和 Cloud Run 部署资源。
