遗传毒性
- 作者仓库星标 0
- 作者更新于 2026年8月24日 23:09
- 作者仓库 skills
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @trailofbits · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS
- 运行环境要求
- Node.js · Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# 1. Build the code graph
uv run trailmark analyze --language auto --summary {targetDir}
# 2. Run mutation testing (language-dependent)
# Python:
uv run mutmut run --paths-to-mutate {targetDir}/src
uv run mutmut results
# 2b. Run necessist (if language supported)
necessist
# 3. Analyze results with this skill's workflow (Phase 3)
第 1 阶段:构建代码图并运行预分析
使用 Trailmark 解析目标代码库,并在突变测试之前运行预分析。预分析计算爆炸半径、入口点、特权边界和污点传播,第 3 阶段将其用于分类。使用`QueryEngine` API构建图表并运行预分析:`QueryEngine.from_directory("{targetDir}", language="auto")`
第 2 阶段:运行突变测试
选择并运行适当的框架。有关特定于语言的设置,请参阅references/mutation-frameworks.md。捕获幸存的突变体。每个框架的报告不同,但针对每个突变体提取这些字段:
阶段 2b:运行 Necessist(可选)
如果支持目标语言(Go、Rust、Solidity/Foundry、TypeScript/Hardhat、TypeScript/Vitest、Rust/Anchor),请运行 necessist 来查找不必要的测试语句。它独立于阶段 2 运行,并且可以并行执行。过滤到删除后测试通过的结果。参见
第三阶段:分诊结果
对于每个幸存的突变体和每个必要的删除,使用图形数据确定其分类桶。必要的移除必须首先映射到生产函数(请参阅references/graph-analysis.md)。
# Genotoxic
Combines mutation testing and necessist (test statement removal) with
code graph analysis to triage findings into actionable categories:
false positives, missing unit tests, and fuzzing targets.
## When to Use
- After mutation testing reveals survived mutants that need triage
- Identifying where unit tests would have the highest impact
- Finding functions that need fuzz harnesses instead of unit tests
- Prioritizing test improvements using data flow context
- Filtering out harmless mutants from actionable ones
- Finding unnecessary test statements that indicate weak assertions (necessist)
## When NOT to Use
- Codebase has no existing test suite (write tests first)
- Pure documentation or configuration changes
- Single-file scripts with trivial logic
## Prerequisites
- **trailmark** installed — if `uv run trailmark` fails, run:
```bash
uv tool install trailmark
# Python snippets: uv run --with trailmark python - (a tool env is not importable)
```
**DO NOT** fall back to "manual verification" or "manual analysis"
as a substitute for running trailmark. Install it first. If installation
fails, report the error instead of switching to manual analysis.
- A **mutation testing framework** for the target language — if the framework
command fails (not found, not installed), install it using the instructions
in [references/mutation-frameworks.md](references/mutation-frameworks.md).
**DO NOT** fall back to "manual mutation analysis" or skip mutation testing.
Install the framework first. If installation fails, report the error
instead of switching to manual mutation analysis.
- **necessist** (optional, recommended) — if the target language is
supported (Go, Rust, Solidity/Foundry, TypeScript/Hardhat,
TypeScript/Vitest, Rust/Anchor), install with `cargo install necessist`.
See [references/mutation-frameworks.md](references/mutation-frameworks.md)
for details.
- An existing test suite that passes
- **macOS environment**: Run `ulimit -n 1024` before any `mull-runner`
invocation. macOS Tahoe (26+) sets unlimited file descriptors by
default, which crashes Mull's subprocess spawning. See
[references/mutation-frameworks.md](references/mutation-frameworks.md)
for details.
---
## Rationalizations to Reject
| Rationalization | Why It's Wrong | Required Action |
|-----------------|----------------|-----------------|
| "All survived mutants need tests" | Many are harmless or equivalent | Triage before writing tests |
| "Mutation testing is too noisy" | Noise means you're not triaging | Use graph data to filter |
| "Unit tests cover everything" | Complex data flows need fuzzing | Check entrypoint reachability |
| "Dead code mutants don't matter" | Dead code should be removed | Flag for cleanup |
| "Low complexity = low risk" | Boundary bugs hide in simple code | Check mutant location |
| "Tool isn't installed, I'll do it manually" | Manual analysis misses what tooling catches | Install the tool first |
| "Necessist isn't mutation testing, skip it" | Necessist finds what mutation testing misses: weak tests | Run both when the language supports it |
---
## Quick Start
```bash
# 1. Build the code graph
uv run trailmark analyze --language auto --summary {targetDir}
# 2. Run mutation testing (language-dependent)
# Python:
uv run mutmut run --paths-to-mutate {targetDir}/src
uv run mutmut results
# 2b. Run necessist (if language supported)
necessist
# 3. Analyze results with this skill's workflow (Phase 3)
```
---
## Workflow Overview
```
Phase 1: Graph Build → Parse codebase with trailmark
↓
Phase 2: Mutation Run → Execute mutation testing framework
Phase 2b: Necessist Run → Remove test statements (optional, parallel)
↓
Phase 3: Triage → Classify findings using graph data
↓
Output: Categorized Report
├── Corroborated (both tools flag same function — highest value)
├── False Positives (harmless, skip)
├── Missing Tests (write unit tests)
└── Fuzzing Targets (set up fuzz harnesses)
```
---
## Decision Tree
```
├─ Need to set up mutation testing for a language?
│ └─ Read: references/mutation-frameworks.md
│
├─ Need to set up necessist or find weak test statements?
│ └─ Read: references/mutation-frameworks.md (Necessist section)
│
├─ Need to understand the triage criteria in depth?
│ └─ Read: references/triage-methodology.md
│
├─ Need to understand how graph data informs triage?
│ └─ Read: references/graph-analysis.md
│
└─ Already have results + graph? Use Phase 3 below.
```
---
## Phase 1: Build Code Graph and Run Pre-Analysis
Parse the target codebase with trailmark and run pre-analysis **before**
mutation testing. Pre-analysis computes blast radius, entry points, privilege
boundaries, and taint propagation, which Phase 3 uses for triage.
```bash
uv run trailmark analyze --language auto --summary {targetDir}
```
Use the `QueryEngine` API to build the graph and run pre-analysis:
1. `QueryEngine.from_directory("{targetDir}", language="auto")`
2. Call `engine.preanalysis()` — **mandatory** before triage
3. Export with `engine.to_json()` for cross-referencing with mutation results
If auto-detection is wrong for the target, rerun with an explicit language or
comma-separated list such as `python,rust`.
See [references/graph-analysis.md](references/graph-analysis.md) for the
full API: node mapping, reachability queries, blast radius, and
pre-analysis subgraph lookups.
---
## Phase 2: Run Mutation Testing
Select and run the appropriate framework. See
[references/mutation-frameworks.md](references/mutation-frameworks.md) for
language-specific setup.
**Capture survived mutants.** Each framework reports differently, but
extract these fields per mutant:
| Field | Description |
|-------|-------------|
| File path | Source file containing the mutant |
| Line number | Line where mutation was applied |
| Mutation type | What was changed (operator, value, etc.) |
| Status | survived, killed, timeout, error |
Filter to **survived** mutants only for Phase 3.
---
## Phase 2b: Run Necessist (Optional)
If the target language is supported (Go, Rust, Solidity/Foundry,
TypeScript/Hardhat, TypeScript/Vitest, Rust/Anchor), run necessist to
find unnecessary test statements. This runs independently of Phase 2 and
can execute in parallel.
```bash
# Auto-detect framework
necessist
# Or target specific test files
necessist tests/test_parser.rs
# Export results
necessist --dump
```
Filter to findings where the test **passed after removal**. See
[references/mutation-frameworks.md](references/mutation-frameworks.md)
for framework-specific configuration and the normalized record format.
Map each removal to a production function using the algorithm in
[references/graph-analysis.md](references/graph-analysis.md).
---
## Phase 3: Triage Findings
For each survived mutant and each necessist removal, determine its
triage bucket using graph data. Necessist removals must first be mapped
to a production function (see
[references/graph-analysis.md](references/graph-analysis.md)).
### Quick Classification (Mutation Testing)
| Signal | Bucket | Reasoning |
|--------|--------|-----------|
| No callers in graph | **False Positive** | Dead code, mutant is unreachable |
| Only test callers | **False Positive** | Test infrastructure, not production |
| Logging/display string | **False Positive** | Cosmetic, no behavioral impact |
| Equivalent mutant | **False Positive** | Behavior unchanged despite mutation |
| Simple function, low CC, no entrypoint path | **Missing Tests** | Unit test is straightforward |
| Error handling path | **Missing Tests** | Should have negative test cases |
| Boundary condition (off-by-one) | **Missing Tests** | Property-based test candidate |
| Pure function, deterministic | **Missing Tests** | Easy to test, high value |
| High CC (>10), entrypoint reachable | **Fuzzing Target** | Complex + exposed = fuzz it |
| Parser/validator/deserializer | **Fuzzing Target** | Structured input handling |
| Many callers (>10) + moderate CC | **Fuzzing Target** | High blast radius |
| Binary/wire protocol handling | **Fuzzing Target** | Fuzzers excel at format testing |
### Quick Classification (Necessist)
| Signal | Bucket | Reasoning |
|--------|--------|-----------|
| Redundant setup or debug call | **False Positive** | Statement genuinely unnecessary |
| Cannot map to production function | **False Positive** | No graph context for triage |
| Call removed, no assertion checks its effect | **Missing Tests** | Test has weak assertions |
| Assertion removed, test still passes | **Missing Tests** | Redundant or insufficient coverage |
| Maps to high-CC entrypoint-reachable function | **Fuzzing Target** | Complex + exposed + weak test |
When both mutation testing and necessist flag the same production
function, mark as **corroborated** — highest confidence finding.
For detailed criteria, see
[references/triage-methodology.md](references/triage-methodology.md).
### Graph Queries for Triage
For each mutant, map it to its containing graph node and use pre-analysis
subgraphs (tainted, high_blast_radius, privilege_boundary) from Phase 1
to classify it. The classification logic checks: no callers → false
positive, privilege boundary → fuzzing, high CC + tainted → fuzzing,
high blast radius → fuzzing, otherwise → missing tests.
See [references/graph-analysis.md](references/graph-analysis.md) for
the `batch_triage` implementation and node mapping functions.
---
## Output Format
Generate a markdown report:
```markdown
# Genotoxic Triage Report
## Summary
- Total survived mutants: N
- Total necessist removals: N
- Corroborated findings: N
- False positives: N (N%)
- Missing test coverage: N (N%)
- Fuzzing targets: N (N%)
## Corroborated Findings
| File | Line | Function | Mutation Signal | Necessist Signal | Action |
|------|------|----------|----------------|------------------|--------|
## False Positives
| File | Line | Mutation | Reason | Source |
|------|------|----------|--------|--------|
## Missing Test Coverage
| File | Line | Function | CC | Callers | Suggested Test | Source |
|------|------|----------|----|---------|----------------|--------|
## Fuzzing Targets
| File | Line | Function | CC | Entrypoint Path | Blast Radius | Source |
|------|------|----------|----|-----------------|--------------|--------|
```
The `Source` column is `mutation`, `necessist`, or `corroborated`.
Write the report to `GENOTOXIC_REPORT.md` in the working directory.
---
## Quality Checklist
Before delivering:
- [ ] Trailmark graph built for target language
- [ ] Mutation framework ran to completion
- [ ] Necessist ran (if language supported) or noted as not applicable
- [ ] All survived mutants triaged (none unclassified)
- [ ] All necessist removals triaged (if applicable)
- [ ] Corroborated findings identified (if both tools ran)
- [ ] False positives have clear justifications
- [ ] Missing test items include suggested test type
- [ ] Fuzzing targets include entrypoint paths and blast radius
- [ ] Report file written to `GENOTOXIC_REPORT.md`
- [ ] User notified with summary statistics
---
## Integration
**trailmark skill:**
- Phase 1: Build code graph, query complexity and entrypoints
- Phase 3: Caller analysis, reachability, blast radius
**property-based-testing skill:**
- Missing test coverage items involving boundary conditions
- Roundtrip/idempotence properties for serialization mutants
**testing-handbook-skills (fuzzing):**
- Fuzzing target items: use `harness-writing`, `cargo-fuzz`, `atheris`
---
## Supporting Documentation
- **[references/mutation-frameworks.md](references/mutation-frameworks.md)** -
Language-specific framework setup, output parsing, and necessist configuration
- **[references/triage-methodology.md](references/triage-methodology.md)** -
Detailed triage criteria, edge cases, and worked examples for both
mutation testing and necessist
- **[references/graph-analysis.md](references/graph-analysis.md)** -
Graph query patterns, test-to-production mapping, and result merging
---
**First-time users:** Start with Phase 1 (graph build), then run mutations,
then use the Quick Classification table in Phase 3.
**Experienced users:** Jump to Phase 3 and use the Decision Tree to load
specific reference material.
章节与文件索引
按说明文件中的顺序排列。
何时使用
何时不使用
先决条件
拒绝的理由
第 1 阶段:构建代码图并运行预分析
文件/命令 -> uv run trailmark · cargo install necessist · ulimit -n 1024 · mull-runner · QueryEngine · QueryEngine.from_directory("{targetDir}", language="auto") · engine.preanalysis() · engine.to_json()
内容校验值 -> c03ba7a052ed
当前原文的自动摘译,尚未人工审校。
何时使用
突变测试揭示需要分类的幸存突变体后 确定单元测试影响最大的位置 查找需要模糊工具而不是单元测试的功能 使用数据流上下文优先考虑测试改进 从可操作的突变体中过滤掉无害的突变体
何时不使用
代码库没有现有的测试套件(首先编写测试) 纯文档或配置更改 具有简单逻辑的单文件脚本
先决条件
已安装 Trailmark — 如果
uv run trailmark失败,请运行:不要退回到“手动验证”或“手动分析”来替代运行 Trailmark。首先安装它。如果安装失败,请报告错误,而不是切换到手动分析。目标语言的突变测试框架 - 如果该框架拒绝的理由
合理化 · 为什么这是错误的 · 需要采取的行动 “所有幸存的突变体都需要测试” · 许多是无害的或等效的 · 编写测试之前进行分类 “突变测试噪音太大” · 噪音意味着你没有进行分类 · 使用图形数据来过滤 “单元测试涵盖了一切” · 复杂的数据流需要模糊测试 · 检查入口点可达性 “死代码突变体并不重要” · 死代码应该被删除 · 清理标志