Command-Line Tools Reference¶

Tip

See CLI Overview for an overview of these tools.

mate-cli¶

A CLI tool to interact with the MATE REST API

usage: mate-cli [-h] [--conn CONN]
                {artifact,build,compile,analysis,poi,graph,manticore,oneshot}
                ...

-h, --help¶: show this help message and exit

--conn <conn>¶: the connection string of the REST API

mate-cli analysis¶

usage: mate-cli analysis [-h] {get,task,run} ...

-h, --help¶: show this help message and exit

mate-cli analysis get¶

usage: mate-cli analysis get [-h]

-h, --help¶: show this help message and exit

mate-cli analysis run¶

usage: mate-cli analysis run [-h] build_id [analysis_id]

build_id¶: the ID of the build for which to run an analysis task

analysis_id¶: the ID of the analysis to run (defaults to running all analyses)

-h, --help¶: show this help message and exit

mate-cli analysis task¶

usage: mate-cli analysis task [-h] [id]

id¶: the ID of the build for which to query analysis tasks

-h, --help¶: show this help message and exit

mate-cli artifact¶

usage: mate-cli artifact [-h] {create,dump,get} ...

-h, --help¶: show this help message and exit

mate-cli artifact create¶

usage: mate-cli artifact create [-h]
                                {compile-target:single,compile-target:tarball,compile-target:bitcode,compile-target:brokered-challenge,blight:journal,compile-output:binary,compile-output:bitcode,compile-output:shared-library,compile-output:shared-library:bitcode,compile-output:static-library,compile-output:static-library:bitcode,compile-output:compile-log,build-output:merged-bitcode,build-output:canonical-bitcode,build-output:signatures,build-output:mate-jsonl,build-output:quotidian-headache-log,build-output:quotidian-wedlock-log,build-output:quotidian-canonical-binary,build-output:quotidian-jsonl,build-output:cpg-jsonl,build-output:debug-pointer-analysis,build-output:task-log,mantiserve-task:log}
                                path

kind¶: the kind of artifact

path¶: the path to the artifact file to be uploaded

-h, --help¶: show this help message and exit

mate-cli artifact dump¶

usage: mate-cli artifact dump [-h] [-o OUTPUT] id

id¶: the ID of the artifact

-h, --help¶: show this help message and exit

-o <output>, --output <output>¶: the file to dump to

mate-cli artifact get¶

usage: mate-cli artifact get [-h]
                             [--kind {compile-target:single,compile-target:tarball,compile-target:bitcode,compile-target:brokered-challenge,blight:journal,compile-output:binary,compile-output:bitcode,compile-output:shared-library,compile-output:shared-library:bitcode,compile-output:static-library,compile-output:static-library:bitcode,compile-output:compile-log,build-output:merged-bitcode,build-output:canonical-bitcode,build-output:signatures,build-output:mate-jsonl,build-output:quotidian-headache-log,build-output:quotidian-wedlock-log,build-output:quotidian-canonical-binary,build-output:quotidian-jsonl,build-output:cpg-jsonl,build-output:debug-pointer-analysis,build-output:task-log,mantiserve-task:log}]
                             [artifact-id [artifact-id ...]]

artifact-id¶: the ID of the artifact

-h, --help¶: show this help message and exit

--kind {compile-target:single,compile-target:tarball,compile-target:bitcode,compile-target:brokered-challenge,blight:journal,compile-output:binary,compile-output:bitcode,compile-output:shared-library,compile-output:shared-library:bitcode,compile-output:static-library,compile-output:static-library:bitcode,compile-output:compile-log,build-output:merged-bitcode,build-output:canonical-bitcode,build-output:signatures,build-output:mate-jsonl,build-output:quotidian-headache-log,build-output:quotidian-wedlock-log,build-output:quotidian-canonical-binary,build-output:quotidian-jsonl,build-output:cpg-jsonl,build-output:debug-pointer-analysis,build-output:task-log,mantiserve-task:log}¶: the kind of artifact to filter for

mate-cli build¶

usage: mate-cli build [-h] {create,get,get-bc} ...

-h, --help¶: show this help message and exit

mate-cli build create¶

usage: mate-cli build create [-h] [-p] [-w] [--target TARGET]
                             [--do-pointer-analysis]
                             [--no-do-pointer-analysis]
                             [--machine-code-mapping]
                             [--no-machine-code-mapping]
                             [--control-dependence] [--no-control-dependence]
                             [--llvm-memory-dependence]
                             [--no-llvm-memory-dependence]
                             [--llvm-pretty-strings]
                             [--no-llvm-pretty-strings]
                             [--translation-unit-nodes]
                             [--no-translation-unit-nodes] [--argument-edges]
                             [--no-argument-edges]
                             [--line-program-source-info]
                             [--no-line-program-source-info]
                             [--pointer-analysis {debug,subset,unification}]
                             [--context-sensitivity {insensitive,1-callsite,2-callsite,3-callsite,4-callsite,5-callsite,6-callsite,7-callsite,8-callsite,9-callsite,1-caller,2-caller,3-caller,4-caller,5-caller,6-caller,7-caller,8-caller,9-caller,1-file,2-file,3-file,4-file,5-file,6-file,7-file,8-file,9-file}]
                             [--memory-limit-mb BUILDOPTIONS_MEMORY_LIMIT_MB]
                             [--extra-linker-flags BUILDOPTIONS_EXTRA_LINKER_FLAGS]
                             [--time-llvm-passes] [--no-time-llvm-passes]
                             [--schema-validation] [--no-schema-validation]
                             [--merge-library-bitcode]
                             [--no-merge-library-bitcode]
                             [--merge-bitcode-only-needed]
                             [--no-merge-bitcode-only-needed]
                             [--merge-bitcode-internalize]
                             [--no-merge-bitcode-internalize]
                             [--debug-pointer-analysis]
                             [--no-debug-pointer-analysis]
                             [--debug-mate-jsonl] [--no-debug-mate-jsonl]
                             [--debug-quotidian-jsonl]
                             [--no-debug-quotidian-jsonl] [--debug-cpg-jsonl]
                             [--no-debug-cpg-jsonl]
                             id

id¶: the ID of the compilation to build

-h, --help¶: show this help message and exit

-p, --run-all-pois¶: run all POI analysis on each build

-w, --wait¶: wait until all builds finish

--target <target>¶: the binary to target

--do-pointer-analysis¶

--no-do-pointer-analysis¶

--machine-code-mapping¶

--no-machine-code-mapping¶

--control-dependence¶

--no-control-dependence¶

--llvm-memory-dependence¶

--no-llvm-memory-dependence¶

--llvm-pretty-strings¶

--no-llvm-pretty-strings¶

--translation-unit-nodes¶

--no-translation-unit-nodes¶

--argument-edges¶

--no-argument-edges¶

--line-program-source-info¶

--no-line-program-source-info¶

--pointer-analysis {debug,subset,unification}¶

--context-sensitivity {insensitive,1-callsite,2-callsite,3-callsite,4-callsite,5-callsite,6-callsite,7-callsite,8-callsite,9-callsite,1-caller,2-caller,3-caller,4-caller,5-caller,6-caller,7-caller,8-caller,9-caller,1-file,2-file,3-file,4-file,5-file,6-file,7-file,8-file,9-file}¶

--memory-limit-mb <buildoptions_memory_limit_mb>¶

--extra-linker-flags <buildoptions_extra_linker_flags>¶

--time-llvm-passes¶

--no-time-llvm-passes¶

--schema-validation¶

--no-schema-validation¶

--merge-library-bitcode¶

--no-merge-library-bitcode¶

--merge-bitcode-only-needed¶

--no-merge-bitcode-only-needed¶

--merge-bitcode-internalize¶

--no-merge-bitcode-internalize¶

--debug-pointer-analysis¶

--no-debug-pointer-analysis¶

--debug-mate-jsonl¶

--no-debug-mate-jsonl¶

--debug-quotidian-jsonl¶

--no-debug-quotidian-jsonl¶

--debug-cpg-jsonl¶

--no-debug-cpg-jsonl¶

mate-cli build get¶

usage: mate-cli build get [-h]
                          [--state {created,building,inserting,built,failed}]
                          [id]

id¶: the ID of the build

-h, --help¶: show this help message and exit

--state {created,building,inserting,built,failed}¶: the state of build we want to filter for

mate-cli build get-bc¶

usage: mate-cli build get-bc [-h] id

id¶: the ID of the build

-h, --help¶: show this help message and exit

mate-cli compile¶

usage: mate-cli compile [-h] {create,get} ...

-h, --help¶: show this help message and exit

mate-cli compile create¶

usage: mate-cli compile create [-h] [-w]
                               [--artifact-id ARTIFACT_ID | --challenge-name CHALLENGE_NAME | --challenge-id CHALLENGE_ID | --target-id TARGET_ID]
                               [--testbed] [--no-testbed] [--containerized]
                               [--no-containerized]
                               [--experimental-embed-bitcode]
                               [--no-experimental-embed-bitcode]
                               [--docker-image COMPILEOPTIONS_DOCKER_IMAGE]
                               [--containerized-infer-build]
                               [--no-containerized-infer-build]
                               [--make-targets COMPILEOPTIONS_MAKE_TARGETS]
                               [--extra-compiler-flags COMPILEOPTIONS_EXTRA_COMPILER_FLAGS]

-h, --help¶: show this help message and exit

-w, --wait¶: wait until the compilation finishes

--artifact-id <artifact_id>¶: the ID of the artifact to compile

--challenge-name <challenge_name>¶: the name of the challenge to compile

--challenge-id <challenge_id>¶: the ID of the challenge to compile

--target-id <target_id>¶: The ID of the challenge target to compile

--testbed¶

--no-testbed¶

--containerized¶

--no-containerized¶

--experimental-embed-bitcode¶

--no-experimental-embed-bitcode¶

--docker-image <compileoptions_docker_image>¶

--containerized-infer-build¶

--no-containerized-infer-build¶

--make-targets <compileoptions_make_targets>¶

--extra-compiler-flags <compileoptions_extra_compiler_flags>¶

mate-cli compile get¶

usage: mate-cli compile get [-h]
                            [--state {created,compiling,compiled,failed,rejected}]
                            [id]

id¶: the ID of the compilation

-h, --help¶: show this help message and exit

--state {created,compiling,compiled,failed,rejected}¶: the state of compilation we want to filter for

mate-cli graph¶

usage: mate-cli graph [-h] {get,node,slice,function} ...

-h, --help¶: show this help message and exit

mate-cli graph function¶

usage: mate-cli graph function [-h] build_id

build_id¶: the ID of the build for which to get function nodes

-h, --help¶: show this help message and exit

mate-cli graph get¶

usage: mate-cli graph get [-h]
                          build_id
                          {forward_dataflow,reverse_dataflow,forward_control_flow,reverse_control_flow,forward_control_dependence,reverse_control_dependence,callsites,callers,callees,operands,uses,forward_points_to,reverse_points_to,forward_points_to_reachable,reverse_points_to_reachable,forward_allocation,reverse_allocation,forward_memory_subregion,reverse_memory_subregion,aliased_memory_locations,signatures}
                          origin_node_ids [origin_node_ids ...]

build_id¶: the ID of the build to get graphs

kind¶: the type of graph to retrieve

origin_node_ids¶: the origin nodes for which to start looking for graphs

-h, --help¶: show this help message and exit

mate-cli graph node¶

usage: mate-cli graph node [-h] build_id node_id

build_id¶: the ID of the build for which to get nodes

node_id¶: the ID of the node to retrieve

-h, --help¶: show this help message and exit

mate-cli graph slice¶

usage: mate-cli graph slice [-h] [--avoid-node-id AVOID_NODE_IDS]
                            [--focus-node-ids FOCUS_NODE_IDS]
                            build_id source_id sink_id
                            {forward_dataflow,reverse_dataflow,forward_control_flow,reverse_control_flow,forward_control_dependence,reverse_control_dependence,callsites,callers,callees,operands,uses,forward_points_to,reverse_points_to,forward_points_to_reachable,reverse_points_to_reachable,forward_allocation,reverse_allocation,forward_memory_subregion,reverse_memory_subregion,aliased_memory_locations,signatures}

build_id¶: the ID of the build from which to retrieve the slice

source_id¶: ID of the node at which to start the slice

sink_id¶: ID of the node at which to end the slice

kind¶: the type of slice to retrieve

-h, --help¶: show this help message and exit

--avoid-node-id <avoid_node_ids>¶: the slice will exclude paths through these nodes

--focus-node-ids <focus_node_ids>¶: the slice will include only paths through these nodes

mate-cli manticore¶

usage: mate-cli manticore [-h] {get,stop} ...

-h, --help¶: show this help message and exit

mate-cli manticore get¶

usage: mate-cli manticore get [-h]
                              [--state {created,running,completed,failed}]

-h, --help¶: show this help message and exit

--state {created,running,completed,failed}¶: the state of Manticore task we want to filter for

mate-cli manticore stop¶

usage: mate-cli manticore stop [-h] task-id [task-id ...]

task-id¶: the ID of the Manticore task to stop

-h, --help¶: show this help message and exit

mate-cli oneshot¶

usage: mate-cli oneshot [-h] [-p] [-d] source_handle

source_handle¶: describes a source, can be either a source file, tarball, directory, artifact ID or broker challenge name

-h, --help¶: show this help message and exit

-p, --run-all-pois¶: run all POI analysis on each build

-d, --debug¶: enable all debugging outputs during the CPG build

mate-cli poi¶

usage: mate-cli poi [-h] {get,set} ...

-h, --help¶: show this help message and exit

mate-cli poi get¶

usage: mate-cli poi get [-h] [build_id]

build_id¶: the ID of the build for which to find POIs for (defaults to returning all POIs)

-h, --help¶: show this help message and exit

mate-cli poi set¶

usage: mate-cli poi set [-h] [--done] [--not-done] [--flagged] [--not-flagged]
                        [poi_id]

poi_id¶: the ID of the POI of which to modify

-h, --help¶: show this help message and exit

--done¶: mark the POI as done

--not-done¶: mark the POI as not done

--flagged¶: mark the POI as flagged

--not-flagged¶: mark the POI as not flagged

Note

The mate.build.tob_chess_utils.tools CLIs are legacy interfaces that should not be used directly. They are in the process of being removed. MATE does not use these CLIs and does not test their functionality.

python3 -m mate.build.tob_chess_utils.tools.margin¶

Flatten ToB JSONL into MATE-compatible JSONL

usage: python3 -m mate.build.tob_chess_utils.tools.margin [-h] -w WEDLOCK -a
                                                          ASPIRIN -t
                                                          HEADACHE_TI -c
                                                          HEADACHE_CU -o
                                                          OUTPUT [-S] [-Xs]
                                                          [-Xc] [-Xt] [-Xg]
                                                          [-Xw] [-Xp] [-Xv]
                                                          [-Xi] [-xe]

-h, --help¶: show this help message and exit

-w <wedlock>, --wedlock <wedlock>¶: Wedlock input

-a <aspirin>, --aspirin <aspirin>¶: Aspirin input

-t <headache_ti>, --headache_ti <headache_ti>¶: Headache TI input

-c <headache_cu>, --headache_cu <headache_cu>¶: Headache CU input

-o <output>, --output <output>¶: Output JSONL

-S, --sanity_checks¶: Perform input sanity checks

-Xs, --omit_plt_stub_nodes¶: Don’t emit PLT function stub nodes

-Xc, --omit_translation_unit_nodes¶: Don’t emit translation unit nodes

-Xt, --omit_type_nodes¶: Don’t emit type nodes

-Xg, --omit_global_nodes¶: Don’t emit global variable nodes

-Xw, --omit_wedlock_function_nodes¶: Don’t emit Wedlock function nodes

-Xp, --omit_param_nodes¶: Don’t emit function parameter nodes

-Xv, --omit_var_nodes¶: Don’t emit function local variable nodes

-Xi, --omit_asm_inst_nodes¶: Don’t emit ASM instruction nodes

-xe, --emit_arg_edges¶: Do emit Argument <-> DWARFArgument edges

python3 -m mate.build.tob_chess_utils.tools.aspirin¶

Extract variable information and basic block addresses from a migraine-instrumented binary and the output of the headache pass

usage: python3 -m mate.build.tob_chess_utils.tools.aspirin [-h] -b BINARY -H
                                                           HEADACHE_VI
                                                           [-o OUTPUT] [-Xl]

-h, --help¶: show this help message and exit

-b <binary>, --binary <binary>¶: ELF input

-H <headache_vi>, --headache_vi <headache_vi>¶: Headache VI input

-o <output>, --output <output>¶: JSONL output

-Xl, --omit_line_program¶: Don’t emit source line pairings that come from the line program

python3 -m mate.build.tob_chess_utils.tools.migraine¶

Generate an assembly patch for storing program feature addresses in a section

usage: python3 -m mate.build.tob_chess_utils.tools.migraine
       [-h] -w WEDLOCK [-o OUTPUT]

-h, --help¶: show this help message and exit

-w <wedlock>, --wedlock <wedlock>¶: Wedlock input

-o <output>, --output <output>¶: Output file