🛡️ AutoSOC Agent

项目简介

AutoSOC Agent 是一个基于 Agentic AI 技术的自动化安全运营中心系统，专注于网络流量分析和安全威胁检测。它采用先进的微内核 + 插件化架构，结合大语言模型的推理能力，实现了对网络流量的智能分析和安全威胁的自动检测。

核心功能

• 无感摄入：自动监听指定目录，当流量包放入后自动完成预处理
• 智能分析：利用大语言模型分析网络流量，识别潜在的安全威胁
• 插件化架构：支持自定义插件开发，轻松扩展新的安全分析功能
• 实时预警：发现异常流量时及时发出预警
• 流量可视化：提供直观的流量分析结果可视化

系统架构

AutoSOC Agent 采用 微内核 + 插件化架构，严格遵循开闭原则，确保新功能的扩展不会破坏现有核心。

架构层次

1. 内核层 (Core)：系统的"不动产"，负责生命周期管理、依赖注入、数据库连接池等
2. 基建层 (Infrastructure)：通用工具组件，如 Tshark 封装、目录监听、预处理引擎等
3. 领域层 (Domain)：系统的数据契约，定义统一的数据模型
4. 插件层 (Features/Plugins)：独立的功能包，如流量分析、SQL 注入检测等

数据流

1. 数据摄入：通过 Watchdog 监听目录，发现新的流量包
2. 预处理：Preprocessor 自动完成 PCAP 切片、Zeek 日志提取等
3. 情报上板：将提取的情报注入到 SQLite 黑板数据库
4. AI 分析：大语言模型分析结构化数据，识别安全威胁
5. 结果输出：生成分析报告并发出预警

目录结构

src/app/
├── core/                  # 🟢 [内核层] 系统的"不动产"
│   ├── server.py          # FastMCP 启动入口 & 环境变量注入
│   ├── loader.py          # 动态加载器：扫描 features 并注册
│   ├── context.py         # 依赖注入容器 (DI Container)
│   └── database.py        # SQLite 异步黑板与状态机
│
├── infrastructure/        # 🟡 [基建层] 屏蔽底层工具差异
│   ├── base_runner.py     # 包含熔断与超时的执行引擎基类
│   ├── tshark_runner.py   # Tshark 安全执行器 (防注入)
│   ├── watchdog.py        # 目录监听黑洞服务
│   └── preprocessor/      # 流量预处理引擎
│
├── domain/                # 🟣 [领域层] 数据契约
│   ├── traffic.py         # 流量相关数据模型
│   ├── workflow.py        # 工作流相关数据模型
│   └── interaction.py     # 交互相关数据模型
│
└── features/              # 🔴 [插件层] 业务逻辑游乐场
    ├── traffic_inspector/ # 流量分析插件
    ├── decoder/           # 数据解码插件
    └── admin_tools/       # 管理工具插件

安装指南

前置依赖

• Python 3.10+：系统运行环境
• Wireshark：提供 tshark 和 editcap 工具
• Zeek：可选，用于提取结构化日志
• SQLite：轻量级数据库，用于存储分析结果

安装步骤

1. 克隆项目

   git clone <repository-url>
   cd traffic_analysis
   

2. 创建虚拟环境

   python -m venv venv
   # Windows
   venv\Scripts\activate
   # Linux/Mac
   source venv/bin/activate
   

3. 安装依赖

   pip install -r requirements.txt
   

4. 配置环境变量（可选）

   # Windows
   set APP_WORKSPACE=./workspace
   set TSHARK_PATH=C:\Program Files\Wireshark\tshark.exe
   
   # Linux/Mac
   export APP_WORKSPACE=./workspace
   export TSHARK_PATH=/usr/bin/tshark
   

使用方法

启动系统

python run.py

系统启动后，会自动监听 workspace/pcap_inbox/ 目录，当流量包放入该目录时，系统会自动开始分析。

核心工具使用

1. 流量分析

   • get_pcap_summary：获取流量包的全局统计信息
   • inspect_packets：使用 Wireshark 语法查询特定数据包

2. 数据解码

   • decode_payload：解码各种编码格式的数据

3. 管理工具

   • run_garbage_collection：运行垃圾回收，清理过期数据

插件开发

AutoSOC Agent 支持自定义插件开发，只需按照以下步骤即可：

1. 创建插件目录

   mkdir -p src/app/features/my_plugin
   

2. 创建插件初始化文件

   # src/app/features/my_plugin/__init__.py
   from mcp.server.fastmcp import FastMCP
   from app.core.context import AppContext
   
   def register(mcp: FastMCP, ctx: AppContext):
       """
       插件注册函数
       """
       # 注册工具
       @mcp.tool(name="my_tool")
       async def my_tool(param: str) -> str:
           """
           我的工具
           """
           return f"处理结果: {param}"
   
       ctx.logger.info("plugin_registered", plugin="my_plugin")
   

3. 重启系统

   系统会自动发现并加载新的插件。

依赖项

依赖	版本	用途
Python	3.10+	运行环境
pydantic	最新版	数据验证和序列化
watchdog	最新版	目录监听
aiosqlite	最新版	异步 SQLite 操作
structlog	最新版	结构化日志
mcp	最新版	Agent 通信协议
Wireshark	3.0+	网络分析工具
Zeek	5.0+	流量日志提取

配置选项

配置项	环境变量	默认值	说明
工作目录	APP_WORKSPACE	./workspace	系统工作目录
Tshark 路径	TSHARK_PATH	自动查找	Tshark 可执行文件路径
数据库名称	DB_NAME	blackboard.db	数据库文件名称
监控目录	DROPZONE_FOLDER	pcap_inbox	流量包收件箱目录
最大包数限制	MAX_PACKET_LIMIT	1000	单次查询最大返回包数
默认超时时间	DEFAULT_TIMEOUT	30	子进程默认超时时间（秒）

贡献指南

我们欢迎社区贡献，包括但不限于：

• 修复 bug
• 添加新功能
• 改进文档
• 优化性能

贡献流程

1. Fork 仓库
2. 创建分支：git checkout -b feature/your-feature
3. 提交更改：git commit -m "Add your feature"
4. 推送分支：git push origin feature/your-feature
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

联系方式

• 项目主页：<repository-url>
• 问题反馈：<repository-url>/issues
• 邮箱：<maintainer-email>

致谢

• Wireshark：提供了强大的网络分析工具
• Zeek：提供了优秀的网络流量分析框架
• FastMCP：提供了高效的 Agent 通信协议
• 所有贡献者：感谢你们的辛勤工作和宝贵建议

---

AutoSOC Agent - 让网络安全分析更加智能、高效！