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:
- 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. 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. 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
1---
2name: trailmark-variant-neighborhood
3description: "Expands one confirmed or suspected vulnerability into a Trailmark graph neighborhood of variant candidates by finding sibling functions, shared callers and callees, common sensitive sinks, common entrypoint paths, interface implementations, override relationships, type/reference neighbors, and structurally similar nodes. Use after one issue is found to seed variant-analysis, semgrep-rule-creator, static-analysis, or manual review with graph-derived candidate locations."
4allowed-tools:
5 - Bash
6 - Read
7 - Grep
8 - Glob
9 - Write
10metadata:
11 source: https://skillmd.com/skills/gabrielmoreira/trailmark-variant-neighborhood
12---
13
14# Trailmark Variant Neighborhood
15
16Expand one seed issue into graph-derived variant candidates. This skill
17generates review targets, not confirmed findings.
18
19## When to Use
20
21- A finding is confirmed or plausible and variants may exist
22- The vulnerable pattern depends on call context
23- The issue involves a shared sink, source, validator, interface, override,
24 trait, hook, handler, adapter, or critical type
25- The next step is to seed `variant-analysis`, `semgrep-rule-creator`,
26 `static-analysis`, or manual review
27
28## When NOT to Use
29
30- No seed issue exists. Use discovery or triage first.
31- The pattern is purely syntactic and already obvious. Use
32 `semgrep-rule-creator` directly.
33- The question is exploit-chain composition across multiple findings. Use a
34 composition workflow.
35- The goal is remediation verification. Use a remediation-review workflow.
36- The seed cannot be bound to a graph node.
37
38## Rationalizations to Reject
39
40| Rationalization | Why It Is Wrong | Required Action |
41|---|---|---|
42| "Nearby code means variant" | Proximity is only a candidate reason | Rank it as a review target |
43| "Only exact same names matter" | Variants often share sinks or preconditions, not names | Expand across callers, callees, interfaces, and types |
44| "Every candidate is a finding" | This skill outputs candidates for review | Avoid vulnerability claims |
45| "Unreachable candidates can be ignored completely" | They may become reachable after refactors | Rank lower or list as deferred |
46| "Graph candidates replace semantic pattern work" | Graph structure finds locations, not root-cause semantics | Hand off to variant-analysis, Semgrep, CodeQL, or manual review |
47
48## Workflow
49
50```
51Variant Neighborhood Progress:
52- [ ] Step 1: Normalize and bind the seed
53- [ ] Step 2: Expand graph neighborhoods
54- [ ] Step 3: Rank candidates
55- [ ] Step 4: Extract variant pattern guidance
56- [ ] Step 5: Emit handoff packet
57```
58
59### Step 1: Normalize And Bind The Seed
60
61Accept finding text, file/line, function name, or output from
62`trailmark-finding-triage`. Bind the seed to a Trailmark node and record the
63root cause in plain language.
64
65If the seed has no concrete graph binding, stop before inventing variants.
66
67### Step 2: Expand Neighborhoods
68
69Use the dimensions in
70[references/neighborhood-patterns.md](references/neighborhood-patterns.md):
71
72- shared callers
73- shared callees and sinks
74- entrypoint path neighbors
75- interface, override, trait, and implementation siblings
76- file or module cluster neighbors
77- taint or privilege-boundary peers
78- type and state-reference neighbors
79
80Bound expansion to avoid candidate floods.
81
82### Step 3: Rank Candidates
83
84Rank with [references/ranking.md](references/ranking.md). Prioritize
85entrypoint-reachable, tainted, boundary-adjacent, high-blast-radius, shared
86sink, same-interface, and close-distance candidates. Penalize test, mock,
87generated, vendor, unreachable, and trusted-internal-only candidates.
88
89### Step 4: Extract Pattern Guidance
90
91Summarize what should be searched for syntactically and what requires semantic
92review. Identify whether follow-up belongs in:
93
94- `variant-analysis`
95- `semgrep-rule-creator`
96- `static-analysis` with CodeQL or SARIF-producing tools
97- manual review
98
99### Step 5: Emit Handoff Packet
100
101Use [references/output-format.md](references/output-format.md). Include
102ranked candidates, inclusion reasons, exclusions, limitations, and the
103variant-analysis handoff.
104
105## Stop Conditions
106
107- No graph binding exists
108- Candidate count is too high and the root cause is underspecified
109- Trailmark cannot analyze the target language
110- The seed is only in test, generated, or vendor code and the user did not say
111 that code is in scope