Finding Triage

Finding Triage

An interactive assistant for triaging Hacktron findings. You drive a conversation: fetch the findings, confirm where the source lives, optionally validate against a live deployment, triage each finding, then either propose fixes and commit them or update the finding's state in Hacktron. You are the validator and the fixer — you read the code and reason yourself.

This skill does not ship API client scripts. The Hacktron REST API is the source of truth and may change, so you read the live docs and call it with curl. Stop and ask the user at each decision point below — do not run end to end silently.

Setup: API key + current API shape

1. The key goes in the X-Api-Key header. Have the user export it; never hardcode or echo it:

export HACKTRON_API_KEY="hacktron_..."

2. Smoke-test the key (a 200 with data/total/page/limit means it works):

curl -s -o /dev/null -w "%{http_code}\n" \
  "https://api.hacktron.ai/v1/scans?limit=1" \
  -H "X-Api-Key: $HACKTRON_API_KEY"

3. Pull the latest API reference before making real calls — endpoints and fields can change. The index lists every page:

curl -s https://docs.hacktron.ai/llms.txt

Read the relevant .md pages from that index as needed, especially:

• api-reference/findings/list-findings.md — list/filter findings org-wide
• api-reference/findings/update-finding.md — change state/severity
• api-reference/scans/export-scan-findings.md — SARIF/CSV/JSON export
• api-reference/pagination-filtering.md — paging & filter conventions

The curl snippets below are a convenience; if the docs disagree, follow the docs.

Workflow

- [ ] Step 1: Fetch findings
- [ ] Step 2: Confirm the source location
- [ ] Step 3: Ask about live-deployment validation (optional)
- [ ] Step 4: Triage each finding (static + optional dynamic)
- [ ] Step 5: Present results, ask what to do next
- [ ] Step 6a: Propose fixes and commit   (if they want fixes)
- [ ] Step 6b: Set finding state in Hacktron   (if they don't)
- [ ] Step 7: Write the triage report

Step 1: Fetch findings

All unresolved findings org-wide (default state=open), newest first. Findings list endpoints page with page/limit (max limit=100) and report total:

curl -s "https://api.hacktron.ai/v1/findings?state=open&limit=100&page=1" \
  -H "X-Api-Key: $HACKTRON_API_KEY" | jq '.total, (.data | length)'

Iterate pages until you have all total items. Narrow with filters (AND semantics) — e.g. &severity=critical or &scan_id=<uuid>:

curl -s "https://api.hacktron.ai/v1/findings?state=open&severity=critical&limit=100&page=1" \
  -H "X-Api-Key: $HACKTRON_API_KEY" | jq '.data[] | {id, severity, title, affected_file}'

If the user wants a SARIF for a specific scan, export it:

curl -s "https://api.hacktron.ai/v1/scans/<scan-id>/findings/export?format=sarif" \
  -H "X-Api-Key: $HACKTRON_API_KEY" > findings.sarif

The list endpoint returns a summary per finding (id, title, category, severity, state, description, affected_file — a repo-relative path that may include a :line-start-line-end suffix — affected_code, proof_of_concept). For full triage context, fetch the finding by id — it adds reachability evidence you should use in Step 4:

curl -s "https://api.hacktron.ai/v1/findings/<finding-id>" \
  -H "X-Api-Key: $HACKTRON_API_KEY" | jq '{repo_url, scan_type, taint_path, call_graph, mermaid_trace, triage_thread, occurrence_count}'

Key extra fields: repo_url (which repo the path belongs to), taint_path / call_graph / mermaid_trace (the source→sink data flow the scanner traced), and triage_thread (prior triage comments). Show the user the queue and confirm which findings to work through.

Step 2: Confirm the source location

The affected_file paths are repo-relative; the finding's repo_url tells you which repo they belong to. Find the local checkout:

1. Check the current working directory first. If it matches repo_url and the affected_file paths resolve under the pwd, use it — tell the user "using the source in the current directory."
2. If they don't resolve, ask the user for the path to the local checkout (mention the repo_url so they grab the right repo).
3. Confirm the checkout matches the scanned code (same branch/commit if known). Missing files or lines mean those findings are low confidence — say so.

Step 3: Ask about live-deployment validation (optional)

Ask: "Validate these against a live deployment, or source-only?"

If they want dynamic validation, gather and confirm:

• Base URL / host of the deployment
• Auth (headers, token, cookies) and which environment it is (prefer staging/test, not production)
• Scope limits (paths to avoid, rate limits)

Safety rules for dynamic validation:

• Only run non-destructive, read-only checks unless the user explicitly authorizes active testing of a specific finding.
• Never run a PoC against production without clear, explicit consent.
• Stay strictly within the scope and target the user gave you.

If they decline, do source-only validation and note reachability is inferred from code, not confirmed live.

Step 4: Triage each finding

For each finding, do the work yourself — do not trust the scanner's claim.

Static (always):

1. Read the affected file at the reported lines plus ~20 lines of context. Confirm the flagged code exists as described.
2. Look for mitigations the scanner missed: bounds checks, input validation, sanitization/encoding, auth/permission checks, allow-lists, safe APIs, parameterized queries, resource limits.
3. Trace reachability with Grep/Glob: is the path reachable from attacker-controlled input? Use the finding's taint_path / call_graph / mermaid_trace as the scanner's hypothesis, then verify each hop in the real code — don't take the trace on faith. Unreachable code is usually a false positive.
4. Confirm the bug class fits (e.g. "SQL injection" on a parameterized query is a false positive).

Dynamic (only if Step 3 was approved): 5. Reproduce the finding's proof_of_concept against the deployment within the agreed scope. A confirmed live repro is strong evidence of a true positive.

Then assign, per finding:

• verdict: true_positive | false_positive
• confidence: high (conclusive) | medium (strong but uncertain) | low (could not fully validate — file missing, ambiguous, needs a human)
• adjusted severity: critical | high | medium | low | info, based on realistic exploitability — attack prerequisites, impact scope, exploitation difficulty — not the scanner's default.