sast-pipeline

SAiST Pipeline

Three-phase static analysis: gaps → resolve → run rules.

CLI Binary

This skill requires the auditor-addon-cli skill for the aud binary. Before running any aud command, load that skill to determine the correct binary path.

Scope

When the user provides specific files or a file list as input to this skill, use those exact files as the scope for all commands. Do NOT broaden to glob patterns — the user's scope is intentional, and broad globs pull in out-of-scope files that create irrelevant gaps and noisy findings.

# User provides: contracts/src/Vault.sol contracts/src/Token.sol
aud gaps contracts/src/Vault.sol contracts/src/Token.sol

# NOT: aud gaps "contracts/src/**/*.sol"

Only use glob patterns when the user explicitly asks for a broad scan (e.g., "scan all Solidity files").

Phase 1: Gaps Scan

Run aud gaps <files...> to build the symbol graph and emit all unresolved references. Use aud gaps --help for filtering options (by priority, kind, etc.).

Gaps only cover four reference kinds: import, call, inheritance, and using_for. State-variable, modifier, event, and custom-error references live in the AST, not the graph — rules query them via ast.find or graph.find_in_scope, so missing ones don't appear in aud gaps.

Gaps are grouped by priority:

• high — in call chains from public entry points
• medium — have public callers
• low — internal, unlikely to affect rule accuracy

Clean (no gaps) → skip to Phase 3. Otherwise proceed to Phase 2.

Phase 2: Resolve Gaps

Review gaps and resolve what you can. Create a CSV file:

ref_id,target_file,target_line,target_name
a4f2e81b,src/Ownable.sol,15,onlyOwner
b7c3d012,src/Ownable.sol,3,Ownable

Triage:

• high: always resolve
• medium: resolve if they touch public entry points or affect rule accuracy
• low: safe to skip

How to resolve a gap: Use only basic file operations — Read, Glob, Grep. No scripts.

1. Grep the codebase for the target name (function, contract, modifier, type)
2. Read the candidate file to confirm it's the right definition
3. Note the file path, line number, and name — add a row to the CSV

Use aud peek on candidate files to quickly scan signatures without reading full source.

Iterate: After resolving a batch, re-run aud gaps <files...> --resolutions=resolutions.csv to confirm progress. Resolve more if high/medium gaps remain. Repeat until only low-priority or genuinely unresolvable gaps are left.

Resolution target files do NOT need to be in the original scope — aud automatically parses them into the graph when applying the CSV. Findings and gaps still only report on scoped files.

Phase 3: Run Rules

Run aud run <files...> --resolutions=resolutions.csv (omit --resolutions if Phase 1 was clean). Use aud run --help for options (specific rules, adhoc rule files, confidence filters, etc.).

Findings are tagged with a confidence kind:

• issue — high confidence, confirmed defect
• smell — medium confidence, likely problem
• pointer — low confidence, suspicious pattern

Custom Rules (Per-Engagement)

Custom rules are .lua files (see rule-authoring skill for authoring details). The flywheel:

1. Find an issue during manual review
2. Recognize it's a repeatable pattern
3. Write a custom rule (see aud run --help for --rule-path usage)
4. Test against the known instance
5. Run against the full codebase to discover other instances