Currently there is several binaries that can be invoked (all are work in progress, some more stable than others)

• circuitous-lift - main driver, takes some representation of instruction bytes and produces a corresponding circuit.
• circuitous-run - interpret, right now mainly used for testing purposes.
• circuitous-seed - parses binary or binaries for instruction to be lifted.
• circuitous-cost-gen - will eventually produce cost for each node in circuit, currently in early development.
• circuitous-decoder - auto-generates an instruction decoder for a given circuit, currently in early development.

Due to usage of gflags (deprecated, will be removed), remill cmd line flags are exposed, from which probably --arch and --os are most interesting to users of circuitous. Please note that compared to remill circuitous does not set default values, instead they must be always provided by user.

Tool itself provides mostly output options:

• --json-out json debug output.
• --ir-out binary format, that can later be loaded by circuitous-run.
• --verilog-out verilog module circuit that can be passed to next stage of the pipeline.
• --dot-out dot diagram, useful for debug of smaller circuits.
• --dbg print extra debug information during runtime.

As for input, there will be several options to load inputs, right now:

• --bytes-in bytes to be used as inputs - after one instruction is parsed, the reader moves to the next (it does not try parse byte by byte). For example --bytes-in 76ff. No spaces between bytes, no hex prefix or suffix!
• --ciff-in output of circuitous-seed.
• --ir_in output of previous invocation of lift (--ir_out).

For example if the goal was to lift 65870c0f for 32bit x86, than following invocation could be used:

> circuitous-lift --logtostderr --arch x86 --os macos --ir-out out.circir --bytes-in 65870c0f

--logtostderr is from logging library, which without any args silently stores logs in tmp dir. Output is not exactly well handled, so there may be a lot of garbage, consider > lift.log 2>&1 to hide it in file.

Similarly to lift, it also uses same remill cmd options (most notable --arch). Overall usage is unstable right now, eventually most of it will be provided by both api and cli, but it is in progress work.

seed is a program responsible for parsing a binary (or multiple) in a really simple byte-by-byte way. Since that would result in too many instructions, there are several mechanism to select only those one wishes to:

• --filter file plain file where each allowed opcode is on separate line (see scripts/seed_sets/*.filter)
• --prune-spec file spec to restrain the opcodes even further (see scripts/seed_sets/*.prune) other than these, seed will by default fuzz all instructions and keep only one representative.

For output there are several options, the most ideal is

• --cif file which will store the parsed instruction together with their opcodes into a file. Can be subsequently loaded into lift via --ciff-in.
• --out file DEPRECATED stores plain bytes into file. Cannot be easily loaded into lift (one has to concat them manually and then pass via --bytes-in).

Other useful flags

• --config file list of files (each on new line) to parse.

Example of invocation may therefore look like following

> cat seed.config
myfile1.bin
myfile2.bin
> circuitous-seed --arch x86 --out result.out --cif result.ciff \
                  --config seed.config --filter seed.filter --prune seed.spec

Circuitous decoder like other tools accept arguments for remill, and takes as input either x86 bytes in plain text, output from circuitous-seed and circuitous-seed

• --arch: passed to remill

• --os: passed to remill

• --bytes-in: input bytes in plain text, example: 488b

• --ir-in: output file retrieved from circuitous-lift

• --ciff-in: output file retrieved from circuitous-seed

• --dec-out specifies the path to the generated source file.