mirror of
https://github.com/trailofbits/skills
synced 2026-06-21 14:12:00 +00:00
trailmark: add variant neighborhood skill
This commit is contained in:
Scott Arciszewski
@@ -225,8 +225,8 @@
|
||||
},
|
||||
{
|
||||
"name": "trailmark",
|
||||
"version": "0.10.0",
|
||||
"description": "Builds multi-language source and binary code graphs for security analysis: call graphs, attack surface mapping, blast radius, taint propagation, complexity hotspots, entry point enumeration, proxy/unresolved-call tracking, type/reference analysis, and structural diffs. Generates Mermaid diagrams, runs graph-informed mutation testing triage (genotoxic), generates mutation-driven test vectors (vector-forge), extracts crypto protocol message flows, converts Mermaid diagrams to ProVerif models, projects SARIF/weAudit/binary findings onto code graphs, triages single findings with graph evidence, and gates branch diffs for structural review regressions. Use when analyzing call paths, mapping attack surface, visualizing code architecture, triaging survived mutants, generating cryptographic test vectors, diagramming crypto protocols, formally verifying protocols, augmenting audits with static analysis findings, deciding whether one candidate issue is reachable, or reviewing graph-level PR risk.",
|
||||
"version": "0.11.0",
|
||||
"description": "Builds multi-language source and binary code graphs for security analysis: call graphs, attack surface mapping, blast radius, taint propagation, complexity hotspots, entry point enumeration, proxy/unresolved-call tracking, type/reference analysis, and structural diffs. Generates Mermaid diagrams, runs graph-informed mutation testing triage (genotoxic), generates mutation-driven test vectors (vector-forge), extracts crypto protocol message flows, converts Mermaid diagrams to ProVerif models, projects SARIF/weAudit/binary findings onto code graphs, triages single findings with graph evidence, gates branch diffs for structural review regressions, and expands seed findings into variant-neighborhood candidates. Use when analyzing call paths, mapping attack surface, visualizing code architecture, triaging survived mutants, generating cryptographic test vectors, diagramming crypto protocols, formally verifying protocols, augmenting audits with static analysis findings, deciding whether one candidate issue is reachable, reviewing graph-level PR risk, or seeding variant analysis.",
|
||||
"author": {
|
||||
"name": "Scott Arciszewski",
|
||||
"url": "https://github.com/tob-scott-a"
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "trailmark",
|
||||
"version": "0.10.0",
|
||||
"description": "Builds multi-language source and binary code graphs for security analysis: call graphs, attack surface mapping, blast radius, taint propagation, complexity hotspots, entry point enumeration, proxy/unresolved-call tracking, type/reference analysis, and structural diffs. Generates Mermaid diagrams, runs graph-informed mutation testing triage (genotoxic), generates mutation-driven test vectors (vector-forge), extracts crypto protocol message flows, converts Mermaid diagrams to ProVerif models, projects SARIF/weAudit/binary findings onto code graphs, triages single findings with graph evidence, and gates branch diffs for structural review regressions. Use when analyzing call paths, mapping attack surface, visualizing code architecture, triaging survived mutants, generating cryptographic test vectors, diagramming crypto protocols, formally verifying protocols, augmenting audits with static analysis findings, deciding whether one candidate issue is reachable, or reviewing graph-level PR risk.",
|
||||
"version": "0.11.0",
|
||||
"description": "Builds multi-language source and binary code graphs for security analysis: call graphs, attack surface mapping, blast radius, taint propagation, complexity hotspots, entry point enumeration, proxy/unresolved-call tracking, type/reference analysis, and structural diffs. Generates Mermaid diagrams, runs graph-informed mutation testing triage (genotoxic), generates mutation-driven test vectors (vector-forge), extracts crypto protocol message flows, converts Mermaid diagrams to ProVerif models, projects SARIF/weAudit/binary findings onto code graphs, triages single findings with graph evidence, gates branch diffs for structural review regressions, and expands seed findings into variant-neighborhood candidates. Use when analyzing call paths, mapping attack surface, visualizing code architecture, triaging survived mutants, generating cryptographic test vectors, diagramming crypto protocols, formally verifying protocols, augmenting audits with static analysis findings, deciding whether one candidate issue is reachable, reviewing graph-level PR risk, or seeding variant analysis.",
|
||||
"author": {
|
||||
"name": "Scott Arciszewski",
|
||||
"url": "https://github.com/tob-scott-a"
|
||||
|
||||
@@ -51,6 +51,7 @@ uv pip install trailmark
|
||||
| `mermaid-to-proverif` | Convert Mermaid sequence diagrams into ProVerif formal verification models |
|
||||
| `audit-augmentation` | Project SARIF, weAudit, and v0.4 binary-analysis graph findings onto code graphs as annotations and subgraphs |
|
||||
| `trailmark-finding-triage` | Triage one finding, SARIF result, weAudit annotation, suspicious function, or report excerpt with reachability, taint, privilege-boundary, and blast-radius evidence |
|
||||
| `trailmark-variant-neighborhood` | Expand one seed issue into graph-derived variant candidates for variant-analysis, Semgrep, CodeQL, or manual review |
|
||||
| `trailmark-summary` | Quick structural overview (auto-detected languages, entry points, dependencies) for vivisect/galvanize |
|
||||
| `trailmark-structural` | Full structural analysis with all pre-analysis passes (blast radius, taint, privilege boundaries, complexity) |
|
||||
|
||||
@@ -77,6 +78,7 @@ trailmark/
|
||||
│ └── examples/
|
||||
├── audit-augmentation/ # SARIF/weAudit integration
|
||||
├── trailmark-finding-triage/ # Single-finding evidence packets
|
||||
├── trailmark-variant-neighborhood/ # Variant candidate neighborhoods
|
||||
├── trailmark-summary/ # Quick overview for vivisect/galvanize
|
||||
└── trailmark-structural/ # Full structural analysis
|
||||
```
|
||||
|
||||
@@ -125,7 +125,8 @@ Write the evidence packet using
|
||||
|
||||
Hand off promoted PoC-worthy issues to the user's PoC workflow. Hand off
|
||||
related findings to a composition workflow. Hand off repeatable root causes to
|
||||
`variant-analysis` or a custom Semgrep/CodeQL rule workflow.
|
||||
`trailmark-variant-neighborhood`, `variant-analysis`, or a custom Semgrep/CodeQL
|
||||
rule workflow.
|
||||
|
||||
## Example Prompts
|
||||
|
||||
|
||||
@@ -0,0 +1,109 @@
|
||||
---
|
||||
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
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
icon_small: "assets/trail-of-bits-mark.svg"
|
||||
icon_large: "assets/trail-of-bits-mark.svg"
|
||||
brand_color: "#D83A34"
|
||||
@@ -0,0 +1 @@
|
||||
<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>
|
||||
|
After Width: | Height: | Size: 3.0 KiB |
+59
@@ -0,0 +1,59 @@
|
||||
# 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))
|
||||
|
||||
if hasattr(engine, "entrypoint_paths_to"):
|
||||
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
|
||||
@@ -0,0 +1,66 @@
|
||||
# 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
|
||||
@@ -0,0 +1,44 @@
|
||||
# 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 |
|
||||
@@ -308,3 +308,7 @@ pre-analysis pass documentation.
|
||||
Use `trailmark-finding-triage` when the user has one concrete candidate
|
||||
finding, SARIF result, weAudit annotation, suspicious function, or report
|
||||
excerpt and needs a handoff-ready reachability and blast-radius evidence packet.
|
||||
|
||||
Use `trailmark-variant-neighborhood` after one seed issue is known and the user
|
||||
needs graph-derived variant candidates for `variant-analysis`, Semgrep, CodeQL,
|
||||
or manual review.
|
||||
|
||||
Reference in New Issue
Block a user