Skill vector-forge
✓ OficialGenera nuevos vectores de prueba criptográficos mediante el uso de mutation testing para identificar y atacar rutas de código no cubiertas en las implementaciones de algoritmos.
- Estrellas en GitHub
- 8136
- Archivos
- 8
- Último commit
- 11 nov 2026
- Licencia
- CC-BY-SA-4.0
- Herramientas permitidas
- —
¿Qué hace la skill vector-forge?
Genera nuevos vectores de prueba criptográficos mediante el uso de mutation testing para identificar y atacar rutas de código no cubiertas en las implementaciones de algoritmos.
Resumen generado a partir del SKILL.md de la skill.
Sobre la skill vector-forge
Los ingenieros criptográficos y los investigadores de seguridad utilizan vector-forge para identificar y cubrir sistemáticamente las brechas de cobertura en las implementaciones de algoritmos. La herramienta automatiza el proceso de encontrar rutas de código de implementación que los vectores de prueba existentes no logran ejecutar, utilizando mutation testing para crear errores intencionales. Al analizar qué mutaciones sobreviven, el sistema identifica errores lógicos específicos que las pruebas actuales no pueden detectar.
Un agente debe cargar este SKILL cuando se le asigne la tarea de generar nuevos vectores de prueba criptográficos, medir brechas de cobertura de Wycheproof o crear suites de pruebas multiplataforma. El flujo de trabajo depende de la herramienta trailmark para construir grafos de llamadas para el análisis de alcanzabilidad y utiliza frameworks de mutación específicos de cada lenguaje como gremlins para Go, cargo-mutants para Rust, mutmut para Python o Mull para C/C++. El proceso produce un informe de cobertura detallado y un conjunto de nuevos vectores de prueba diseñados para atacar los mutantes que escaparon, demostrando finalmente su efectividad al comparar las tasas de eliminación de mutaciones antes y después de aplicar los nuevos vectores.
Lo que un agente puede hacer con ella
- 1Generar vectores de prueba criptográficos específicosCrea nuevos vectores de prueba que ejecuten específicamente las rutas de código no cubiertas en una implementación de un algoritmo criptográfico.
- 2Evaluar la cobertura de los vectores de prueba existentesMide qué tan eficazmente una suite actual de vectores de prueba cubre una implementación específica de un protocolo.
- 3Identificar brechas en las rutas de código de la implementaciónEncuentra áreas específicas del código de un algoritmo que no son alcanzadas por ningún vector de prueba actual.
- 4Crear suites de pruebas estilo WycheproofDesarrolla vectores de prueba multiplataforma similares al estándar Wycheproof para garantizar la consistencia entre diferentes librerías.
Escrito a partir del SKILL.md de la skill. Cada caso de uso se verifica con una cita del mismo.
Cómo instalar la skill vector-forge
Cada comando copia la carpeta de la skill al directorio de skills del cliente. Reinicia el cliente o inicia una nueva sesión para cargarla.Instalar la skill vector-forge en Plugin
/plugin marketplace add trailofbits/skills /plugin install trailmark@trailofbits
Instalar la skill vector-forge en Claude Code
~/.claude/skills/vector-forge/SKILL.md
$ npx degit trailofbits/skills/plugins/trailmark/skills/vector-forge ~/.claude/skills/vector-forgeInstalar la skill vector-forge en Claude Code (project)
.claude/skills/vector-forge/SKILL.md
$ npx degit trailofbits/skills/plugins/trailmark/skills/vector-forge .claude/skills/vector-forgeInstalar la skill vector-forge en Codex
~/.agents/skills/vector-forge/SKILL.md
$ npx degit trailofbits/skills/plugins/trailmark/skills/vector-forge ~/.agents/skills/vector-forgeInstalar la skill vector-forge en Gemini CLI
~/.gemini/skills/vector-forge/SKILL.md
$ npx degit trailofbits/skills/plugins/trailmark/skills/vector-forge ~/.gemini/skills/vector-forgeInstalar la skill vector-forge en Claude.ai
npx degit trailofbits/skills/plugins/trailmark/skills/vector-forge vector-forge && zip -r vector-forge.zip vector-forge # claude.ai → Customize → Skills → + → Create skill → Upload a skill → vector-forge.zip
Verificaciones automáticas
Ejecutado 15 nov 2026Informe completo →Aún sin verificar. Una skill necesita 80 puntos, ningún hallazgo grave y datos suficientes para comprobarla. Cómo funcionan las verificaciones · Qué corregir para obtener más puntos
- Repositorio de origen vinculado y accesibletrailofbits/skills/plugins/trailmark/skills/vector-forge is public and reachablegithub.com/trailofbits/skills/tree/HEAD/plugins/trailmark/sk ↗Aprobado
- Licencia de código abierto (OSI)CC-BY-SA-4.0 is not OSI-approvedspdx.org/licenses/CC-BY-SA-4.0.html ↗Hallazgo
- Commit o lanzamiento en el último añoLast commit 2026-11-11github.com/trailofbits/skills/commits ↗Aprobado
- Sin descargar y ejecutar ni robo de credenciales en los scriptsNo scripts in the skill folderAprobado
- Sin instrucciones ocultas en SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/trailofbits/skills/blob/HEAD/plugins/trailmark/sk ↗Aprobado
- Las herramientas preaprobadas están acotadasNo pre-approved tools; the agent asks before using onegithub.com/trailofbits/skills/blob/HEAD/plugins/trailmark/sk ↗Aprobado
- SKILL.md sigue el formato de Agent SkillsValid name and description; says when to use it; 479 linesgithub.com/trailofbits/skills/blob/HEAD/plugins/trailmark/sk ↗Aprobado
SKILL.md
Ver en GitHubVector Forge
Uses mutation testing to systematically identify gaps in test vector coverage, then generates new test vectors that close those gaps. Measures effectiveness by comparing mutation kill rates before and after.
When to Use
- Generating test vectors for cryptographic algorithms or protocols
- Evaluating how well existing test vectors cover an implementation
- Finding implementation code paths that no test vector exercises
- Creating Wycheproof-style cross-implementation test vectors
- Measuring the concrete coverage value of a test vector suite
When NOT to Use
- No implementations exist yet (need code to mutate)
- Single trivial implementation with no edge cases
- Testing application logic rather than algorithm implementations
- The algorithm has no public test vectors to compare against
Prerequisites
- trailmark installed — if
uv run trailmarkfails, run:uv tool install trailmark
Python snippets: uv run --with trailmark python - (a tool env is not importable)
- At least one implementation of the target algorithm in a
language with mutation testing support
- A test harness that consumes test vectors and exercises
the implementation
- A mutation testing framework for the target language
---
## Rationalizations to Reject
| Rationalization | Why It's Wrong | Required Action |
|-----------------|----------------|-----------------|
| "We have enough test vectors" | Mutation testing proves otherwise | Run the baseline first |
| "The implementation's own tests are sufficient" | Own tests often share blind spots with the impl | Cross-impl vectors catch different bugs |
| "FFI crates can be mutation tested at the binding layer" | Mutations to wrappers don't affect the underlying impl | Mutate the actual implementation language |
| "Timeouts mean the mutation was caught" | Timeouts are ambiguous — could be killed or alive | Resolve timeouts before drawing conclusions |
| "All mutants are equivalent" | Most aren't — verify by reading the mutation | Classify each escaped mutant individually |
| "Checking valid vectors is enough" | Permissive mutations survive without negative assertions | Assert rejection for every invalid vector |
| "Manual analysis is fine" | Manual analysis misses what tooling catches | Install and run the tools |
---
## Workflow Overview
Phase 1: Discovery → Find implementations to test ↓ Phase 2: Harness → Write/adapt test vector harness for each impl ↓ Phase 3: Baseline → Run mutation testing with existing vectors ↓ Phase 4: Escape Analysis → Classify escaped mutants by code path ↓ Phase 5: Vector Gen → Create test vectors targeting escapes ↓ Phase 6: Validation → Re-run mutation testing, compare before/after ↓ Output: Coverage Report + New Test Vectors
---
## Phase 1: Discovery
Find implementations of the target algorithm. Look for:
1. **Pure implementations** in high-level languages (Go, Rust, Python)
— these are the best mutation testing targets
2. **FFI wrapper crates** — identify these early so you don't waste
time mutating wrapper glue code
3. **Reference implementations** — useful for cross-verification but
may not be the best mutation targets
For each implementation, note:
- Language and mutation testing framework
- Whether it's pure code or FFI wrappers
- Existing test suite size and coverage
- Which API surface the test vectors will exercise
### Implementation Type Classification
| Type | Mutation Value | Example |
|------|---------------|---------|
| Pure implementation | High | zkcrypto/bls12_381 (Rust), gnark-crypto (Go) |
| FFI bindings to C/asm | Low at binding layer | blst Rust crate |
| C/C++ implementation | High (use Mull) | blst C library |
| Generated code | Medium (mutations may be equivalent) | gnark-crypto generated field arithmetic |
**Key insight:** If an implementation delegates to another language
via FFI, you must mutate the *underlying* implementation, not the
bindings. For C/C++ underneath Rust/Go/Python, use Mull or similar.
---
## Phase 2: Harness
For each implementation, create a test harness that:
1. Reads test vectors from JSON files (Wycheproof format recommended)
2. Exercises the implementation's API for each vector
3. Asserts **both acceptance and rejection**:
- Valid vectors: deserialization succeeds, output matches expected
- Invalid vectors: deserialization fails or verification rejects
4. Adds **roundtrip assertions** for valid deserialization vectors:
`serialize(deserialize(bytes)) == bytes`
5. Reports pass/fail per vector with test IDs
**Critical:** A harness that only checks valid vectors will miss all
permissive mutations (e.g., `&` → `|` in validation). See
[references/lessons-learned.md](references/lessons-learned.md) §7.
The harness must be runnable by the mutation testing framework.
For most frameworks this means:
- **Go:** A `_test.go` file in the same package as the implementation
- **Rust:** An integration test in `tests/` or inline `#[test]` functions
- **Python:** A pytest test file
- **C/C++:** A test binary linked against the implementation
### Harness Placement
The harness must live *inside the implementation's package* so the
mutation framework can see it. This usually means:
```bash
# Go: add test file to the package being mutated
cp wycheproof_test.go /path/to/impl/package/
# Rust: add integration test
cp wycheproof.rs /path/to/crate/tests/
# Python: add test to the test directory
cp test_wycheproof.py /path/to/package/tests/
Handling Existing Vectors
If the implementation already has test vectors:
- Run mutation testing with ONLY the existing vectors (baseline)
- Run mutation testing with ONLY your new vectors
- Run mutation testing with BOTH combined
- The delta between (1) and (3) shows the new vectors' value
Phase 3: Baseline
Run mutation testing with existing test vectors only.
Framework Selection
See references/mutation-frameworks.md for language-specific setup.
| Language | Framework | Command |
|---|---|---|
| Go | gremlins | gremlins unleash ./path/to/package |
| Rust | cargo-mutants | cargo mutants -j N --timeout T |
| Python | mutmut | mutmut run --paths-to-mutate src/ |
| C/C++ | Mull | mull-runner -test-framework=GoogleTest binary |
Parallelism
Always use parallel execution for large codebases:
cargo mutants -j 8(Rust, 8 parallel workers)gremlins unleash --timeout-coefficient 3(Go, increase timeouts)mutmut run --runner "pytest -x -q"(Python, fail-fast)
Recording Baseline Results
Capture these metrics per implementation:
| Metric | Description |
|---|---|
| Total mutants | Number of mutations generated |
| Killed | Mutants caught by tests |
| Survived/Lived | Mutants NOT caught (these are the targets) |
| Not covered | Code paths no test reaches at all |
| Timed out | Ambiguous — resolve before comparing |
| Efficacy % | Killed / (Killed + Survived) |
| Coverage % | (Total - Not covered) / Total |
Save the full mutation log for Phase 4 analysis.
Phase 4: Escape Analysis (Graph-Informed Triage)
Classify each escaped (survived + not covered) mutant using the Trailmark call graph for reachability and blast radius analysis.
This phase MUST use the genotoxic skill's triage methodology. The call graph transforms mutation results from a flat list of survived mutants into an actionable, prioritized set of vector targets.
Step 1: Build the Call Graph
Build a Trailmark code graph for each implementation before triaging mutations:
# Go
uv run trailmark analyze --language go --summary {targetDir}
# Rust
uv run trailmark analyze --language rust --summary {targetDir}
The graph provides:
- Caller chains — trace from public API entry points to mutated functions to determine reachability
- Cyclomatic complexity — prioritize high-CC functions
- Blast radius — functions with many callers have wider impact if their mutations survive
Step 2: Filter to Relevant Code
Mutation frameworks test the entire package. Filter results to only the files/functions that test vectors should exercise:
# Go (gremlins)
grep -E "(LIVED|NOT COVERED)" baseline.log \
| grep -E " at (relevant|files)" \
| sort
# Rust (cargo-mutants)
cat mutants.out/missed.txt | grep "src/relevant"
Step 3: Graph-Informed Classification
For each escaped mutant, map it to its containing function in the call graph and apply the genotoxic triage criteria:
| Graph Signal | Classification | Action |
|---|---|---|
| No callers in graph | False Positive | Dead code, skip |
| Only test callers | False Positive | Test infrastructure |
| Logging/display/formatting | False Positive | Cosmetic |
| Cross-package callers but NOT COVERED | Cross-Package Gap | See below |
| Reachable from public API, low CC | Missing Vector | Design targeted vector |
| Reachable from public API, high CC (>10) | Fuzzing Target | Both vector + fuzz harness |
| Validation/error-handling path | Negative Vector | Craft invalid input that triggers path |
| Optimization path (GLV, SIMD, batch) | Edge-Case Vector | Input that triggers optimization threshold |
|→^ after left shift (e.g. (t<<1) | carry) |
Equivalent Mutant | Skip — bit 0 always 0, OR=XOR |
ct_eq &→| on Montgomery limbs |
API-Unreachable | Needs library-internal tests, not vectors |
| Equivalent mutation (behavior unchanged) | False Positive | Skip |
Step 4: Identify Cross-Package Test Gaps
Critical pitfall: Mutation frameworks often only run tests within the same package as the mutation. For Go (gremlins) and Rust (cargo-mutants), this means:
- A mutation in
hash_to_curve/g2.goonly runs tests in thehash_to_curvepackage, NOT tests in the parentbls12381package that imports it - Functions that are fully exercised by cross-package tests will appear as NOT COVERED — these are false positives
- To confirm: check if the mutated function is called from a test in a different package that wouldn't be run
To resolve cross-package gaps:
- Add a thin test in the sub-package that calls through the same code path as the cross-package test
- Or run gremlins with
--test-pkg ./...(if supported) - Or document as a framework limitation in the report
Step 5: Prioritize by Security Impact
Using the call graph, rank surviving mutants by impact:
| Priority | Criteria | Example |
|---|---|---|
| P0 — Critical | Mutant weakens validation/equality/authentication | ct_eq: & → | makes equality permissive |
| P1 — High | Mutant in deserialization flag parsing | from_compressed: & → | accepts invalid flags |
| P2 — Medium | Mutant in field arithmetic internals | Fp::square: | → ^ corrupts computation |
| P3 — Low | Mutant in optimization path | phi endomorphism: only affects performance path |
| Skip | Formatting, display, equivalent mutation | Debug::fmt return value replacement |
Step 6: Group by Vector Strategy
Group escaped mutants by the code path they represent and the type of test vector needed:
Deserialization flag validation (P1):
- g1.rs:339,363-365,384 — from_compressed_unchecked flags
→ Need: valid-point-wrong-flag vectors
Field arithmetic (P2):
- fp.rs:371-376,406,635-643 — subtract_p, neg, square
→ Need: field arithmetic KATs with edge-case values
Optimization thresholds (P3):
- g1.go:68, g2.go:75 — GLV vs windowed multiplication
→ Need: scalar multiplication with large scalars
Cross-package (framework limitation):
- hash_to_curve/g2.go:242-278 — isogeny, sgn0
→ Document as false positive or add sub-package test
Each group becomes a target for new test vectors in Phase 5.
Phase 5: Vector Generation
For each escaped code path group, design test vectors that force execution through that path.
Vector Design Patterns
| Code Path Type | Vector Strategy |
|---|---|
| Point deserialization | Malformed points: wrong length, invalid field elements, off-curve, wrong subgroup, identity point |
| Signature verification | Valid sig + all single-bit corruptions of sig, pk, msg |
| Hash-to-curve | Known answer tests (KATs) with edge-case inputs: empty, single byte, max length |
| Aggregate operations | 1 signer, many signers, duplicate signers, mixed valid/invalid |
| Error handling | Every error path should have a vector that triggers it |
| Arithmetic edge cases | Zero, one, field modulus - 1, points at infinity |
| Serialization flags | Every valid flag combination + every invalid flag combination |
| Roundtrip integrity | For every valid deser vector, assert serialize(deserialize(b)) == b |
| Carry/reduction faults | Reimplement at reduced limb widths, inject faults, extract distinguishing inputs |
Single-Fault Negative Vectors
Each negative vector should have exactly one defect with everything else valid — this isolates which validation check is being tested. See references/vector-patterns.md for per-flag construction examples.
Fault Simulation (Limb-Width Reimplementation)
When mutation testing only applies local operator swaps, deeper architectural bugs (carry propagation, reduction overflow) go untested. To close this gap, reimplement the target algorithm at reduced limb widths (8, 16, 25, 32 bits) and deliberately inject faults — then generate vectors that catch them.
See references/fault-simulation.md for the full methodology: limb-width selection, fault injection catalog, vector extraction, and validation workflow.
Cross-Implementation Verification
Every new test vector MUST be verified against at least two independent implementations before being added to the suite:
- Generate the vector using implementation A
- Verify with implementation B (different codebase, ideally different language)
- If B disagrees, investigate — one implementation has a bug
Vector Format
Use Wycheproof JSON format (algorithm, testGroups[].tests[]
with tcId, comment, result, flags). See
references/vector-patterns.md
for the full schema.
Wycheproof contributions: Use Wycheproof's vectorgen tool rather
than formatting vector files directly. Supply the generated changes as an
envelope. The vectorgen tool can add, update, or replace vectors while
handling tcId assignment, test counts, canonical formatting, and schema
validation. Go-based generators can avoid the vectorgen CLI tool and instead
call the programmatic github.com/c2sp/wycheproof/vectorgen API.
See references/lessons-learned.md §14 and the upstream vectorgen guide for the current workflow and commands.
Phase 6: Validation
Re-run mutation testing with the new test vectors included.
Tip: Use per-file mutation testing for fast iteration during vector development (see references/lessons-learned.md §12). Only run full-crate tests for the final comparison.
Before/After Comparison
| Metric | Baseline | With New Vectors | Delta |
|---|---|---|---|
| Killed | X | Y | Y - X |
| Survived | A | B | A - B (should decrease) |
| Not Covered | C | D | C - D (should decrease) |
| Efficacy % | E% | F% | F - E |
Success Criteria
Vectors have both retroactive value (killing mutants in existing code) and proactive value (catching bugs in future implementations). Generate both kinds — boundary-condition vectors may not improve kill rates in mature libraries but will catch bugs in new implementations. See references/lessons-learned.md §13.
Retroactive (measurable): previously survived/uncovered mutants become killed, no regressions.
If kill rates don't change: the implementation's own tests likely already cover those paths. The vectors still add cross-implementation verification value. Document which case applies.
Output Format
Write VECTOR_FORGE_REPORT.md covering: target algorithm,
implementations tested, baseline results, escape analysis,
new vectors generated, after results, before/after delta, and
conclusions. See
references/report-template.md
for the full template.
Quality Checklist
Before delivering:
- At least one pure implementation mutation-tested (not just FFI wrappers)
- Baseline run completed with existing vectors
- Trailmark call graph built for each implementation
- All escaped mutants triaged using graph-informed classification
- Cross-package false positives identified and documented
- Security-critical mutations (ct_eq, validation, auth) prioritized as P0/P1
- Fault simulation and mutation-derived vectors cross-verified against 2+ implementations
- After run completed with new vectors included
- Before/after delta computed and explained
- Report written to
VECTOR_FORGE_REPORT.md - New test vectors saved in standard format (Wycheproof JSON)
Integration
| Skill | Relationship |
|---|---|
| genotoxic (required for Phase 4) | Provides graph-informed triage — call graph cuts actionable mutants by 30-50% |
| mutation-testing (mewt/muton) | Use for Solidity; Vector Forge is language-agnostic |
| property-based-testing | Better than hand-crafted vectors for bitwise mutations in field arithmetic |
| testing-handbook-skills (fuzzing) | Functions with CC > 10 and surviving mutants need both vectors and fuzz harnesses |
Supporting Documentation
- references/mutation-frameworks.md - Language-specific mutation testing framework setup
- references/vector-patterns.md - Common test vector patterns for cryptographic primitives
- references/fault-simulation.md - Limb-width reimplementation for carry, reduction, and overflow faults
- references/report-template.md - Full markdown template for the Vector Forge report
- references/lessons-learned.md - BLS12-381 case study: FFI kill rates, timeout masking, cross-package false positives, bitwise mutation gaps, and security-critical priorities
Archivos de esta skill
8Preguntas sobre la skill vector-forge
¿Cómo instalo la skill vector-forge en Claude Code?
Ejecuta npx degit trailofbits/skills/plugins/trailmark/skills/vector-forge ~/.claude/skills/vector-forge. Claude Code carga las skills desde ~/.claude/skills (todos los proyectos) o .claude/skills (un proyecto) y usa una skill cuando su descripción coincide con la tarea.
¿Qué clientes pueden usar la skill vector-forge?
Cualquier cliente que lea el formato Agent Skills: Claude Code, Codex, Gemini CLI y claude.ai (subir como ZIP). Los scripts de la skill se ejecutan solo donde el cliente permite la ejecución de código.
¿Cuál es el propósito principal de Vector Forge?
Utiliza mutation testing para identificar sistemáticamente brechas en la cobertura de los vectores de prueba y genera nuevos vectores para cerrar dichas brechas.
¿Cómo se mide la efectividad de los nuevos vectores de prueba?
La efectividad se mide comparando las tasas de eliminación de mutaciones (mutation kill rates) antes y después de introducir los nuevos vectores.