interface:
  display_name: "Trailmark Variant Neighborhood"
  short_description: "Find graph neighbors that may share a vulnerability"
  icon_small: "assets/trail-of-bits-mark.svg"
  icon_large: "assets/trail-of-bits-mark.svg"
  brand_color: "#D83A34"

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