{"id":18894170,"url":"https://github.com/trailofbits/circuitous","last_synced_at":"2025-10-30T13:01:36.907Z","repository":{"id":194489517,"uuid":"274225600","full_name":"trailofbits/circuitous","owner":"trailofbits","description":"binary-\u003eLLVM-\u003ecircuits","archived":false,"fork":false,"pushed_at":"2024-02-26T09:19:15.000Z","size":3279,"stargazers_count":19,"open_issues_count":75,"forks_count":6,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-03-28T12:51:16.410Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","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/trailofbits.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2020-06-22T19:32:44.000Z","updated_at":"2024-10-10T21:22:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"08bb1d90-44c4-46cb-b8c3-fda2789e81e3","html_url":"https://github.com/trailofbits/circuitous","commit_stats":null,"previous_names":["trailofbits/circuitous"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fcircuitous","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fcircuitous/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fcircuitous/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailofbits%2Fcircuitous/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trailofbits","download_url":"https://codeload.github.com/trailofbits/circuitous/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248984403,"owners_count":21193742,"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-11-08T08:19:10.908Z","updated_at":"2025-10-30T13:01:36.812Z","avatar_url":"https://github.com/trailofbits.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build](https://github.com/trailofbits/circuitous/actions/workflows/build.yml/badge.svg)](https://github.com/trailofbits/circuitous/actions/workflows/build.yml)\n\n## Overview\n\nCircuitous is a set of tools and libraries used in Trail of Bits' work on the DARPA SIEVE program\nto generate circuits used in zero-knowledge proofs of exploit. It is unique in that\nthe circuits it produces are tailored to a specific binary. Circuitous accomplishes this\nby lifting binaries to LLVM and recovering instruction decoding via fuzzing.\nIt lowers to a custom CircIR, further optimizing using an equality saturation-based framework.\nCircIR can be targeted to output circuits in a variety of formats: we use Verilog on SIEVE.\n\nUsing a binary-specific circuit has many benefits: principally, it reduces circuit area\nby only modeling instructions actually used in the binary\n(as opposed to the entirety of an instruction set supported by a processor)-\nno need to pay for what you don't use.\nSince circuits are generated rather than handwritten, they are super easy to extend (just run\nthe tooling again if your binary changes). The framework can also be used to\nexperiment with different approaches to circuit design (e.g., different gate cost models).\n\nWhile we do provide core parts of the project as a libary, there are also some\ndrivers ready to be used. `circuitous-seed` can provide a list of instructions\nto lift from a given binary. (This list can subsequently be modified to exclude instructions.)\n`circuitous-lift` then takes this input and emits a circuit, generally in Verilog.\nWe will eventually provide a full step-by step example, but for now, you can invoke `--help` on the\nrespective tools, check out the `Usage` section and tests, or open an issue or discussion topic!\n\nSince this project is in active development, there are some caveats:\n * We currently support only a subset of x86 (both 32-bit and 64-bit -\n   see [Tiny86](https://github.com/trailofbits/sholva) for more details)\n   and the API is not super stable yet.\n * Due to how the internals of Circuitous work, it is hard to produce a circuit with\n   all forms of given instruction (e.g., all variants of `add`) - since it ingests the\n   instruction encoding as input.\n * Reducing circuit size is a really hard task, and we are still trying to\n   improve effectiveness of some of our optimizations.\n\n\n## Build\nBuild of circuitous follows the traditional, modern `cmake` build process.\nThe simplest way to build and install the project is to use premade presets that take care of downloading all dependencies.\nDependencies of circuitous are managed by `vcpkg` manifest file.\nBefore building one need to specify environment variables `CXX_COMMON_ROOT` and `VCPKG_ROOT` that point to folders of pre-downloaded [vcpkg](https://github.com/microsoft/vcpkg) and [cxx-common](https://github.com/lifting-bits/cxx-common/tree/port-files) or\nrun `scripts/build/setup.sh` to download and setup these dependencies automatically. We also suggest setting `CC` and `CXX` to clang when also building dependancies, as some require this.\n\nDepending on your system, use `linux` or `osx` preset.  To make `debug` build use `deb` presets:\n\n```\n# configure project\ncmake --preset ninja-cxx-common-x64-osx-rel\n\n# build project\ncmake --build --preset ninja-cxx-common-osx-rel\n\n# install project\ncmake --build --preset ninja-cxx-common-osx-rel --target install\n```\n\n## Development build\n\nIf you want to use your own prebuilt dependencies, project presets allow you to configure the build.\nFor example, if you have prebuilt `llvm`, can be from `cxx-common` package, you can specify `CMAKE_PREFIX_PATH` to point to `LLVMConfig.cmake` folder.  For example:\n\n```\nCMAKE_PREFIX_PATH=${CXX_COMMON_ROOT}/installed/x64-linux-rel/share/:${CMAKE_PREFIX_PATH}\n```\n\nThen use presets with prefix `ninja-cxx-common-system-llvm` and your desired triplet. Similarly, to build with system remill use presets prefixed `ninja-system-remill`.\n\n## Testing\n\n```\nctest --preset ninja-cxx-common-osx-deb-test\n```\n\n## Dependencies\n\n| Name | Version |\n| ---- | ------- |\n| [Git](https://git-scm.com/) | Latest |\n| [CMake](https://cmake.org/) | 3.23+ |\n| [Clang](http://clang.llvm.org/) | 12+ |\n| [ccache](https://ccache.dev/) | Latest |\n| [cxx-common](https://github.com/lifting-bits/cxx-common) | 0.2.6 |\n| [llvm](https://github.com/lifting-bits/cxx-common) | 14+ |\n| [remill](https://github.com/lifting-bits/remill) | Latest |\n| [gap](https://github.com/lifting-bits/gap) | Latest |\n| [doctest](https://github.com/doctest/doctest) | 2.4.8+ |\n| [spdlog](https://github.com/gabime/spdlog) | 1.10.0 |\n\nFor python dependencies see `requirements.txt` and for c++ `vcpkg.json`.\n\n\n# Usage\n\n## circuitous-lift\n\nThe main binary that produces the circuits. It has several options, which falls\ninto few categories.\n * `--arch` and `--os` are defaulted to mac and current machine (these are\n   needed to initialise libraries circuitous uses under the hood)\n * Some form of input\n  - `--bytes-in` raw bytes in human readable form (for example `1468` for some\n    version of `ADC`). More encodings should be just concatenated together.\n  - `--ciff-in` a config file provided by `circuitous-seed`. You can find some\n    example in `scripts/seed_sets/*.ciff`\n * Run information\n  - `--lift-with` to specify the lifter to use (currently only `v2` is supported\n    with `v1` being deprecated and `v3` in active development. As you probably\n    guessed these are placeholder names.\n * Outputs\n  - `--verilog-out` outputs the circuit in verilog\n * Random\n  - `--quiet` to silence debug/log outputs\n\nSo an example invocation may look like\n```bash\ncircuitous-lift --arch amd64 --os macos \\\n                --lift-with v2 \\\n                --bytes-in 1468 \\\n                --verilog-output out.v \\\n                --quiet\n```\n\n## Tests\n\nSee `test/README.md`\n\n## Dev Container for Actions\n\nRun manually __Build Dev Container__ action or execute:\n\n```\ndocker build .devcontainer --no-cache \\\n    -t ghcr.io/trailofbits/circuitous-ubuntu-22.04-dev:latest\n```\n\n```\ndocker push ghcr.io/trailofbits/circuitous-ubuntu-22.04-dev:latest\n```\n\nThis requires to have CLI access to github resources.\n\n## Benchmarks\n\nSee `scripts/bench/README.md`.\n\n## Distribution and Licensing\nThis research was developed with funding from the Defense Advanced Research\nProjects Agency (DARPA) under Agreement No. HR001120C0084.\n\nThe views, opinions, and/or findings expressed are those of the author(s) and\nshould not be interpreted as representing the official views or policies of the\nDepartment of Defense or the U.S. Government.\n\nDISTRIBUTION STATEMENT A: Approved for public release, distribution unlimited.\n\n*circuitous* is licensed under the GNU AGPLv3 License. A copy of the terms can\nbe found in the [LICENSE](./LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailofbits%2Fcircuitous","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrailofbits%2Fcircuitous","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailofbits%2Fcircuitous/lists"}