{"id":29717771,"url":"https://github.com/devdanzin/lafleur","last_synced_at":"2025-07-24T08:17:41.756Z","repository":{"id":305586228,"uuid":"1023278639","full_name":"devdanzin/lafleur","owner":"devdanzin","description":"A feedback-driven, evolutionary fuzzer for the CPython JIT compiler.","archived":false,"fork":false,"pushed_at":"2025-07-20T23:08:45.000Z","size":72,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-21T00:24:44.752Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devdanzin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null}},"created_at":"2025-07-20T22:44:31.000Z","updated_at":"2025-07-20T23:08:49.000Z","dependencies_parsed_at":"2025-07-21T00:38:57.435Z","dependency_job_id":null,"html_url":"https://github.com/devdanzin/lafleur","commit_stats":null,"previous_names":["devdanzin/lafleur"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/devdanzin/lafleur","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devdanzin%2Flafleur","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devdanzin%2Flafleur/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devdanzin%2Flafleur/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devdanzin%2Flafleur/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devdanzin","download_url":"https://codeload.github.com/devdanzin/lafleur/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devdanzin%2Flafleur/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266814318,"owners_count":23988552,"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","status":"online","status_checked_at":"2025-07-24T02:00:09.469Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2025-07-24T08:17:39.358Z","updated_at":"2025-07-24T08:17:41.301Z","avatar_url":"https://github.com/devdanzin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lafleur\n\nA feedback-driven, evolutionary fuzzer for the CPython JIT compiler.\n\n`lafleur` is a specialized fuzzer designed to find crashes, correctness bugs, and hangs in CPython's experimental JIT compiler. Unlike traditional fuzzers that generate code randomly, `lafleur` uses a coverage-guided, evolutionary approach. It executes test cases, observes their effect on the JIT's behavior by analyzing verbose trace logs, and uses that feedback to guide its mutations, becoming progressively smarter at finding interesting code paths over time.\n\n### Features\n\n  * **Coverage-Guided:** Uses uop-edge coverage to intelligently guide the fuzzing process.\n  * **AST-Based Mutation:** Mutates the structure of Python code directly, enabling complex and syntactically correct transformations.\n  * **JIT-Specific Mutators:** Includes a library of mutation strategies specifically designed to attack common JIT compiler weaknesses like type speculation, inline caching, and guard handling.\n  * **Differential Testing:** Features a mode to find silent correctness bugs by comparing the output of JIT-compiled code against the standard interpreter.\n  * **Intelligent Scheduling:** Employs a multi-factor scoring system to prioritize fuzzing test cases that are fast, small, and have discovered rare or fertile code paths.\n\n-----\n\n### Installation and Setup\n\n`lafleur` is a tool that requires a specific CPython build environment. Follow these steps carefully.\n\n#### Step 1: CPython Prerequisite\n\n`lafleur` must be run with a **debug build of CPython that has the experimental JIT compiler enabled**.\n\n1.  **Clone CPython:**\n    ```bash\n    git clone https://github.com/python/cpython.git\n    cd cpython\n    ```\n2.  **Configure \u0026 Build (First Pass):**\n    ```bash\n    ./configure --with-pydebug --enable-experimental-jit\n    make -j$(nproc)\n    ```\n3.  **Create Virtual Environment:**\n    ```bash\n    ./python -m venv ~/venvs/lafleur_venv\n    ```\n\n#### Step 2: Install `lafleur` and Tune the JIT\n\nWith the venv created, you can now install `lafleur` and use its JIT-tuning tool.\n\n1.  **Activate Your Virtual Environment:**\n    ```bash\n    source ~/venvs/lafleur_venv/bin/activate\n    ```\n2.  **Install `lafleur` from PyPI:**\n    ```bash\n    pip install lafleur\n    ```\n3.  **Tune the JIT:** Run the `lafleur` tuning script, pointing it at your CPython source directory. This modifies C header files to make the JIT more aggressive, which is ideal for fuzzing.\n    ```bash\n    lafleur-jit-tweak /path/to/your/cpython\n    ```\n4.  **Rebuild CPython:** Recompile CPython to apply the tuned settings.\n    ```bash\n    cd /path/to/your/cpython\n    make -j$(nproc)\n    ```\n\n#### Step 3: `fusil` Seeder (Optional)\n\n`lafleur` can use the classic `fusil` fuzzer to generate an initial set of interesting seed files. This is recommended but optional.\n\n1.  **Install `fusil`:**\n    ```bash\n    git clone https://github.com/fusil-fuzzer/fusil.git\n    cd fusil\n    pip install .\n    ```\n2.  **Configure `sudoers`:** The `fusil` seeder requires root privileges. To allow `lafleur` to call it without a password, run `sudo visudo` and add the following line, replacing the placeholders with your absolute paths:\n    ```bash\n    # Allow your_username to run the fusil seed generator without a password\n    your_username ALL=(ALL) NOPASSWD: /path/to/fusil_venv/bin/python3 /path/to/fusil/fuzzers/fusil-python-threaded *\n    ```\n\n  * **Alternative: Manual Seeding:** If you prefer not to install `fusil`, you can create a directory named `corpus/jit_interesting_tests/` in your working directory and place your own hand-crafted Python seed files inside it.\n\n-----\n\n### Usage\n\nOnce installed, you can run `lafleur` from any directory. It will create its output subdirectories (`corpus/`, `crashes/`, etc.) in the current working directory.\n\n#### Basic Usage (Resuming a Run)\n\nIf a corpus already exists, this command will load the state and resume the fuzzing session.\n\n```bash\n# Don't forget to activate your venv first!\nlafleur --fusil-path /path/to/fusil/fuzzers/fusil-python-threaded\n```\n\n#### Seeding a New Corpus\n\nUse `--min-corpus-files` to instruct `lafleur` to call the `fusil` seeder until the corpus has at least 20 files before starting.\n\n```bash\nlafleur --fusil-path /path/to/fusil/fuzzers/fusil-python-threaded --min-corpus-files 20\n```\n\n#### Differential Testing\n\nUse `--differential-testing` to enable the mode for finding silent correctness bugs.\n\n```bash\nlafleur --fusil-path /path/to/fusil/fuzzers/fusil-python-threaded --differential-testing\n```\n\n-----\n\n### Interpreting the Results\n\nThe most important findings from a fuzzing run will be saved in three directories:\n\n  * **`crashes/`**: Contains scripts that caused a hard crash (e.g., SegFault) or raised a critical error. Each `.py` file is accompanied by a `.log` file containing the output from the crash.\n  * **`timeouts/`**: Contains scripts that ran for too long (default \\\u003e 10 seconds), often indicating an infinite loop bug.\n  * **`divergences/`**: When in `--differential-testing` mode, this contains scripts where the JIT's behavior differed from the standard interpreter's.\n\nA helpful command to filter out low-value crashes and find potentially interesting ones is:\n\n```bash\ngrep -L -E \"(statically|indentation|unsupported|formatting|invalid syntax)\" crashes/*.log | sed 's/\\.log$/.py/'\n```\n\n-----\n\n### Contributing \u0026 Filing Issues\n\n`lafleur` is an open-source project, and contributions are welcome.\n\nTo file a bug report or a feature request, please use the project's **[GitHub Issues](https://github.com/devdanzin/lafleur/issues)** page. When filing a bug, please include:\n\n1.  The crashing test case (`.py` file).\n2.  The full log file (`.log`).\n3.  The commit hash of the CPython version you are fuzzing (you can paste the output of `python -VV`).\n\n### History and the Name\n\n`lafleur` began as an advanced feature set within the [fusil](https://github.com/devdanzin/fusil) project, which was created by Victor Stinner.\n\nThe name comes from the expression \"la fleur au fusil\", which matches the spirit with which the project was started.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevdanzin%2Flafleur","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevdanzin%2Flafleur","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevdanzin%2Flafleur/lists"}