Merge pull request #43 from onflow/claude/gracious-goldberg-7dc0ec

Add local security scanning (static analysis + AI audit)

Author: peterargue

.gitignore

@@ -0,0 +1,11 @@
+# Local security scan output — NEVER commit. This repo is public and the
+# contracts hold real value; findings must stay local.
+/security/reports/
+
+# Local Claude Code state and vendored audit skills (security/vendor-skills.sh).
+# This is a public repo — keep all local Claude artifacts out of it.
+/.claude/
+
+# Aderyn default report locations
+/report.md
+/solidity/report.md

Makefile

@@ -12,3 +12,78 @@ solidity-build:
 .PHONY: solidity-test
 solidity-test:
 	cd solidity && FOUNDRY_PROFILE=ci forge test -vvv
+
+# ---------------------------------------------------------------------------
+# Security scanning (LOCAL ONLY, containerized)
+#
+# This repository is PUBLIC and the contracts hold real value. Security scans
+# are intentionally NOT run in CI — public Actions logs, issues, PR comments,
+# and artifacts would leak live vulnerabilities. Every scanner runs inside a
+# locked-down Docker container (see security/docker/) so untrusted analysis —
+# especially community AI skills — cannot read host files or secrets:
+#   static tier -> no network at all
+#   AI tier     -> egress restricted to the Anthropic API; needs a Claude
+#                  credential (see Credentials in docs/security-scanning.md)
+# Reports stay in security/reports/ (gitignored) and are never committed/posted.
+#
+# Requires Docker. Build the image once with `make security-build`.
+# ---------------------------------------------------------------------------
+
+SKILL ?= solidity-auditor
+
+# Run all security scans (local only).
+.PHONY: security
+security: security-build security-static security-ai
+
+# Build the pinned scanner toolchain image.
+.PHONY: security-build
+security-build:
+	./security/scan.sh build
+
+# Store your Claude Code OAuth token in the macOS Keychain (one-time, per-dev).
+.PHONY: security-set-token
+security-set-token:
+	./security/scan.sh set-token
+
+# Verify a Claude credential is available (preflight for the AI tier).
+.PHONY: security-check-cred
+security-check-cred:
+	./security/scan.sh check-cred
+
+# Run all non-AI static analyzers (sealed, no network).
+.PHONY: security-static
+security-static: security-slither security-aderyn security-solhint
+
+.PHONY: security-slither
+security-slither:
+	./security/scan.sh slither
+
+.PHONY: security-aderyn
+security-aderyn:
+	./security/scan.sh aderyn
+
+.PHONY: security-solhint
+security-solhint:
+	./security/scan.sh solhint
+
+.PHONY: security-ai
+security-ai: security-check-cred security-ai-review security-ai-audit security-ai-skills security-ai-summarize
+
+# AI reviews (need a Claude credential — see docs). Output is local + gitignored.
+.PHONY: security-ai-review
+security-ai-review:
+	./security/scan.sh ai-review
+
+.PHONY: security-ai-audit
+security-ai-audit:
+	./security/scan.sh ai-audit
+
+# Skills-based audit. Override the skill: `make security-ai-skills SKILL=scv-scan`
+.PHONY: security-ai-skills
+security-ai-skills:
+	./security/scan.sh ai-skills $(SKILL)
+
+# Summarize all reports in security/reports/ by severity (stdout only).
+.PHONY: security-ai-summarize
+security-ai-summarize:
+	./security/scan.sh summarize

docs/security-scanning.md

@@ -0,0 +1,119 @@
+# Security Scanning
+
+Local, containerized security scanning for the Solidity codebase, set up per the
+[Continuous Security Testing/Auditing](https://www.notion.so/3521aee1232480958886c3666758b9f0)
+recommendation. Supplementary to formal audits, not a replacement.
+
+## Threat model: why local + containerized + pinned
+
+This repository is **public** and the contracts **hold real value**, which drives
+two distinct controls:
+
+1. **No public CI.** Every place a GitHub Action surfaces output is public on a
+   public repo — issues, PR comments, **Actions logs, and artifacts**. Scanners
+   print findings to the log, so running them in CI would leak live, unfixed
+   vulnerabilities. All scanning runs locally; reports go to `security/reports/`
+   (gitignored) and are never committed or posted.
+
+2. **The AI skills are an untrusted supply chain.** The community skill repos are
+   third-party and community-writable, and their content is loaded as
+   *instructions* into a tool-enabled agent. Two mitigations:
+   - **Pinning (integrity):** `security/vendor-skills.sh` checks out exact,
+     reviewed commit SHAs and fails closed if a commit is gone — so a poisoned
+     upstream commit can't silently run. Bump a SHA only after reviewing the diff.
+   - **Containment:** every scanner runs inside a locked-down Docker container so
+     a malicious skill can't read host files/secrets or exfiltrate:
+     - **Static tier** (Slither/Aderyn/Solhint): `--network none`, `--cap-drop ALL`,
+       source mounted **read-only**. Fully airtight.
+     - **AI tier** (review/audit/skills/summarize): egress restricted to the
+       **Anthropic API only** (`security/docker/init-firewall.sh`),
+       the Claude credential is the only secret present, source mounted read-only.
+
+Pinning + container = integrity + containment. Note what containment does **not**
+fix: a poisoned skill can still produce dishonest *output* (e.g. hide a finding),
+so AI results stay advisory and should be cross-checked against the static tools.
+
+## Prerequisites
+
+- **Docker.** Build the pinned toolchain image once:
+  ```sh
+  make security-build
+  ```
+  The image (`security/docker/Dockerfile`) bundles Foundry, Slither, Aderyn,
+  Solhint, and the Claude CLI at pinned versions, with `solc` pre-cached so the
+  static tier compiles with no network.
+- **AI tier only:** a credential, resolved at run time — no permanent env var
+  needed. See [Credentials](#credentials) below. The static tier needs nothing.
+
+## Credentials
+
+The AI tier authenticates with a **Claude Code OAuth token** (tied to your own
+Claude subscription — no separate API billing). The token is **per-developer**,
+so each person stores their own; there is no shared key. It is fetched at run
+time and injected into the sealed container by reference (`-e NAME`, never on the
+command line), and is never written to disk in the repo or kept in your shell.
+
+One-time setup, per developer (default: macOS Keychain, zero extra tooling):
+
+```sh
+claude setup-token       # mint a long-lived token tied to your account
+make security-set-token  # paste it once; stored encrypted in your login Keychain
+```
+
+After that, `make security-ai-*` fetches it automatically.
+
+Credential resolution (precedence, highest first):
+
+1. `CLAUDE_CODE_OAUTH_TOKEN` in the environment → used directly (CI / power users).
+2. `ANTHROPIC_API_KEY` in the environment → used directly.
+3. **1Password**, *only if* `FCM_OP_TOKEN_REF='op://<your-vault>/<item>/credential'`
+   is set (use your own/Private vault — the token is personal, not shared).
+4. **macOS Keychain** (the default) — what `make security-set-token` writes.
+
+## Make targets
+
+| Target | Tier | Notes |
+|--------|------|-------|
+| `make security` | all | everything: build + all static + all AI |
+| `make security-build` | — | build the scanner image (run once / after updates) |
+| `make security-set-token` | — | store your Claude OAuth token in the Keychain (one-time) |
+| `make security-check-cred` | — | verify a Claude credential is available (AI-tier preflight) |
+| `make security-static` | static | all static analyzers: Slither + Aderyn + Solhint |
+| `make security-slither` | static | report → `security/reports/slither-report-<ts>.txt` |
+| `make security-aderyn` | static | report → `security/reports/aderyn-report-<ts>.md` |
+| `make security-solhint` | static | report → `security/reports/solhint-report-<ts>.txt` |
+| `make security-ai` | AI | all AI tiers: review + audit + skills + summarize |
+| `make security-ai-review` | AI | reviews current branch changes |
+| `make security-ai-audit` | AI | full-codebase audit |
+| `make security-ai-skills` | AI | `SKILL=<name>`; vendors pinned skills, then audits |
+| `make security-ai-summarize` | AI | rolls up all reports by severity to stdout |
+
+## How it fits together
+
+- **Prompts** live in `security/prompts/` and encode the vault/curator threat
+  model. They forbid creating issues/comments or writing findings to tracked files.
+- **`security/scan.sh`** is the single dispatcher: it builds the image on demand
+  and runs each tool with the right isolation flags (static = no network, AI =
+  API-only egress + key).
+- **`security/docker/`** holds the `Dockerfile`, the two entrypoints
+  (`entry-static.sh`, `entry-ai.sh`), and the egress allowlist
+  (`init-firewall.sh`).
+- **`security/vendor-skills.sh`** clones the pinned skill SHAs on the host, into a
+  gitignored `.claude/skills/`, which is mounted read-only into the sealed
+  container (so the container needs no GitHub egress).
+
+## Reports
+
+All reports are written under `security/reports/` (gitignored). **Do not commit or
+share these files** — they may describe live, unfixed vulnerabilities. AI is
+non-deterministic; run audits more than once and cross-check.
+
+## Updating a skill
+
+Review the upstream diff, then update the corresponding `*_SHA` in
+`security/vendor-skills.sh`. Never point at a floating branch.
+
+## Config files (safe to commit)
+
+- `solidity/slither.config.json` — filters out `lib/`, `test/`, `script/`.
+- `solidity/.solhint.json`, `solidity/.solhintignore` — Solhint rules/ignores.

security/docker/Dockerfile

@@ -0,0 +1,71 @@
+# Security scanning toolchain — all tools pinned, solc pre-cached for offline use.
+#
+# Built once (`make security-build`) and reused by every scan. The static tier
+# runs this image with `--network none`; the AI tier runs it with egress
+# restricted to the Anthropic API only (see security/docker/init-firewall.sh).
+#
+# Tools are pinned to exact versions so a rebuild is reproducible and a poisoned
+# upstream release can't silently change what runs.
+
+FROM node:24-bookworm-slim
+
+# Pinned tool versions ------------------------------------------------------
+ARG SLITHER_VERSION=0.11.5
+ARG SOLHINT_VERSION=6.2.1
+ARG ADERYN_VERSION=0.6.8
+ARG CLAUDE_VERSION=2.1.146
+ARG SOLC_VERSION=0.8.35
+ARG FOUNDRY_VERSION=stable
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    FOUNDRY_DIR=/root/.foundry \
+    PATH=/root/.foundry/bin:/opt/slither/bin:/usr/local/bin:$PATH
+
+# Base packages: python (slither), git, curl, jq, and the firewall tooling
+# (iptables/ipset/dnsutils) used only by the AI tier's egress allowlist.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ca-certificates curl git jq xz-utils \
+        python3 python3-venv python3-pip \
+        iptables ipset dnsutils \
+    && rm -rf /var/lib/apt/lists/*
+
+# Slither (isolated venv) ---------------------------------------------------
+RUN python3 -m venv /opt/slither \
+    && /opt/slither/bin/pip install --no-cache-dir "slither-analyzer==${SLITHER_VERSION}"
+
+# Solhint + Claude Code CLI (pinned) ---------------------------------------
+RUN npm install -g "solhint@${SOLHINT_VERSION}" "@anthropic-ai/claude-code@${CLAUDE_VERSION}"
+
+# Aderyn (pinned release binary, arm64 linux) ------------------------------
+RUN curl -fsSL "https://github.com/Cyfrin/aderyn/releases/download/aderyn-v${ADERYN_VERSION}/aderyn-aarch64-unknown-linux-gnu.tar.xz" \
+        -o /tmp/aderyn.tar.xz \
+    && mkdir -p /tmp/aderyn-extract \
+    && tar -xJf /tmp/aderyn.tar.xz -C /tmp/aderyn-extract \
+    && install -m 0755 "$(find /tmp/aderyn-extract -type f -name aderyn | head -1)" /usr/local/bin/aderyn \
+    && rm -rf /tmp/aderyn.tar.xz /tmp/aderyn-extract \
+    && aderyn --version
+
+# Foundry (forge) -----------------------------------------------------------
+RUN curl -L https://foundry.paradigm.xyz | bash \
+    && /root/.foundry/bin/foundryup --install "${FOUNDRY_VERSION}" \
+    && forge --version
+
+# Pre-cache solc so the static tier can compile with no network. Warming a
+# throwaway project forces foundry-compilers to download solc into ~/.svm,
+# which Slither (via crytic-compile/forge) and Aderyn both reuse offline.
+RUN mkdir -p /tmp/warm/src \
+    && printf '[profile.default]\nsolc_version = "%s"\n' "${SOLC_VERSION}" > /tmp/warm/foundry.toml \
+    && printf 'pragma solidity %s; contract Warm {}' "${SOLC_VERSION}" > /tmp/warm/src/Warm.sol \
+    && (cd /tmp/warm && forge build) \
+    && rm -rf /tmp/warm
+
+# Make forge/slither resolvable regardless of shell/PATH handling.
+RUN ln -sf /root/.foundry/bin/forge /usr/local/bin/forge \
+    && ln -sf /root/.foundry/bin/cast /usr/local/bin/cast \
+    && ln -sf /opt/slither/bin/slither /usr/local/bin/slither
+
+# Entrypoints + egress firewall (copied last to keep heavy layers cached).
+COPY entry-static.sh entry-ai.sh init-firewall.sh /usr/local/bin/
+RUN chmod +x /usr/local/bin/entry-static.sh /usr/local/bin/entry-ai.sh /usr/local/bin/init-firewall.sh
+
+WORKDIR /work

security/docker/entry-ai.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+#
+# Entrypoint for the AI tier. Brings up the egress allowlist (api.anthropic.com
+# only), then copies the read-only source into a writable workdir and runs the
+# requested command. The only secret in the container is the Claude credential
+# (CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY), and the only reachable network
+# destination is the Anthropic API.
+
+set -euo pipefail
+
+# Set NO_FIREWALL=1 only for local debugging — never in normal use.
+if [ "${SECURITY_NO_FIREWALL:-0}" != "1" ]; then
+  /usr/local/bin/init-firewall.sh
+fi
+
+# Keep Claude's traffic to the Anthropic API only. Without this, it would attempt
+# telemetry / auto-update / error-reporting calls that the egress allowlist
+# blocks, stalling the run on connection timeouts.
+export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
+export DISABLE_AUTOUPDATER=1
+export DISABLE_TELEMETRY=1
+export DISABLE_ERROR_REPORTING=1
+export DISABLE_BUG_COMMAND=1
+
+cp -a /repo/. /work/
+cd /work
+
+# Heads-up on stderr (not stdout, so it stays out of the saved report). Claude in
+# headless mode prints nothing until it finishes.
+echo ">> Scan running in a sealed container. Claude produces no output until it" >&2
+echo "   finishes — this is normal and may take a couple of minutes. Please wait." >&2
+
+exec "$@"

security/docker/entry-static.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+#
+# Entrypoint for the static tier. The host source is mounted read-only at /repo;
+# copy it into a writable workdir so Foundry/Slither/Aderyn can compile without
+# touching the host, then run the requested command. No network is available.
+
+set -euo pipefail
+
+cp -a /repo/. /work/
+cd /work
+exec "$@"

security/docker/init-firewall.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+#
+# Egress allowlist for the AI tier: permit ONLY DNS + HTTPS to the Anthropic API,
+# default-drop everything else. Requires NET_ADMIN. Run once at container start.
+#
+# The scan agent cannot run arbitrary shell (its tool allowlist excludes Bash
+# beyond git/forge), so a poisoned skill cannot undo these rules from inside the
+# agent. This caps exfiltration: even if a skill tries to phone home, there is no
+# route off-box except to api.anthropic.com.
+
+set -euo pipefail
+
+iptables -F
+iptables -P INPUT DROP
+iptables -P FORWARD DROP
+iptables -P OUTPUT DROP
+
+# Loopback
+iptables -A INPUT  -i lo -j ACCEPT
+iptables -A OUTPUT -o lo -j ACCEPT
+
+# Established/related return traffic
+iptables -A INPUT  -m state --state ESTABLISHED,RELATED -j ACCEPT
+iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
+
+# DNS (needed to resolve the API host)
+iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
+iptables -A OUTPUT -p tcp --dport 53 -j ACCEPT
+
+# Allow HTTPS only to the resolved Anthropic API IPs
+# Progress messages go to stderr so they don't pollute the report (captured from
+# stdout).
+allow_host() {
+  local host="$1" ip
+  for ip in $(getent ahostsv4 "$host" | awk '{print $1}' | sort -u); do
+    iptables -A OUTPUT -p tcp -d "$ip" --dport 443 -j ACCEPT
+    echo "  allow $host -> $ip:443" >&2
+  done
+}
+
+echo ">> egress firewall: allowing api.anthropic.com only" >&2
+allow_host api.anthropic.com
+
+# Reject (not silently drop) any other egress so a blocked connection fails fast
+# instead of hanging on a timeout. The policy DROP above remains a backstop.
+iptables -A OUTPUT -p tcp -j REJECT --reject-with tcp-reset
+iptables -A OUTPUT -j REJECT --reject-with icmp-port-unreachable
+
+echo ">> egress firewall active (api.anthropic.com only; others rejected)" >&2