CyberSec-AI Agent — 企业级网络安全智能体系统

Agent = 推理能力 + 执行能力 + 结果闭环 + 自我学习

---

一、系统架构图

┌──────────────────────────────────────────────────────────────────┐
│                       用户交互层 (Workbench)                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │  CLI 命令行  │  │  Python API │  │  Webhook    │              │
│  │  cybersec   │  │  orchestrator│  │  (SIEM集成) │              │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
│         └─────────────────┼─────────────────┘                    │
│                           ▼                                       │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │  ⚖️  合规网关：中华人民共和国网络安全法授权校验           │     │
│  └─────────────────────────────────────────────────────────┘     │
│                           ▼                                       │
├──────────────────────────────────────────────────────────────────┤
│  感知层 (Perception Layer)                                       │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │  意图解析 → vuln_scan / threat_hunt / pen_test / ...    │     │
│  │  实体抽取 → IPs / Domains / CVEs / Tactics               │     │
│  │  澄清生成 → 模糊需求自动追问                              │     │
│  └─────────────────────────────────────────────────────────┘     │
│                           ▼                                       │
├──────────────────────────────────────────────────────────────────┤
│  编排层 (Orchestrator Layer)                                     │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │  任务分解 → 按意图映射到多步骤工作流                      │     │
│  │  动态注入 → 从学习层获取历史最优参数                       │     │
│  │  上下文传递 → 步骤间共享 findings / risk_score / assets   │     │
│  └─────────────────────────────────────────────────────────┘     │
│                           ▼                                       │
├──────────────────────────────────────────────────────────────────┤
│  工具层 (7 个专业安全智能体)                                     │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐             │
│  │威胁情报 Agent │ │漏洞扫描 Agent│ │威胁狩猎 Agent│             │
│  │ THREAT_INTEL │ │  VULN_SCAN   │ │ THREAT_HUNT  │             │
│  │ 蓝队          │ │ 蓝队          │ │ 蓝队          │             │
│  └──────┬───────┘ └──────┬───────┘ └──────┬───────┘             │
│         └─────────────────┼─────────────────┘                    │
│                           ▼                                       │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐             │
│  │应急响应 Agent│ │渗透测试 Agent│ │风险评估 Agent│             │
│  │INCIDENT_RESP │ │   PEN_TEST   │ │  RISK_ASSESS │             │
│  │ 蓝/紫队       │ │  红队         │ │  紫队         │             │
│  └──────┬───────┘ └──────┬───────┘ └──────┬───────┘             │
│         └─────────────────┼─────────────────┘                    │
│                           ▼                                       │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │ 报告生成 Agent  — 整合所有智能体输出 → 结构化报告         │     │
│  │ REPORT_GEN (蓝/紫队)                                     │     │
│  └─────────────────────────────────────────────────────────┘     │
├──────────────────────────────────────────────────────────────────┤
│  反馈层 (Feedback Layer)   ← 每步执行后实时评估                   │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │ 指标监控 · 趋势分析 · 自动恢复 · 跨会话统计               │     │
│  └─────────────────────────────────────────────────────────┘     │
│                           ▲                                       │
├──────────────────────────────────────────────────────────────────┤
│  学习层 (Learning Layer)   ← 持续迭代优化                        │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │ 模式挖掘 · 阈值自适应 · 策略推荐 · JSON 持久化            │     │
│  └─────────────────────────────────────────────────────────┘     │
│                           ▲                                       │
├──────────────────────────────────────────────────────────────────┤
│  支撑层 (Infrastructure)                                         │
│  logging / JSON存储 / asyncio并发 / UUID会话                    │
└──────────────────────────────────────────────────────────────────┘

---

二、三种使用角色

                    ┌──────────────────────────┐
                    │      用户角色选择         │
                    └────────────┬─────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              ▼                                  ▼
    ┌─────────────────┐                  ┌─────────────────┐
    │   🔵 蓝队 (DEF)  │                  │   🔴 红队 (ATT)  │
    │  防守 / 运营     │                  │  攻击 / 演练     │
    └────────┬────────┘                  └────────┬────────┘
             │                                     │
    ┌────────┴─────────────────────────────────────┴────────┐
    │                                                      │
    ▼                                                      ▼
  威胁情报                                             渗透测试
  漏洞扫描                                              攻击模拟
  威胁狩猎                                              kill chain
  应急响应                                              权限提升
  风险评估                                              报告生成
                                                        (红队视角)
    ┌────────────────────────────────────────────────────┐
    │              🟣 紫队 (COOP)                         │
    │         攻防协同 · 报告生成 · 风险评估               │
    └────────────────────────────────────────────────────┘

---

三、快速开始

3.1 安装

# 从 PyPI 安装
pip install cybersec-agent

# 或从本地源码安装
cd cybersec-agent
pip install -e .

3.2 命令行使用

# 启动交互式演示
python -m cybersec_agent.main

3.3 Python API 使用

import asyncio
from cybersec_agent import CyberSecOrchestrator
from cybersec_agent.core.base import Role

async def main():
    orch = CyberSecOrchestrator()

    # ① 漏洞扫描 + 风险评估（蓝队典型流程）
    result = await orch.run(
        "扫描 192.168.1.0/24 网段，发现高危漏洞并评估风险",
        role=Role.BLUE
    )
    print(result["report"])

    # ② 渗透测试（红队视角）
    result = await orch.run(
        "对 example.com 进行渗透测试，覆盖 Recon 到 Exploit",
        role=Role.RED
    )

    # ③ 查看学习统计
    learning = orch.learning.get_learning_report()
    print(f"已学习任务: {learning['total_learned_tasks']}")
    print(f"总体成功率: {learning['overall_success_rate']:.1%}")

asyncio.run(main())

---

四、CLI 命令行工具

# 安装
pip install cybersec-agent

# 查看帮助
cybersec --help

# 显示欢迎横幅 + 合规声明 + 当前配置
cybersec init

# 运行安全任务
cybersec run "对 192.168.1.0/24 进行漏洞扫描" --role blue
cybersec run "对 example.com 进行渗透测试"   --role red
cybersec run " hunting for APT phishing indicators" --role blue

# 切换模型（默认 openai/gpt-4o → 本地 ollama/llama3.2）
cybersec model --list          # 查看所有可用模型
cybersec model --set ollama/llama3.2   # 设为本地免费模型
cybersec model --set openai/gpt-4o-mini
cybersec model                  # 查看当前配置

# 列出所有智能体
cybersec agents

# 查看学习统计
cybersec stats

模型配置自动保存到 ~/.cybersec/config.json，下次启动自动加载。

---

五、核心场景与使用流程

场景 A：常规漏洞扫描（蓝队）

用户输入 → 感知层解析意图=vuln_scan
    ↓
编排层分解为 3 步：
    Step 1 → vuln_scan_agent.discover(target_ips)
    Step 2 → vuln_scan_agent.scan(findings=step1输出)
    Step 3 → risk_assess_agent.prioritize(findings=step2输出)
    ↓
学习层注入历史最优参数（如有）
    ↓
反馈层评估每步成功率 + 耗时
    ↓
生成最终报告

场景 B：事件应急响应（蓝队）

用户输入 → 感知层解析意图=incident_response
    ↓
编排层分解为 4 步：
    Step 1 → ir_agent.triage(indicators=[IOC列表])
    Step 2 → ir_agent.collect()        # 证据采集
    Step 3 → ir_agent.contain()        # 遏制隔离
    Step 4 → ir_agent.timeline()       # 时间线重建
    ↓
生成 IR 报告（符合 NIST SP 800-61）

场景 C：渗透测试演练（红队）

用户输入 → 感知层解析意图=pen_test
    ↓
编排层分解为 4 步：
    Step 1 → pen_test_agent.recon(target_domain)
    Step 2 → pen_test_agent.scan()
    Step 3 → pen_test_agent.exploit()
    Step 4 → report_agent.generate(type="pentest_report")
    ↓
生成渗透测试报告（符合 PTES / OWASP）

场景 D：威胁情报聚合（蓝队）

用户输入 → 感知层解析意图=threat_intel
    ↓
编排层分解为 3 步：
    Step 1 → threat_intel_agent.collect()      # 多源 IOC 聚合
    Step 2 → threat_intel_agent.analyze()       # ATT&CK 映射 / APT 归因
    Step 3 → report_agent.generate(type="threat_intel_report")
    ↓
生成威胁情报报告（符合 STIX 2.0）

---

六、智能体能力矩阵

Agent	角色	输入	核心能力	输出
ThreatIntel	🔵	IOC / APT 名称	STIX 聚合、ATT&CK 映射、归因分析	IOC 报告
VulnScan	🔵	IP/网段/域名	端口扫描、CVE 匹配、CVSS/EPSS 评分	漏洞清单
ThreatHunt	🔵	假设/日志	UEBA 异常检测、Sigma/YARA 规则生成、横向移动追踪	狩猎报告
IncidentResp	🔵	IOC/告警	事件分级、证据采集、遏制清除、时间线	IR 报告
PenTest	🔴	目标域名/IP	侦察→扫描→利用→后渗透、kill chain 全覆盖	渗透报告
Report	🟣	多 Agent 输出	Markdown/HTML/PDF 生成、等保2.0/ISO27001 合规映射	结构化报告
RiskAssess	🟣	漏洞列表+资产	资产价值×威胁×脆弱性=风险值、P0-P3 优先级排序	风险矩阵

---

七、六层架构详解

Layer 1  感知层 (Perception)
         输入：自然语言 / 结构化请求
         输出：意图 + 实体 + 置信度
         关键：正则意图识别、实体抽取（IP/CVE/Tactic）

Layer 2  编排层 (Orchestrator)
         输入：PerceptionResult
         输出：步骤列表 (steps[])
         关键：意图→步骤映射、步骤间数据传递、学习参数注入

Layer 3  工具层 (Agents)
         7 个专业化智能体，每个继承 BaseAgent
         关键：execute() + generate_feedback() 双接口

Layer 4  反馈层 (Feedback)
         输入：每步执行结果
         输出：FeedbackMetric + 跨会话趋势
         关键：成功率追踪、MTTR 计算、趋势判断

Layer 5  学习层 (Learning)
         输入：LearningRecord[]
         输出：策略建议（params_hint）
         关键：pattern 挖掘、阈值自适应、JSON 持久化

Layer 6  合规层 (Compliance)
         在感知层入口强制插入法律声明
         关键：所有操作需书面授权，禁止破坏性攻击

---

八、学习闭环机制

┌─────────────────────────────────────────────────────────┐
│                    学习闭环 (Learning Loop)              │
│                                                         │
│   执行任务 → 记录结果 → 挖掘模式 → 注入优化 → 再次执行   │
│      │                                                         │
│      ▼                                                         │
│   LearningRecord(成功/失败/耗时/参数)                          │
│      │                                                         │
│      ▼                                                         │
│   LearnedPattern (成功率 > 阈值 + 样本数 > 3)                  │
│      │                                                         │
│      ▼                                                         │
│   get_strategy_hint() → 返回 suggested_params                  │
│      │                                                         │
│      └──→ _inject_learning() → 合并到下一步 params             │
│                                                             │
└─────────────────────────────────────────────────────────┘

示例：
  第1次运行：scan 参数 default_timeout=30
  第10次运行：学习引擎发现 timeout=60 时成功率 95% vs timeout=30 时 60%
  第11次运行：自动注入 timeout=60 → 成功率提升至 95%

---

九、文件结构

cybersec-agent/
├── cybersec_agent/
│   ├── __init__.py            # 包导出
│   ├── main.py                # 编排器入口 + 示例
│   ├── core/
│   │   ├── base.py            # BaseAgent / BaseOrchestrator / Role
│   │   ├── perception.py      # 感知层 + 法律合规声明
│   │   ├── feedback.py        # 反馈层 + 跨会话趋势
│   │   └── learning.py        # 学习层 + 模式挖掘
│   └── agents/
│       ├── threat_intel.py    # 威胁情报
│       ├── vuln_scanner.py    # 漏洞扫描
│       ├── threat_hunter.py   # 威胁狩猎
│       ├── incident_response.py # 应急响应
│       ├── pen_test.py        # 渗透测试
│       ├── report_gen.py      # 报告生成
│       └── risk_assessor.py   # 风险评估
├── reports/                   # 学习数据存储 & 报告输出
├── pyproject.toml
└── README.md

---

十、集成方式

9.1 CLI 一键启动

python -m cybersec_agent.main

9.2 Python 嵌入

from cybersec_agent import CyberSecOrchestrator
from cybersec_agent.core.base import Role

orch = CyberSecOrchestrator()
result = await orch.run("扫描内网段并生成风险报告", role=Role.BLUE)
# result["report"] → 完整报告
# result["learning"] → 学习统计

9.3 SIEM / SOC 集成（预留接口）

# 通过 webhook 接收告警，触发响应
orch = CyberSecOrchestrator()

# 将 SIEM 告警直接传入
result = await orch.run(
    "SOC 告警: host-x 检测到 Mimikatz 进程，IOC=abc123",
    role=Role.BLUE
)
# 自动触发 IncidentResponseAgent 进行处置

---

十一、自定义模型配置

系统支持灵活的 LLM 后端切换，每个 Agent 可使用不同提供商/型号的模型。

10.1 支持的提供商

提供商	Provider 常量	API Key 环境变量	说明
OpenAI	Provider.OPENAI	OPENAI_API_KEY	默认，支持 GPT-4o / o1 / o3 等
OpenRouter	Provider.OPENROUTER	OPENROUTER_API_KEY	统一接入 100+ 模型
Ollama	Provider.OLLAMA	无需	本地运行 Llama/Qwen/Mistral 等
Anthropic	Provider.ANTHROPIC	ANTHROPIC_API_KEY	Claude 系列（需 pip install anthropic）
自定义端点	Provider.CUSTOM	手动指定	任何 OpenAI 兼容 API

10.2 快速配置示例

import asyncio
from cybersec_agent import CyberSecOrchestrator
from cybersec_agent.config.models import ModelConfig, AgentModelConfig, Provider
from cybersec_agent.core.base import Role

# === 方式一：全局默认模型 ===
orch = CyberSecOrchestrator(
    model_config=AgentModelConfig(
        default=ModelConfig(
            provider=Provider.OPENAI,
            model_name="gpt-4o",
            api_key="sk-xxx",   # 或设置 OPENAI_API_KEY 环境变量
            temperature=0.5,
            max_tokens=4096,
        )
    )
)

# === 方式二：每个 Agent 使用不同模型 ===
orch = CyberSecOrchestrator(
    model_config=AgentModelConfig(
        default=ModelConfig(provider=Provider.OPENAI, model_name="gpt-4o"),
        agent_overrides={
            "pen_test_agent":      ModelConfig(provider=Provider.OPENAI, model_name="gpt-4o-mini"),  # 轻量快速
            "threat_hunt_agent":   ModelConfig(provider=Provider.OLLAMA,  model_name="llama3.2"),    # 本地免费
            "incident_response_agent": ModelConfig(provider=Provider.OPENAI, model_name="o3-mini"),  # 推理最强
            "report_agent":        ModelConfig(provider=Provider.OPENROUTER, model_name="anthropic/claude-3.5-sonnet"),
        }
    )
)

# === 方式三：纯环境变量驱动（无需代码中写 key）===
# 设置环境变量：export OPENAI_API_KEY="sk-xxx"
# export OPENAI_MODEL="gpt-4o"
from cybersec_agent.config.models import build_model_config_from_env
orch = CyberSecOrchestrator(
    model_config=AgentModelConfig(default=build_model_config_from_env(Provider.OPENAI))
)

async def main():
    result = await orch.run(
        "对 10.0.0.0/24 进行漏洞扫描",
        role=Role.BLUE
    )
    print(result["report"])

asyncio.run(main())

10.3 各智能体推荐模型

Agent	推荐模型	理由
PenTest	gpt-4o-mini 或本地 llama3.2	逻辑推理要求适中，追求速度
ThreatHunt	llama3.2 (Ollama)	长期运行，本地模型零成本
IncidentResponse	o3-mini 或 claude-3.5-sonnet	需要强推理和应急判断
Report	gpt-4o 或 claude-3.5-sonnet	报告质量要求高
其余 Agent	gpt-4o 默认	平衡性能与成本

10.4 自定义 API 端点

系统支持连接任意 OpenAI 兼容的自托管 LLM 服务：

# vLLM 本地部署（最常用）
cybersec model --set custom/gpt-4o --url http://localhost:8000/v1 --key dummy

# LocalAI
cybersec model --set custom/llama3.2 --url http://localhost:8080/v1

# LM Studio
cybersec model --set custom/llama3.2 --url http://localhost:1234/v1

# 远程私有 API
cybersec model --set custom/qwen2.5 --url https://api.internal.com/v1 --key sk-xxx

# 不保存 key（每次运行时从环境变量读取）
export OPENAI_API_KEY=sk-xxx
cybersec model --set custom/gpt-4o --url http://localhost:8000/v1

安全提示：使用 --key 传入的 API Key 不会保存到配置文件，仅在本会话中使用。如需持久化，请设置对应环境变量（OPENAI_API_KEY / ANTHROPIC_API_KEY）。

---

十二、合规声明

⚖️ 本系统严格遵循《中华人民共和国网络安全法》及相关法律法规。 所有安全评估、渗透测试及漏洞扫描操作必须在获得明确书面授权后进行。 禁止对未授权目标实施任何形式的破坏性攻击或未经授权的系统访问。

使用本系统即表示您确认已获得相应授权，并承诺仅用于合法合规的安全研究目的。

---

十三、版本历史

版本	更新内容
v0.5.0	新增自定义 API 端点：--url/--key 支持任意 OpenAI 兼容服务（vLLM/LocalAI/LM Studio 等），KEY 不落地存储
v0.4.1	新增 CLI 命令行工具：cybersec run/agents/stats/model/init，支持配置持久化
v0.4.0	新增自定义 LLM 模型配置：支持 OpenAI/Ollama/OpenRouter/Anthropic，每个 Agent 可独立指定模型
v0.3.1	新增法律合规声明、启动横幅提示
v0.2.0	新增学习层：模式挖掘、策略注入、阈值自适应
v0.1.0	初始发布：7 Agent + 5层架构 + 反馈闭环