anchor-audit 0.1.0

package/rules/006-missing-rent-exemption-check.md

@@ -0,0 +1,47 @@
+# Rule 006: Missing Rent-Exemption Check
+
+**Severity:** Low
+**Category:** Account validation
+
+## Description
+Accounts created or resized through raw system-program calls must be funded to the rent-exempt minimum for their size. Anchor's `init` and `realloc` handle this automatically, but manual `create_account` / `transfer` + `allocate` flows that compute lamports themselves can under-fund the account. The runtime rejects most non-exempt account creation today, but programs that accept *existing* accounts and assume durable state should still verify exemption rather than assume it.
+
+## Vulnerable pattern
+```rust
+// Manual account creation with a hardcoded lamport amount
+let create_ix = system_instruction::create_account(
+    payer.key,
+    new_account.key,
+    1_000_000, // guessed value — not Rent::get()?.minimum_balance(space)
+    space as u64,
+    program_id,
+);
+invoke(&create_ix, &[payer.clone(), new_account.clone()])?;
+```
+
+## Why this is dangerous
+Under-funded accounts fail at runtime in ways that surface as hard-to-diagnose errors, and lamport-balance assumptions elsewhere in the program (e.g. treating every account's balance above some floor as withdrawable) can double-count the rent reserve. Draining an account below its rent-exempt minimum while leaving it open also makes subsequent writes fail.
+
+## Fix pattern
+```rust
+let rent = Rent::get()?;
+let lamports = rent.minimum_balance(space);
+let create_ix = system_instruction::create_account(
+    payer.key, new_account.key, lamports, space as u64, program_id,
+);
+invoke(&create_ix, &[payer.clone(), new_account.clone()])?;
+```
+In Anchor, prefer `#[account(init, payer = payer, space = 8 + Data::INIT_SPACE)]`, which funds exemption automatically.
+
+## Detection heuristic
+- `system_instruction::create_account` with a literal/derived lamport value not based on `Rent::minimum_balance`
+- Lamport withdrawals that drain an account to zero or below `Rent::minimum_balance(data_len)` while the account stays open
+- Programs reading `account.lamports()` as "user balance" without subtracting the rent reserve
+
+## References
+- Solana docs — rent (https://solana.com/docs/core/fees#rent)
+- Anchor docs — account constraints, init (https://www.anchor-lang.com/docs/account-constraints)
+- 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 exploit attributed to this pattern; it appears in audits as a robustness/informational finding that compounds with lamport-accounting bugs (see Rule 023).

package/rules/007-account-aliasing.md

@@ -0,0 +1,53 @@
+# Rule 007: Account Aliasing (Duplicate Mutable Accounts)
+
+**Severity:** High
+**Category:** Account validation
+
+## Description
+An instruction takes two mutable accounts of the same type for two distinct logical roles (sender/receiver, position A/position B) but never checks that they are different accounts. Passing the *same* account for both roles makes the handler's reads and writes interleave on one underlying account, corrupting balance math — typically letting value be created or destroyed.
+
+## Vulnerable pattern
+```rust
+#[derive(Accounts)]
+pub struct Transfer<'info> {
+    #[account(mut)]
+    pub from: Account<'info, Balance>,
+    #[account(mut)]
+    pub to: Account<'info, Balance>, // may be the same account as `from`
+    pub authority: Signer<'info>,
+}
+
+pub fn transfer(ctx: Context<Transfer>, amount: u64) -> Result<()> {
+    ctx.accounts.from.amount -= amount;
+    ctx.accounts.to.amount += amount; // overwrites the deduction when aliased
+    Ok(())
+}
+```
+
+## Why this is dangerous
+With `from == to`, Anchor deserializes the account into two independent in-memory copies; the last one serialized on exit wins. In the pattern above the `to` copy never saw the deduction, so the attacker's balance is credited `amount` with no debit — free money on every call.
+
+## Fix pattern
+```rust
+#[derive(Accounts)]
+pub struct Transfer<'info> {
+    #[account(mut)]
+    pub from: Account<'info, Balance>,
+    #[account(mut, constraint = to.key() != from.key() @ ErrorCode::DuplicateAccount)]
+    pub to: Account<'info, Balance>,
+    pub authority: Signer<'info>,
+}
+```
+
+## Detection heuristic
+- Two or more `#[account(mut)]` fields of the same account type in one context
+- No `constraint = a.key() != b.key()` (or distinct PDA seeds) separating same-typed mutable accounts
+- Handlers performing read-modify-write on both accounts (balances, counters, positions)
+
+## References
+- Coral sealevel-attacks — 6-duplicate-mutable-accounts (https://github.com/coral-xyz/sealevel-attacks/tree/master/programs/6-duplicate-mutable-accounts)
+- Solana program security course — duplicate mutable accounts (https://solana.com/developers/courses/program-security/duplicate-mutable-accounts)
+- 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; a standard critical finding in public audit reports for AMM/order-matching programs that move value between same-typed accounts.

package/rules/008-uninitialized-account-use.md

@@ -0,0 +1,53 @@
+# Rule 008: Uninitialized Account Use
+
+**Severity:** High
+**Category:** Account validation
+
+## Description
+An account is read or written before its initialization is complete or verified. This includes deserializing accounts whose data is still all zeroes, trusting fields of an account that a separate "initialize" instruction was supposed to populate, and `zero`-copy patterns that skip an is-initialized flag. Zeroed bytes often deserialize into *valid-looking* defaults (authority = `Pubkey::default()`, amount = 0).
+
+## Vulnerable pattern
+```rust
+pub fn withdraw(ctx: Context<Withdraw>) -> Result<()> {
+    let vault = &ctx.accounts.vault;
+    // If vault was never initialized, vault.authority == Pubkey::default()
+    // and an attacker can satisfy this by passing the default pubkey path
+    if vault.authority != ctx.accounts.authority.key() {
+        return err!(ErrorCode::Unauthorized);
+    }
+    // ...
+    Ok(())
+}
+```
+
+## Why this is dangerous
+An attacker sequences instructions so the consuming instruction runs against an account that exists (rent-funded, correct owner) but was never initialized, or races initialization in the same transaction. Default field values then pass or bypass checks — `Pubkey::default()` authorities, zero balances treated as "no debt", or flags that read as false.
+
+## Fix pattern
+```rust
+#[account]
+pub struct Vault {
+    pub is_initialized: bool,
+    pub authority: Pubkey,
+}
+
+// Anchor's Account<'info, Vault> already rejects accounts whose
+// discriminator is unset (never went through `init`). For raw accounts:
+require!(vault.is_initialized, ErrorCode::Uninitialized);
+require_keys_neq!(vault.authority, Pubkey::default());
+```
+Use `#[account(zero)]` only for accounts being initialized *in this instruction*, never for accounts being consumed.
+
+## Detection heuristic
+- `AccountInfo`/`UncheckedAccount` data deserialized without a discriminator or `is_initialized` check
+- Authority comparisons that would pass for `Pubkey::default()`
+- `#[account(zero)]` on accounts that are read before being written
+- Multi-step init flows (create, then configure) where step 2+ doesn't verify step 1 ran
+
+## References
+- Coral sealevel-attacks — 4-initialization (https://github.com/coral-xyz/sealevel-attacks/tree/master/programs/4-initialization)
+- Neodyme — Solana common pitfalls (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)
+
+## Real-world exploits (if any)
+No single attributed public exploit; closely related to reinitialization attacks (Rule 031), which have caused fund loss in unaudited programs.

package/rules/009-missing-mut-constraint.md

@@ -0,0 +1,52 @@
+# Rule 009: Missing `mut` Constraint
+
+**Severity:** Medium
+**Category:** Account validation
+
+## Description
+A handler modifies an account's data or lamports, but the account is not declared `#[account(mut)]`. Anchor only persists changes for accounts marked writable; without `mut`, the runtime either rejects the transaction (for lamport changes) or silently discards data mutations at serialization time, depending on the access path. Logic that *appears* to update state — debiting a balance, flipping a flag — leaves on-chain state untouched.
+
+## Vulnerable pattern
+```rust
+#[derive(Accounts)]
+pub struct RecordDebt<'info> {
+    pub user_state: Account<'info, UserState>, // missing #[account(mut)]
+    #[account(mut)]
+    pub vault: Account<'info, Vault>,
+    pub user: Signer<'info>,
+}
+
+pub fn borrow(ctx: Context<RecordDebt>, amount: u64) -> Result<()> {
+    ctx.accounts.user_state.debt += amount; // never persisted
+    ctx.accounts.vault.balance -= amount;   // persisted — funds leave
+    Ok(())
+}
+```
+
+## Why this is dangerous
+The asymmetry is the exploit: the value-moving side persists while the bookkeeping side does not. In the example, a user borrows repeatedly and their recorded debt stays at zero — the protocol pays out with no liability recorded. Even when the failure mode is a transaction error, it can brick critical paths like liquidations.
+
+## Fix pattern
+```rust
+#[derive(Accounts)]
+pub struct RecordDebt<'info> {
+    #[account(mut, has_one = user)]
+    pub user_state: Account<'info, UserState>,
+    #[account(mut)]
+    pub vault: Account<'info, Vault>,
+    pub user: Signer<'info>,
+}
+```
+
+## Detection heuristic
+- Handler assigns to fields of an account (`ctx.accounts.x.field = ...`, `+=`, `-=`) whose struct field lacks `#[account(mut)]`
+- Lamport mutation (`try_borrow_mut_lamports`) on non-`mut` accounts
+- Pairs of accounts where one side of a balanced operation is `mut` and the other is not
+
+## References
+- Anchor docs — account constraints (https://www.anchor-lang.com/docs/account-constraints)
+- The Anchor Book — the Accounts struct (https://book.anchor-lang.com/anchor_in_depth/the_accounts_struct.html)
+- 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 exploit attributed; typically caught as a correctness bug in audits because it makes state updates silently no-op.

package/rules/010-missing-close-constraint.md

@@ -0,0 +1,48 @@
+# Rule 010: Missing or Improper Close Constraint
+
+**Severity:** Medium
+**Category:** Account validation
+
+## Description
+Closing an account on Solana means draining its lamports, but a "manual close" that only transfers lamports leaves the account's data intact for the rest of the transaction — and garbage collection only happens after the transaction ends. A close path that doesn't zero the data and mark the account closed (or that doesn't exist at all, stranding rent) is incorrect. Anchor's `close = receiver` constraint performs all required steps.
+
+## Vulnerable pattern
+```rust
+pub fn close_position(ctx: Context<ClosePosition>) -> Result<()> {
+    let position = ctx.accounts.position.to_account_info();
+    let dest = ctx.accounts.receiver.to_account_info();
+    // Lamports drained — but data and discriminator left intact
+    **dest.try_borrow_mut_lamports()? += position.lamports();
+    **position.try_borrow_mut_lamports()? = 0;
+    Ok(())
+}
+```
+
+## Why this is dangerous
+Within the same transaction, the attacker sends rent-exempt lamports back to the "closed" account in a later instruction, preventing garbage collection. The account survives with stale data and can be passed into other instructions as if still live — e.g. a closed loan position that still vouches for collateral (see Rule 032 for the revival half of this attack).
+
+## Fix pattern
+```rust
+#[derive(Accounts)]
+pub struct ClosePosition<'info> {
+    #[account(mut, has_one = owner, close = receiver)]
+    pub position: Account<'info, Position>,
+    #[account(mut)]
+    pub receiver: SystemAccount<'info>,
+    pub owner: Signer<'info>,
+}
+```
+Anchor's `close` drains lamports, zeroes data, and writes the `CLOSED_ACCOUNT_DISCRIMINATOR`.
+
+## Detection heuristic
+- Manual lamport-drain "closes" (`try_borrow_mut_lamports` to zero) without zeroing `data` and setting a closed discriminator
+- Account types that are initialized somewhere but have no close path at all (stranded rent, unbounded account growth)
+- Close instructions missing an authority check on who may close
+
+## References
+- Coral sealevel-attacks — 9-closing-accounts (https://github.com/coral-xyz/sealevel-attacks/tree/master/programs/9-closing-accounts)
+- Solana program security course — closing accounts (https://solana.com/developers/courses/program-security/closing-accounts)
+- Anchor docs — account constraints, close (https://www.anchor-lang.com/docs/account-constraints)
+
+## Real-world exploits (if any)
+No single attributed public exploit; the revival variant is a standard critical audit finding (see Rule 032).

package/rules/011-pda-seed-collision.md

@@ -0,0 +1,49 @@
+# Rule 011: PDA Seed Collision
+
+**Severity:** High
+**Category:** PDA
+
+## Description
+Two logically distinct PDAs can derive to the same address when their seed schemes overlap. Seeds are concatenated raw bytes with no delimiters or type tags, so `["vault", user, mint]` and `["vault", mint, user]`-style ambiguities, variable-length seeds (user-supplied strings), or two account kinds sharing a prefix can all collide. A PDA created for one purpose then satisfies derivation checks for another.
+
+## Vulnerable pattern
+```rust
+// Two account kinds, same seed shape — both derive from ["pool", key]
+#[account(seeds = [b"pool", base_mint.key().as_ref()], bump)]
+pub lending_pool: Account<'info, LendingPool>,
+
+// elsewhere in the program:
+#[account(seeds = [b"pool", quote_mint.key().as_ref()], bump)]
+pub staking_pool: Account<'info, StakingPool>,
+
+// Or: variable-length user input lets ["ab" + "cd"] == ["a" + "bcd"]
+#[account(seeds = [name.as_bytes(), suffix.as_bytes()], bump)]
+pub named_account: Account<'info, Named>,
+```
+
+## Why this is dangerous
+An attacker crafts inputs so the address of an account they control (or one with favorable state) derives identically to the account the program expects in a different context. Seed checks pass, and the program operates on the wrong account — mixing pools, reusing one account for two roles, or hijacking a namespace.
+
+## Fix pattern
+```rust
+// Distinct literal prefixes per account kind, fixed-length seeds,
+// and a length cap on any user-supplied seed component
+#[account(seeds = [b"lending_pool", base_mint.key().as_ref()], bump)]
+pub lending_pool: Account<'info, LendingPool>,
+
+#[account(seeds = [b"staking_pool", quote_mint.key().as_ref()], bump)]
+pub staking_pool: Account<'info, StakingPool>,
+```
+
+## Detection heuristic
+- Multiple account types whose `seeds = [...]` share the same literal prefix and shape
+- Seeds containing user-controlled variable-length data (strings, vecs) — adjacent variable-length seeds are always ambiguous
+- The same seed tuple used by more than one instruction for different account types
+
+## References
+- Neodyme — Solana common pitfalls (https://neodyme.io/en/blog/solana_common_pitfalls/)
+- Sec3 — How to audit Solana smart contracts (https://www.sec3.dev/blog)
+- Solana docs — program derived addresses (https://solana.com/docs/core/pda)
+
+## Real-world exploits (if any)
+No public headline exploit; seed-design findings appear in public Neodyme and Sec3 audit reports, usually rated high due to namespace hijack potential.

package/rules/012-missing-bump-validation.md

@@ -0,0 +1,55 @@
+# Rule 012: Missing Bump Validation
+
+**Severity:** Medium
+**Category:** PDA
+
+## Description
+A PDA account is accepted without any verification that its address actually derives from the expected seeds and bump for this program. If the account is typed `AccountInfo`/`UncheckedAccount` (or the handler recomputes nothing), an attacker can pass an arbitrary account where a PDA is expected, or pass a PDA derived from different seeds than intended.
+
+## Vulnerable pattern
+```rust
+#[derive(Accounts)]
+pub struct Withdraw<'info> {
+    /// CHECK: vault PDA — but nothing verifies the derivation
+    #[account(mut)]
+    pub vault_authority: AccountInfo<'info>,
+    #[account(mut)]
+    pub vault_token: Account<'info, TokenAccount>,
+    pub user: Signer<'info>,
+}
+```
+
+## Why this is dangerous
+The program assumes `vault_authority` is *its* PDA for *this* vault, but any account passes. Depending on what the handler does, the attacker redirects authority checks, signs CPIs with the wrong derivation, or points shared logic at an account from an unrelated context. PDA identity is only meaningful if it is recomputed and compared.
+
+## Fix pattern
+```rust
+#[derive(Accounts)]
+pub struct Withdraw<'info> {
+    /// CHECK: derivation enforced by seeds + bump below
+    #[account(
+        mut,
+        seeds = [b"vault_authority", vault_token.key().as_ref()],
+        bump = vault.authority_bump, // stored canonical bump
+    )]
+    pub vault_authority: AccountInfo<'info>,
+    #[account(mut)]
+    pub vault_token: Account<'info, TokenAccount>,
+    #[account(has_one = vault_token)]
+    pub vault: Account<'info, Vault>,
+    pub user: Signer<'info>,
+}
+```
+
+## Detection heuristic
+- Accounts whose names imply PDA roles (`*_authority`, `*_pda`, `escrow`, `vault`) with no `seeds`/`bump` constraint and no manual `find_program_address` comparison
+- Handlers that use an account as a CPI signer (`invoke_signed`) whose address was never validated against those signer seeds
+- `bump` arguments accepted from instruction data and used without verification (see Rule 013)
+
+## References
+- Coral sealevel-attacks — 7-bump-seed-canonicalization (https://github.com/coral-xyz/sealevel-attacks/tree/master/programs/7-bump-seed-canonicalization)
+- Anchor docs — account constraints, seeds/bump (https://www.anchor-lang.com/docs/account-constraints)
+- Solana program security course — bump seed canonicalization (https://solana.com/developers/courses/program-security/bump-seed-canonicalization)
+
+## Real-world exploits (if any)
+No single attributed public exploit; unvalidated PDA inputs are a recurring high-severity finding in public OtterSec and Sec3 reports.

package/rules/013-non-canonical-bump-accepted.md

@@ -0,0 +1,52 @@
+# Rule 013: Non-Canonical Bump Accepted
+
+**Severity:** High
+**Category:** PDA
+
+## Description
+For any set of seeds there are typically several valid bump values that produce off-curve addresses, but only one *canonical* bump (the highest, found by `find_program_address`). If a program accepts a caller-supplied bump and validates only that the resulting address is a valid PDA — rather than that it used the canonical bump — an attacker can derive multiple distinct, valid PDAs from the same logical seeds.
+
+## Vulnerable pattern
+```rust
+#[derive(Accounts)]
+#[instruction(bump: u8)]
+pub struct Init<'info> {
+    #[account(
+        init, payer = user, space = 8 + 32,
+        seeds = [b"user", user.key().as_ref()],
+        bump, // with the bump taken from instruction args, any valid bump passes
+    )]
+    pub user_pda: Account<'info, UserData>,
+    #[account(mut)]
+    pub user: Signer<'info>,
+}
+// handler trusts the `bump` arg and calls create_program_address with it
+```
+
+## Why this is dangerous
+The attacker initializes several PDAs for the same seeds using different non-canonical bumps, creating duplicate "user" accounts where the program assumed one-per-user. This defeats per-user accounting, one-time-claim guards, and uniqueness invariants — e.g. claiming an airdrop multiple times.
+
+## Fix pattern
+```rust
+#[account(
+    init, payer = user, space = 8 + 32,
+    seeds = [b"user", user.key().as_ref()],
+    bump, // Anchor uses the canonical bump from find_program_address
+)]
+pub user_pda: Account<'info, UserData>,
+// On later use, re-derive with the stored canonical bump:
+#[account(seeds = [b"user", user.key().as_ref()], bump = user_pda.bump)]
+```
+
+## Detection heuristic
+- `bump` values read from instruction arguments and passed to `create_program_address` / `Pubkey::create_program_address`
+- `bump = <user_input>` rather than bare `bump` (canonical) or `bump = stored_bump`
+- Any use of `create_program_address` without a preceding `find_program_address` canonical comparison
+
+## References
+- Coral sealevel-attacks — 7-bump-seed-canonicalization (https://github.com/coral-xyz/sealevel-attacks/tree/master/programs/7-bump-seed-canonicalization)
+- Solana program security course — bump seed canonicalization (https://solana.com/developers/courses/program-security/bump-seed-canonicalization)
+- Anchor docs — PDA constraints (https://www.anchor-lang.com/docs/account-constraints)
+
+## Real-world exploits (if any)
+No single attributed public exploit; canonical-bump findings are common in public audits of claim/airdrop and per-user-account programs.

package/rules/014-predictable-pda.md

@@ -0,0 +1,57 @@
+# Rule 014: Predictable / Attacker-Controlled PDA Seeds
+
+**Severity:** High
+**Category:** PDA
+
+## Description
+A PDA's authority or identity derives entirely from seeds the attacker can choose, with no signer or ownership tying the PDA to a legitimate principal. Because anyone can compute and request initialization of such a PDA, the attacker front-runs or pre-creates the account, taking control of state the program treats as authoritative.
+
+## Vulnerable pattern
+```rust
+#[derive(Accounts)]
+#[instruction(market_id: u64)]
+pub struct CreateMarket<'info> {
+    #[account(
+        init, payer = anyone, space = 8 + Market::INIT_SPACE,
+        seeds = [b"market", market_id.to_le_bytes().as_ref()],
+        bump,
+    )]
+    pub market: Account<'info, Market>,
+    #[account(mut)]
+    pub anyone: Signer<'info>, // no admin/authority gate
+}
+```
+
+## Why this is dangerous
+Since `market_id` is attacker-chosen and no privileged signer is required, an attacker creates markets at addresses the protocol (or integrators) will later trust, seeding them with malicious parameters (fee recipient = attacker, oracle = attacker). Any later instruction that resolves "the market for id X" lands on the attacker's account.
+
+## Fix pattern
+```rust
+#[derive(Accounts)]
+#[instruction(market_id: u64)]
+pub struct CreateMarket<'info> {
+    #[account(
+        init, payer = admin, space = 8 + Market::INIT_SPACE,
+        seeds = [b"market", market_id.to_le_bytes().as_ref()],
+        bump,
+    )]
+    pub market: Account<'info, Market>,
+    #[account(mut, address = config.admin)] // only the protocol admin may create
+    pub admin: Signer<'info>,
+    #[account(seeds = [b"config"], bump = config.bump)]
+    pub config: Account<'info, Config>,
+}
+```
+
+## Detection heuristic
+- `init` on a PDA whose seeds are fully attacker-supplied (instruction args, user-chosen ids) with no privileged `Signer` / `address =` gate
+- PDAs whose seeds omit any principal binding (no `user.key()`, no `authority.key()`) for accounts that represent ownership
+- Programs that resolve trusted singletons by attacker-chosen id without verifying who created them
+
+## References
+- Neodyme — Solana common pitfalls (https://neodyme.io/en/blog/solana_common_pitfalls/)
+- Sec3 — Solana security best practices (https://www.sec3.dev/blog)
+- Solana docs — program derived addresses (https://solana.com/docs/core/pda)
+
+## Real-world exploits (if any)
+No single attributed public exploit; front-running of permissionlessly-creatable PDAs is a recurring audit finding for market/pool factories.

package/rules/015-insecure-pda-across-upgrades.md

@@ -0,0 +1,54 @@
+# Rule 015: Insecure PDA Layout Across Upgrades
+
+**Severity:** Medium
+**Category:** PDA
+
+## Description
+Solana programs are upgradeable, but PDA accounts created by an old version persist with their old data layout. If an upgrade changes an account struct's fields, order, or size — or changes the seed scheme — without a versioning/migration strategy, the new code misinterprets existing accounts' bytes or can no longer derive their addresses.
+
+## Vulnerable pattern
+```rust
+// v1
+#[account]
+pub struct Vault { pub authority: Pubkey, pub balance: u64 }
+
+// v2 inserts a field in the middle — existing accounts now misparse:
+#[account]
+pub struct Vault {
+    pub authority: Pubkey,
+    pub admin: Pubkey, // NEW, shifts `balance` bytes
+    pub balance: u64,
+}
+// No version tag, no migration instruction.
+```
+
+## Why this is dangerous
+Old accounts deserialize with shifted fields: `balance` reads bytes that used to be part of another field, producing wrong values that flow into withdrawal/accounting logic. If the seed scheme changed instead, old accounts become unreachable, stranding user funds. Either way an attacker can exploit the mismatch or the protocol simply loses correctness.
+
+## Fix pattern
+```rust
+#[account]
+pub struct Vault {
+    pub version: u8, // bump on layout change
+    pub authority: Pubkey,
+    pub balance: u64,
+    pub admin: Pubkey, // append new fields at the END
+}
+// Provide an explicit `migrate_vault` instruction that reads version,
+// reallocs if needed, and writes the new layout. Append-only fields +
+// realloc with zero-init (see Rule 040) preserve old data.
+```
+
+## Detection heuristic
+- `#[account]` structs without a `version`/`schema` field in an upgradeable program
+- Field insertions/removals/reorderings in account structs between versions (check git history)
+- Seed-scheme changes for already-initialized PDAs with no migration instruction
+- `realloc` on existing accounts without preserving prior field offsets
+
+## References
+- Anchor docs — program upgrades and account layout (https://www.anchor-lang.com/docs)
+- Helius — A Hitchhiker's Guide to Solana Program Security (https://www.helius.dev/blog/a-hitchhikers-guide-to-solana-program-security)
+- Sec3 — Solana program upgrade considerations (https://www.sec3.dev/blog)
+
+## Real-world exploits (if any)
+No single attributed public exploit; layout-migration bugs surface in audits of long-lived upgradeable protocols and can corrupt accounting silently.

package/rules/016-bump-mismatch.md

@@ -0,0 +1,49 @@
+# Rule 016: Stored Bump Mismatch
+
+**Severity:** Medium
+**Category:** PDA
+
+## Description
+A program stores a PDA's bump at initialization and later re-derives the PDA, but the verification path doesn't actually pin the derivation to the stored bump — or stores the bump but then re-derives with `find_program_address` (recomputing the canonical bump) inconsistently across instructions. Inconsistent bump handling lets a non-canonical-bump PDA pass in one instruction and fail in another, or lets the wrong account satisfy a check.
+
+## Vulnerable pattern
+```rust
+// init stores the canonical bump
+ctx.accounts.state.bump = ctx.bumps.state;
+
+// ...but a later instruction re-derives canonically and signs with that,
+// ignoring the stored bump entirely:
+let (pda, bump) = Pubkey::find_program_address(&[b"state", user.key().as_ref()], ctx.program_id);
+let seeds = &[b"state", user.key().as_ref(), &[bump]];
+// If the account was created with a different (non-canonical) bump,
+// `pda` won't match the real account, or signing fails silently.
+```
+
+## Why this is dangerous
+Mismatched bump sources cause CPI signing to use the wrong signer seeds (transactions fail, or worse, a different valid PDA is authorized), and address checks that should reject an account can pass when a non-canonical bump was stored. The inconsistency is the bug: every code path must use the same stored canonical bump.
+
+## Fix pattern
+```rust
+// Store canonical bump once at init:
+ctx.accounts.state.bump = ctx.bumps.state;
+
+// Always reuse the stored bump for both constraints and signing:
+#[account(seeds = [b"state", user.key().as_ref()], bump = state.bump)]
+pub state: Account<'info, State>,
+
+let seeds = &[b"state", user.key().as_ref(), &[ctx.accounts.state.bump]];
+let signer = &[&seeds[..]];
+```
+
+## Detection heuristic
+- A `bump` field stored at init but some instructions use `find_program_address` / `ctx.bumps` instead of the stored value
+- `bump = state.bump` in some constraints and bare `bump` in others for the same PDA
+- `invoke_signed` seeds whose bump source differs from the constraint's bump source
+
+## References
+- Anchor docs — bumps and seeds (https://www.anchor-lang.com/docs/account-constraints)
+- Coral sealevel-attacks — 7-bump-seed-canonicalization (https://github.com/coral-xyz/sealevel-attacks/tree/master/programs/7-bump-seed-canonicalization)
+- Solana program security course — bump seed canonicalization (https://solana.com/developers/courses/program-security/bump-seed-canonicalization)
+
+## Real-world exploits (if any)
+No public attributed exploit; reported in audits as a consistency/correctness issue that can brick CPI-signing instructions.

package/rules/017-arbitrary-cpi.md

@@ -0,0 +1,56 @@
+# Rule 017: Arbitrary CPI (Unvalidated Target Program)
+
+**Severity:** Critical
+**Category:** CPI
+
+## Description
+A program performs a cross-program invocation to a program whose ID comes from a passed-in account, without verifying it against the expected program ID. The attacker supplies their own malicious program in place of the intended one (e.g. a fake "token program"), and the CPI executes attacker code with whatever accounts and signer seeds the calling program provides.
+
+## Vulnerable pattern
+```rust
+#[derive(Accounts)]
+pub struct Transfer<'info> {
+    pub token_program: AccountInfo<'info>, // unvalidated
+    #[account(mut)]
+    pub from: Account<'info, TokenAccount>,
+    #[account(mut)]
+    pub to: Account<'info, TokenAccount>,
+    pub authority: Signer<'info>,
+}
+
+pub fn transfer(ctx: Context<Transfer>, amount: u64) -> Result<()> {
+    let ix = /* build a transfer ix targeting ctx.accounts.token_program.key() */;
+    invoke(&ix, &[/* accounts */])?; // calls whatever program was passed
+    Ok(())
+}
+```
+
+## Why this is dangerous
+The attacker passes a program they control as `token_program`. Instead of transferring tokens, the fake program does nothing (so the caller believes a transfer happened) or manipulates the accounts it was handed. When the calling program signs the CPI with a PDA, the attacker's program inherits that PDA's authority for the duration of the call.
+
+## Fix pattern
+```rust
+#[derive(Accounts)]
+pub struct Transfer<'info> {
+    pub token_program: Program<'info, Token>, // Anchor verifies the ID
+    #[account(mut)]
+    pub from: Account<'info, TokenAccount>,
+    #[account(mut)]
+    pub to: Account<'info, TokenAccount>,
+    pub authority: Signer<'info>,
+}
+// Or, for raw AccountInfo: require_keys_eq!(token_program.key(), expected::ID);
+```
+
+## Detection heuristic
+- CPI target programs typed as `AccountInfo`/`UncheckedAccount` rather than `Program<'info, T>`
+- `invoke` / `invoke_signed` where the target program ID is read from accounts without a preceding `require_keys_eq!` against a known ID
+- Program IDs taken from instruction data or config accounts that are themselves attacker-controllable
+
+## References
+- Coral sealevel-attacks — 5-arbitrary-cpi (https://github.com/coral-xyz/sealevel-attacks/tree/master/programs/5-arbitrary-cpi)
+- Solana program security course — arbitrary CPI (https://solana.com/developers/courses/program-security/arbitrary-cpi)
+- Neodyme — Solana common pitfalls (https://neodyme.io/en/blog/solana_common_pitfalls/)
+
+## Real-world exploits (if any)
+No single attributed public headline exploit; arbitrary-CPI is one of the most common critical findings across public Solana audit reports.