Skip to main content

foundry_evm_fuzz/
inspector.rs

1use crate::invariant::RandomCallGenerator;
2use alloy_primitives::{Address, Bytes, U256};
3use evm2::{
4    EvmTypes, Inspector,
5    interpreter::{Interpreter, Message, MessageKind, MessageResult},
6};
7use foundry_evm_core::constants::CHEATCODE_ADDRESS;
8
9/// A sub-call observed by the [`Fuzzer`] inspector.
10///
11/// `depth` is 1-indexed relative to the top-level call: depth 1 is a direct call
12/// from the top-level callee, depth 2 is a sub-call of that call, and so on. The
13/// top-level call itself is never recorded.
14#[derive(Clone, Debug, PartialEq, Eq)]
15pub struct ObservedCall {
16    pub depth: u32,
17    pub caller: Address,
18    pub target: Address,
19    pub calldata: Bytes,
20    pub value: Option<U256>,
21}
22
23/// An inspector that overrides calls to simulate reentrancy and records sub-calls for the
24/// invariant fuzzer.
25#[derive(Clone, Debug, Default)]
26pub struct Fuzzer {
27    /// Given a strategy, it generates a random call.
28    pub call_generator: Option<RandomCallGenerator>,
29    /// Whether sub-calls should be buffered for later corpus seeding.
30    record_calls: bool,
31    /// Sub-calls observed since the last drain.
32    observed_calls: Vec<ObservedCall>,
33    /// Current EVM call depth. 0 means no active call, 1 means top-level call.
34    call_depth: u32,
35    /// Additional network-specific cheatcode addresses that must not be overridden.
36    extra_cheatcode_addresses: &'static [Address],
37}
38
39impl<T: EvmTypes> Inspector<T> for Fuzzer {
40    fn call(
41        &mut self,
42        interp: &mut Interpreter<'_, '_, T>,
43        message: &mut Message<T>,
44    ) -> Option<MessageResult<T>> {
45        // We don't want to override the very first call made to the test contract.
46        if self.call_generator.is_some() && interp.host().tx_env().origin != message.caller {
47            self.override_call(interp, message);
48        }
49
50        self.call_depth = self.call_depth.saturating_add(1);
51        if self.should_record_observed_call(message.kind) {
52            self.observed_calls.push(ObservedCall {
53                depth: self.call_depth - 1,
54                caller: message.caller,
55                target: message.destination,
56                calldata: message.input.to_bytes(interp.memory()),
57                value: (!message.value.is_zero()).then_some(message.value),
58            });
59        }
60
61        None
62    }
63
64    fn call_end(
65        &mut self,
66        _interp: &mut Interpreter<'_, '_, T>,
67        _message: &Message<T>,
68        _result: &mut MessageResult<T>,
69    ) {
70        if let Some(ref mut call_generator) = self.call_generator {
71            // Decrement depth when any call ends while inside an override
72            if call_generator.override_depth > 0 {
73                call_generator.override_depth -= 1;
74            }
75        }
76
77        self.call_depth = self.call_depth.saturating_sub(1);
78    }
79}
80
81impl Fuzzer {
82    /// Sets additional network-specific cheatcode addresses that must not be overridden.
83    pub const fn with_extra_cheatcode_addresses(mut self, addresses: &'static [Address]) -> Self {
84        self.extra_cheatcode_addresses = addresses;
85        self
86    }
87
88    /// Enables or disables sub-call buffering.
89    pub const fn with_call_recording(mut self, record_calls: bool) -> Self {
90        self.record_calls = record_calls;
91        self
92    }
93
94    /// Enables or disables sub-call buffering on an existing inspector.
95    pub const fn set_call_recording(&mut self, record_calls: bool) {
96        self.record_calls = record_calls;
97    }
98
99    /// Returns the buffered sub-calls observed since the last drain.
100    pub fn take_observed_calls(&mut self) -> Vec<ObservedCall> {
101        std::mem::take(&mut self.observed_calls)
102    }
103
104    #[inline]
105    const fn should_record_observed_call(&self, kind: MessageKind) -> bool {
106        self.record_calls && self.call_depth > 1 && matches!(kind, MessageKind::Call)
107    }
108
109    #[inline]
110    fn is_cheatcode_address(&self, address: Address) -> bool {
111        address == CHEATCODE_ADDRESS || self.extra_cheatcode_addresses.contains(&address)
112    }
113
114    /// Overrides an external call to simulate reentrancy attacks.
115    ///
116    /// This function detects reentrancy vulnerabilities by replacing external calls
117    /// with callbacks that reenter the caller contract.
118    ///
119    /// For calls with value (ETH transfers):
120    /// 1. Performs the ETH transfer via the journal first
121    /// 2. Replaces the call with a reentrant callback (value = 0)
122    ///
123    /// For calls without value:
124    /// - Replaces the call entirely with a reentrant callback
125    ///
126    /// This simulates malicious contracts that immediately reenter when called.
127    fn override_call<T: EvmTypes>(
128        &mut self,
129        interp: &mut Interpreter<'_, '_, T>,
130        call: &mut Message<T>,
131    ) {
132        let target_is_cheatcode = self.is_cheatcode_address(call.destination);
133        let Some(ref mut call_generator) = self.call_generator else {
134            return;
135        };
136
137        // Skip if:
138        // - Caller is test contract (don't override the initial calls from the test)
139        // - Not a CALL scheme (only override CALLs, not STATICCALLs, DELEGATECALLs, etc.)
140        // - Inside an override (prevent recursive overrides)
141        // - Target is cheatcode address
142        // - Neither caller nor target is a handler contract
143        //
144        // We override calls when either the caller OR target is a handler. This covers:
145        // 1. EtherStore pattern: handler sends ETH out, attacker reenters handler
146        // 2. Rari pattern: external protocol sends ETH to handler, handler reenters protocol
147        if call.caller == call_generator.test_address
148            || !matches!(call.kind, MessageKind::Call)
149            || call_generator.override_depth > 0
150            || target_is_cheatcode
151        {
152            return;
153        }
154        {
155            let handlers = call_generator.handler_addresses.read();
156            if !handlers.contains(&call.caller) && !handlers.contains(&call.destination) {
157                return;
158            }
159        }
160
161        // There's only a ~27% chance that an override happens (90% * 30% from strategy).
162        let Some(tx) = call_generator.next(call.caller, call.destination) else {
163            return;
164        };
165
166        // For value transfers, perform the ETH transfer before injecting the callback.
167        // This simulates a malicious receive() that gets the ETH and then reenters.
168        let state = interp.host().state_mut();
169        let has_value = !call.value.is_zero() && call.gas_limit > 2300;
170        if has_value && state.transfer(&call.caller, &call.destination, &call.value).is_err() {
171            return;
172        }
173
174        // Replace the call with a reentrant callback. The message carries the code it runs, so
175        // load the new target's code instead of running the original target's.
176        let target = tx.call_details.target;
177        call.code = state
178            .account(&target)
179            .and_then(|mut account| account.load_code())
180            .expect("failed to load account");
181        call.input = tx.call_details.calldata.into();
182        call.caller = tx.sender;
183        call.destination = target;
184        call.call_target = target;
185        call.code_address = target;
186        // Clear value since ETH was already transferred above
187        call.value = U256::ZERO;
188
189        // Track that we're inside an overridden call to avoid recursive overrides
190        call_generator.override_depth = 1;
191    }
192}
193
194#[cfg(test)]
195mod tests {
196    use super::*;
197    use crate::{BasicTxDetails, CallDetails};
198    use alloy_network::TransactionBuilder;
199    use alloy_primitives::{B256, keccak256, map::AddressSet};
200    use evm2::{
201        Evm,
202        bytecode::Bytecode,
203        evm::{AccountInfo, InMemoryDB},
204    };
205    use foundry_evm_core::{
206        constants::MONAD_CHEATCODE_ADDRESS,
207        evm::{
208            EthEvmNetwork, EvmEnv, EvmFactoryFor, FoundryEvmFactory, FoundryEvmNetwork,
209            FoundryTxConversion, SpecFor, TransactionRequestFor, TypesFor,
210        },
211    };
212    use parking_lot::RwLock;
213    use proptest::{strategy::Just, test_runner::TestRunner};
214    use std::sync::Arc;
215
216    const CALLER: Address = Address::with_last_byte(0xCA);
217    const HANDLER: Address = Address::with_last_byte(0xA1);
218    const VICTIM: Address = Address::with_last_byte(0xA2);
219    const REENTRANT: Address = Address::with_last_byte(0xA3);
220
221    /// `call(gas(), VICTIM, 0, 0, 0, 0, 0); stop`.
222    fn handler_code() -> Vec<u8> {
223        let mut code = [0x60, 0x00].repeat(5);
224        code.push(0x73);
225        code.extend_from_slice(VICTIM.as_slice());
226        code.extend([0x5a, 0xf1, 0x00]);
227        code
228    }
229
230    /// `mstore(0, 7); mstore(32, 1); sstore(keccak256(0, 64), 2); stop`.
231    const VICTIM_CODE: &[u8] = &[
232        0x60, 0x07, 0x60, 0x00, 0x52, 0x60, 0x01, 0x60, 0x20, 0x52, 0x60, 0x40, 0x60, 0x00, 0x20,
233        0x60, 0x02, 0x90, 0x55, 0x00,
234    ];
235
236    /// `sstore(0, 1); stop`.
237    const REENTRANT_CODE: &[u8] = &[0x60, 0x01, 0x60, 0x00, 0x55, 0x00];
238
239    /// Calls `HANDLER`, running `handler`, from `CALLER` with `fuzzer` on `FEN`'s default spec.
240    fn run<FEN: FoundryEvmNetwork>(
241        fuzzer: Fuzzer,
242        handler: &[u8],
243    ) -> (Evm<'static, TypesFor<FEN>>, Fuzzer)
244    where
245        TransactionRequestFor<FEN>: Default,
246    {
247        let chain_id = 31337;
248        let mut db = InMemoryDB::default();
249        db.insert_account_info(&CALLER, AccountInfo::default().with_balance(U256::from(1e18)));
250        for (address, code) in
251            [(HANDLER, handler), (VICTIM, VICTIM_CODE), (REENTRANT, REENTRANT_CODE)]
252        {
253            let code = Bytecode::new_legacy(Bytes::copy_from_slice(code));
254            let account = AccountInfo::default().with_balance(U256::from(7)).with_code(code);
255            db.insert_account_info(&address, account);
256        }
257        let factory = EvmFactoryFor::<FEN>::default();
258        let spec = SpecFor::<FEN>::default();
259        let env = EvmEnv::new(spec, factory.version(spec, chain_id), Default::default());
260        let mut evm = factory.create_evm(db, env);
261        evm.set_inspector(fuzzer);
262        let request = TransactionRequestFor::<FEN>::default()
263            .with_from(CALLER)
264            .with_to(HANDLER)
265            .with_nonce(0)
266            .with_chain_id(chain_id)
267            .with_gas_limit(1_000_000)
268            .with_max_fee_per_gas(0)
269            .with_max_priority_fee_per_gas(0);
270        let tx = TypesFor::<FEN>::tx_from_request(request).unwrap();
271        assert!(evm.transact(&tx).unwrap().commit().status);
272        let fuzzer = *evm.clear_inspector_as::<Fuzzer>().unwrap();
273        (evm, fuzzer)
274    }
275
276    fn slot<T: EvmTypes>(evm: &mut Evm<'_, T>, address: Address, slot: U256) -> U256 {
277        evm.state_mut().storage_slot_untracked(&address, &slot).unwrap()
278    }
279
280    fn fuzzer_suite<FEN: FoundryEvmNetwork>()
281    where
282        TransactionRequestFor<FEN>: Default,
283    {
284        // Observation: the sub-call. The handler writes the mapping slot.
285        let fuzzer = Fuzzer::default().with_call_recording(true);
286        let (mut evm, mut fuzzer) = run::<FEN>(fuzzer, &handler_code());
287        let mapping_slot = keccak256([B256::with_last_byte(7), B256::with_last_byte(1)].concat());
288        assert_eq!(slot(&mut evm, VICTIM, mapping_slot.into()), U256::from(2));
289        assert_eq!(
290            fuzzer.take_observed_calls(),
291            [ObservedCall {
292                depth: 1,
293                caller: HANDLER,
294                target: VICTIM,
295                calldata: Bytes::new(),
296                value: None,
297            }]
298        );
299
300        // Override: the handler's call to the victim reenters through `REENTRANT` instead.
301        let callback = BasicTxDetails {
302            warp: None,
303            roll: None,
304            sender: VICTIM,
305            call_details: CallDetails { target: REENTRANT, calldata: Bytes::new(), value: None },
306        };
307        let mut generator = RandomCallGenerator::new(
308            Address::with_last_byte(0x7E),
309            AddressSet::from_iter([HANDLER]),
310            TestRunner::deterministic(),
311            Just(callback.call_details.clone()),
312            Arc::new(RwLock::new(Address::ZERO)),
313        );
314        generator.last_sequence.write().push(Some(callback));
315        generator.set_replay(true);
316        let fuzzer = Fuzzer { call_generator: Some(generator), ..Default::default() };
317        let (mut evm, _) = run::<FEN>(fuzzer, &handler_code());
318        assert_eq!(slot(&mut evm, REENTRANT, U256::ZERO), U256::ONE);
319        assert_eq!(slot(&mut evm, VICTIM, mapping_slot.into()), U256::ZERO);
320    }
321
322    #[test]
323    fn fuzzer_networks() {
324        fuzzer_suite::<EthEvmNetwork>();
325        fuzzer_suite::<foundry_evm_core::evm::TempoEvmNetwork>();
326        #[cfg(feature = "optimism")]
327        fuzzer_suite::<foundry_evm_core::evm::OpEvmNetwork>();
328        #[cfg(feature = "base")]
329        fuzzer_suite::<foundry_evm_core::evm::BaseEvmNetwork>();
330        #[cfg(feature = "monad")]
331        fuzzer_suite::<foundry_evm_core::evm::MonadEvmNetwork>();
332    }
333
334    #[test]
335    fn network_cheatcode_addresses_are_opt_in() {
336        let ethereum = Fuzzer::default();
337        assert!(!ethereum.is_cheatcode_address(MONAD_CHEATCODE_ADDRESS));
338
339        let monad = Fuzzer::default().with_extra_cheatcode_addresses(&[MONAD_CHEATCODE_ADDRESS]);
340        assert!(monad.is_cheatcode_address(MONAD_CHEATCODE_ADDRESS));
341    }
342
343    #[test]
344    fn observed_calls_are_disabled_by_default() {
345        let (_, mut fuzzer) = run::<EthEvmNetwork>(Fuzzer::default(), &handler_code());
346        assert!(fuzzer.take_observed_calls().is_empty());
347    }
348
349    #[test]
350    fn observed_calls_record_only_valued_subcalls() {
351        // `mstore(0, 0xcafebabe); call(gas(), VICTIM, 7, 28, 4, 0, 0);
352        // delegatecall(gas(), VICTIM, 0, 0, 0, 0); stop`.
353        let mut handler = vec![0x63, 0xca, 0xfe, 0xba, 0xbe, 0x60, 0x00, 0x52];
354        handler.extend([0x60, 0x00, 0x60, 0x00, 0x60, 0x04, 0x60, 0x1c, 0x60, 0x07, 0x73]);
355        handler.extend_from_slice(VICTIM.as_slice());
356        handler.extend([0x5a, 0xf1, 0x50]);
357        handler.extend([0x60, 0x00, 0x60, 0x00, 0x60, 0x00, 0x60, 0x00, 0x73]);
358        handler.extend_from_slice(VICTIM.as_slice());
359        handler.extend([0x5a, 0xf4, 0x50, 0x00]);
360
361        let fuzzer = Fuzzer::default().with_call_recording(true);
362        let (_, mut fuzzer) = run::<EthEvmNetwork>(fuzzer, &handler);
363
364        // The top-level call and the delegate call are not recorded.
365        assert_eq!(
366            fuzzer.take_observed_calls(),
367            [ObservedCall {
368                depth: 1,
369                caller: HANDLER,
370                target: VICTIM,
371                calldata: Bytes::from_static(&[0xca, 0xfe, 0xba, 0xbe]),
372                value: Some(U256::from(7)),
373            }]
374        );
375        assert!(fuzzer.take_observed_calls().is_empty());
376    }
377}