sting-raider/AegisFlow

# AegisFlow [](https://github.com/sting-raider/AegisFlow/actions/workflows/ci.yml) [](LICENSE) AegisFlow 是一个自适应的混合网络入侵检测系统，支持确定性 PCAP 重放、显式 Linux 实时捕获、可解释的风险融合、事件分组，以及实时分析师仪表板。 它不保证零日漏洞检测，默认不检查 payload，也不阻断流量。在安装依赖项和镜像后，检测器和离线 demo 不需要 LLM、API key、GPU 或互联网连接。 ## 架构 ``` flowchart LR T["Demo / PCAP / explicit live"] --> S["Sensor"] E["Suricata EVE"] --> S S --> R1["Redis flow stream"] R1 --> D["Detector\ncalibrated classifier + Isolation Forest + autoencoder + fusion"] D --> R2["Detection stream"] R2 --> A["FastAPI / incidents"] A --> P["PostgreSQL"] A --> W["REST + WebSocket"] W --> UI["React operations dashboard"] ``` Demo profile 以独立进程的方式运行 `sensor`、`detector`、`api` 和 `dashboard`，并配合使用 Redis 和 PostgreSQL。测试可以使用相同的领域逻辑，配合进程内 adapter 和 SQLite。  ## 快速开始 要求：带有 Compose 的 Docker、GNU Make，以及足够的空间用于存放 Python/Node 镜像。 ``` make demo ``` 然后打开： - Dashboard: - API/OpenAPI: - Metrics: 内置流量是合成的且非破坏性的。它会产生普通流量、已知签名的 fixture、类似扫描的扇出、突发流量，以及统计上异常的出站传输。使用 `make demo-stop` 停止。 当前干净的验证重放会持久化 6 个流、1 个签名事件、5 个警报（包括不同的已知攻击和可疑未知结果）以及 1 个事件。第二次重放不会改变这些计数，因为事件 ID 是确定性的，并且数据库写入是幂等的。 本地开发： ``` make install make train-smoke uv run python -m apps.api.main npm --prefix apps/dashboard run dev uv run python -m training.cli.evaluate_dataset --help ``` ## 命令 ``` make lint make typecheck make test make train-smoke make replay PCAP=/absolute/path/capture.pcap make live INTERFACE=eth0 make suricata-replay PCAP=/absolute/path/capture.pcap make benchmark make reset ``` ## 验证状态 2026-08-01 的最新本地验证已通过： - 在 56 个 Python 源文件上进行了 Ruff 和严格的 MyPy 检查； - 112 个 Python 测试，上次测量的后端覆盖率为 84%； - dashboard ESLint、生产环境构建、4 个组件交互测试以及 Chromium E2E； - `npm audit --audit-level=high` 报告零漏洞； - 干净的 Compose 镜像构建、数据库迁移、离线重放、REST/metrics 检查，以及独立的 Redis/PostgreSQL 重启恢复； - 带有显式丢弃、队列清理、延迟、CPU 和内存报告的有界队列过载基准测试。 有关测量的证据及其局限性，请参见 [`docs/PROGRESS.md`](docs/PROGRESS.md)、[`docs/COMPLETION_AUDIT.md`](docs/COMPLETION_AUDIT.md) 和 [`docs/BENCHMARK_LATEST.json`](docs/BENCHMARK_LATEST.json)。 `make live` 仅限 Linux 使用，需要显式指定接口，并会打印授权警告。它构建了一个专用的非 root NFStream sensor 目标，仅带有 `NET_RAW` 权限；API 和 detector 继续放弃所有 capability。Suricata 重放 profile 没有网络，仅接受显式挂载的 PCAP。切勿将恶意流量重放到真实网络中。 ## 训练与模型 `make train-smoke` 在确定性的合成数据上对逻辑回归、树模型和紧凑的 MLP 进行基准测试，使用不相交的分组训练/校准/测试分区，仅在训练行上拟合预处理，通过分组的训练折 CV 校准所选分类器，并且仅在良性数据行上训练 Isolation Forest 和一个紧凑的降噪 autoencoder。Bundle v3 包含特征 schema、预处理、分类器、两个异常模型、标签、通过校准得出的阈值、良性经验异常 CDF、融合比较指标、训练来源、artifact hash 和 SHA-256 校验和。生产环境的提升是原子的，并会记录回滚历史。检测器需要经过校准的 v3 bundle；旧的 v1/v2 历史记录仍可迁移检查，但无法进行推理。 Smoke 指标仅作为安装证据。它们不是关于操作质量的声明。公共数据集单独下载，从不提交到仓库。参见 [`docs/ML_METHODOLOGY.md`](docs/ML_METHODOLOGY.md) 和 [`docs/DATASETS.md`](docs/DATASETS.md)。 该仓库包含一份针对官方 UNSW-NB15 训练/测试分区的可重现的精确混合报告。它通过运行时检测所使用的同一批处理预测器，对 175,341 行训练数据和 82,332 行测试数据进行了评分。该报告是经过深思熟虑且坦诚的：四状态宏 F1 为 0.156，良性误报率为 64.4%，因此该模型不适合用于生产环境的提升。请参见 [`官方评估报告`](docs/evaluation/unsw-nb15-official-split.json)。 ## 安全与隐私 - 不保留数据包 payload。 - 原始 IP 会从 ML 特征向量中排除。 - 无效/与 schema 不兼容的流会产生错误，绝不会得出良性结果。 - 模型文件在受信任的本地 `joblib` 反序列化之前会进行校验和检查。 - 容器以非 root 用户运行，放弃 capability，在可行的情况下使用只读文件系统，并将主机端口绑定到 loopback。 - 分析师反馈永远不会修改原始检测结果。 - 漂移不能重新训练或提升模型。 - 可选的解释 provider 仅接收经过净化的结构化字段。 - 变更请求体、流消息、流长度以及 WebSocket 连接/帧都是有界的；被拒绝的队列记录仅保留结构性摘要和 SHA-256 hash。 - Sensor、detector、API、访问和运行时应用程序事件使用经过脱敏处理的单行 JSON 日志，而 Prometheus 暴露了流、检测、队列、模型、漂移、WebSocket 和数据库的运行状况指标。 可选的事件解释默认禁用，仅当从事件中发起请求时才会运行。确定性解释始终可用；配置的远程或 loopback 本地 provider 具有超时、重试、速率、隐私和缓存限制。参见 [`docs/AI_EXPLANATIONS.md`](docs/AI_EXPLANATIONS.md)。在进行实时部署之前，请阅读完整的 [`威胁模型`](docs/THREAT_MODEL.md)。 ## 已知局限性 - 内置模型是合成的 smoke 数据，不是生产模型。 - UNSW-NB15 的精确混合官方评估具有不可接受的高达 64.4% 的良性误报率。独立族群保留、基于时间的以及真正的跨数据集证据仍未完成；发布的报告是反面证据，而非性能声明。 - API 访问控制目前对变更操作使用可选的共享密钥，尚未提供经过身份验证的用户身份、RBAC、SSO/OIDC 或租户隔离。 - 运行时检测默认为单消息/单 worker；测量的过载基准测试有意记录了丢弃情况，不作为生产容量的声明。 - Scapy PCAP adapter 是确定性的，但经过了刻意的精简。NFStream 6.6.0 已针对 PCAP 和显式 Linux 实时接口进行了验证；其 Windows 原生引擎不可用，因此 Windows 回退到 Scapy 重放。 - Windows 支持 demo 和 PCAP 重放，但不支持实时捕获。 - 部署的 smoke bundle 仍然针对确定性的合成数据进行校准。公共评估会为审查的数据集重新训练相同的模型族群和融合路径，但不会提升结果。 - Redis/PostgreSQL 重启恢复使用消费者组、陈旧条目声明、持久确认、有界重试和幂等事件 ID。Compose 故障矩阵记录在 `docs/PROGRESS.md` 中。 - 未实现主动响应或自动阻断。 正在进行的生产就绪扩展和未解决的证据要求记录在 [`docs/COMPLETION_AUDIT.md`](docs/COMPLETION_AUDIT.md) 中。在该矩阵结束之前，不应将已完成的离线 demo 描述为企业级生产就绪状态。 ## 上游与许可 该架构参考了 `isaiah-harville/NIDS` 的 `277c4ff...` 提交；所有 AegisFlow 运行时代码均为完全重写。上游 README 中写的是 MIT，而其实际根许可证是 Apache-2.0。请参见 [`UPSTREAM.md`](UPSTREAM.md) 和 [`上游审计`](docs/UPSTREAM_AUDIT.md)。AegisFlow 保留其实际的 [Apache License 2.0](LICENSE)。

标签：Apex, Metaprompt, 入侵检测系统, 安全数据湖, 搜索引擎查询, 机器学习, 测试用例, 网络安全, 自定义请求头, 请求拦截, 逆向工具, 隐私保护