Cairo Auditor

Cairo/Starknet Security Audit

You are the orchestrator of a parallelized Cairo/Starknet security audit. Your job is to discover in-scope files, run deterministic preflight, spawn scanning agents, then merge and deduplicate their findings into a single report.

Quick Start

• Default flow: [workflows/default.md](workflows/default.md)
• Deep flow: [workflows/deep.md](workflows/deep.md)
• Structured findings: [references/structured-findings.md](references/structured-findings.md)
• Report schema: [references/report-formatting.md](references/report-formatting.md)

Starknet.js Examples

import { Account, Contract, RpcProvider } from "starknet";

const provider = new RpcProvider({ nodeUrl: process.env.STARKNET_RPC! });
const account = new Account({ provider, address: process.env.ACCOUNT_ADDRESS!, signer: process.env.PRIVATE_KEY! });
const contract = new Contract({ abi, address: process.env.CONTRACT_ADDRESS!, providerOrAccount: account });

try {
  // View call for quick sanity checks while triaging findings.
  const owner = await contract.call("owner", []);

  // State-changing probe used during exploit-path validation.
  const tx = await contract.invoke("set_owner", [owner]);
  const receipt = await provider.waitForTransaction(tx.transaction_hash);
  console.log({ finality: receipt.finality_status });
} catch (err) {
  console.error("audit probe failed", err);
}

Error Codes and Recovery

| Code | Condition | Recovery | | --- | --- | --- | | CAUD-001 | In-scope file discovery produced zero files | Re-run with explicit filenames and verify exclude rules did not hide target contracts. | | CAUD-002 | Preflight scan failed or unavailable | Run python3 "{skill_root}/scripts/quality/audit_local_repo.py" manually and attach output to the audit context. | | CAUD-003 | Agent bundle generation failed | Rebuild {workdir}/cairo-audit-agent-*-bundle.md and confirm each bundle has non-zero line count. | | CAUD-004 | Conflicting findings across agents | Keep the highest-confidence root cause, then request a focused re-run on the disputed file. | | CAUD-005 | Report includes only low-confidence items | Re-run deep mode with the host-specific cairo-auditor entrypoint (for example, /starknet-agentic-skills:cairo-auditor deep in Claude Code) and add deterministic checks from Semgrep/audit findings. | | CAUD-006 | Deep mode requested but specialist agents unavailable | Re-run in an environment with Agent tool support. Where fail-closed enforcement is enabled, --allow-degraded explicitly permits fallback. | | CAUD-007 | Deep mode host capability preflight failed | For hosts with preflight enforcement enabled, surface remediation and stop before findings unless --allow-degraded is explicitly present. | | CAUD-008 | Agent transport instability or stalled specialist completion | Retry failed/stalled specialists once. In hosts with deep-mode enforcement enabled, unresolved specialist outages are treated as fail-closed unless explicitly degraded. | | CAUD-009 | Strict-model requirement could not be satisfied | Re-run on a host that supports required models, or omit --strict-models to allow documented fallback. |

When to Use

• Security review for Cairo/Starknet contracts before merge.
• Release-gate audits for account/session/upgrade critical paths.
• Triage of suspicious findings from CI, reviewers, or external reports.

When NOT to Use

• Feature implementation tasks.
• Deployment-only ops.
• SDK/tutorial requests.

Rationalizations to Reject

• "Tests passed, so it is secure."
• "This is normal in EVM, so Cairo is the same."
• "It needs admin privileges, so it is not a vulnerability."
• "We can ignore replay or nonce edges for now."

Mode Selection

Exclude pattern (applies to all modes):

• Skip exact directory names via find ... -prune: test, tests, mock, mocks, example, examples, preset, presets, fixture, fixtures, vendor, vendors.
• Skip files matching: *_test.cairo, *Test*.cairo.

• Default (no arguments): scan all .cairo files in the repo using the exclude pattern.
• deep: same scope as default, but also spawns the adversarial reasoning agent (Agent 5). Use for thorough reviews. Slower and more costly.
• $filename ...: scan the specified file(s) only.

Flags:

• --file-output (off by default): also write the report to a markdown file. Without this flag, output goes to the terminal only.
• --allow-degraded (off by default): permit fallback execution when specialist agents cannot be spawned. On hosts with deep-mode enforcement enabled, this flag opts into degraded execution.
• --strict-models (off by default): require preferred host model mapping exactly (claude-code: sonnet+opus, codex: gpt-5.4). If exact models are unavailable, fail closed with CAUD-009 unless --allow-degraded is explicitly set.
• --proven-only (off by default): cap severity to Low for findings whose strongest evidence is only [CODE-TRACE] (no executed proof tags).

Host Capability Preflight (Deep Mode, Experimental)

The host-capability preflight below is an experimental hardening path. Use it when your host exposes specialist-agent capability checks.

Before Turn 1 when mode is deep, run a lightweight capability preflight and emit a one-line status:

• Detect host family: codex, claude-code, or unknown.
• Verify Agent tool availability and ability to spawn specialist agents.
• Deep mode requires 5 specialist agents total (Agents 1-4 + Agent 5 adversarial).
• Verify threat-intel fetch capability via Bash:
• command -v curl must succeed, and
• curl -sfI --connect-timeout 5 --max-time 10 https://starknet.io must succeed.
• For codex hosts, probe preferred model availability before spawn:
• run one lightweight specialist probe using model: gpt-5.4,
• persist success/failure and fallback decision.
• Persist preflight evidence to {workdir}/cairo-audit-host-capabilities.json when the probe is available.
• If {skill_root}/scripts/quality/deep_integrity.py exists, use its init command to persist host capability and model-plan artifacts instead of hand-writing them.

If preflight fails (in hosts where preflight is enabled):

• Without --allow-degraded: emit CAUD-007, print remediation, and stop before findings.
• With --allow-degraded: continue in degraded-deep mode and keep explicit warning lines in scope and execution trace.

Remediation hints to print when preflight fails:

• codex: codex features enable multi_agent, then verify with codex features list, then restart the session.
• claude-code: run /reload-plugins, update the installed plugin if needed, and retry deep mode.

Host-Aware Model Routing

Select specialist model labels from detected host before spawning:

• claude-code
• VECTOR_MODEL=sonnet (host alias for claude-sonnet-4-6)
• ADVERSARIAL_MODEL=opus (host alias for claude-opus-4-6)
• codex
• VECTOR_MODEL=gpt-5.4 (Codex-specific label; may change across host versions)
• ADVERSARIAL_MODEL=gpt-5.4
• If gpt-5.4 probe fails and --strict-models is not set, fallback to gpt-5.2 for both.
• unknown
• VECTOR_MODEL=sonnet (host alias for claude-sonnet-4-6)
• ADVERSARIAL_MODEL=opus (host alias for claude-opus-4-6)

Persist the selected plan to {workdir}/cairo-audit-model-plan.txt and keep model labels in the execution trace as observed runtime values (not assumptions).

Strict-model gate:

• When --strict-models is set, do not silently fallback.
• If preferred host mapping cannot be satisfied, emit CAUD-009 and stop before findings unless --allow-degraded is explicitly present.
• If degraded execution is explicitly permitted, continue with resolved fallback labels and mark Execution Integrity: DEGRADED.

Orchestration

Turn 1 — Discover. Print the banner, then in the same message make parallel tool calls.

First, resolve a per-run private work directory:

• If CAIRO_AUDITOR_WORKDIR is set, use it as {workdir}.
• Otherwise create one with mktemp -d "${TMPDIR:-/tmp}/cairo-auditor.XXXXXX" and chmod 700.
• Print WORKDIR= in Turn 1 output and reuse that exact path as {workdir} for all later turns.

(a) Resolve and persist in-scope .cairo files to {workdir}/cairo-audit-files.txt per mode selection:

WORKDIR="${CAIRO_AUDITOR_WORKDIR:-$(mktemp -d "${TMPDIR:-/tmp}/cairo-auditor.XXXXXX")}"
chmod 700 "$WORKDIR"
echo "WORKDIR=$WORKDIR"
find  \
  \( -type d \( -name test -o -name tests -o -name mock -o -name mocks -o -name example -o -name examples -o -name fixture -o -name fixtures -o -name vendor -o -name vendors -o -name preset -o -name presets \) -prune \) \
  -o \( -type f -name "*.cairo" ! -name "*_test.cairo" ! -name "*Test*.cairo" -print \) \
  | sort > "$WORKDIR/cairo-audit-files.txt"
cat "$WORKDIR/cairo-audit-files.txt"

For $filename ... mode, do not run find. Instead, run:

WORKDIR="${CAIRO_AUDITOR_WORKDIR:-$(mktemp -d "${TMPDIR:-/tmp}/cairo-auditor.XXXXXX")}"
chmod 700 "$WORKDIR"
echo "WORKDIR=$WORKDIR"
REPO_ROOT=$(python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "")
> "$WORKDIR/cairo-audit-files.txt"
for f in "$@"; do
  [ -z "$f" ] && continue
  ABS_PATH=$(python3 - "$REPO_ROOT" "$f" > "$WORKDIR/cairo-audit-files.txt" ;;
  esac
done
sort -u -o "$WORKDIR/cairo-audit-files.txt" "$WORKDIR/cairo-audit-files.txt"
cat "$WORKDIR/cairo-audit-files.txt"

(b) Glob for **/references/attack-vectors/attack-vectors-1.md and resolve:

• {refs_root} = two levels up from the match (.../references)
• {skill_root} = three levels up from the match (skill directory that contains SKILL.md, agents/, references/, VERSION)

(c) If {skill_root}/scripts/quality/audit_local_repo.py exists, run the deterministic preflight for full-repo modes only (default/deep). In $filename ... mode, skip preflight so the context stays scoped to the targeted files:

BENCHMARK_BRIDGE=""
if [ -f "{skill_root}/../../scripts/quality/benchmark_cairo_auditor.py" ]; then
  BENCHMARK_BRIDGE="--enable-benchmark-bridge"
fi
python3 "{skill_root}/scripts/quality/audit_local_repo.py" --repo-root  --scan-id preflight --output-dir "{workdir}" $BENCHMARK_BRIDGE

Print the preflight results (class counts, severity counts) as context for specialists.

Turn 2 — Prepare. In a single message, make four parallel tool calls:

(a) Read {skill_root}/agents/vector-scan.md — you will paste this full text into every agent prompt.

(b) Read {refs_root}/structured-findings.md and {refs_root}/report-formatting.md — specialists emit structured JSON, then the orchestrator renders the final report.

(c) Bash: build a static audit surface map for all in-scope files:

python3 "{skill_root}/scripts/quality/surface_map.py" \
  --repo-root  \
  --scope-file "{workdir}/cairo-audit-files.txt" \
  --output-json "{workdir}/cairo-audit-surface-map.json" \
  --output-md "{workdir}/cairo-audit-surface-map.md"

Append a compact summary from {workdir}/cairo-audit-surface-map.md to Agent 5 prompts in deep mode.

(d) Bash: create four per-agent bundle files ({workdir}/cairo-audit-agent-{1,2,3,4}-bundle.md) in a single command. Each bundle concatenates:

• all in-scope .cairo files (with ### path headers and fenced code blocks),
• {refs_root}/judging.md,
• {refs_root}/structured-findings.md,
• {refs_root}/report-formatting.md,
• {refs_root}/attack-vectors/attack-vectors-N.md (one per agent — only the attack-vectors file differs).

Print line counts per bundle. Example command:

Before running this command, substitute placeholders ({refs_root}, {repo-root}) with the concrete paths resolved in Turn 1.

REFS="{refs_root}"
SRC="{repo-root}"
WORKDIR="{workdir}"
IN_SCOPE="$WORKDIR/cairo-audit-files.txt"
set -euo pipefail

build_code_block() {
  while IFS= read -r f; do
    [ -z "$f" ] && continue
    REL=$(echo "$f" | sed "s|$SRC/||")
    echo "### $REL"
    echo '```cairo'
    cat "$f"
    echo '```'
    echo ""
  done  "$WORKDIR/cairo-audit-agent-$i-bundle.md"
  echo "Bundle $i: $(wc -l ` in execution trace and continue.
- If unavailable/offline, continue and mark this stage as `SKIPPED` in execution trace.
- Keep query commands/examples aligned with `threat-intel-sources.md`.

Threat-intel usage rules:

- Intel is a prioritization aid only.
- Never report a finding from intel alone.
- Every reported finding must still pass the local FP gate with a concrete in-scope path.

**Turn 3 — Spawn.** Use foreground Agent tool calls only (do NOT use `run_in_background`).

- Always spawn Agents 1–4 in parallel.
- In **deep** mode, use adaptive fanout:
  - If the largest in-scope file is `1800` lines: 600 seconds (Wave B regime, very large bundles)
- Retry failed/stalled specialists serially (one at a time) to reduce transport saturation.
- If retry still fails, treat the specialist as unavailable.

Integrity gate (for hosts where deep-mode enforcement is enabled):
- In **deep** mode, if any required specialist agent (1-4 or 5) cannot be spawned or returns unavailable, treat the run as failed unless `--allow-degraded` is explicitly present.
- On failure, stop before findings and print `CAUD-006` with a one-line reason plus host remediation hints.
- If a specialist output is malformed (not `No findings.` and not valid finding blocks), rerun that specialist once; if still malformed, treat it as unavailable.
- When `--strict-models` is set, treat model fallback as unavailable capability and enforce the same fail-closed behavior (`CAUD-009`) unless `--allow-degraded` is explicitly present.
**Turn 4 — Report.** Merge all agent results and emit the report in canonical order:

0. If `{skill_root}/scripts/quality/structured_report.py` exists, render through it with all `{workdir}/cairo-audit-agent-*-findings.json` files, the preflight JSON path, `{workdir}/cairo-audit-files.txt`, the resolved execution-integrity value, and `--proven-only` when that flag is active. Use its Markdown output as the report body.
1. Deduplicate by root cause (keep the higher-confidence version, merge broader attack path details; on confidence tie keep higher priority, then more complete path evidence).
2. Apply evidence tags per `references/judging.md` Evidence Tags section:
   - Validate every finding has `[CODE-TRACE]`; if a source agent omitted it, add `[CODE-TRACE]` during merge normalization.
   - Add `[PREFLIGHT-HIT]` if the deterministic preflight flagged the same class or entry point.
   - Add `[CROSS-AGENT]` if 2+ agents independently reported the same root cause before deduplication.
   - Add `[ADVERSARIAL]` if Agent 5 discovered or confirmed the finding.
3. Findings with only `[CODE-TRACE]` (no additional tags) are valid but lower-signal; reviewers use the Evidence column in Findings Index to prioritize review order.
4. Sort findings by priority (`P0` first); within each priority tier sort by confidence (highest first).
5. Re-number findings sequentially starting at `1`.
6. Insert one **Below Confidence Threshold** separator row in the findings index immediately before the first finding with confidence  You are not using the latest version. Update via your install method (e.g. `git pull` or reinstall the plugin) for best security coverage.

Then continue normally. If the fetch fails (offline, timeout), skip silently.

Use this command for the remote check:

```bash
curl -sf --connect-timeout 5 --max-time 10 https://raw.githubusercontent.com/keep-starknet-strange/starknet-agentic/main/skills/cairo-auditor/VERSION

Limitations

• Works best on codebases under 5,000 lines of Cairo. Past that, triage accuracy and mid-bundle recall degrade.
• For large codebases, run per-module by passing explicit file arguments ($filename ...) rather than full-repo.
• AI catches pattern-based vulnerabilities reliably but cannot reason about novel economic exploits, cross-proto

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: keep-starknet-strange
• Source: keep-starknet-strange/starknet-agentic
• License: MIT
• Homepage: https://starknet-agentic.com

Install and usage instructions live in the source repository linked above.