interface:
  display_name: "Trailmark Finding Triage"
  short_description: "Assess a security finding with code graph evidence"
  icon_small: "assets/trail-of-bits-mark.svg"
  icon_large: "assets/trail-of-bits-mark.svg"
  brand_color: "#D83A34"

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

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

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

entry_paths = engine.entrypoint_paths_to(node_id)
```

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

downstream = engine.reachable_from(node_id)
```

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