Metadata-Version: 2.4
Name: cybersec-agent
Version: 0.3.1
Summary: Enterprise cybersecurity AI agent system — 7 specialized agents with LLM orchestrator and 5-layer architecture
Author: CyberSec-AI
License: MIT
Keywords: security,cybersecurity,agent,pentest,threat-intel,mitre-attack
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

# 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 安装

```bash
# 从 PyPI 安装
pip install cybersec-agent

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

### 3.2 命令行使用

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

### 3.3 Python API 使用

```python
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())
```

---

## 四、核心场景与使用流程

### 场景 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 一键启动

```bash
python -m cybersec_agent.main
```

### 9.2 Python 嵌入

```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 集成（预留接口）

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

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

---

## 十、合规声明

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

---

## 版本历史

| 版本 | 更新内容 |
|:---:|:---|
| v0.3.0 | 新增法律合规声明、启动横幅提示 |
| v0.2.0 | 新增学习层：模式挖掘、策略注入、阈值自适应 |
| v0.1.0 | 初始发布：7 Agent + 5层架构 + 反馈闭环 |
