b33fydan/ARES
GitHub: b33fydan/ARES
对抗推理引擎系统，通过结构化辩论与证据绑定实现幻觉免疫的网络安全威胁检测。
Stars: 1 | Forks: 0
# ARES — 对抗推理引擎系统
**一种用于抗幻觉网络安全威胁检测的结构化辩论框架。**
ARES 使用多个 AI 代理之间的结构化辩论来分析安全威胁。它不盲目信任单一模型的输出，而是让三个专业化代理在一个封闭世界证据系统中相互论证，从而将幻觉转化为模式违规，而非神秘的 AI 行为。
## 核心思想
传统 AI 安全工具的致命缺陷在于：它们可以自信地编造证据。ARES 通过**辩证推理**解决这一问题：
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ ARCHITECT │────►│ SKEPTIC │────►│ ORACLE │
│ (Thesis) │ │ (Antithesis) │ │ (Synthesis) │
│ │ │ │ │ │
│ "This is a │ │ "Could be │ │ "Verdict: │
│ privilege │ │ scheduled │ │ THREAT_ │
│ escalation │ │ maintenance" │ │ CONFIRMED" │
│ attack!" │ │ │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┴───────────────────────┘
│
┌───────────▼───────────┐
│ EVIDENCE PACKET │
│ (Frozen Facts) │
│ │
│ All claims must cite │
│ facts that exist here │
└───────────────────────┘
```
**关键创新**：代理无法凭空捏造事实。每一个断言都必须引用不可变证据包（EvidencePacket）中的 `fact_id`。协调器会拒绝任何包含不存在引用的消息。这使得潜在幻觉变为可捕获的验证错误。
## 架构
```
ares/
├── graph/ # Security graph schema
│ ├── schema.py # Node/Edge definitions for security data
│ ├── store.py # Graph storage
│ └── validators.py # Graph validation
│
├── dialectic/ # Dialectical reasoning engine
│ ├── evidence/ # Evidence system
│ │ ├── provenance.py # Source tracking
│ │ ├── fact.py # Immutable fact representation
│ │ ├── packet.py # Frozen evidence container
│ │ └── extractors/ # Log-to-evidence converters
│ │ ├── protocol.py # Extractor protocol
│ │ ├── windows.py # Windows Event Log extractor
│ │ ├── syslog.py # Syslog extractor
│ │ └── netflow.py # NetFlow extractor
│ │
│ ├── messages/ # Communication protocol
│ │ ├── assertions.py # ASSERT, LINK, ALT assertion types
│ │ └── protocol.py # DialecticalMessage, MessageBuilder
│ │
│ ├── coordinator/ # Enforcement layer
│ │ ├── validator.py # Message validation against evidence
│ │ ├── cycle.py # Dialectical cycle state machine
│ │ ├── coordinator.py # Central authority (the "Bouncer")
│ │ ├── orchestrator.py # Single-turn production pipeline
│ │ └── multi_turn.py # Multi-turn debate orchestration
│ │
│ ├── agents/ # Reasoning agents
│ │ ├── base.py # AgentBase with critical invariants
│ │ ├── context.py # TurnContext, DataRequest
│ │ ├── patterns.py # AnomalyPattern, BenignExplanation, Verdict
│ │ ├── architect.py # THESIS phase — threat hypothesis
│ │ ├── skeptic.py # ANTITHESIS phase — benign alternatives
│ │ ├── oracle.py # SYNTHESIS phase — Judge + Narrator
│ │ └── strategies/ # LLM and rule-based agent strategies
│ │ ├── protocol.py # Strategy protocol
│ │ ├── rule_based.py # Deterministic strategy
│ │ ├── llm_strategy.py # Claude-powered strategy
│ │ ├── client.py # Anthropic API client
│ │ ├── prompts.py # Agent prompt templates
│ │ ├── live_cycle.py # Live LLM cycle runner
│ │ └── observability.py # Cycle metrics and logging
│ │
│ ├── memory/ # Memory stream
│ │ ├── entry.py # Memory entry representation
│ │ ├── stream.py # Stream interface
│ │ ├── chain.py # Evidence chain tracking
│ │ └── backends/ # Storage backends
│ │ └── in_memory.py # In-memory backend
│ │
│ └── scripts/ # Benchmark and corpus tools
│ ├── scenario_corpus.py # 33-scenario test corpus
│ ├── run_llm_benchmark.py # Live LLM benchmark runner
│ ├── benchmark_report.py # Report generation
│ ├── run_live_cycle.py # Single-scenario live runner
│ └── sample_packets.py # Example evidence packets
│
└── visual/ # ARES-VISION visualization system
├── events.py # Dialectical event model
├── emitter.py # Event emitter for cycles
├── live_emitter.py # Real-time WebSocket emitter
├── replayer.py # Session replay engine
├── diagnostics.py # Visual diagnostics
├── visualizer/ # Three.js particle physics visualizer
│ └── index_v5.html # Standalone visualizer (latest)
└── tests/ # Visual pipeline tests
```
## 快速开始
### 要求
- Python 3.11+
- Anthropic API 密钥（用于实时 LLM 分析）[Anthropic API 密钥](https://console.anthropic.com/)
### 安装
```
# 克隆仓库
git clone https://github.com/b33fydan/ARES.git
cd ARES
# 创建虚拟环境
python -m venv venv
venv\Scripts\activate # Windows
# source venv/bin/activate # Linux/Mac
# 安装依赖
pip install -r requirements.txt
```
### 运行测试
```
# 运行所有测试（2,246 个测试）
python -m pytest ares/ -v
# 按组件运行
python -m pytest ares/dialectic/tests/agents/ -v
python -m pytest ares/dialectic/tests/coordinator/ -v
python -m pytest ares/visual/tests/ -v
# 运行实时 LLM 测试（需要 ANTHROPIC_API_KEY）
python -m pytest ares/ -v --run-live-llm
# 运行带覆盖率
python -m pytest ares/ --cov=ares --cov-report=term-missing
```
### 基础用法
```
from ares.dialectic.evidence import EvidencePacket, Fact, Provenance, SourceType, EntityType
from ares.dialectic.agents import ArchitectAgent, SkepticAgent, OracleJudge, OracleNarrator
from ares.dialectic.agents.context import TurnContext, AgentRole
from ares.dialectic.messages.protocol import Phase
# 1. 构建包含安全事实的证据包
packet = EvidencePacket(packet_id="packet-001")
packet.add_fact(Fact(
fact_id="fact-001",
entity_type=EntityType.USER,
entity_id="user-jsmith",
field="privilege_level",
value="SYSTEM",
provenance=Provenance(source_type=SourceType.WINDOWS_EVENT_LOG, ...)
))
packet.freeze()
# 2. 创建智能体并绑定到证据
architect = ArchitectAgent(agent_id="arch-001")
skeptic = SkepticAgent(agent_id="skep-001")
architect.observe(packet)
skeptic.observe(packet)
# 3. 运行辩证周期
arch_context = TurnContext(
phase=Phase.THESIS,
packet_id=packet.packet_id,
snapshot_id=packet.snapshot_id,
cycle_id="cycle-001",
turn_number=1,
seen_fact_ids=frozenset()
)
arch_result = architect.act(arch_context)
skeptic.receive(arch_result.message)
skep_context = TurnContext(
phase=Phase.ANTITHESIS,
packet_id=packet.packet_id,
snapshot_id=packet.snapshot_id,
cycle_id="cycle-001",
turn_number=2,
seen_fact_ids=arch_result.message.fact_ids
)
skep_result = skeptic.act(skep_context)
# 4. 得出结论
verdict = OracleJudge.compute_verdict(
architect_msg=arch_result.message,
skeptic_msg=skep_result.message,
packet=packet
)
print(f"Verdict: {verdict.outcome}") # THREAT_CONFIRMED, THREAT_DISMISSED, or INCONCLUSIVE
print(f"Confidence: {verdict.confidence}")
print(f"Evidence: {verdict.supporting_fact_ids}")
```
## 关键不变式
ARES 将五条架构规则作为**模式违规**强制执行，而非运行时检查：
### 1. 数据包绑定
代理绑定到特定的证据包。它们不能使用来自其他包的事实。
```
agent.observe(packet_a)
agent.act(context_for_packet_b) # raises PacketMismatchError
```
### 2. 阶段约束
每个代理只能在其指定的阶段运行。
```
# Architect = 仅论点 | Skeptic = 仅反论 | Oracle = 仅综合
architect.act(antithesis_context) # raises PhaseViolationError
```
### 3. 证据溯源
所有断言必须引用绑定包中存在的 `fact_id`。
```
coordinator.submit(message_with_fake_facts) # raises ValidationError
```
### 4. 预言者分离
预言者分为判断者（确定性）和叙述者（受限）：
- **OracleJudge** — 纯函数，不使用 LLM，仅根据证据计算判决
- **OracleNarrator** — 解释判决，但无法修改判决内容
### 5. 判决锁定
一旦 OracleJudge 计算出判决，该判决即不可更改。OracleNarrator 在构造时接收一个锁定的判决。
## 免疫系统隐喻
ARES 以生物免疫系统为建模基础：
| 免疫系统组件 | ARES 组件 |
|--------------|-----------|
| 抗原 | 证据包中的事实 |
| T 辅助细胞 | 架构代理（识别威胁） |
| 调节性 T 细胞 | 怀疑代理（防止过度反应） |
| 细胞毒性 T 细胞 | 协调器（强制执行、终止） |
| MHC 限制 | 数据包绑定（仅响应绑定证据） |
| 克隆选择 | 证据追踪（仅存留有效的响应） |
| 自身免疫预防 | 封闭世界原则（无法攻击自身或产生幻觉） |
## 开发状态
ARES 已经历 39 个开发周期，并采用零回归策略。
### 阶段 1：架构固化 — 已完成
核心图模式、证据系统、消息协议、协调器与代理基础。
### 阶段 2：LLM 集成与基准测试 — 已完成
实时 Anthropic 集成、策略模式、提示工程、33 场景基准语料库、多轮辩论基础设施。
### 阶段 3：选择性升级 — 已完成（负结果）
研究了多轮辩论是否能提升准确性。发现：单轮流水线优于多轮辩论。这是一个有效的研究结果，并指导了单轮生产架构的设计。
### 阶段 4：精度提升与可视化 — 已完成
证据提取器（Windows、Syslog、NetFlow）、精度强化、ARES-VISION 粒子物理可视化器（支持实时 WebSocket 流与会话回放）。
| 组件 | 测试数 |
|------|--------|
| 证据系统 | 449 |
| 代理与策略 | 505 |
| 协调器与编排 | 389 |
| 基准与脚本 | 367 |
| 可视化管线 | 213 |
| 内存流 | 158 |
| 消息 | 85 |
| **总计** | **2,246** |
## 技术栈
- **语言**：Python 3.11
- **LLM**：Anthropic Claude（通过 `anthropic` SDK）
- **测试**：pytest（2,246 个测试，65 个因实时 LLM 跳过）
- **图计算**：NetworkX
- **可视化**：Three.js、WebSocket、粒子物理引擎
- **数据**：冻结数据类（不可变性作为架构约束）
## 许可证
[MIT](LICENSE)
## 作者
由 [Daniel Gmys-Casiano](https://github.com/b33fydan) 构建，采用结构化偏执与对抗性思维。
> “幻觉是模式违规，而非神秘的 AI 行为。”
标签：Agent协作, AI安全, Chat Copilot, Clair, Cloudflare, JSONLines, MITRE ATT&CK, PyRIT, Schema违反检测, 人工智能推理, 可信AI, 多智能体系统, 大模型安全, 威胁情报, 对抗推理, 幻觉免疫, 开发者工具, 攻击模拟, 特权检测, 结构化辩论, 网络安全威胁检测, 论题-反论题-综合, 证据冻结, 证据驱动决策, 辩证AI, 逆向工具, 零信任, 驱动签名利用