trustabl-enrich

Trustabl Enrich

Applies Trustabl scan findings directly to source files. "Enrich" covers the full remediation loop: adding what is absent (guardrails, docstrings, timeouts, type annotations) and correcting what is wrong (unsafe patterns, misconfigurations). The scan result already contains the solution — this skill translates it into code.

When to Use

• You have output from trustabl scan (JSON, SARIF, or plain text) and want findings applied to source files automatically
• You want to remediate agent misconfigurations without editing each file manually
• You are triaging findings to separate real issues from false positives before applying changes

This skill does not run trustabl scan. Run the scan first (or use the trustabl-scan skill), then invoke this skill with the results.

Input Formats

All three formats produced by the Trustabl CLI are accepted. The skill detects the format automatically.

Format	Command
JSON	trustabl scan --format json
SARIF 2.1.0	trustabl scan --format sarif
Plain text	paste terminal output directly

When you run trustabl scan yourself (e.g. to produce input, or to re-verify at the end), resolve the binary the way the trustabl-scan skill does: prefer "$TRUSTABL_BIN", then the plugin-managed path reported by the Trustabl SessionStart check this session, then trustabl on PATH.

If the input cannot be parsed or contains zero findings, report clearly and stop — do not proceed to enrichment.

SARIF extraction path:

• Findings: runs[0].results[]
• File + line: locations[0].physicalLocation.artifactLocation.uri + locations[0].physicalLocation.region.startLine
• Explanation: message.text
• Fix (primary): result.fixes[0].description.text — present on most results
• Fix (fallback): runs[0].tool.driver.rules[] — match on id == ruleId, read help.text; use when fixes array is absent

JSON extraction path:

• Findings: findings[]
• File + line range: file_path + start_line … end_line (1-indexed, inclusive; a single-line finding sets end_line == start_line; both are 0 for repo-level findings with no location). Note: Trustabl 0.1.4 renamed the former flat line field to start_line / end_line — read those, not line.
• Explanation: explanation · Fix: suggested_fix
• Also present per finding: rule_id, scope, severity, confidence. Dependency CVE findings (when the scan ran with --vuln-scan / vuln_scan) appear in the same findings array — the advisory id (CVE / GHSA / PYSEC) is the rule_id, and start_line points at the dependency's line in its manifest. The structured vulnerabilities[] array carries the same matches with fixed_in versions.

Workflow

1. Parse — detect the format and normalize every finding into: file, start_line, end_line, rule_id, scope, severity, confidence, explanation, suggested_fix. (For SARIF, end_line may be absent for a single-line region — fall back to start_line.)

2. Summarize — render a Markdown table before touching any file:

   | # | File | Line | Rule | Scope | Severity | Confidence | Explanation |

3. Enrich per file — group findings by file. For each file:

   • Read the current file content
   • Pass all findings for that file plus the file content to the model
   • The model returns replacement ranges guided by the scan's explanation and suggested_fix

4. Apply bottom-up — within each file, sort enrichments by line_start descending, then apply using the Edit tool. Bottom-up order prevents line-offset drift.

5. Report — after all edits: <file>: N enrichment(s) applied, M false positive(s) skipped, K external action(s) required. Then ask: "Re-run trustabl scan to confirm findings are resolved?" — never run it automatically.

System Prompt

Use this prompt verbatim for each file's model call.

You are a security engineer enriching AI agent source code based on findings from a Trustabl static analysis scan.

INPUTS
You will receive:
1. The current content of a source file
2. A list of findings for that file, each with:
   - start_line / end_line: the flagged line range (1-indexed, inclusive; equal for a single-line finding)
   - rule_id: Trustabl rule that fired
   - scope: tool | agent | subagent | repo
   - severity: info | low | medium | high | critical
   - confidence: 0.0–1.0
   - explanation: what is wrong and why it matters
   - suggested_fix: the exact change Trustabl recommends

Read the file content carefully before generating any replacement.

OUTPUT
Return a raw JSON array — one object per finding, in the same order as input. No prose. No markdown fences.

[
  {
    "rule_id": "<rule_id from input>",
    "line_start": <first line of replacement range — must include the flagged line>,
    "line_end": <last line of replacement range>,
    "replacement": "<exact replacement lines, original indentation preserved, no trailing newline>",
    "false_positive": false,
    "reason": "<populated only if false_positive is true>"
  }
]

SCOPE GUIDE
- tool: enrich the tool function — add missing docstrings, network timeout kwargs, type annotations, failure handlers, normalized paths
- agent: enrich the Agent / AgentDefinition constructor — add missing input_guardrails, output_guardrails, fix tool_use_behavior, correct MCP server wiring
- subagent: enrich the .claude/agents/*.md frontmatter — fix tools list, align description to tools, add missing name field
- repo: enrich project-level config — add tracing processor, add SandboxAgent, update pyproject.toml / package.json settings

RULES
- The scan's `explanation` and `suggested_fix` fields are the authoritative spec. Do not invent a different solution.
- line_start and line_end MUST include the flagged range (start_line..end_line). Expand the range only if adjacent lines must also change for the replacement to be syntactically valid.
- If the fix is a config or external action with no code edit, set line_start and line_end to 0 and replacement to "".
- Set false_positive: true only when the code is demonstrably correct despite the finding. Populate reason with the specific evidence.
- Preserve the file's indentation style (tabs vs spaces) and language idioms.
- Do not add comments to enriched code explaining the change.
- Do not add imports that are not required by the replacement code.

Applying Enrichments

After the model returns the JSON array:

If the response cannot be parsed as a JSON array, halt immediately and report the raw model response to the user — do not attempt heuristic extraction.

1. Group enrichments by file.
2. Sort each file's enrichments by line_start descending.
3. Apply each enrichment with the Edit tool.
4. Skip and log entries where line_start == 0 as: [external action required] <rule_id>: <suggested_fix>
5. Skip and log entries where false_positive == true as: [false positive] <rule_id>: <reason>

Findings with no file location (META findings and repo-scoped findings where file_path is empty): show them in the summary table with File: (repo-level) and Line: —, then log them as external actions — do not attempt an Edit for these.

Constraints

MUST DO

• Show the findings table before touching any file
• Read the current file content before generating enrichments for it
• Apply enrichments bottom-up within each file
• Echo rule_id in every enrichment object
• Mark false positives with an explicit reason
• Log line_start == 0 entries as external actions required
• Ask before re-running trustabl scan

MUST NOT DO

• Run trustabl scan — this skill enriches only
• Change lines outside line_start–line_end unless required for syntactic validity
• Invent findings not present in the scan output
• Deviate from the scan's suggested_fix field
• Add comments to enriched code
• Collapse multiple findings into one edit