Before running PASTIS, the target must be harnessed, and all variants compiled for each engines. In order one should launch:
the broker with all parameters of the campaign
the fuzzing engines (with no specific order)
The broker can be launched with
pastis-broker binary. Command line arguments are
Usage: pastis-broker [OPTIONS] [PARGVS]... Options: --version Show the version and exit. -w, --workspace PATH Workspace directory to store data -r, --sast-report FILE SAST report to use -b, --bins DIRECTORY Directory containing binaries [required] -m, --mode [FULL|NO_TRANSMIT] Mode of broking -c, --chkmode [CHECK_ALL|ALERT_ONLY|ALERT_ONE] Check mode (all or alert driven) -i, --injloc [STDIN|ARGV] Seed injection location -e, --engine TEXT Fuzzing engine module to load (python module) --tt-config PATH Triton configuration file --hf-config PATH Honggfuzz configuration file -s, --seed PATH Initial seed or directory of seeds to give as initial corpus -t, --timeout INTEGER Timeout of the campaign. Time after which stopping the campaign -p, --port INTEGER Port to bind to --mem-threshold INTEGER RAM consumption limit --help Show this message and exit.
--workspacedefines the directory where all runtime data will be stored. If it does not exists it is created, otherwise information are partially loaded from it. The utility can thus load all corpus and crash files from an existing workspace. Other files are essentially not reused.
--sast-reportSAST report to use if any. If a report is provided, clients are automatically launched in
ALERT_ONLYmode otherwise they are launched in
--binsis the only mandatory parameter as it indicates an executable binary or a directory containing various variant of the same binary. Indeed,
honggfuzzrequires the binary to be compiled with instrumentation while
tritondseneed not. Similarly, depending on clients architecture the appropriate variant in the right architecture can be provided.
pastis-brokerautomatically detects the various variant in a given directory which simplifies the broker usage as it will automatically provide the appropriate variant depending on client’s capabilities.
At the moment solely ELF Linux binaries are supported. Supporting other platforms would require extra engineering effort.
--modedefines the “broking” behavior for
pastis-broker. Possible values are:
FULL: transmit all seeds to other clients. Performs the maximal sharing between peers
NO_TRANSMIT: receive data from clients but does not forward to one-another seeds
--chkmode: Indicate engines, the mode they are meant to run.
CHECK_ALL: normal exploration and global vulnerability discovery
ALERT_ONLY: only perform security checks on alerts taken from the SAST report. Also enables reporting when an alert is covered or validated
ALERT_ONE: Directed exploration toward a single alert (TritonDSE only)
--injloc: Whether the input is given on
--engine: Name of a broker-addon to load, that describes an engine capabilities.
--seedallows specifying a file or a directory of files containing the initial corpus for the campain.
--tt-configTriton specific parameters to be sent as configuration to any Triton clients The file is a JSON file as defined in
tritondse. If the parameter is a directory all files contained inside will be considered as different configuration files. That enables launching different Triton instances with different parameters. In this case
pastis-brokerwill launch a triton instance in each configuration and will loop if there is more.
--hf-configHonggfuzz specific parameters to be sent to
hf-wrapper. The file is text file that will be transmitted as-is to honggfuzz command line. The parameter can also be a directory with various configuration files.
--timeoutfuzzing campaign timeout
--portNetwork port on which to listen on
--mem-threshold: Memory watchdog in percent, that will kill Triton instances if the limit is reached
Without configuration specific files, pastis-broker will automatically equilibrate the coverage modes for clients. For instance three instances of TritonDSE will each be launched with different coverage criteria (block, edge, path). Similarly, if a client support different fuzzing engines pastis-broker will automatically balances honggfuzz instances and Triton instances.
Engines can be launched with theirs appropriate binary:
pastis-aflpp online [IP] [PORT]
pastis-honggfuzz online [IP] [PORT]
pastis-triton online [IP] [PORT]
If no IP or port is provided, they will automatically connect to localhost:5555.
pastisd is meant to be used as a daemon. It will check the availability of all
fuzzers and will connect to the broker announcing all available engines. It is thus the broker
that will automatically decide which fuzzer to launch. The
pastisd daemon will receive
start message from the broker containing the fuzzer to launch and will do it.
$ pastisd IP
If no IP, is provided it will automatically connect to pastis.lan:5555.
This program is under maintainance, please favor launching each fuzzers explicitely.
Corpus, crashes, clients logs and telemetry are stored in the broker workspace.
It thus aggregate all data related to a campaign. If a SAST report have been
provided it also provides for each alertes data returned by clients, inputs triggered
the crash of the alert etc. In this mode
pastis-broker also export a final CSV
indicating which alerts have been covered or triggered. The workspace folder also
enables restarting an interrupted campaign. The workspace file structure is the following:
workspace/ alerts_data/ (alert related data if a report was provided) binaries/ (binaries used, copied from --bins argument) corpus/ (corpus files) crashes/ (crash files) hangs/ (hang files) logs/ (log files, one file per client) broker.log (log file of the broker) sastreport.bin (copy of the SAST report if provided) results.csv (synthetic results of alerts, if a report is provided)