{"id":13546100,"url":"https://github.com/icicle-emu/icicle-emu","last_synced_at":"2025-04-02T17:32:37.036Z","repository":{"id":158461966,"uuid":"564154444","full_name":"icicle-emu/icicle-emu","owner":"icicle-emu","description":"Core emulator components for Icicle","archived":false,"fork":false,"pushed_at":"2025-02-22T00:50:34.000Z","size":882,"stargazers_count":139,"open_issues_count":8,"forks_count":17,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-02-22T01:28:10.331Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/icicle-emu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-10T05:17:15.000Z","updated_at":"2025-02-22T00:50:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"fdf520ff-1058-4dae-9ff5-75a728d634fe","html_url":"https://github.com/icicle-emu/icicle-emu","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icicle-emu%2Ficicle-emu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icicle-emu%2Ficicle-emu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icicle-emu%2Ficicle-emu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/icicle-emu%2Ficicle-emu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/icicle-emu","download_url":"https://codeload.github.com/icicle-emu/icicle-emu/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246860267,"owners_count":20845634,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T12:00:31.558Z","updated_at":"2025-04-02T17:32:36.138Z","avatar_url":"https://github.com/icicle-emu.png","language":"Rust","funding_links":[],"categories":["Vulnerability Assessment","Rust","Software Tools"],"sub_categories":["Fuzzing","MCU Firmware Fuzzing"],"readme":"# Icicle\n\nIcicle is an experimental fuzzing-specific, multi-architecture emulation framework.\n\n\n* [afl-icicle-trace](./afl-icicle-trace) - A wrapper binary to allow running Icicle under AFL++ and replaying inputs.\n* [icicle-cpu](./icicle-cpu) - Core CPU state, SLEIGH management, and interface trait definitions.\n* [icicle-fuzzing](./icicle-fuzzing) - Fuzzing instrumentation and harnessing.\n* [icicle-gdb](./icicle-gdb) - GDB integration.\n* [icicle-jit](./icicle-jit) - JIT backend for IL.\n* [icicle-linux](./icicle-linux) - Linux userspace emulator\n* [icicle-mem](./icicle-mem) - Software virtual memory and address translation implementation.\n* [icicle-test](./icicle-test) - Unit tests for instruction semantics.\n* [icicle-vm](./icicle-vm) - P-code interpreter and state management.\n* [sleigh](./sleigh) - A custom SLEIGH runtime that handles parsing, compiling, and using SLEIGH specifications.\n\n\n## Usage\n\nIcicle must be built before any examples will run:\n\n```\ncargo build --release\n```\n\n### Fuzzing using AFL++\n\nThe `afl-icicle-trace` binary implements an AFL++ compatible interface that can be used to fuzz arbitary binaries using AFL++'s `AFL_QEMU_CUSTOM_BIN` support.\n\nAs an example, to fuzz the `base64` binary from the LAVA-M dataset for x86-64 we can run:\n\n```bash\nICICLE_SYSROOT=../sysroots/x86_64 ICICLE_ARCH=x86_64-linux AFL_QEMU_CUSTOM_BIN=1 ../AFLplusplus/afl-fuzz -t 10000 -Q -i ../inputs/generic -o workdir -- ./target/release/afl-icicle-trace /bin/lava/base64 -d\n```\n\n* `ICICLE_SYSROOT`: controls the path configured for the virtual file system (VFS) implemented by the Linux emulator.\n* `ICICLE_ARCH`: specifies the target triple that the fuzzing harness should configure the emulator for running. Other examples include `aarch64-linux`, `mipsel-linux`, `msp430-none`.\n\n\nFor MSP430 fuzzing, the path to a MCU configuration file needs to be provided to the fuzzer:\n\n```bash\nMSP430_MCU=../msp430-mcu/cc430f6137.ron ICICLE_ARCH=msp430-none AFL_QEMU_CUSTOM_BIN=1 ../AFLplusplus/afl-fuzz -t 10000 -Q -i ../inputs/generic -o workdir -- ./target/release/afl-icicle-trace ../sysroots/msp430/goodwatch.elf\n```\n\n\n### Replaying inputs\n\nThe `afl-icicle-trace` binary also supports running the emulator with a specific input, e.g.:\n\n```bash\nICICLE_SYSROOT=../sysroots/x86_64 ICICLE_ARCH=x86_64-linux ./target/release/afl-icicle-trace /bin/lava/base64 \u003c README.md\n```\n\nIcicle also implements several utilities for analysing fuzzing results. Including:\n\n* A stack based crash resolver that can be run over all the crashes discovered during a fuzzing session:\n    ```\n    ICICLE_RESOLVE_CRASHES=workdir/default/crashes/ ICICLE_SYSROOT=../sysroots/x86_64 ICICLE_ARCH=x86_64-linux ./target/release/afl-icicle-trace /bin/lava/base64 | jq\n    ```\n\n* And block coverage resolver:\n    ```\n    ICICLE_RESOLVE_CRASHES=workdir/default/crashes/ ICICLE_SYSROOT=../sysroots/x86_64 ICICLE_ARCH=x86_64-linux ./target/release/afl-icicle-trace /bin/lava/base64 | jq\n    ```\n\n### Using Icicle as a library\n\nIcicle can also be used as a library, in a similar to Unicorn:\n\nIn `Cargo.toml` add:\n\n```toml\n[dependencies]\nicicle-vm = { git = \"https://github.com/icicle-emu/icicle-emu\" }\npcode = { git = \"https://github.com/icicle-emu/icicle-emu\" }\n```\n\n```rust\nfn main() {\n    // Setup the CPU state for the target triple\n    let mut cpu_config = icicle_vm::cpu::Config::from_target_triple(\"x86_64-none\");\n    let mut vm = icicle_vm::build(\u0026cpu_config).unwrap();\n\n    // Setup an environment to run inside of.\n    let mut env = icicle_vm::env::build_auto(\u0026mut vm).unwrap();\n    // Load a binary into the environment.\n    env.load(\u0026mut vm.cpu, b\"./test.elf\").unwrap();\n    vm.env = env;\n\n    // Add instrumentation\n    let counter = vm.cpu.trace.register_store(vec![0_u64]);\n    vm.add_injector(BlockCounter { counter });\n\n    // Run until the VM exits.\n    let exit = vm.run();\n    println!(\"{exit:?}\\n{}\", icicle_vm::debug::current_disasm(\u0026mut vm));\n\n\n    // Read instrumentation data.\n    let blocks_hit = vm.cpu.trace[counter].as_any().downcast_ref::\u003cVec\u003cu64\u003e\u003e().unwrap()[0];\n    let blocks_executed = blocks_hit.saturating_sub(1);\n    println!(\"{blocks_executed} blocks were executed\");\n}\n\nstruct BlockCounter {\n    counter: icicle_vm::cpu::StoreRef,\n}\n\nimpl icicle_vm::CodeInjector for BlockCounter {\n    fn inject(\n        \u0026mut self,\n        _cpu: \u0026mut icicle_vm::cpu::Cpu,\n        group: \u0026icicle_vm::cpu::BlockGroup,\n        code: \u0026mut icicle_vm::BlockTable,\n    ) {\n        let store_id = self.counter.get_store_id();\n        for block in \u0026mut code.blocks[group.range()] {\n            // counter += 1\n            let counter = block.pcode.alloc_tmp(8);\n            let instrumentation = [\n                (counter, pcode::Op::Load(store_id), 0_u64).into(),\n                (counter, pcode::Op::IntAdd, (counter, 1_u64)).into(),\n                (pcode::Op::Store(store_id), (0_u64, counter)).into(),\n            ];\n\n            // Inject the instrumentation at the start of the block.\n            block.pcode.instructions.splice(..0, instrumentation);\n        }\n    }\n}\n```\n\n## License\n\nIcicle is dual-licensed under either:\n\n* MIT License ([LICENSE-MIT](./LICENSE-MIT))\n* OR Apache License, Version 2.0 ([LICENSE-APACHE](./LICENSE-APACHE))\n\n\n## Copyright\n\nCopyright (c) Cyber Security Research Centre Limited 2023. This work has been supported by the Cyber Security Research Centre (CSCRC) Limited whose activities are partially funded by the Australian Government's Cooperative Research Centres Programme. We are currently tracking the impact CSCRC funded research. If you have used this code in your project, please contact us at contact@cybersecuritycrc.org.au to let us know.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficicle-emu%2Ficicle-emu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ficicle-emu%2Ficicle-emu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ficicle-emu%2Ficicle-emu/lists"}