trailmark-variant-neighborhood

어떤 스킬인가요?

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.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

interface:
  icon_small: "assets/trail-of-bits-mark.svg"
  icon_large: "assets/trail-of-bits-mark.svg"
  brand_color: "#D83A34"

<svg xmlns="http://www.w3.org/2000/svg" width="94" height="56" fill="none" viewBox="0 0 94 56"><path fill="#F0F4F7" d="m34.04 54.662-7.61-4.147L24.593 56l9.433-1.335c-.029 0-.043 0 .014-.003"/><path fill="#F0F4F7" d="m34.039 54.662-.014.003c.035 0 .096-.003.014-.003m26.191-2.67 6.124-1.804 2.301-7.26-5.655.387zM74.805 5.478l-4.68-3.035-2.62 8.332 5.15 1.548zM43.224 3.532s3.172.973 4.423 1.328l4.508 1.335L52.234 0l-7.928 1.576zm-31.473 23.14 5.566.014 1.982-6.216-5.06-1.342c-.538 1.708-1.94 5.837-2.488 7.544M1.394 20.896l4.164 4.338 2.398-7.696-5.11-1.357zm88.205 24.841c-.086-2.18-.692-2.894-1.978-4.232l-6.71.447c1.871 1.175 3.018 2.63 3.255 4.583.261 2.145-2.068 4.623-4.322 4.623-1.258 0-1.885-.987-1.885-2.12.035-.845.333-1.942.777-2.673h-5.691c-.444 1.136-.813 2.418-.813 3.625 0 4.136 3.659 5.197 7.131 5.197 3.62 0 6.616-.696 8.501-4.03.85-1.505 1.806-3.663 1.735-5.42M18.804.56 1.362.576 0 4.86l6.394-.007-3.161 9.962 5.114 1.356 3.551-11.322 5.544-.007z"/><path fill="#F0F4F7" d="M20.707 15.898c.628-.04 1.258-.04 1.886-.04 1.035-.003 2.587.072 2.587 1.499.004.987-.366 2.233-.66 3.184-.551 1.942-1.214 3.88-1.325 5.858l5.727-.007c-.151-3.185 1.842-5.968 1.838-9.117 0-2.123-1.627-2.964-3.512-3.294l.552-.075c4.103-.554 6.39-3.738 6.386-7.729-.004-4.423-3.738-5.666-7.544-5.662l-6.576.007c-1.87 5.751-3.645 11.534-5.462 17.31l5.057 1.339zM24.245 4.58l1.849-.004c1.369 0 2.734.327 2.738 1.939.003 1.977-1.437 5.31-3.803 5.31l-3.031.004zm11.959 21.883 2.949-5.531 7.06-.008-.215 5.564 5.544-.004.441-18.94-4.763-1.43a89 89 0 0 0-.677 10.71h-.036l-5.322.004c1.914-3.586 3.749-7.2 5.4-10.906L42.77 4.775 30.437 26.466zm39.249-.036 1.402-4.214-7.43.01 2.753-8.612-5.15-1.548-4.584 14.375zm-34.411 1.658h-7.28l-6.834 21.18 8.698 4.694c5.208-.196 8.856-4.012 8.856-9.252 0-2.013-1.258-3.586-3.215-4.136 3.846-.877 6.319-3.33 6.319-7.356-.004-3.923-3.072-5.13-6.544-5.13m-2.993 20.318c-1.036 1.537-2.143 1.647-3.881 1.647h-2.254l2.476-7.611c1.81.07 5.024-.366 5.024 2.268 0 1.168-.698 2.744-1.365 3.696m-.444-9.667h-2.072l2.18-6.7c1.626.075 4.694-.436 4.694 2.053.04 2.928-1.846 4.647-4.802 4.647M58.67 9.582l-5.522 18.29-4.878 14.836 5.856-.447 4.23-13.2h.006l5.713-17.878c-.796-.22-3.964-1.228-5.404-1.601m2.738 18.542-1.37 4.278h6.398l-2.993 9.525 5.584-.38 2.913-9.145h5.541l1.37-4.278zm25.351-.259c-5.726 0-9.127 3.951-9.127 9.444.007.798.727 2.765 2.2 3.422l6.888-.462c-1.172-.98-3.243-3.29-3.243-4.519 0-1.686.95-3.891 2.91-3.891 1.33 0 2.143.366 2.143 1.793 0 .916-.444 1.757-.702 2.638h5.322c.333-.77.849-2.528.849-3.334.004-3.994-3.913-5.09-7.24-5.09m-63.15.372c-2.605 0-2.978 1.906-3.623 3.93-.215.728-.623 1.615-.623 2.379 0 1.47 1.315 1.75 2.537 1.75 1.494.01 2.29-.487 2.82-1.878.362-.952 1.305-3.568 1.305-4.488 0-1.303-1.326-1.693-2.416-1.693m.728 1.87c0 .328-.373 1.392-.498 1.765l-.577 1.782c-.226.675-.498 1.449-1.359 1.449-.487 0-.802-.28-.802-.785 0-.653.509-1.864.724-2.538.215-.671.498-2.01 1.247-2.269.168-.056.351-.078.534-.078.34 0 .749.302.749.664zm5.902 2.674.394-1.292H28.37l.613-1.928h2.38l.42-1.292h-4.126l-2.48 7.924h1.735l1.075-3.412z"/></svg>

# Neighborhood Patterns

Use multiple bounded graph dimensions. Each dimension creates candidate review
targets, not findings.

| Dimension | Query idea | Variant hypothesis |
|---|---|---|
| Same caller | Other callees of the seed's caller | Caller applies the same bad precondition before several sinks |
| Same callee/sink | Other callers of the vulnerable sink | Missing validation before the same sink elsewhere |
| Same entrypoint path | Nodes on related paths from the same entrypoint | Adjacent unchecked operation in the same user flow |
| Same interface/override | Implementations of the same interface, trait, override, hook, or adapter family | One implementation fixed, sibling remains vulnerable |
| Same file/module cluster | Neighboring functions with similar dependencies | Copy/paste or parallel business logic |
| Same taint/boundary class | Nodes with the same taint and boundary status | Same trust transition, different operation |
| Same type/reference use | Functions touching the same critical type or state object | Missing invariant around the same asset |

## Query Sketches

```python
seed = "{bound_node}"
callers = engine.callers_of(seed)
callees = engine.callees_of(seed)

same_caller_candidates = []
for caller in callers:
    same_caller_candidates.extend(engine.callees_of(caller))

same_sink_candidates = []
for callee in callees:
    if is_sensitive_sink(callee):
        same_sink_candidates.extend(engine.callers_of(callee))

paths = engine.entrypoint_paths_to(seed)

if hasattr(engine, "type_references"):
    type_neighbors = engine.type_references(seed)
```

## Expansion Bounds

Use the smallest useful candidate set:

- cap each dimension at the top 10 candidates unless the user asks for more
- prefer graph distance 1 or 2 before wider expansion
- exclude generated, vendor, test, and mock paths by default
- stop and ask for a narrower root cause when more than 50 candidates survive
  first-pass ranking

## Evidence To Preserve

For each candidate, preserve:

- node ID and source location
- neighborhood dimension
- distance from seed when available
- reachability and trust level
- taint and privilege-boundary status
- shared sink, caller, interface, or type reason
- exclusion or penalty reason

# Output Format

Use Markdown unless the user asks for JSON.

```markdown
# Trailmark Variant Neighborhood

## Seed

- Finding:
- Bound node:
- Root cause:

## Candidate Summary

| Rank | Candidate | Reason | Reachability | Confidence |
|---|---|---|---|---|

## Graph Neighborhoods

### Shared Callers
### Shared Callees / Sinks
### Entrypoint Path Neighbors
### Interface Or Implementation Siblings
### Type / State Neighbors

## Variant-Analysis Handoff

- Root cause:
- Keep specific:
- Abstract:
- Suggested searches:
- Suggested CodeQL/Semgrep direction:

## Exclusions And Limitations
```

## Wording Requirements

- Say "candidate" or "review target", not "variant vulnerability".
- Explain why each candidate was included.
- Separate graph similarity from semantic root-cause similarity.
- Include exclusions so reviewers understand why obvious nearby code was not
  prioritized.

## Handoff Guidance

For `variant-analysis`, provide:

- seed location
- root cause in one sentence
- ranked candidate table
- positive and negative examples
- graph dimensions that produced useful candidates

For `semgrep-rule-creator`, provide:

- the syntax that should stay specific
- the syntax that should be abstracted
- at least one true-positive candidate and one likely negative example

For `static-analysis`, provide:

- candidate files and functions
- suggested source, sink, or path query shape
- SARIF output expectation if the user wants machine-readable results

# Ranking

Rank candidates by review value, not by confirmed severity.

## Positive Signals

| Signal | Effect |
|---|---|
| Entrypoint-reachable | Strong priority increase |
| Untrusted or semi-trusted entrypoint path | Strong priority increase |
| Tainted | Strong priority increase |
| Privilege-boundary adjacent | Strong priority increase |
| High blast radius | Priority increase |
| Shares vulnerable sink | Priority increase |
| Same interface, override, trait, hook, or adapter family | Priority increase |
| Same critical type or state reference | Priority increase |
| Graph distance 1 or 2 from seed | Priority increase |

## Negative Signals

| Signal | Effect |
|---|---|
| Unreachable from modeled entrypoints | Lower priority; keep if root cause is strong |
| Trusted-internal-only | Lower priority |
| Test, mock, generated, or vendor code | Exclude unless in scope |
| Ambiguous binding | Lower confidence |
| Proxy or dynamic edge uncertainty dominates | Lower confidence and add limitation |

## Rank Labels

| Rank | Meaning |
|---|---|
| `High` | Review first; strong structural similarity and reachability |
| `Medium` | Plausible variant; needs semantic review |
| `Low` | Weak or unreachable candidate; keep for completeness or deferred review |
| `Excluded` | Out of scope, generated, vendor, or insufficient binding |

## Confidence Labels

| Confidence | Use when |
|---|---|
| `High` | Exact binding, explicit relationship, clear reachability |
| `Medium` | Clear relationship but some path or root-cause uncertainty |
| `Low` | Ambiguous binding, dynamic dispatch uncertainty, or weak similarity |

---
name: trailmark-variant-neighborhood
description: "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."
allowed-tools:
  - Bash
  - Read
  - Grep
  - Glob
  - Write
---

# 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