genotoxic

Files (6)

• SKILL.md
• openai.yaml · agents/
• trail-of-bits-mark.svg · assets/
• graph-analysis.md · references/
• mutation-frameworks.md · references/
• triage-methodology.md · references/

SKILL.md (first lines)

# 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.

From trailofbits/skills, CC-BY-SA-4.0.

More from trailofbits/skills