trailmark variant neighborhood
- Repo stars 0
- Author updated Aug 24, 2026, 11:09 PM
- Author repo skills
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @trailofbits · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Node.js
- Detected file/system behavior
-
- Read-only
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
Accept finding text, file/line, function name, or output from `trailmark-finding-triage`. Bind the seed to a Trailmark node and record the root cause in plain language. If the seed has no concrete graph binding, stop before inventing variants.
Use the dimensions in references/neighborhood-patterns.md: shared callers shared callees and sinks entrypoint path neighbors
Rank with references/ranking.md. Prioritize entrypoint-reachable, tainted, boundary-adjacent, high-blast-radius, shared sink, same-interface, and close-distance candidates. Penalize test, mock, generated, vendor, unreachable, and trusted-internal-only candidates.
Summarize what should be searched for syntactically and what requires semantic review. Identify whether follow-up belongs in: `variant-analysis` `semgrep-rule-creator` `static-analysis` with CodeQL or SARIF-producing tools
Use references/output-format.md. Include ranked candidates, inclusion reasons, exclusions, limitations, and the variant-analysis handoff.
# Trailmark Variant Neighborhood
Expand one seed issue into graph-derived variant candidates. This skill
generates review targets, not confirmed findings.
## When to Use
- A finding is confirmed or plausible and variants may exist
- The vulnerable pattern depends on call context
- The issue involves a shared sink, source, validator, interface, override,
trait, hook, handler, adapter, or critical type
- The next step is to seed `variant-analysis`, `semgrep-rule-creator`,
`static-analysis`, or manual review
## When NOT to Use
- No seed issue exists. Use discovery or triage first.
- The pattern is purely syntactic and already obvious. Use
`semgrep-rule-creator` directly.
- The question is exploit-chain composition across multiple findings. Use a
composition workflow.
- The goal is remediation verification. Use a remediation-review workflow.
- The seed cannot be bound to a graph node.
## Rationalizations to Reject
| Rationalization | Why It Is Wrong | Required Action |
|---|---|---|
| "Nearby code means variant" | Proximity is only a candidate reason | Rank it as a review target |
| "Only exact same names matter" | Variants often share sinks or preconditions, not names | Expand across callers, callees, interfaces, and types |
| "Every candidate is a finding" | This skill outputs candidates for review | Avoid vulnerability claims |
| "Unreachable candidates can be ignored completely" | They may become reachable after refactors | Rank lower or list as deferred |
| "Graph candidates replace semantic pattern work" | Graph structure finds locations, not root-cause semantics | Hand off to variant-analysis, Semgrep, CodeQL, or manual review |
## Workflow
```
Variant Neighborhood Progress:
- [ ] Step 1: Normalize and bind the seed
- [ ] Step 2: Expand graph neighborhoods
- [ ] Step 3: Rank candidates
- [ ] Step 4: Extract variant pattern guidance
- [ ] Step 5: Emit handoff packet
```
### Step 1: Normalize And Bind The Seed
Accept finding text, file/line, function name, or output from
`trailmark-finding-triage`. Bind the seed to a Trailmark node and record the
root cause in plain language.
If the seed has no concrete graph binding, stop before inventing variants.
### Step 2: Expand Neighborhoods
Use the dimensions in
[references/neighborhood-patterns.md](references/neighborhood-patterns.md):
- shared callers
- shared callees and sinks
- entrypoint path neighbors
- interface, override, trait, and implementation siblings
- file or module cluster neighbors
- taint or privilege-boundary peers
- type and state-reference neighbors
Bound expansion to avoid candidate floods.
### Step 3: Rank Candidates
Rank with [references/ranking.md](references/ranking.md). Prioritize
entrypoint-reachable, tainted, boundary-adjacent, high-blast-radius, shared
sink, same-interface, and close-distance candidates. Penalize test, mock,
generated, vendor, unreachable, and trusted-internal-only candidates.
### Step 4: Extract Pattern Guidance
Summarize what should be searched for syntactically and what requires semantic
review. Identify whether follow-up belongs in:
- `variant-analysis`
- `semgrep-rule-creator`
- `static-analysis` with CodeQL or SARIF-producing tools
- manual review
### Step 5: Emit Handoff Packet
Use [references/output-format.md](references/output-format.md). Include
ranked candidates, inclusion reasons, exclusions, limitations, and the
variant-analysis handoff.
## Stop Conditions
- No graph binding exists
- Candidate count is too high and the root cause is underspecified
- Trailmark cannot analyze the target language
- The seed is only in test, generated, or vendor code and the user did not say
that code is in scope
Listed in source order.
sections -> When to Use → When NOT to Use → Rationalizations to Reject → Workflow → Step 1: Normalize And Bind The Seed → Step 2: Expand Neighborhoods
terms -> Expand one seed issue into graph-derived variant candidates. · - No seed issue exists. · Accept finding text, file/line, function name, or output from trailmark-finding-triage. · If the seed has no concrete graph binding, stop before inventing variants. · Bound expansion to avoid candidate floods. · Rank with [references/ranking.md](references/ranking.md). · Summarize what should be searched for syntactically and what requires semantic review. · Use [references/output-format.md](references/output-format.md).
files/cmd -> variant-analysis · semgrep-rule-creator · static-analysis · trailmark-finding-triage
body sha256 -> e927038dc1be
When to Use
A finding is confirmed or plausible and variants may exist The vulnerable pattern depends on call context The issue involves a shared sink, source, validator, interface, override, trait, hook, handler, adapter, or critical type The next step is to seed
variant-analysis,semgrep-rule-creator,When NOT to Use
No seed issue exists. Use discovery or triage first. The pattern is purely syntactic and already obvious. Use
semgrep-rule-creatordirectly. The question is exploit-chain composition across multiple findings. Use a composition workflow.Rationalizations to Reject
Rationalization · Why It Is Wrong · Required Action "Nearby code means variant" · Proximity is only a candidate reason · Rank it as a review target "Only exact same names matter" · Variants often share sinks or preconditions, not names · Expand across callers, callees, interfaces, and types "Every candidate is a finding" · This skill outputs candidates for review · Avoid vulnerability claims "Unreachable candidates can be ignored completely" · They may become reachable after refactors · Rank lower or list as deferred
Step 1: Normalize And Bind The Seed
Accept finding text, file/line, function name, or output from
trailmark-finding-triage. Bind the seed to a Trailmark node and record the root cause in plain language. If the seed has no concrete graph binding, stop before inventing variants.Step 2: Expand Neighborhoods
Use the dimensions in references/neighborhood-patterns.md: shared callers shared callees and sinks entrypoint path neighbors