/trailmark-finding-triage

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).

Shortcut for Steps 2–4 (file/line findings)

For file/line anchors, run the bundled script. It builds the graph and preanalysis once, binds every finding, and prints the Graph Evidence fields as JSON: all matching nodes and the primary one (the node containing the first line, then the narrowest), entrypoint paths with each entrypoint's trust level, `tainted` / `entrypoint_reachable` / `privilege_boundary` / `high_blast_radius` membership, callers, callees, downstream nodes, and the Trailmark version. Pass several findings in one call rather than rebuilding the graph per finding.

uv run --no-project "{baseDir}/scripts/evidence_packet.py" --target <dir> --finding <file>:<line>[-<end>] --out evidence.json [--finding ...] [--language auto]

With `--out`, the complete packet stays on disk and stdout contains only delivery counts. Read relevant finding records from that file. Without `--out`, stdout is the full packet. Relative anchors may be target- or working-directory-relative; ambiguous existing paths are rejected. Choose `--path-base target` or `cwd`, or use an absolute path. Lines must be positive and ordered; column syntax is not supported. Containers cover module/class/contract declarations when no callable overlaps. Inspect `binding` (exact, nested or ambiguous), `binding_kind`, all matches, unavailable signals and parser diagnostic limitations before judging the result. A zero-node graph is a failure. Batching shares graph work only: write a separate human verdict for each finding.

A finding that binds to nothing comes back with `bound_node: null` and the reason. The script judges nothing: read the bound code and its callers, decide attacker control, and treat an empty path list as a limitation to explain (dynamic dispatch, proxies, missing entrypoint models), not as proof. Use the steps below for inputs the script does not take (function names, SARIF via `audit-augmentation`) and for queries it does not run (`connect_subgraphs`).

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 c