mirror of
https://github.com/trailofbits/skills
synced 2026-06-21 14:12:00 +00:00
trailmark: add finding triage skill
This commit is contained in:
Scott Arciszewski
@@ -225,8 +225,8 @@
|
||||
},
|
||||
{
|
||||
"name": "trailmark",
|
||||
"version": "0.8.3",
|
||||
"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, and projects SARIF/weAudit/binary findings onto code graphs. Use when analyzing call paths, mapping attack surface, visualizing code architecture, triaging survived mutants, generating cryptographic test vectors, diagramming crypto protocols, formally verifying protocols, or augmenting audits with static analysis findings.",
|
||||
"version": "0.9.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, and triages single findings with graph evidence. 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, or deciding whether one candidate issue is reachable.",
|
||||
"author": {
|
||||
"name": "Scott Arciszewski",
|
||||
"url": "https://github.com/tob-scott-a"
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "trailmark",
|
||||
"version": "0.8.3",
|
||||
"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, and projects SARIF/weAudit/binary findings onto code graphs. Use when analyzing call paths, mapping attack surface, visualizing code architecture, triaging survived mutants, generating cryptographic test vectors, diagramming crypto protocols, formally verifying protocols, or augmenting audits with static analysis findings.",
|
||||
"version": "0.9.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, and triages single findings with graph evidence. 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, or deciding whether one candidate issue is reachable.",
|
||||
"author": {
|
||||
"name": "Scott Arciszewski",
|
||||
"url": "https://github.com/tob-scott-a"
|
||||
|
||||
@@ -49,6 +49,7 @@ uv pip install trailmark
|
||||
| `graph-evolution` | Compare code graphs at two snapshots to surface security-relevant structural changes text diffs miss |
|
||||
| `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-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) |
|
||||
|
||||
@@ -73,6 +74,7 @@ trailmark/
|
||||
├── mermaid-to-proverif/ # Sequence diagram → ProVerif
|
||||
│ └── examples/
|
||||
├── audit-augmentation/ # SARIF/weAudit integration
|
||||
├── trailmark-finding-triage/ # Single-finding evidence packets
|
||||
├── trailmark-summary/ # Quick overview for vivisect/galvanize
|
||||
└── trailmark-structural/ # Full structural analysis
|
||||
```
|
||||
@@ -84,3 +86,4 @@ trailmark/
|
||||
| `mutation-testing` | Guidance for running mutation frameworks (mewt, muton) — use before genotoxic for triage |
|
||||
| `differential-review` | Text-level security diff review — complements graph-evolution's structural analysis |
|
||||
| `audit-context-building` | Deep architectural context before vulnerability hunting |
|
||||
| `variant-analysis` | Search for related candidates after trailmark-finding-triage identifies a repeatable root cause |
|
||||
|
||||
@@ -27,6 +27,7 @@ also import an external binary-analysis graph JSON export via
|
||||
- Cross-referencing static analysis findings with blast radius or taint data
|
||||
- Querying which functions have high-severity findings
|
||||
- Visualizing audit coverage alongside code structure
|
||||
- Preparing one SARIF or weAudit result for `trailmark-finding-triage`
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
@@ -162,6 +163,10 @@ annotated nodes. Use `engine.subgraph_names()` to see available subgraphs.
|
||||
- Findings on high blast radius nodes: overlap with `high_blast_radius`
|
||||
- Findings on privilege boundaries: overlap with `privilege_boundary`
|
||||
|
||||
For one candidate finding that needs a reachability verdict or PoC handoff,
|
||||
continue with `trailmark-finding-triage` and use the augmented node as the
|
||||
bound candidate.
|
||||
|
||||
## Annotation Format
|
||||
|
||||
Findings are stored as standard Trailmark annotations:
|
||||
|
||||
@@ -0,0 +1,137 @@
|
||||
---
|
||||
name: trailmark-finding-triage
|
||||
description: "Performs graph-assisted triage of a single security finding, SARIF result, weAudit annotation, suspicious function, or report excerpt using Trailmark reachability, entrypoint paths, taint, privilege-boundary, blast-radius, caller/callee, and neighborhood evidence. Use when deciding whether one candidate issue is reachable, prioritizing a finding before PoC work, preparing evidence for exploit validation, or checking whether a static-analysis result is actionable."
|
||||
allowed-tools:
|
||||
- Bash
|
||||
- Read
|
||||
- Grep
|
||||
- Glob
|
||||
- Write
|
||||
---
|
||||
|
||||
# Trailmark Finding Triage
|
||||
|
||||
Build a concise graph evidence packet for one candidate finding. This skill
|
||||
answers whether the affected code is reachable, what graph evidence supports
|
||||
or weakens the claim, and what manual review is still required before calling
|
||||
the issue exploitable.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Triage one static-analysis result before spending PoC time
|
||||
- Check whether a manual finding is entrypoint-reachable
|
||||
- Build an evidence packet for PoC work
|
||||
- Review a single suspicious function discovered during manual audit
|
||||
- Decide whether one issue should be promoted, deprioritized, or treated as
|
||||
part of a broader chain analysis
|
||||
|
||||
## When NOT to Use
|
||||
|
||||
- Multiple weak findings might compose into a stronger chain. Use a chain or
|
||||
composition workflow instead.
|
||||
- The user wants a full audit. Use an audit or design-review workflow instead.
|
||||
- The user wants remediation verification for a known finding. Use a
|
||||
remediation-review workflow instead.
|
||||
- The target is a PR or branch diff. Use `graph-evolution` plus a differential
|
||||
review workflow.
|
||||
- No concrete finding, function, file/line, or suspicious sink exists yet. Use
|
||||
discovery skills first.
|
||||
|
||||
## Rationalizations to Reject
|
||||
|
||||
| Rationalization | Why It Is Wrong | Required Action |
|
||||
|---|---|---|
|
||||
| "The scanner says high severity, so reachability is obvious" | Static findings need graph and code context before promotion | Bind the finding to a graph node and check entrypoint paths |
|
||||
| "No entrypoint path means impossible" | It may mean parser, proxy, or dynamic dispatch limitations | Report the limitation separately from reachability |
|
||||
| "An auth check appears on the path, so the issue is safe" | The check may enforce the wrong predicate or be bypassed by another path | Treat validation/auth as review targets, not proof |
|
||||
| "One reachable path is enough for a PoC claim" | The path still needs attacker-controlled inputs and compatible preconditions | Separate graph reachability from exploitability |
|
||||
| "This is probably a chain" | Single-finding triage stops at one candidate | Hand off related findings to a composition workflow |
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
Finding Triage Progress:
|
||||
- [ ] Step 1: Normalize the candidate
|
||||
- [ ] Step 2: Build or reuse the Trailmark graph
|
||||
- [ ] Step 3: Bind the candidate to graph node(s)
|
||||
- [ ] Step 4: Analyze reachability, taint, boundaries, and blast radius
|
||||
- [ ] Step 5: Decide and emit the evidence packet
|
||||
```
|
||||
|
||||
### Step 1: Normalize the Candidate
|
||||
|
||||
Accept file/line, function name, SARIF result, weAudit annotation, Markdown
|
||||
finding excerpt, or a manual claim. Normalize it to:
|
||||
|
||||
- title
|
||||
- source type
|
||||
- file path and line range if present
|
||||
- function or node hint
|
||||
- suspected source, sink, or asset
|
||||
- claimed impact
|
||||
|
||||
If there is no concrete code anchor, stop and ask for one.
|
||||
|
||||
For input handling details, see
|
||||
[references/input-normalization.md](references/input-normalization.md).
|
||||
|
||||
### Step 2: Build Or Reuse The Graph
|
||||
|
||||
Use the public `trailmark` skill workflow. Prefer an existing fresh exported
|
||||
graph or `.trailmark/` artifact when present. Otherwise build a graph with
|
||||
`language="auto"` or the target's explicit language list, then run
|
||||
`engine.preanalysis()`.
|
||||
|
||||
Record the Trailmark version or feature probes used. Feature-gate Trailmark
|
||||
0.4-only APIs with `hasattr()` or CLI help checks.
|
||||
|
||||
### Step 3: Bind The Candidate
|
||||
|
||||
Bind by file and line overlap first, then function name plus file. If several
|
||||
nodes match, list every candidate and select the narrowest enclosing node as
|
||||
primary. If no node matches, report a binding limitation instead of guessing.
|
||||
|
||||
SARIF and weAudit users should reuse the `audit-augmentation` workflow for
|
||||
matching and then inspect the annotated node.
|
||||
|
||||
### Step 4: Analyze Graph Evidence
|
||||
|
||||
Run the query recipe in
|
||||
[references/query-recipes.md](references/query-recipes.md):
|
||||
|
||||
- entrypoint paths to the bound node
|
||||
- trust level of each path when available
|
||||
- membership in `tainted`, `privilege_boundary`, and `high_blast_radius`
|
||||
subgraphs
|
||||
- direct callers and callees
|
||||
- high-impact downstream sinks
|
||||
- sibling or nearby nodes worth manual review
|
||||
|
||||
Do not treat graph reachability as proof of exploitability.
|
||||
|
||||
### Step 5: Decide And Handoff
|
||||
|
||||
Produce one verdict:
|
||||
|
||||
| Verdict | Meaning |
|
||||
|---|---|
|
||||
| `Promote` | Graph evidence supports reachability and plausible impact |
|
||||
| `Needs manual review` | Evidence is suggestive but not decisive |
|
||||
| `Deprioritize` | No reachable path or only trusted/internal paths found |
|
||||
| `Blocked` | Binding or Trailmark analysis failed |
|
||||
|
||||
Write the evidence packet using
|
||||
[references/output-format.md](references/output-format.md).
|
||||
|
||||
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.
|
||||
|
||||
## Example Prompts
|
||||
|
||||
- "Use Trailmark finding triage on `src/Vault.sol:148`; I think withdraw can
|
||||
bypass the balance update."
|
||||
- "Triage this SARIF result before I spend PoC time: `semgrep:error
|
||||
unchecked-transfer` in `contracts/Bridge.sol` line 91."
|
||||
- "This report excerpt claims `parse_packet` is attacker reachable. Build the
|
||||
Trailmark evidence packet and tell me what is still missing."
|
||||
@@ -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 |
@@ -0,0 +1,51 @@
|
||||
# Input Normalization
|
||||
|
||||
Normalize every request into one candidate record before graph analysis.
|
||||
|
||||
## Accepted Inputs
|
||||
|
||||
| Input | Required fields | Notes |
|
||||
|---|---|---|
|
||||
| File/line | `file`, `line` | Best starting point for direct graph binding |
|
||||
| Function name | `function`, optional `file` | Ambiguous across files; ask for file if many nodes match |
|
||||
| SARIF result | `artifactLocation.uri`, `region` | Prefer `audit-augmentation` matching when SARIF is available |
|
||||
| weAudit annotation | file, line, severity, text | Convert 0-indexed lines to Trailmark's expected source lines when needed |
|
||||
| Markdown finding | title, location or symbol | Extract the claimed impact but do not assume it is true |
|
||||
| Manual claim | anchor plus suspected issue | Ask for a concrete anchor if none is provided |
|
||||
|
||||
## Candidate Record
|
||||
|
||||
Use this shape in notes and final output:
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Unchecked balance update before transfer",
|
||||
"source_type": "manual|sarif|weaudit|report|function",
|
||||
"file": "src/Vault.sol",
|
||||
"line_range": [148, 168],
|
||||
"function_hint": "withdraw(uint256)",
|
||||
"suspected_source": "external caller",
|
||||
"suspected_sink": "value transfer",
|
||||
"claimed_impact": "withdrawal without balance decrement"
|
||||
}
|
||||
```
|
||||
|
||||
## Stop Conditions
|
||||
|
||||
Stop and request a concrete anchor when:
|
||||
|
||||
- only a vulnerability class is provided
|
||||
- only a package or directory is provided
|
||||
- the excerpt has no file, function, line, symbol, or SARIF/weAudit location
|
||||
- all matching graph nodes are test, generated, or vendor code and the user did
|
||||
not say those are in scope
|
||||
|
||||
## Ambiguity Handling
|
||||
|
||||
If multiple graph nodes match:
|
||||
|
||||
1. Keep all matches in the evidence packet.
|
||||
2. Prefer file/line overlap over name matching.
|
||||
3. Prefer the narrowest enclosing node.
|
||||
4. Mark confidence `Low` unless the candidate source unambiguously identifies
|
||||
the intended node.
|
||||
@@ -0,0 +1,63 @@
|
||||
# Output Format
|
||||
|
||||
Return a concise evidence packet. Use Markdown unless the user asks for JSON.
|
||||
|
||||
```markdown
|
||||
# Trailmark Finding Triage: <title>
|
||||
|
||||
## Verdict
|
||||
|
||||
Status: Promote | Needs manual review | Deprioritize | Blocked
|
||||
Confidence: High | Medium | Low
|
||||
|
||||
## Candidate
|
||||
|
||||
- Source:
|
||||
- Location:
|
||||
- Bound node:
|
||||
- Claimed issue:
|
||||
|
||||
## Graph Evidence
|
||||
|
||||
- Entrypoint reachable:
|
||||
- Entry paths:
|
||||
- Tainted:
|
||||
- Privilege boundary:
|
||||
- Blast radius:
|
||||
- Direct callers:
|
||||
- Direct callees:
|
||||
- Relevant sinks:
|
||||
|
||||
## Manual Review Targets
|
||||
|
||||
| Target | Why it matters |
|
||||
|---|---|
|
||||
|
||||
## Limitations
|
||||
|
||||
## Recommended Next Step
|
||||
```
|
||||
|
||||
## Verdict Criteria
|
||||
|
||||
| Verdict | Use when |
|
||||
|---|---|
|
||||
| `Promote` | The candidate binds cleanly, has reachable entrypoint paths, and graph evidence supports plausible impact |
|
||||
| `Needs manual review` | The candidate is reachable but exploitability depends on validation, authorization, type, or state semantics |
|
||||
| `Deprioritize` | The candidate is not entrypoint-reachable, is only trusted-internal, or sits in test/generated/vendor code outside scope |
|
||||
| `Blocked` | The candidate cannot be bound, Trailmark fails, or the language/parser is unsupported |
|
||||
|
||||
## Confidence Criteria
|
||||
|
||||
| Confidence | Use when |
|
||||
|---|---|
|
||||
| `High` | Binding is exact, paths are explicit, and graph evidence is consistent |
|
||||
| `Medium` | Binding is clear but path or sink evidence has uncertainty |
|
||||
| `Low` | Binding is ambiguous, dynamic dispatch/proxy edges dominate, or important graph features are unavailable |
|
||||
|
||||
## Wording Requirements
|
||||
|
||||
- Say "graph evidence supports" instead of "Trailmark proves".
|
||||
- Say "manual review target" for validators, auth checks, and sanitizers.
|
||||
- Separate "reachable" from "attacker controlled".
|
||||
- Separate "candidate" from "confirmed vulnerability".
|
||||
@@ -0,0 +1,92 @@
|
||||
# Query Recipes
|
||||
|
||||
Use these recipes after building a graph and running `engine.preanalysis()`.
|
||||
Feature-gate optional Trailmark 0.4 APIs with `hasattr()`.
|
||||
|
||||
## Build And Preanalyze
|
||||
|
||||
```python
|
||||
from trailmark.query.api import QueryEngine
|
||||
|
||||
engine = QueryEngine.from_directory("{targetDir}", language="auto")
|
||||
engine.preanalysis()
|
||||
```
|
||||
|
||||
If auto-detection is wrong, rerun with an explicit language or comma-separated
|
||||
language list.
|
||||
|
||||
## Bind A File/Line Candidate
|
||||
|
||||
Prefer Trailmark or `audit-augmentation` matching helpers when available. If
|
||||
working from exported JSON, match nodes whose location file equals the
|
||||
candidate file and whose line span overlaps the candidate line range. Pick the
|
||||
smallest span as primary.
|
||||
|
||||
## Reachability
|
||||
|
||||
```python
|
||||
node_id = "{bound_node}"
|
||||
|
||||
if hasattr(engine, "entrypoint_paths_to"):
|
||||
entry_paths = engine.entrypoint_paths_to(node_id)
|
||||
else:
|
||||
entry_paths = []
|
||||
for entry in engine.attack_surface():
|
||||
for path in engine.paths_between(entry["name"], node_id):
|
||||
entry_paths.append(path)
|
||||
```
|
||||
|
||||
Classify paths as:
|
||||
|
||||
- `untrusted_external`
|
||||
- `semi_trusted_external`
|
||||
- `trusted_internal`
|
||||
- `unknown`
|
||||
|
||||
If no path exists, distinguish likely dead/internal code from parser,
|
||||
language, proxy, dynamic dispatch, or missing-entrypoint modeling gaps.
|
||||
|
||||
## Taint And Privilege Boundaries
|
||||
|
||||
```python
|
||||
tainted = node_id in set(engine.subgraph("tainted"))
|
||||
boundary = node_id in set(engine.subgraph("privilege_boundary"))
|
||||
entry_reachable = node_id in set(engine.subgraph("entrypoint_reachable"))
|
||||
```
|
||||
|
||||
When `connect_subgraphs()` exists, use it to find paths from tainted nodes to
|
||||
privilege-boundary nodes and check whether the candidate sits on or near those
|
||||
paths.
|
||||
|
||||
## Blast Radius And Neighborhood
|
||||
|
||||
```python
|
||||
callers = engine.callers_of(node_id)
|
||||
callees = engine.callees_of(node_id)
|
||||
high_blast = node_id in set(engine.subgraph("high_blast_radius"))
|
||||
|
||||
if hasattr(engine, "reachable_from"):
|
||||
downstream = engine.reachable_from(node_id)
|
||||
else:
|
||||
downstream = []
|
||||
```
|
||||
|
||||
Flag downstream sinks involving:
|
||||
|
||||
- value transfer
|
||||
- authorization or role decisions
|
||||
- persistence or state writes
|
||||
- parsing or deserialization
|
||||
- cryptographic keys, sessions, or signatures
|
||||
- external process, network, or file operations
|
||||
|
||||
## Evidence Limits
|
||||
|
||||
Always record:
|
||||
|
||||
- Trailmark version or feature probes
|
||||
- unsupported languages or parser errors
|
||||
- unresolved/proxy/dynamic call uncertainty
|
||||
- unmatched or ambiguous graph binding
|
||||
- missing entrypoint modeling
|
||||
- places where manual security judgment is still required
|
||||
@@ -18,6 +18,7 @@ semantic metadata for security analysis.
|
||||
- Adding LLM-inferred annotations (assumptions, preconditions) to code units
|
||||
- Importing external binary-analysis graphs to connect source and binary views
|
||||
- Querying transitive slices, entrypoint paths, subgraph edges, or type references
|
||||
- Producing graph evidence for one suspicious function or candidate finding
|
||||
- Pre-analysis before mutation testing (genotoxic skill) or diagramming
|
||||
|
||||
## When NOT to Use
|
||||
@@ -303,3 +304,7 @@ security analysis patterns.
|
||||
|
||||
See [references/preanalysis-passes.md](references/preanalysis-passes.md) for
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user