euxis

一个超快的、自动化的代码库安全审计工具。

## 这究竟是什么 **Euxis 像人类安全审计员一样验证代码——只需不到三分钟——并生成一个 Sigstore 签名的证据包，任何监管机构都可以离线验证。** 当软件团队需要证明他们的应用符合 SOC 2、ISO 27001、NIST、OWASP 或其他十四种框架时，他们通常需要花钱请人类专家花几周时间阅读代码、运行检查并编写报告。Euxis 是一个单一的二进制文件，你可以直接将其放入 CI pipeline 中：每次代码更改时，它都会运行人类会执行的相同审计，并输出一个防篡改的、随时可供监管机构查阅的证据包。 该证据包是一个 **Sigstore Bundle v0.3** —— 一个封装在 SLSA v1.2 来源谓词中的 in-toto Statement v1，通过 Ed25519 进行 DSSE 签名，并与 SARIF 发现结果、CycloneDX 1.6 + SPDX 3.0.1 SBOM 以及 OpenVEX 异常文档捆绑在一起。验证者（审计员、监管机构、SOC）可以使用 `euxis verify` 或任何兼容 sigstore 的工具离线检查此链条——无需连接到供应商服务。完整的结构剖析请参阅 [`docs/evidence-packs/anatomy.md`](docs/evidence-packs/anatomy.md)，验证操作手册请参阅 [`docs/evidence-packs/verifying-a-bundle.md`](docs/evidence-packs/verifying-a-bundle.md)。 相同的引擎以可嵌入的 C++23 SDK 形式跨十六个库发布，因此构建 Agent 验证系统的团队可以将其直接集成到自己的产品中——请参阅下方的[在 C++ 中嵌入 euxis](#embedding-euxis-in-c)。 ## 这些术语的真正含义 | 你会看到的短语 | 它的实际含义 | |---|---| | **加密签名的证据包** | 防篡改的数字回执。向监管机构保证审计结果是真实的，没有被伪造。下个季度针对相同的代码重新运行相同的审计：相同的字节，相同的摘要。 | | **原生速度 / C++23 静态二进制文件** | 一个运行迅速的干净二进制文件。没有需要预热的 Python runtime，没有回合制的 JIT 延迟，Agent 循环中也没有解释器。 | | **Swarm of agents** | 一组同时工作以阅读和测试代码不同部分的 AI 助手，由单一控制器协调。 | | **FinOps router** | 智能预算管理器。将简单的任务路由给便宜的模型（Ollama, Haiku），将困难的任务路由给昂贵的模型（Opus, GPT-5），这样你就不会花冤枉钱。 | | **A2A v0.2 agent meshes** | 允许独立 Agent 交换任务的标准化的网络协议。开放规范；非 Euxis 特有。 | | **CI pipeline 集成** | 将其放入 GitHub Actions / GitLab CI / Jenkins 中。每次有人推送代码时都会运行。如果合规闸门被破坏，则导致构建失败。 | | **Forensic mode** | 最深度的审查模式（`euxis review --forensic`）。增加了供应链审计、依赖项来源审查和准入策略执行。大约 3 分钟，而分诊模式约需 45 秒。 | ## 你如何使用它 ``` euxis triage . # 45-second bounded scan euxis check . # standard verification, ~3 min euxis review . --forensic # forensic depth + supply-chain audit euxis certify-readiness . --framework soc2 # SOC 2 readiness report euxis sbom . --format=both # CycloneDX 1.6 + SPDX 3.0.1 euxis slopsquatting . # LLM-hallucinated-package guard euxis attest evidence.tar.gz # Sigstore-signed evidence bundle euxis verify evidence.tar.gz.sigstore.json # offline signature check euxis cache stats # incremental scan cache ``` 将输出通过管道传递给你的 CI 闸门，或者将证据包交给监管机构。有关欧盟网络弹性法案的映射，请参阅 [`docs/compliance/cra.md`](docs/compliance/cra.md)，有关 DORA / TLPT 的映射，请参阅 [`docs/compliance/dora.md`](docs/compliance/dora.md)。 ## 目录 **快速开始** - [安装](#install) — 先决条件、构建、验证 - [快速入门](#quick-start) — 五分钟内完成首次验证 - [十分钟导览](docs/getting-started.md) — `vulndb` + `sbom` + 多 Agent 分诊，包含实际输出 **命令界面** - [核心命令](#core-commands) — 日常使用的动词 - [命令组](#command-groups) — 完整的八个命令组 **SDK / 库参考** - [在 C++ 中嵌入 euxis](#embedding-euxis-in-c) — SDK 示例 - [公共库](#public-libraries) — 十六个库的矩阵 - [构建选项](#build-options) — CMake 功能标志 - [提供商策略](#provider-strategy) — FinOps router 默认设置 **证据与合规** - [证据包剖析](docs/evidence-packs/anatomy.md) — 从上到下的 bundle 布局 - [验证一个 bundle](docs/evidence-packs/verifying-a-bundle.md) — 操作手册 - [欧盟网络弹性法案映射](docs/compliance/cra.md) — CRA 第 13 / 14 条 - [DORA / TLPT 映射](docs/compliance/dora.md) — 金融服务工作流 - [基准测试方法](docs/benchmarks/methodology.md) — 如何测量扫描 + 证据数据 **操作** - [架构](#architecture) — 一目了然的目录布局 - [为什么采用这种方法？](#why-this-approach) — 设计理由 - [从源代码构建](#building-from-source) — make 目标 - [基准测试](#benchmarks) — 两个测试套件，两项工作 - [文档](#documentation) — 所有参考文档 - [贡献](#contributing) - [许可证](#license) ## 安装 从三种途径中选择一种。第一种是推荐的默认途径；对于开发者，仍然保留从源代码构建的途径。 ### 一键安装 (Linux + macOS，支持所有四种架构) ``` curl -fsSL https://raw.githubusercontent.com/sebastienrousseau/euxis/main/scripts/release/install.sh | sh ``` 检测平台，从 GitHub Release 下载匹配的 tarball，验证 SHA-256，如果 `cosign` 在 `PATH` 中则可选择性地验证 cosign 无密钥签名，并将二进制文件放置在 `~/.local/bin/euxis`。设置 `EUXIS_VERSION=v0.1.x` 以锁定特定的 tag，或设置 `EUXIS_INSTALL_DIR=/usr/local/bin` 进行系统级安装。 ### 原生安装包 | 渠道 | 安装命令 | |---|---| | **Homebrew (个人 tap)** | `brew tap sebastienrousseau/tap && brew install euxis` | | **Debian / Ubuntu (`.deb`)** | `curl -fsSL -O https://github.com/sebastienrousseau/euxis/releases/latest/download/euxis-linux-amd64.deb && sudo dpkg -i euxis-linux-amd64.deb` | | **RHEL / Fedora / openSUSE (`.rpm`)** | `sudo rpm -i https://github.com/sebastienrousseau/euxis/releases/latest/download/euxis-linux-amd64.rpm` | | **Docker (GHCR, 多架构)** | `docker run --rm ghcr.io/sebastienrousseau/euxis:latest --version` | `.deb` / `.rpm` 包和多架构 Docker 镜像由 [`.github/workflows/release.yml`](.github/workflows/release.yml) 在每次推送 `v*` 标签时生成，通过 Sigstore 无密钥 OIDC 签名，并使用 GitHub 原生的 SLSA 构建来源进行认证。 ### 从源码构建 当你需要未发布的 commit、想要自定义构建模式（sanitizers, gbench, GUI），或者在没有预构建 tarball 的平台（FreeBSD, NixOS, Windows-native）上运行时，请从源码构建。 ### 前提条件 | 工具 | 最低版本 | 检查命令 | |---|---|---| | CMake | 3.28 | `cmake --version` | | C++ 编译器 | GCC 14+ 或 Clang 18+ | `g++ --version` 或 `clang++ --version` | | Git | 2.x | `git --version` | | libsodium | 1.0.18+ | `pkg-config --modversion libsodium` | | SQLite | 3.x | `sqlite3 --version` | 可选，仅在启用相应功能时需要： | 工具 | 需求来源 | 安装 | |---|---|---| | Qt6 | `apps/etx` 桌面 GUI | `brew install qt` / `pacman -S qt6-base` | | Doxygen | `EUXIS_BUILD_DOCS=ON`（默认开启） | `pacman -S doxygen graphviz` | | Google Benchmark | 当 `EUXIS_BUILD_GBENCH=ON` 时自动拉取 | — | ### 平台设置 | 平台 | 命令 | |---|---| | macOS (Homebrew) | `brew install cmake gcc libsodium sqlite` | | Ubuntu / Debian / WSL2 | `sudo apt update && sudo apt install -y cmake g++-14 git libsodium-dev libsqlite3-dev` | | Arch / CachyOS | `sudo pacman -S cmake gcc git libsodium sqlite` | ### 构建 ``` git clone https://github.com/sebastienrousseau/euxis.git ~/.euxis cd ~/.euxis make cpp-build # Release + LTO, parallel make cpp-test # ctest, all suites sudo ln -sf ~/.euxis/cmake-build/apps/cli/euxis-cli /usr/local/bin/euxis ``` ### 验证 ``` euxis doctor ``` ## 快速入门 ``` euxis triage . # 45-second bounded triage euxis check . # standard verification, ~3 min euxis review . --forensic # forensic depth + supply-chain audit euxis certify-readiness . --framework soc2 # SOC 2 readiness report euxis compare . # triage vs deep, side-by-side euxis stats --last 5 # recent metrics + drift history ``` 分诊路径专为 CI 限定时间。完整审查路径专为人工审查限定时间。认证路径输出可重现的证据包。 如需查看带有真实输出的分步导览——包括 `doctor`、`vulndb query`、`sbom --enrich` 以及多 Agent 结论——请参阅 [`docs/getting-started.md`](docs/getting-started.md)。 ## 核心命令 Core 组是日常使用的操作界面。别名映射到规范命令。 | 命令 | 别名 | 功能描述 | |---|---|---| | `euxis check [target]` | — | 标准验证。默认模式。 | | `euxis triage [target]` | `euxis quick` | 快速有限分诊，约 45 秒。 | | `euxis review [target]` | `euxis deep` | 深度验证，标准模式或 `--forensic`。 | | `euxis certify-readiness [target] --framework ` | — | 跨越 18 个领域的认证就绪情况。 | | `euxis compare ` | — | 比较分诊结果与深度验证的差异。 | | `euxis stats` | `euxis metrics` | 验证指标 + 漂移历史。 | | `euxis policy ` | — | 策略检查和执行。 | | `euxis playbook ` | `euxis pb` | 运行多步骤验证 pipeline。 | | `euxis combo run ""` | — | 多 Agent 执行图。 | | `euxis doctor` | `euxis diag` | 环境诊断。 | ## 命令组 Euxis 跨越八个组发布 60 个命令：**Core, Lifecycle, System, Fleet, Knowledge, Infrastructure, Development, Specialized**。完整清单位于 [`docs/reference/cli-reference.md`](docs/reference/cli-reference.md)；`euxis --help` 会在终端枚举每一个命令和标志。 | 组 | 主要命令 | |---|---| | Core | `check`, `triage`, `review`, `certify-readiness`, `compare`, `stats`, `policy`, `playbook`, `doctor` | | Lifecycle | 会话和运行状态管理 | | System | 主机检查和配置 | | Fleet | Agent 名单、路由和分配 | | Knowledge | 语料库和参考数据 | | Infrastructure | 网关和部署接口 | | Development | 仅用于开发的助手 (lint, fmt, format-check) | | Specialized | 针对特定框架的工作流 | ## 在 C++ 中嵌入 euxis CLI 使用的相同库作为公共 SDK 在 `libs/` 下发布。最基础的端到端示例位于 [`docs/examples/cpp/a2a_minimal_server/`](docs/examples/cpp/a2a_minimal_server/)，它用不到 100 行 C++23 代码构建了一个 A2A v0.2 server handler。 ``` cmake -B cmake-build -DEUXIS_BUILD_EXAMPLES=ON cmake --build cmake-build --target euxis_example_a2a_minimal_server ./cmake-build/docs/examples/cpp/a2a_minimal_server/euxis_example_a2a_minimal_server ``` 预期输出是完整的 A2A 任务生命周期：`agent/card`、`capabilities/list`、`task/create`、`task/get`、`task/cancel`、再次 `task/get`。请参阅示例自带的 `README.md` 获取带有注释的演练过程。 ## 公共库 十六个静态库从 `libs/` 发布。仅需链接应用程序实际使用的部分。 | 库 | 公共头文件 | 用途 | |---|---|---| | `euxis-a2a-cpp` | `` | A2A v0.2 协议 — 卡片、任务、JSON-RPC server | | `euxis-a2a-types-cpp` | `` | 共享消息 + 传输类型 | | `euxis-runtime-cpp | `` | Agent 会话、生命周期、工具注册表 | | `euxis-core-cpp` | `` | FinOps router、supervisor、swarm orchestrator | | `euxis-crypto-cpp` | `` | AES-256-GCM、Ed25519、BLAKE2b 密钥派生 | | `euxis-identity-cpp` | `` | DID、ERC-8004 证明、凭证 | | `euxis-network-cpp` | `` | MCP client、WebSocket 传输、弹性机制 | | `euxis-bridge-cpp` | `` | 外部工具准入、审计、验证 | | `euxis-metrics-cpp` | `` | mdspan 遥测、验证 pipeline | | `euxis-memory-cpp` | `` | 基于 SQLite 的持久化记忆 | | `euxis-inference-cpp` | `` | 通过 llama.cpp、ollama 进行本地推理 | | `euxis-adapters-cpp` | `` | 出站通道适配器 (Slack, Discord, Telegram) | | `euxis-security-cpp` | `` | 威胁检测、策略执行 | | `euxis-platform-cpp` | `` | OS 抽象 (macOS, Linux, WSL2) | | `euxis-publisher-cpp` | `` | 文档渲染和导出 | | `euxis-bench-cpp` | `` | 基准测试套件和结果矩阵 | 完整的 API 参考文档由 `cmake --build cmake-build --target docs` 生成（需要 `doxygen`；如果不存在则回退为无操作）。输出将保存在 `cmake-build/docs/html/` 中，并使用 [doxygen-awesome-css](https://jothepro.github.io/doxygen-awesome-css/) 进行样式设置。 ## 构建选项 除非另有说明，所有可选功能默认关闭。仅启用应用程序所需的内容。 | 选项 | 默认 | 启用的功能 | |---|---|---| | `EUXIS_BUILD_EXAMPLES` | `OFF` | `docs/examples/cpp/` 下的第一方 SDK 示例 | | `EUXIS_BUILD_GBENCH` | `OFF` | 用于 `performance` 套件的 Google Benchmark 统计测试框架 | | `EUXIS_BUILD_DOCS` | `ON` | Doxygen API 参考目标（如果缺少 doxygen 则自动跳过） | | `EUXIS_NATIVE_ARCH` | `OFF` | 在开发构建中使用 `-march=native` | | `EUXIS_COVERAGE` | `OFF` | 启用 gcov 插桩 | | `EUXIS_DISABLE_SANITIZERS` | `OFF` | 在调试构建中跳过 ASan/UBSan | ``` # 示例 + 统计基准测试 + 文档 cmake -B cmake-build \ -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \ -DEUXIS_BUILD_EXAMPLES=ON \ -DEUXIS_BUILD_GBENCH=ON ``` ## 提供商策略 Euxis 根据任务类别将推理工作路由到最佳的提供商。可以通过 [`data/config/provider_strategy.json`](data/config/provider_strategy.json) 对每个环境的映射进行配置，并可在运行时通过环境变量覆盖。 | 任务类别 | 默认提供商 | 回退方案 | |---|---|---| | 研究 / 综合 | OpenAI | Gemini, Claude | | 编码 / 架构 / 审计 | Claude | Gemini, Ollama | | 深度研究 / 安全 | Gemini | OpenAI, Claude | | 私有 / 本地 | Ollama | — | | 微调编辑 | Aider | Claude, Ollama | | 终端自动化 | Kiro | ShellGPT, Claude | 环境变量覆盖：`EUXIS_DEFAULT_RESEARCH_PROVIDER`，`EUXIS_DEFAULT_CODING_PROVIDER`，`EUXIS_DEFAULT_SECURITY_PROVIDER`。 [`libs/core/src/router.cpp`](libs/core/src/router.cpp) 中的 `FinOpsRouter` 使用结构体数组 (Structure-of-Arrays) 评分循环在每个类别中进行选择——无分支、支持 SIMD 向量化、确定性。`swarm` 优先级通过原子轮询计数器在提供商之间循环。 ## 架构 ``` apps/ Application layer cli/ Command-line interface — 60 commands, 8 groups etx/ Qt6 desktop GUI — 17 screens gateway/ HTTP/WebSocket server publisher/ Document rendering engine libs/ SDK layer — 16 static libraries a2a/ A2A v0.2 protocol implementation a2a-types/ Shared message and transport types adapters/ Outbound channel adapters bench/ Benchmark harnesses (custom + optional Google Benchmark) bridge/ CLI bridge for external-tool execution + admission core/ FinOps router, supervisor, swarm orchestrator crypto/ AES-256-GCM, Ed25519, BLAKE2b, Argon2id identity/ DID, ERC-8004 attestation, credential management inference/ Local inference via llama.cpp, ollama memory/ Persistent memory store, SQLite-backed metrics/ mdspan telemetry, fast collector, validation pipeline network/ MCP client, WebSocket transport, resilience patterns platform/ OS abstraction (macOS, Linux, WSL2) publisher/ Document export runtime/ Agent session, lifecycle, tool manifest, validator security/ Threat detection, policy enforcement, errors data/ Configuration, agent prompts, playbooks, docs docs/ Documentation site sources + SDK examples ``` ## 为什么采用这种方法？ Euxis 是一个原生构建的多 Agent 代码认证 CLI，而不是对解释型 runtime 的封装。其实现全部采用 C++23——头文件使用 `std::expected` 进行错误处理（遍布 `libs/` 的 61 个位置），使用 `std::mdspan` 收集指标，并使用 concepts 作为适配器接口。同一个二进制文件在进程内运行整个 Agent 循环：没有 Python 启动，没有 JIT 预热，没有回合制的marshalling成本。 三个架构选择促使了从解释型同类方案的重写： 1. **加密证明处于热路径中。** 每次验证都带有 Ed25519 证明。AES-256-GCM 上下文 (`libs/crypto/aes_gcm.hpp`) 缓存了一次密钥调度，并在多次调用中分摊其成本——在 x86_64-v3 上测得速度为 1.54 GiB/s，而 simple API 为 1.50 GiB/s，两者都远高于 50,000 次/秒的 SLO 目标。解释型 runtime 每次调用都需要支付调度成本。 2. **A2A 是一等公民，而不是拼凑上去的。** `libs/a2a` 端到端地实现了 v0.2 协议接口——agent 卡片、验证、JSON-RPC server、HTTP 和 WebSocket 传输，以及 3000 万次/秒的 msgpack 二进制序列化。最小可行性嵌入位于 `docs/examples/cpp/a2a_minimal_server/main.cpp` 的 SDK 示例中。 3. **没有动态插件加载。** `libs/` 下的每个库都静态链接到使用它的应用程序中。配置更改不需要重新链接，但任何 euxis 二进制文件的*功能接口*完全在构建时确定。这对于审计工具来说是一项功能：构建是确定且可重现的，验证不能被运行时加载的插件静默扩展。 权衡之处在于，euxis 无法提供个人 AI 助手框架（如 OpenClaw, Hermes Agent）那样匹配的插件加载器人体工程学。这是故意的——该产品专注于验证，而不是可扩展性。 ## 从源码构建 ``` make cpp-configure # CMake configure (Release, LTO, _FORTIFY_SOURCE=3) make cpp-build # Build all targets make cpp-test # Run test suite (ctest) make cpp-clean # Remove build artifacts make cpp-format # clang-format pass make cpp-coverage # Build with coverage (requires gcovr, lcov) make cpp-clang-tidy # Static analysis ``` 使用 `make cpp-build CPP_BUILD_JOBS=8` 覆盖并行度。该仓库锁定 `-DCMAKE_POLICY_VERSION_MINIMUM=3.5`，以适应早于现代最低版本策略的第三方 CMake 文件。 ## 基准测试 euxis 附带两个互补的测试套件。完整指南请参阅 [`libs/bench/README.md`](libs/bench/README.md)。 | 套件 | 用于 | 输出 | |---|---|---| | 自定义 (`euxis-bench-cpp`) | 针对五个套件中硬编码的 SLO 目标进行 CI 冒烟测试 | 通过 `ResultMatrix` 输出 JSON | | Google Benchmark (`euxis_perf_gbench`, 可选) | `performance` 套件的统计分析；趋势跟踪 | `benchmark::` 控制台 / JSON / CSV | 在 GCC 16 / x86_64-v3 上的初始运行 (`euxis_perf_gbench --benchmark_min_time=0.1s`)： | 基准测试 | 时间 | 吞吐量 | |---|---|---| | `BM_CryptoThroughput_Simple` | 0.640 us | 1.50 GiB/s | | `BM_CryptoThroughput_Cached` | 0.622 us | 1.54 GiB/s | | `BM_KeyDerivation_FastPath` | 0.203 us | — | | `BM_AgentCardMsgpackRoundTrip` | 33.1 ns | 30.3 M ops/sec | 合成的微基准测试测量的是库的开销，而不是用户可见的性能。在优化基准测试识别出的热路径之前，请对实际的 `euxis-cli` 工作负载进行性能分析 (`perf record euxis-cli triage .`)，并确认该函数出现在生产环境的调用图中。 ## 文档 | 指南 | 内容 | |---|---| | [快速入门](docs/essentials/quick-start.md) | 五分钟内从克隆到验证 | | [用户指南](docs/guides/user-guide.md) | 完整的 CLI 参考和模式 | | [CLI 参考](docs/reference/cli-reference.md) | 每个命令、标志和示例 | | [Fleet 指南](docs/guides/fleet-guide.md) | Agent 名单和路由 | | [基准测试套件](libs/bench/README.md) | 自定义套件 vs. Google Benchmark，何时使用哪一个 | | [SDK 示例](docs/examples/cpp/a2a_minimal_server/README.md) | 最小 A2A v0.2 server | | API 参考 | 本地构建：`cmake --build cmake-build --target docs` | 托管文档位于 [sebastienrousseau.github.io/euxis](https://sebastienrousseau.github.io/euxis/)。 ## 贡献 欢迎提交 Issues 和 pull requests。有关开发环境设置、commit 签名策略和审查流程，请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。所有的 commit 必须经过加密签名。 对于大范围的更改（格式化操作、警告消除行动、覆盖率提升行动），请先开启一个 issue 以便在发送 PR 之前就范围达成一致。 安全披露：请参阅 [`SECURITY.md`](SECURITY.md) 了解协调披露政策。 ## 许可证 AGPL-3.0 — 见 [LICENSE](LICENSE)。 Euxis v0.0.2 · [euxis.co](https://euxis.co)

标签：Bash脚本, DLL 劫持, LLM防护, LNA, SAST, 大语言模型, 盲注攻击, 请求拦截, 错误基检测, 静态代码分析