sahajamoth/apex
GitHub: sahajamoth/apex
APEX 是一款智能测试探索工具，通过自动化生成测试用例驱使代码库达到近乎完整的分支覆盖率，同时发现死代码、不稳定测试与安全漏洞。
Stars: 2 | Forks: 0
# APEX — Autonomous Path EXploration
[](https://github.com/sahajamoth/apex/actions/workflows/ci.yml)
[](https://github.com/sahajamoth/apex/releases/latest)
[](LICENSE)
**别再猜测你的测试遗漏了什么。** APEX 能发现死代码、不稳定的测试 (flaky tests)、安全漏洞以及未测试的分支 —— 然后编写测试来修复它们。
## APEX 在实际项目中发现的问题
```
$ apex run --target ./your-project --lang python
╭──────────────────────────────────────────────────╮
│ APEX — Autonomous Path EXploration │
│ Target: ./your-project (Python, 847 branches) │
╰──────────────────────────────────────────────────╯
Round 1/5 ─────────────────────────────────────────
Coverage: 62% → 71% (+9%)
+142 branches covered | 203 remaining | 8 tests written
```
```
Round 5/5 ─────────────────────────────────────────
Coverage: 71% → 94% (+23%)
Final: 798/847 branches covered
Tests written: 31 new tests across 6 files
```
然后询问它学到了什么：
```
$ /apex-intel
┌─ Test Optimization ──────────────────────────────┐
│ 312 tests → 94 minimal set (3.3× speedup) │
│ 218 tests are redundant — same branch coverage │
└──────────────────────────────────────────────────┘
┌─ Dead Code ──────────────────────────────────────┐
│ 23 branches in 4 files — never executed by any │
│ test or production path │
│ │
│ src/billing.py:89 unreachable after refactor │
│ src/export.py:34 legacy XML path, 0 callers │
│ src/api.py:201 dead error handler │
└──────────────────────────────────────────────────┘
┌─ Flaky Tests ────────────────────────────────────┐
│ 2 tests show nondeterministic branch paths │
│ │
│ test_concurrent_upload — race in file locking │
│ test_session_timeout — depends on wall clock │
└──────────────────────────────────────────────────┘
┌─ Security ───────────────────────────────────────┐
│ src/auth.py:67 — auth bypass: no token check │
│ on admin endpoint (reachable from test_api) │
│ │
│ src/config.py:12 — hardcoded secret: │
│ AWS_KEY = "AKIA..." (not from env) │
└──────────────────────────────────────────────────┘
┌─ Hot Paths ──────────────────────────────────────┐
│ src/auth.py:45 — 12.3% of all branch hits │
│ src/db.py:112 — 8.7% of all branch hits │
│ These functions need the most test coverage. │
└──────────────────────────────────────────────────┘
Deploy Score: 87/100 — GO
```
## 安装
**独立安装程序**（推荐 — macOS 和 Linux）：
```
curl -sSL https://raw.githubusercontent.com/sahajamoth/apex/main/install.sh | sh
```
**Homebrew:**
```
brew install sahajamoth/tap/apex
```
**npm:**
```
npx @apex-coverage/cli run --target . --lang python
```
**pip:**
```
pipx install apex-coverage
```
**Nix:**
```
nix run github:sahajamoth/apex
```
**Cargo**（从源码构建）：
```
cargo install --git https://github.com/sahajamoth/apex
```
## Claude Code 优先
APEX 是为 Claude Code 构建的。其主要接口是斜杠命令 (slash commands) 和自动触发的代理 (agents) —— 而不是你需要学习的 CLI。
### 斜杠命令 (Slash Commands)
| 命令 | 作用 |
|---------|-------------|
| `/apex` | **仪表盘** — 部署评分、关键发现、建议的下一步行动 |
| `/apex-run` | **自主循环** — 衡量缺口、编写测试、重新衡量、重复执行 |
| `/apex-index` | 为智能命令构建逐测试分支索引 |
| `/apex-intel` | 全 SDLC 智能 — 测试质量、风险、死代码、热点路径 (hotpaths)、合约 |
| `/apex-deploy` | 部署就绪状态 — GO / CAUTION / BLOCK 及置信度评分 |
| `/apex-status` | 工作区的覆盖率表 |
| `/apex-gaps` | 未覆盖区域 Top 榜单，包含解释和建议的测试 |
| `/apex-generate` | 针对 crate 中未覆盖分支生成测试 |
| `/apex-ci 0.8` | CI 门禁 — 低于阈值则失败 |
### 自动触发的代理 (Auto-triggered Agents)
当 Claude Code 检测到匹配的意图时，这些代理会自动触发：
| 代理 | 触发示例 |
|-------|-----------------|
| **apex-coverage-analyst** | "what's our coverage?", "which parts are uncovered?" |
| **apex-test-writer** | "write tests for X", "improve coverage in Y" |
| **apex-runner** | "run apex against Z", "run apex on itself" |
| **apex-sdlc-analyst** | "what's our deploy score?", "find flaky tests" |
### 策略选择
`/apex-run` 循环会针对每个缺口自动选择最佳策略：
| 目标 | 首选 | 备选 |
|--------|---------|----------|
| Rust workspace | 源码级测试 | fuzz harness |
| Python project | 源码级测试 | concolic execution |
| C/Rust binary | fuzz | driller (当 fuzz 停滞时) |
| JavaScript | 源码级测试 | — |
## 独立 CLI — 20 个命令，6 个包
## 架构
Rust workspace，16 个 crate。重量级依赖（Z3, LibAFL, PyO3, Inkwell, Firecracker）均在特性标志 (feature flags) 之后 —— 默认不编译。
| Crate | 职责 |
|-------|------|
| `apex-core` | 共享类型、traits、配置 |
| `apex-coverage` | 覆盖率预测器、位图跟踪、连续分支距离启发式算法 |
| `apex-instrument` | 多语言插桩 (Python, JS, Java, Rust, LLVM, WASM) |
| `apex-lang` | 特定语言的测试运行器 |
| `apex-sandbox` | 进程 / WASM / Firecracker 隔离 |
| `apex-agent` | AI 驱动的测试生成、优先级调度器、求解器缓存 |
| `apex-synth` | 通过 Tera 模板 + LLM 引导的优化循环进行测试合成 |
| `apex-symbolic` | SMT-LIB2 约束求解、梯度下降求解器（可选 Z3） |
| `apex-concolic` | Concolic execution（可选 PyO3 tracer） |
| `apex-fuzz` | 覆盖率引导的 fuzzing，含 MOpt（可选 LibAFL） |
| `apex-detect` | 安全模式、硬编码秘密、CWE 映射的发现 |
| `apex-cpg` | 代码属性图 — 通过到达定义 (reaching definitions) 进行污点分析 |
| `apex-index` | 逐测试分支索引、SDLC 分析 |
| `apex-rpc` | gRPC 分布式协调 |
| `apex-mir` | MIR 解析、控制流分析 |
| `apex-cli` | CLI 二进制文件 — 20 个子命令 |
### 分析机制
APEX 整合了既有工具的基础机制
（详见 [docs/INSPIRATION.md](docs/INSPIRATION.md)）：
| 机制 | 来源 | APEX Crate |
|-----------|------|------------|
| 连续分支距离 (Korel fitness) | EvoMaster | `apex-coverage` |
| 梯度下降约束求解 | Angora | `apex-symbolic` |
| 代码属性图 + 污点分析 | Joern | `apex-cpg` |
| LLM 引导的测试优化（闭环） | CoverUp | `apex-synth` |
| 基于优先级的探索调度器 | Owi + EvoMaster | `apex-agent` |
| 带否定推理的求解器缓存 | Owi | `apex-agent` |
## 配置
```
# apex.toml
[coverage]
target = 1.0
min_ratchet = 0.8
[fuzz]
corpus_max = 10000
stall_iterations = 50
[agent]
max_rounds = 3
[sandbox]
process_timeout_ms = 10000
```
## 开发
```
cargo test --workspace
cargo fmt --check
cargo clippy --workspace -- -D warnings
```
## 许可证
[MIT](LICENSE)
从源码构建（含可选功能）
``` # 先决条件 rustup component add llvm-tools-preview cargo install cargo-llvm-cov # 克隆并构建 git clone https://github.com/sahajamoth/apex.git && cd apex cargo build --release # 使用可选的重型功能 (Z3, LibAFL, PyO3) cargo build --release --features "apex-symbolic/z3-solver,apex-fuzz/libafl-backend" ```核心
``` apex run --target ./project --lang python # Coverage gap report apex ratchet --target ./project --min-cov 0.8 # CI gate apex doctor # Check dependencies apex audit --target ./project --lang python # Security audit ```包 A：逐测试分支索引
``` apex index --target ./project --lang python --parallel 8 ``` 在覆盖率下单独运行每个测试，构建 test→branches 的映射。 存储在 `.apex/index.json`。在运行智能命令之前必须执行此操作。包 B：测试智能
``` apex test-optimize --target . # Minimal test subset apex test-prioritize --target . --changed-files src/auth.py apex flaky-detect --target . --lang python --runs 5 ```包 C：源码智能
``` apex dead-code --target . # Semantically dead code apex lint --target . --lang python # Runtime-prioritized lints apex complexity --target . # Exercised vs static complexity ```包 D：行为分析与 CI/CD
``` apex diff --target . --base main # Behavioral diff apex regression-check --target . --base main # CI gate for behavior changes apex risk --target . --changed-files src/auth.py apex hotpaths --target . --top 20 apex contracts --target . # Discover invariants apex deploy-score --target . # Aggregate confidence 0-100 ```包 E：文档
``` apex docs --target . --output docs/behavioral.md ```包 F：安全
``` apex attack-surface --target . --lang python --entry-pattern test_api apex verify-boundaries --target . --lang python \ --entry-pattern test_api --auth-checks check_auth --strict ```可选特性标志
| 特性 | Crate | 启用 | |---------|-------|---------| | `llvm-instrument` | apex-instrument | 通过 inkwell 进行基于 LLVM 的插桩 | | `wasm-instrument` | apex-instrument | WebAssembly 插桩 | | `z3-solver` | apex-symbolic | Z3 SMT 求解器 | | `kani-prover` | apex-symbolic | Kani 有界模型检测 | | `pyo3-tracer` | apex-concolic | Python concolic tracer | | `libafl-backend` | apex-fuzz | LibAFL fuzzer 后端 | | `firecracker` | apex-sandbox | Firecracker microVM 隔离 | ``` cargo build --release --features "apex-symbolic/z3-solver,apex-fuzz/libafl-backend" ```标签：AI工具, Autonomous Testing, Fuzzing, Python, Python工具, 云安全监控, 代码覆盖率, 分支覆盖, 单元测试生成, 可视化界面, 回归测试, 安全测试, 开发效率, 攻击性安全, 无后门, 死代码消除, 测试用例优化, 白盒测试, 网络可观测性, 路径探索, 软件测试工具, 逆向工具, 通知系统, 静态分析