zipgod24/AetherFlow

## 为什么选择 AetherFlow 大多数“AI Agent”代码库都只是链式连接到 OpenAI 的单个 Python 笔记本。AetherFlow 则是作为生产级基础设施来构建的： - **事件驱动，而非 RPC 意大利面条式架构。** Agent 之间从不直接相互调用。所有内容都通过具有持久队列、按阶段死信路由、幂等键和有限次重试的 RabbitMQ topic exchange 传输。你可以在流程中间杀死任何 Agent，整个 saga 会自动恢复。 - **Agentic RAG，而非朴素 RAG。** Retriever 会自行决定*是否*以及*如何*进行搜索。它将密集的 pgvector ANN 与稀疏的 `tsvector` BM25 风格评分（混合搜索）相结合，然后使用倒数秩融合进行重排。它还可以将实时 DNS 查询和威胁情报解析作为另一种工具来执行。 - **DNS 原生服务发现。** 服务通过 SRV 记录相互查找（开发环境使用本地 CoreDNS，生产环境使用 Kubernetes headless services）。没有硬编码的主机名，也不需要外挂 Consul。 - **具备对抗意识。** 专用的 Validator Agent 会在任何 Executor 动作运行之前，筛查每个 Reasoner 的输出是否包含 prompt 注入标记、越狱启发式特征、schema 偏移和引文幻觉。 - **可观测性第一。** 每一个事件、LLM 调用、数据库查询和 DNS 查询都是单个 OpenTelemetry 链路中的一个 span。Jaeger 已内置在 compose 文件中。 - **BYO-LLM。** Ollama 开箱即用支持本地运行。Web UI 中提供了一个密钥管理面板，任何审查人员都可以粘贴 OpenAI / Anthropic / 兼容 OpenAI 的 endpoint，并使用托管模型重新运行同一事件——无需重新构建，也无需编辑环境变量文件。 ## 架构 ``` flowchart LR subgraph Edge UI[Web UI
vanilla JS + Tailwind] CLI[aetherctl CLI] end UI -- HTTP/SSE --> GW CLI -- HTTP --> GW GW[API Gateway
cmd/api-gateway] subgraph Bus[RabbitMQ — topic: aether.events] direction LR RK1((incident.created)) RK2((context.assembled)) RK3((analysis.completed)) RK4((analysis.validated)) RK5((action.executed)) DLX[(aether.dlx
dead-letter)] end GW -- publishes --> RK1 RK1 --> RET[Retriever Agent] RET -- pgvector + tsvector --> PG[(Postgres
+ pgvector)] RET -- SRV + TXT --> DNS{{CoreDNS / k8s DNS}} RET -- threat-intel --> DNS RET -- publishes --> RK2 RK2 --> REA[Reasoner Agent] REA -- chat completion --> LLM[(LLM Provider
Ollama / OpenAI / Anthropic)] REA -- publishes --> RK3 RK3 --> VAL[Validator Agent] VAL -- rejects --> DLX VAL -- publishes --> RK4 RK4 --> EXE[Executor Agent] EXE -- mock action APIs --> EXT[(Firewall / Pager
mock adapters)] EXE -- publishes --> RK5 GW -- SSE stream --> UI GW -.-> OTEL[(OpenTelemetry / Jaeger)] RET -.-> OTEL REA -.-> OTEL VAL -.-> OTEL EXE -.-> OTEL ``` ### Agent 循环的通俗解释 ``` sequenceDiagram autonumber participant U as User / SOC analyst participant GW as API Gateway participant R as Retriever participant Reason as Reasoner participant V as Validator participant E as Executor participant L as LLM U->>GW: POST /v1/incidents { description } GW->>R: incident.created (AMQP) R->>R: DNS A/AAAA/MX/TXT lookups R->>R: pgvector ANN + tsvector hybrid search R->>R: reciprocal rank fusion + dedupe R->>Reason: context.assembled Reason->>L: prompt with retrieved evidence + tool spec L-->>Reason: structured analysis (JSON) Reason->>V: analysis.completed V->>V: prompt-injection scan, schema check,
citation grounding check alt invalid V-->>GW: validation.rejected → DLX else valid V->>E: analysis.validated E->>E: idempotent action (block IP, page on-call) E->>GW: action.executed end GW-->>U: SSE stream of every transition ``` ### 为什么各个组件都非同小可 | 关注点 | AetherFlow 的做法 | 为什么重要 | | --- | --- | --- | | 可靠性 | 带有 `x-death` 跟踪的按阶段死信 exchange；有限次重试；幂等键去重表 | 允许你崩溃任何 Agent 并安全重放 | | 吞吐量 | 按 Agent 调优的 prefetch；消费者池；通过 QoS 实现背压 | 当 LLM 停滞时，单个 Reasoner 不应被淹没 | | 混合 RAG | pgvector (余弦) + Postgres `ts_rank_cd` → 倒数秩融合 → 可选的 cross-encoder 重排槽 | 单独的稠密检索在语义上表现很好，但对于精确标识符（CVE-2024-…, IP 文本）却很糟糕。混合搜索才是生产环境的答案 | | 服务发现 | 每个服务通过 DNS SRV 注册；客户端解析 `_amqp._tcp.aether.local` 等 | 将新的副本放入集群中，总线客户端无需配置即可自动识别 | | LLM 可移植性 | `llm.Provider` 接口；Ollama, OpenAI, Anthropic 以及通用的 OpenAI 兼容适配器；通过 header 实现按请求覆盖 | 审查人员可以在 UI 中切换提供商 | | 安全性 | Prompt 注入词典 + 正则栈，结构化输出 JSON schema 强制执行，支持 mTLS 的传输，仅在 env / Vault 中存储 secrets | Validator 是一个真正的 Agent，而不是摆设 | | 可观测性 | 每个二进制文件中都包含 OTel SDK；通过 AMQP headers 传播 trace；compose 中包含 Jaeger UI | 单个 trace 即可展示从点击到防火墙模拟的完整事件 | ## 快速开始 前置条件：Docker + Docker Compose，Go 1.22+，约 6 GB 可用空间用于 Ollama 镜像。无需 Python，也没有 Node 构建步骤。 ``` git clone https://github.com/zipgod24/aetherflow.git cd aetherflow cp .env.example .env # 启动 RabbitMQ、Postgres+pgvector、Ollama、Jaeger 以及所有 agent make up # 在第二个终端中，初始化 RAG corpus（MITRE ATT&CK + 示例 runbook） make seed # 打开 UI open http://localhost:8080 ``` 然后点击右上角的 **Run demo incident**，或者： ``` ./bin/aetherctl incident submit --file examples/incidents/suspicious-domain.json ./bin/aetherctl incident watch ``` 同样的调用也适用于托管的 LLM —— 在 UI 中打开 **API Keys** 抽屉并粘贴 OpenAI 或 Anthropic 的密钥即可。无需重启。 ## 演示：“可疑域名”事件 运行 `make demo`。AetherFlow 将： 1. 接收一个事件：*"Endpoint 10.0.4.17 正在对 `paypa1-secure-login.com` 发起周期性 DNS 查询。这是恶意的吗？"* 2. **Retriever** 解析域名（A, MX, NS, TXT），从捆绑的威胁情报语料库中提取类似 WHOIS 的提示信息，并跨 MITRE ATT&CK 和您的运维手册对“域名 typosquat C2 beaconing”运行混合搜索。 3. **Reasoner** 要求 LLM 生成结构化的 `IncidentAnalysis` JSON（结论、置信度、IOCs、建议的操作、引文 ID）。 4. **Validator** 根据 schema 检查 JSON，验证每个引用的文档 ID 实际存在于检索到的集合中，扫描注入模式，如果任何检查失败则拒绝。 5. **Executor** 触发模拟防火墙阻断 + 寻呼模拟值班人员（这两个适配器都是接口 —— 可以直接替换为真实实现）。 6. UI 通过 SSE 流式传输每一步，同时位于 `http://localhost:16686` 的单个 Jaeger trace 会展示完整的过程。 ## 项目布局 ``` aetherflow/ ├── cmd/ # one binary per service │ ├── api-gateway/ # HTTP + SSE + UI host │ ├── orchestrator/ # saga coordinator (timeouts, compensations) │ ├── retriever-agent/ # hybrid RAG + DNS tools │ ├── reasoner-agent/ # LLM call with retrieved evidence │ ├── validator-agent/ # adversarial + schema validation │ ├── executor-agent/ # idempotent side effects │ └── aetherctl/ # CLI ├── internal/ │ ├── bus/ # RabbitMQ topology, pub/sub, DLX, retries │ ├── events/ # versioned event schemas │ ├── llm/ # provider interface + adapters │ ├── rag/ # chunker, embedder, pgvector store, hybrid retriever │ ├── agent/ # agent runtime + base loop │ ├── dns/ # SRV discovery + threat-intel resolver │ ├── security/ # prompt-injection defense, schema enforcement │ ├── otel/ # tracing setup │ ├── sse/ # server-sent events fan-out │ └── config/ # env + UI-provided keys ├── web/ui/ # static SPA (no build step) ├── deploy/ │ ├── helm/aetherflow/ # Helm chart │ └── k8s/ # raw manifests ├── docs/ │ ├── adr/ # architecture decision records │ ├── architecture.md │ ├── benchmarks.md │ └── threat-model.md ├── examples/ # sample incidents + RAG corpus ├── scripts/ # seed, demo, dev utilities ├── docker-compose.yml └── Makefile ``` ## 安全模型 AetherFlow 的威胁模型位于 [`docs/threat-model.md`](docs/threat-model.md) 中。简短版本如下： - Reasoner 的 LLM 输出**永远不会被直接信任。** 每个下游消费者（Validator, Executor）都将其视为不受信任的用户输入。 - Validator 运行分层检查：结构化（JSON 是否与 schema 匹配？）、依据性（每个引文 ID 是否出现在检索到的证据集中？）、对抗性（输出是否包含已知的注入标记 —— `ignore previous instructions`、base64 墙壁、角色翻转 token 等？）以及工具安全性（任何建议的操作是否超出了配置的权限级别？）。 - Executor 的操作是幂等的：每个操作都有一个 `idempotency_key`（incident_id + action_kind + target_hash）和一个去重表。 - 服务间的 AMQP 流量支持通过 `RABBITMQ_TLS_*` 环境变量配置的 mTLS。提供的 compose 文件在本地开发中使用明文传输。 - 用户通过 UI 提交的 API 密钥在静态存储时加密（使用来自 `AETHER_MASTER_KEY` 的每个部署的主密钥进行 AES-GCM 加密），并且绝对不会被记录到日志中。 ## BYO LLM ``` ┌─────────────────────────────────────────────┐ │ AetherFlow │ │ ┌─────────────────────────────────────┐ │ │ │ llm.Provider interface │ │ │ └─────────────────────────────────────┘ │ │ ▲ ▲ ▲ ▲ │ │ Ollama OpenAI Anthropic Custom │ │ (default) (any │ │ OpenAI- │ │ compatible)│ └─────────────────────────────────────────────┘ ``` 在 UI 的 **API Keys** 抽屉（右上角）中，选择一个提供商，粘贴密钥，选择模型，点击保存。该设置将按浏览器持久化在 `localStorage` 中，并通过 `POST /v1/config/llm` 同步到网关。随后的事件会在 AMQP 消息头中包含该覆盖配置，并且 Reasoner 仅针对该事件使用它 —— 您默认的 Ollama 配置将保持不变。 ## 状态 这是一个作为可用 MVP 发布的**具有强烈主张的参考架构**。生产环境部署需要：真实的动作适配器（Executor 的防火墙/寻呼机调用都是模拟的）、针对您的环境的 Helm chart 强化、密钥管理集成（HashiCorp Vault 或 AWS KMS，以替代内置的 AES-GCM），以及为 DNS 解析器提供的经认可的威胁情报源。 欢迎提交 PR —— 详见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 Apache 2.0。详见 [LICENSE](LICENSE)。

标签：AI安全, AI风险缓解, Anthropic, API集成, Chat Copilot, CIS基准, DNS解析, EVTX分析, GET参数, Golang, Go语言, LLM代理, LLM评估, Ollama, OpenAI, OpenTelemetry, pgvector, RabbitMQ, RAG, Saga模式, SecOps, 事件编排, 事件驱动架构, 云安全架构, 内存规避, 分布式追踪, 可观测性, 增强检索生成, 多智能体平台, 大模型集成, 威胁情报, 子域名突变, 安全编程, 安全运营, 开发者工具, 开源项目, 扫描框架, 日志审计, 智能应急响应, 服务发现, 死信路由, 测试用例, 消息队列, 混合检索, 用户代理, 程序破解, 请求拦截, 重试机制