anchor-audit 0.1.0

package/dist/reporter.js

@@ -0,0 +1,177 @@
+/**
+ * Render the audit report as markdown (default) or JSON.
+ *
+ * Auto-save behaviour (always on):
+ *   Every run writes a timestamped file to reports/<project>-<timestamp>.<ext>
+ *   so no audit is ever lost.  Pass --output to additionally write to a
+ *   specific path.  Stdout is printed when --output is not supplied.
+ *
+ * JSON output schema
+ * ------------------
+ * {
+ *   "version": "0.1.0",
+ *   "date": "YYYY-MM-DD",
+ *   "metadata": { ...AuditMetadata },
+ *   "summary": { "critical": N, "high": N, "medium": N, "low": N, "total": N },
+ *   "findings": [ ...Finding[] ]
+ * }
+ */
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import chalk from "chalk";
+import { SEVERITY_ORDER } from "./auditor.js";
+const VERSION = "0.1.0";
+export function countBySeverity(findings) {
+    const c = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const f of findings)
+        c[f.severity]++;
+    return c;
+}
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+export function renderJson(findings, meta) {
+    const counts = countBySeverity(findings);
+    const report = {
+        version: VERSION,
+        date: new Date().toISOString().slice(0, 10),
+        ...(meta ? { metadata: meta } : {}),
+        summary: { ...counts, total: findings.length },
+        findings,
+    };
+    return JSON.stringify(report, null, 2);
+}
+// ---------------------------------------------------------------------------
+// Markdown output
+// ---------------------------------------------------------------------------
+const SEV_LABEL = {
+    critical: "CRITICAL",
+    high: "HIGH",
+    medium: "MEDIUM",
+    low: "LOW",
+};
+function renderMetadataBlock(meta) {
+    const rows = [
+        ["Date", meta.date],
+        ["Time", meta.time],
+        ["Model", meta.model],
+        ["Provider", meta.provider],
+        ["Effort", meta.effort],
+        ["CLI Version", `v${meta.cliVersion}`],
+        ["Project", meta.project],
+    ];
+    if (meta.gitBranch)
+        rows.push(["Git Branch", meta.gitBranch]);
+    if (meta.gitCommit)
+        rows.push(["Git Commit", meta.gitCommit]);
+    rows.push(["OS", meta.os]);
+    rows.push(["Duration", formatDuration(meta.durationMs)]);
+    rows.push(["Files Analyzed", String(meta.totalFiles)]);
+    rows.push(["Total Findings", String(meta.totalFindings)]);
+    const lines = ["## Audit Metadata", "", "| Field | Value |", "|-------|-------|"];
+    for (const [k, v] of rows)
+        lines.push(`| ${k} | ${v} |`);
+    return lines.join("\n");
+}
+export function renderMarkdown(findings, meta) {
+    const date = meta?.date ?? new Date().toISOString().slice(0, 10);
+    const counts = countBySeverity(findings);
+    const lines = [];
+    lines.push(`# Anchor Audit Report`);
+    lines.push(`Generated by anchor-audit v${VERSION} on ${date}`);
+    lines.push("");
+    if (meta) {
+        lines.push(renderMetadataBlock(meta));
+        lines.push("");
+    }
+    lines.push("## Summary");
+    lines.push("");
+    lines.push("| Severity | Count |");
+    lines.push("|----------|-------|");
+    for (const sev of ["critical", "high", "medium", "low"]) {
+        lines.push(`| ${sev.charAt(0).toUpperCase() + sev.slice(1).padEnd(7)} | ${counts[sev]} |`);
+    }
+    lines.push(`| **Total** | **${findings.length}** |`);
+    lines.push("");
+    if (findings.length === 0) {
+        lines.push("> No findings. Always verify manually before deploying to mainnet.");
+        return lines.join("\n");
+    }
+    lines.push("## Findings");
+    lines.push("");
+    const bySev = ["critical", "high", "medium", "low"].flatMap((s) => findings.filter((f) => f.severity === s));
+    for (const f of bySev) {
+        const loc = f.line != null ? `${f.file}:${f.line}` : f.file;
+        lines.push(`### [${SEV_LABEL[f.severity]}] Rule ${f.ruleId}: ${f.title}`);
+        lines.push("");
+        lines.push(`**File:** \`${loc}\``);
+        lines.push("");
+        lines.push(`**Description:** ${f.description}`);
+        lines.push("");
+        if (f.vulnerableCode.trim()) {
+            lines.push("**Vulnerable code:**");
+            lines.push("```rust");
+            lines.push(f.vulnerableCode.trim());
+            lines.push("```");
+            lines.push("");
+        }
+        lines.push(`**Recommendation:** ${f.recommendation}`);
+        lines.push("");
+        lines.push(`**Reference:** [rules/${f.ruleId}-${f.ruleName}.md](rules/${f.ruleId}-${f.ruleName}.md)`);
+        lines.push("");
+        lines.push("---");
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Auto-save to reports/
+// ---------------------------------------------------------------------------
+function autoSavePath(project, format) {
+    const ext = format === "json" ? "json" : "md";
+    // Replace colons with dashes for filesystem-safe filenames.
+    const ts = new Date().toISOString().replace(/:/g, "-").replace(/\..+$/, "Z");
+    return join("reports", `${project}-${ts}.${ext}`);
+}
+function writeAutoSave(content, project, format) {
+    mkdirSync("reports", { recursive: true });
+    const savePath = autoSavePath(project, format);
+    writeFileSync(savePath, content, "utf8");
+    return savePath;
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+export async function renderReport(findings, options, meta) {
+    const output = options.format === "json"
+        ? renderJson(findings, meta)
+        : renderMarkdown(findings, meta);
+    const project = meta?.project ?? "audit";
+    // Always auto-save a timestamped copy to reports/.
+    const savedPath = writeAutoSave(output, project, options.format);
+    if (options.output) {
+        writeFileSync(options.output, output, "utf8");
+    }
+    const counts = countBySeverity(findings);
+    const label = counts.critical > 0
+        ? chalk.red(`${counts.critical} critical`)
+        : counts.high > 0
+            ? chalk.yellow(`${counts.high} high`)
+            : chalk.green("clean");
+    process.stderr.write(`Saved report → ${savedPath}` +
+        (options.output ? ` (also → ${options.output})` : "") +
+        ` — ${label}, ${findings.length} total finding(s)\n`);
+    // Print to stdout when no --output flag (terminal viewing).
+    if (!options.output) {
+        process.stdout.write(output + "\n");
+    }
+    // Exit code 1 when any critical or high finding is present.
+    if (counts.critical > 0 || counts.high > 0) {
+        process.exitCode = 1;
+    }
+}
+// Re-export SEVERITY_ORDER so tests can use it without importing from auditor
+export { SEVERITY_ORDER };
+//# sourceMappingURL=reporter.js.map

package/dist/reporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reporter.js","sourceRoot":"","sources":["../src/reporter.ts"],"names":[],"mappings":"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"}

package/dist/rules-loader.d.ts

@@ -0,0 +1,12 @@
+import type { Severity } from "./index.js";
+export interface Rule {
+    /** Zero-padded three-digit ID, e.g. "001". */
+    id: string;
+    /** Slug from the filename, e.g. "missing-signer-check". */
+    name: string;
+    severity: Severity;
+    category: string;
+    /** Full markdown content — sent to the model as audit context. */
+    content: string;
+}
+export declare function loadRules(ruleIdsArg?: string): Promise<Rule[]>;

package/dist/rules-loader.js

@@ -0,0 +1,65 @@
+/**
+ * Loads the rule catalog from the `rules/` directory and parses each rule's
+ * ID, title, severity, and category from its markdown.
+ *
+ * Resolution order (first that exists wins):
+ *   1. repo layout  — <dist>/../../rules   (cli/dist/../../rules)
+ *   2. npm install  — <dist>/../rules      (dist/../rules)
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+function findRulesDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(here, "..", "..", "rules"), // repo: cli/dist/../../rules
+        join(here, "..", "rules"), // installed: cli/dist/../rules
+    ];
+    for (const c of candidates) {
+        if (existsSync(join(c, "INDEX.md")))
+            return c;
+    }
+    throw new Error(`Cannot locate rules/ directory. Tried:\n` +
+        candidates.map((c) => `  ${c}`).join("\n") +
+        `\nRun anchor-audit from the repo root or reinstall the package.`);
+}
+function parseSeverity(content, file) {
+    const m = content.match(/\*\*Severity:\*\*\s*(Critical|High|Medium|Low)/i);
+    if (!m?.[1])
+        throw new Error(`No **Severity:** line found in ${file}`);
+    return m[1].toLowerCase();
+}
+function parseCategory(content) {
+    const m = content.match(/\*\*Category:\*\*\s*(.+)/);
+    return m?.[1]?.trim() ?? "Unknown";
+}
+export async function loadRules(ruleIdsArg) {
+    const rulesDir = findRulesDir();
+    const requested = ruleIdsArg
+        ? new Set(ruleIdsArg.split(",").map((s) => s.trim().padStart(3, "0")))
+        : null;
+    const files = readdirSync(rulesDir)
+        .filter((f) => /^\d{3}-.+\.md$/.test(f))
+        .sort();
+    const rules = [];
+    for (const file of files) {
+        const id = file.slice(0, 3);
+        if (requested && !requested.has(id))
+            continue;
+        const content = readFileSync(join(rulesDir, file), "utf8");
+        rules.push({
+            id,
+            name: file.slice(4, -3), // strip "NNN-" prefix and ".md" suffix
+            severity: parseSeverity(content, file),
+            category: parseCategory(content),
+            content,
+        });
+    }
+    if (rules.length === 0) {
+        throw new Error(requested
+            ? `No rules found for IDs: ${ruleIdsArg}`
+            : `No rule files found in ${rulesDir}`);
+    }
+    return rules;
+}
+//# sourceMappingURL=rules-loader.js.map

package/dist/rules-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules-loader.js","sourceRoot":"","sources":["../src/rules-loader.ts"],"names":[],"mappings":"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"}

package/dist/scanner.d.ts

@@ -0,0 +1,6 @@
+export interface SourceFile {
+    /** Path relative to the audit target root. */
+    path: string;
+    content: string;
+}
+export declare function scanProgram(targetPath: string): Promise<SourceFile[]>;

package/dist/scanner.js

@@ -0,0 +1,42 @@
+/**
+ * File collection for the audit target.
+ *
+ * Recursively walks the target directory, collects every `.rs` source file,
+ * and warns (but does not fail) when the layout doesn't look like an Anchor
+ * program (no `lib.rs` found).
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+const SKIP_DIRS = new Set(["target", "node_modules", ".git", ".anchor"]);
+export async function scanProgram(targetPath) {
+    if (!existsSync(targetPath)) {
+        throw new Error(`Target path does not exist: ${targetPath}`);
+    }
+    if (!statSync(targetPath).isDirectory()) {
+        throw new Error(`Target must be a directory: ${targetPath}`);
+    }
+    const files = [];
+    collectRs(targetPath, targetPath, files);
+    if (files.length === 0) {
+        throw new Error(`No .rs source files found under: ${targetPath}`);
+    }
+    const hasLibRs = files.some((f) => f.path.endsWith("lib.rs"));
+    if (!hasLibRs) {
+        process.stderr.write(`warning: no lib.rs found under ${targetPath} — may not be an Anchor program\n`);
+    }
+    return files;
+}
+function collectRs(base, dir, out) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            if (SKIP_DIRS.has(entry.name))
+                continue;
+            collectRs(base, join(dir, entry.name), out);
+        }
+        else if (entry.isFile() && entry.name.endsWith(".rs")) {
+            const full = join(dir, entry.name);
+            out.push({ path: relative(base, full), content: readFileSync(full, "utf8") });
+        }
+    }
+}
+//# sourceMappingURL=scanner.js.map

package/dist/scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanner.js","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAQ3C,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;AAEzE,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,UAAkB;IAClD,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,+BAA+B,UAAU,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,+BAA+B,UAAU,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,SAAS,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IAEzC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,oCAAoC,UAAU,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC9D,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,kCAAkC,UAAU,mCAAmC,CAChF,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,SAAS,CAAC,IAAY,EAAE,GAAW,EAAE,GAAiB;IAC7D,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAC9D,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC;gBAAE,SAAS;YACxC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QAC9C,CAAC;aAAM,IAAI,KAAK,CAAC,MAAM,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACnC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "anchor-audit",
+  "version": "0.1.0",
+  "description": "AI-driven security audit CLI for Anchor programs on Solana",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "anchor-audit": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "rules"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "rm -rf ./rules && cp -r ../rules ./rules && npm run build",
+    "postpublish": "rm -rf ./rules"
+  },
+  "keywords": [
+    "solana",
+    "anchor",
+    "security",
+    "audit",
+    "claude",
+    "smart-contracts"
+  ],
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "chalk": "^5.4.0",
+    "commander": "^13.0.0",
+    "dotenv": "^17.4.2",
+    "openai": "^4.77.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  }
+}

package/rules/001-missing-signer-check.md

@@ -0,0 +1,57 @@
+# Rule 001: Missing Signer Check
+
+**Severity:** Critical
+**Category:** Account validation
+
+## Description
+An instruction that performs a privileged action (changing an authority, moving funds, mutating user state) accepts the relevant authority account without requiring its signature. Comparing the account's public key against a stored authority proves the *address* matches, but not that the holder of that key approved the transaction — anyone can pass any public key as a read-only account.
+
+## Vulnerable pattern
+```rust
+#[derive(Accounts)]
+pub struct UpdateAuthority<'info> {
+    #[account(mut)]
+    pub vault: Account<'info, Vault>,
+    /// CHECK: current vault authority
+    pub authority: AccountInfo<'info>,
+}
+
+pub fn update_authority(ctx: Context<UpdateAuthority>, new_authority: Pubkey) -> Result<()> {
+    // Key equality only — no signature required
+    require_keys_eq!(ctx.accounts.vault.authority, ctx.accounts.authority.key());
+    ctx.accounts.vault.authority = new_authority;
+    Ok(())
+}
+```
+
+## Why this is dangerous
+An attacker submits the transaction themselves, passing the legitimate authority's public key as the `authority` account without its signature. The key-equality check passes, and the attacker rotates the vault authority to a key they control, then drains the vault through legitimate paths. This is the single most common Solana vulnerability class.
+
+## Fix pattern
+```rust
+#[derive(Accounts)]
+pub struct UpdateAuthority<'info> {
+    #[account(mut, has_one = authority)]
+    pub vault: Account<'info, Vault>,
+    pub authority: Signer<'info>, // Anchor enforces is_signer
+}
+
+pub fn update_authority(ctx: Context<UpdateAuthority>, new_authority: Pubkey) -> Result<()> {
+    ctx.accounts.vault.authority = new_authority;
+    Ok(())
+}
+```
+
+## Detection heuristic
+- Accounts named `authority`, `admin`, `owner`, `signer`, `user`, or `payer` typed as `AccountInfo` or `UncheckedAccount` instead of `Signer`
+- Handlers that mutate state or move lamports/tokens where no account in the context is a `Signer`
+- Key comparisons (`require_keys_eq!`, `==` on `key()`) against a stored authority with no accompanying signature requirement
+- In non-Anchor code paths: missing `if !account.is_signer { return Err(...) }`
+
+## References
+- Neodyme — Solana common pitfalls: missing signer check (https://neodyme.io/en/blog/solana_common_pitfalls/)
+- Coral sealevel-attacks — 0-signer-authorization (https://github.com/coral-xyz/sealevel-attacks/tree/master/programs/0-signer-authorization)
+- Solana program security course — signer authorization (https://solana.com/developers/courses/program-security/signer-auth)
+
+## Real-world exploits (if any)
+No single headline exploit; missing signer checks appear repeatedly in public audit reports (OtterSec, Neodyme, Sec3) as critical findings caught pre-deployment.

package/rules/002-missing-owner-check.md

@@ -0,0 +1,53 @@
+# Rule 002: Missing Owner Check
+
+**Severity:** Critical
+**Category:** Account validation
+
+## Description
+An account is read or trusted without verifying which program owns it. On Solana, only an account's owner program can modify its data, but *anyone* can create an account with arbitrary contents owned by a different program (or the System Program) and pass it into your instruction. If the program deserializes account data without an owner check, an attacker can substitute a forged account with attacker-chosen field values.
+
+## Vulnerable pattern
+```rust
+#[derive(Accounts)]
+pub struct Withdraw<'info> {
+    /// CHECK: config account
+    pub config: AccountInfo<'info>,
+    pub admin: Signer<'info>,
+}
+
+pub fn withdraw(ctx: Context<Withdraw>, amount: u64) -> Result<()> {
+    // Deserializes raw bytes — never checks config.owner
+    let config = Config::try_from_slice(&ctx.accounts.config.data.borrow())?;
+    require_keys_eq!(config.admin, ctx.accounts.admin.key());
+    // ... transfer `amount` out
+    Ok(())
+}
+```
+
+## Why this is dangerous
+The attacker creates their own account with the same byte layout as `Config`, sets `admin` to their own key, and passes it in. The deserialization succeeds, the admin check passes against the forged data, and the attacker withdraws funds. Every field read from an unverified account is attacker-controlled.
+
+## Fix pattern
+```rust
+#[derive(Accounts)]
+pub struct Withdraw<'info> {
+    // Account<'info, T> verifies owner == crate::ID and the discriminator
+    pub config: Account<'info, Config>,
+    pub admin: Signer<'info>,
+}
+```
+For accounts owned by another program, constrain explicitly: `#[account(owner = other_program::ID)]`.
+
+## Detection heuristic
+- `AccountInfo` / `UncheckedAccount` whose `.data` is borrowed and deserialized (`try_from_slice`, `AnchorDeserialize`, manual byte slicing)
+- No `owner =` constraint and no `require_keys_eq!(account.owner, ...)` before trusting the data
+- `/// CHECK:` comments that do not explain a real validation performed elsewhere
+- Raw-Solana handlers missing `if account.owner != program_id` before reads
+
+## References
+- Neodyme — Solana common pitfalls: missing ownership check (https://neodyme.io/en/blog/solana_common_pitfalls/)
+- Coral sealevel-attacks — 2-owner-checks (https://github.com/coral-xyz/sealevel-attacks/tree/master/programs/2-owner-checks)
+- Solana program security course — owner checks (https://solana.com/developers/courses/program-security/owner-checks)
+
+## Real-world exploits (if any)
+Crema Finance (July 2022, ~$8.8M): the attacker supplied a forged tick account that the program trusted without adequate validation of its provenance, enabling fee data manipulation and flash-loan-funded drains.

package/rules/003-missing-discriminator-check.md

@@ -0,0 +1,53 @@
+# Rule 003: Missing Discriminator Check (Type Cosplay)
+
+**Severity:** High
+**Category:** Account validation
+
+## Description
+Anchor prefixes every account with an 8-byte discriminator derived from the account type name, which distinguishes one account type from another at runtime. Code that deserializes account data manually — or uses types that skip the discriminator — allows an account of type A to be passed where type B is expected ("type cosplay"), as long as the byte layouts are compatible.
+
+## Vulnerable pattern
+```rust
+#[derive(Accounts)]
+pub struct AdminAction<'info> {
+    /// CHECK: admin config
+    pub admin_config: AccountInfo<'info>,
+    pub admin: Signer<'info>,
+}
+
+pub fn admin_action(ctx: Context<AdminAction>) -> Result<()> {
+    // UserAccount and AdminConfig are both { authority: Pubkey } —
+    // raw deserialization cannot tell them apart
+    let config = AdminConfig::try_from_slice(&ctx.accounts.admin_config.data.borrow())?;
+    require_keys_eq!(config.authority, ctx.accounts.admin.key());
+    Ok(())
+}
+```
+
+## Why this is dangerous
+An attacker initializes a low-privilege account type (e.g. their own `UserAccount`) whose layout matches the privileged type, then passes it where `AdminConfig` is expected. The deserialization succeeds with attacker-chosen field values, and the attacker passes authority checks meant for admins.
+
+## Fix pattern
+```rust
+#[derive(Accounts)]
+pub struct AdminAction<'info> {
+    // Account<'info, T> verifies the 8-byte discriminator and owner
+    pub admin_config: Account<'info, AdminConfig>,
+    pub admin: Signer<'info>,
+}
+```
+In manual deserialization, compare the first 8 bytes against `AdminConfig::DISCRIMINATOR` before parsing.
+
+## Detection heuristic
+- Manual `try_from_slice` / borsh deserialization of full account data without slicing off and checking the first 8 bytes
+- Account structs with identical or prefix-compatible field layouts used in the same program
+- `#[account]` types deserialized through `AccountInfo` instead of `Account<'info, T>`
+- Non-Anchor programs with multiple account types and no type/version tag byte
+
+## References
+- Coral sealevel-attacks — 3-type-cosplay (https://github.com/coral-xyz/sealevel-attacks/tree/master/programs/3-type-cosplay)
+- Solana program security course — type cosplay (https://solana.com/developers/courses/program-security/type-cosplay)
+- Helius — A Hitchhiker's Guide to Solana Program Security (https://www.helius.dev/blog/a-hitchhikers-guide-to-solana-program-security)
+
+## Real-world exploits (if any)
+No public headline exploit attributed solely to type cosplay; it is a recurring critical finding in public Sec3 and OtterSec audit reports of pre-launch programs.

package/rules/004-account-substitution.md

@@ -0,0 +1,54 @@
+# Rule 004: Account Substitution (Missing Data Matching)
+
+**Severity:** High
+**Category:** Account validation
+
+## Description
+Two or more accounts in an instruction are logically related (a user and their state account, a vault and its token account) but no constraint enforces that relationship. Each account may individually be valid — correct owner, correct type — yet belong to a different user or pool than intended. The attacker substitutes a *valid but wrong* account.
+
+## Vulnerable pattern
+```rust
+#[derive(Accounts)]
+pub struct ClaimRewards<'info> {
+    pub user: Signer<'info>,
+    // Valid UserState account — but nothing ties it to `user`
+    #[account(mut)]
+    pub user_state: Account<'info, UserState>,
+    #[account(mut)]
+    pub reward_vault: Account<'info, TokenAccount>,
+}
+
+pub fn claim_rewards(ctx: Context<ClaimRewards>) -> Result<()> {
+    let amount = ctx.accounts.user_state.pending_rewards; // someone else's rewards
+    // ... transfer to user
+    Ok(())
+}
+```
+
+## Why this is dangerous
+The attacker signs with their own key but passes another user's `UserState` (or a state account from a different pool with a better exchange rate). All type and owner checks pass, and the attacker claims rewards, balances, or withdrawal rights that belong to someone else.
+
+## Fix pattern
+```rust
+#[derive(Accounts)]
+pub struct ClaimRewards<'info> {
+    pub user: Signer<'info>,
+    #[account(mut, has_one = user)] // UserState.user must equal user.key()
+    pub user_state: Account<'info, UserState>,
+    #[account(mut, address = user_state.reward_vault)]
+    pub reward_vault: Account<'info, TokenAccount>,
+}
+```
+
+## Detection heuristic
+- Multiple typed accounts in one context with no `has_one`, `constraint =`, `address =`, or shared PDA `seeds` linking them
+- Handlers that index into one account using identity from another (user → user_state, pool → pool_vault) without an enforced link
+- State structs that store related pubkeys (`user`, `mint`, `vault`) that are never compared against the passed accounts
+
+## References
+- Coral sealevel-attacks — 1-account-data-matching (https://github.com/coral-xyz/sealevel-attacks/tree/master/programs/1-account-data-matching)
+- Solana program security course — account data matching (https://solana.com/developers/courses/program-security/account-data-matching)
+- Neodyme — Solana common pitfalls (https://neodyme.io/en/blog/solana_common_pitfalls/)
+
+## Real-world exploits (if any)
+Cashio (March 2022, ~$48M) is the canonical case of an unvalidated account chain: a forged collateral chain passed individual checks but the links between accounts were never enforced end-to-end.

package/rules/005-sysvar-spoofing.md

@@ -0,0 +1,57 @@
+# Rule 005: Sysvar Spoofing
+
+**Severity:** High
+**Category:** Account validation
+
+## Description
+Sysvar accounts (Clock, Rent, Instructions, EpochSchedule, …) live at well-known addresses, but a program that accepts "the clock account" or "the instructions sysvar" as an untyped `AccountInfo` and parses its data manually never verifies the address. An attacker passes a fake account with attacker-crafted "sysvar" contents — fake timestamps, fake serialized instructions — and the program trusts it.
+
+## Vulnerable pattern
+```rust
+#[derive(Accounts)]
+pub struct Verify<'info> {
+    /// CHECK: instructions sysvar
+    pub instructions: AccountInfo<'info>,
+}
+
+pub fn verify(ctx: Context<Verify>) -> Result<()> {
+    // Deprecated non-checked API: reads whatever account was passed
+    let ix = solana_program::sysvar::instructions::load_instruction_at(
+        0,
+        &ctx.accounts.instructions.data.borrow(),
+    )?;
+    // ... trusts `ix` to be a real instruction in this transaction
+    Ok(())
+}
+```
+
+## Why this is dangerous
+Whatever the program reads from the spoofed account — a timestamp gating a withdrawal, a "previous instruction" proving a signature verification ran — is attacker-controlled. In the worst case the attacker fabricates proof that a security check happened when it never did, bypassing the program's core authorization.
+
+## Fix pattern
+```rust
+#[derive(Accounts)]
+pub struct Verify<'info> {
+    /// CHECK: address constraint pins this to the real sysvar
+    #[account(address = solana_program::sysvar::instructions::ID)]
+    pub instructions: AccountInfo<'info>,
+}
+
+// In the handler, prefer the checked API:
+let ix = solana_program::sysvar::instructions::load_instruction_at_checked(
+    0, &ctx.accounts.instructions)?;
+```
+For Clock/Rent, use `Sysvar<'info, Clock>` / `Clock::get()?` instead of passing accounts at all.
+
+## Detection heuristic
+- Sysvar-named accounts (`clock`, `rent`, `instructions`, `recent_blockhashes`) typed as `AccountInfo` without an `address =` constraint
+- Use of deprecated `load_instruction_at` / `load_current_index` (non-`_checked` variants)
+- Manual parsing of sysvar account data instead of `Clock::get()` / `Rent::get()`
+
+## References
+- Neodyme — Solana common pitfalls: solana_program::sysvar confusion (https://neodyme.io/en/blog/solana_common_pitfalls/)
+- Helius — A Hitchhiker's Guide to Solana Program Security (https://www.helius.dev/blog/a-hitchhikers-guide-to-solana-program-security)
+- Solana docs — sysvar cluster data (https://docs.solanalabs.com/runtime/sysvars)
+
+## Real-world exploits (if any)
+Wormhole bridge (February 2022, ~$325M): the guardian-signature verification used the deprecated non-checked instructions-sysvar API, letting the attacker substitute a fake sysvar account and forge a "signatures verified" result to mint 120k wETH.