trailofbits/substrate-vulnerability-scanner

Substrate Vulnerability Scanner

1. Purpose

Systematically scan Substrate runtime modules (pallets) for platform-specific security vulnerabilities that can cause node crashes, DoS attacks, or unauthorized access. This skill encodes 7 critical vulnerability patterns unique to Substrate/FRAME-based chains.

2. When to Use This Skill

• Auditing custom Substrate pallets
• Reviewing FRAME runtime code
• Pre-launch security assessment of Substrate chains (Polkadot parachains, standalone chains)
• Validating dispatchable extrinsic functions
• Reviewing weight calculation functions
• Assessing unsigned transaction validation logic

3. Platform Detection

File Extensions & Indicators

• Rust files: .rs

Language/Framework Markers

// Substrate/FRAME indicators
#[pallet]
pub mod pallet {
    use frame_support::pallet_prelude::*;
    use frame_system::pallet_prelude::*;

    #[pallet::config]
    pub trait Config: frame_system::Config { }

    #[pallet::call]
    impl<T: Config> Pallet<T> {
        #[pallet::weight(10_000)]
        pub fn example_function(origin: OriginFor<T>) -> DispatchResult { }
    }
}

// Common patterns
DispatchResult, DispatchError
ensure!, ensure_signed, ensure_root
StorageValue, StorageMap, StorageDoubleMap
#[pallet::storage]
#[pallet::call]
#[pallet::weight]
#[pallet::validate_unsigned]

Project Structure

• pallets/*/lib.rs - Pallet implementations
• runtime/lib.rs - Runtime configuration
• benchmarking.rs - Weight benchmarks
• Cargo.toml with frame-* dependencies

Tool Support

• cargo-fuzz: Fuzz testing for Rust
• test-fuzz: Property-based testing framework
• benchmarking framework: Built-in weight calculation
• try-runtime: Runtime migration testing

---

4. How This Skill Works

When invoked, I will:

1. Search your codebase for Substrate pallets
2. Analyze each pallet for the 7 vulnerability patterns
3. Report findings with file references and severity
4. Provide fixes for each identified issue
5. Check weight calculations and origin validation

---

5. Vulnerability Patterns (7 Critical Patterns)

I check for 7 critical vulnerability patterns unique to Substrate/FRAME. For detailed detection patterns, code examples, mitigations, and testing strategies, see VULNERABILITY_PATTERNS.md.

Pattern Summary:

1. Arithmetic Overflow ⚠️ CRITICAL

   • Direct +, -, *, / operators wrap in release mode
   • Must use checked_* or saturating_* methods
   • Affects balance/token calculations, reward/fee math

2. Don't Panic ⚠️ CRITICAL - DoS

   • Panics cause node to stop processing blocks
   • No unwrap(), expect(), array indexing without bounds check
   • All user input must be validated with ensure!

3. Weights and Fees ⚠️ CRITICAL - DoS

   • Incorrect weights allow spam attacks
   • Fixed weights for variable-cost operations enable DoS
   • Must use benchmarking framework, bound all input parameters

4. Verify First, Write Last ⚠️ HIGH (Pre-v0.9.25)

   • Storage writes before validation persist on error (pre-v0.9.25)
   • Pattern: validate → write → emit event
   • Upgrade to v0.9.25+ or use manual #[transactional]

5. Unsigned Transaction Validation ⚠️ HIGH

   • Insufficient validation allows spam/replay attacks
   • Prefer signed transactions
   • If unsigned: validate parameters, replay protection, authenticate source

6. Bad Randomness ⚠️ MEDIUM

   • pallet_randomness_collective_flip vulnerable to collusion
   • Must use BABE randomness (pallet_babe::RandomnessFromOneEpochAgo)
   • Use random(subject) not random_seed()

7. Bad Origin ⚠️ CRITICAL

   • ensure_signed allows any user for privileged operations
   • Must use ensure_root or custom origins (ForceOrigin, AdminOrigin)
   • Origin types must be properly configured in runtime

For complete vulnerability patterns with code examples, see VULNERABILITY_PATTERNS.md.

---

6. Scanning Workflow

Step 1: Platform Identification

1. Verify Substrate/FRAME framework usage
2. Check Substrate version (v0.9.25+ has transactional storage)
3. Locate pallet implementations (pallets/*/lib.rs)
4. Identify runtime configuration (runtime/lib.rs)

Step 2: Dispatchable Analysis

For each #[pallet::call] function:

• [ ] Arithmetic: Uses checked/saturating operations?
• [ ] Panics: No unwrap/expect/indexing?
• [ ] Weights: Proportional to cost, bounded inputs?
• [ ] Origin: Appropriate validation level?
• [ ] Validation: All checks before storage writes?

Step 3: Panic Sweep

# Search for panic-prone patterns
rg "unwrap\(\)" pallets/
rg "expect\(" pallets/
rg "\[.*\]" pallets/  # Array indexing
rg " as u\d+" pallets/  # Type casts
rg "\.unwrap_or" pallets/

Step 4: Arithmetic Safety Check

# Find direct arithmetic
rg " \+ |\+=| - |-=| \* |\*=| / |/=" pallets/

# Should find checked/saturating alternatives instead
rg "checked_add|checked_sub|checked_mul|checked_div" pallets/
rg "saturating_add|saturating_sub|saturating_mul" pallets/

Step 5: Weight Analysis

• [ ] Run benchmarking: cargo test --features runtime-benchmarks
• [ ] Verify weights match computational cost
• [ ] Check for bounded input parameters
• [ ] Review weight calculation functions

Step 6: Origin & Privilege Review

# Find privileged operations
rg "ensure_signed" pallets/ | grep -E "pause|emergency|admin|force|sudo"

# Should use ensure_root or custom origins
rg "ensure_root|ForceOrigin|AdminOrigin" pallets/

Step 7: Testing Review

• [ ] Unit tests cover all dispatchables
• [ ] Fuzz tests for panic conditions
• [ ] Benchmarks for weight calculation
• [ ] try-runtime tests for migrations

---

7. Priority Guidelines

Critical (Immediate Fix Required)

• Arithmetic overflow (token creation, balance manipulation)
• Panic DoS (node crash risk)
• Bad origin (unauthorized privileged operations)

High (Fix Before Launch)

• Incorrect weights (DoS via spam)
• Verify-first violations (state corruption, pre-v0.9.25)
• Unsigned validation issues (spam, replay attacks)

Medium (Address in Audit)

• Bad randomness (manipulation possible but limited impact)

---

8. Testing Recommendations

Fuzz Testing

// Use test-fuzz for property-based testing
#[cfg(test)]
mod tests {
    use test_fuzz::test_fuzz;

    #[test_fuzz]
    fn fuzz_transfer(from: AccountId, to: AccountId, amount: u128) {
        // Should never panic
        let _ = Pallet::transfer(from, to, amount);
    }

    #[test_fuzz]
    fn fuzz_no_panics(call: Call) {
        // No dispatchable should panic
        let _ = call.dispatch(origin);
    }
}

Benchmarking

# Run benchmarks to generate weights
cargo build --release --features runtime-benchmarks
./target/release/node benchmark pallet \
    --chain dev \
    --pallet pallet_example \
    --extrinsic "*" \
    --steps 50 \
    --repeat 20

try-runtime

# Test runtime upgrades
cargo build --release --features try-runtime
try-runtime --runtime ./target/release/wbuild/runtime.wasm \
    on-runtime-upgrade live --uri wss://rpc.polkadot.io

---

9. Additional Resources

• Building Secure Contracts: building-secure-contracts/not-so-smart-contracts/substrate/
• Substrate Documentation: https://docs.substrate.io/
• FRAME Documentation: https://paritytech.github.io/substrate/master/frame_support/
• test-fuzz: https://github.com/trailofbits/test-fuzz
• Substrate StackExchange: https://substrate.stackexchange.com/

---

10. Quick Reference Checklist

Before completing Substrate pallet audit:

Arithmetic Safety (CRITICAL):

• [ ] No direct +, -, *, / operators in dispatchables
• [ ] All arithmetic uses checked_* or saturating_*
• [ ] Type conversions use try_into() with error handling

Panic Prevention (CRITICAL):

• [ ] No unwrap() or expect() in dispatchables
• [ ] No direct array/slice indexing without bounds check
• [ ] All user inputs validated with ensure!
• [ ] Division operations check for zero divisor

Weights & DoS (CRITICAL):

• [ ] Weights proportional to computational cost
• [ ] Input parameters have maximum bounds
• [ ] Benchmarking used to determine weights
• [ ] No free (zero-weight) expensive operations

Access Control (CRITICAL):

• [ ] Privileged operations use ensure_root or custom origins
• [ ] ensure_signed only for user-level operations
• [ ] Origin types properly configured in runtime
• [ ] Sudo pallet removed before production

Storage Safety (HIGH):

• [ ] Using Substrate v0.9.25+ OR manual #[transactional]
• [ ] Validation before storage writes
• [ ] Events emitted after successful operations

Other (MEDIUM):

• [ ] Unsigned transactions use signed alternative if possible
• [ ] If unsigned: proper validation, replay protection, authentication
• [ ] BABE randomness used (not RandomnessCollectiveFlip)
• [ ] Randomness uses random(subject) not random_seed()

Testing:

• [ ] Unit tests for all dispatchables
• [ ] Fuzz tests to find panics
• [ ] Benchmarks generated and verified
• [ ] try-runtime tests for migrations