Running PASTIS

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)

Broker

The broker can be launched with pastis-broker binary. Command line arguments are the following:

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.

  • --workspace defines 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-report SAST report to use if any. If a report is provided, clients are automatically launched in ALERT_ONLY mode otherwise they are launched in CHECK_ALL.

  • --bins is the only mandatory parameter as it indicates an executable binary or a directory containing various variant of the same binary. Indeed, honggfuzz requires the binary to be compiled with instrumentation while tritondse need not. Similarly, depending on clients architecture the appropriate variant in the right architecture can be provided. pastis-broker automatically 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.

Warning

At the moment solely ELF Linux binaries are supported. Supporting other platforms would require extra engineering effort.

  • --mode defines 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 STDIN or via ARGV

  • --engine: Name of a broker-addon to load, that describes an engine capabilities.

  • --seed allows specifying a file or a directory of files containing the initial corpus for the campain.

  • --tt-config Triton 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-broker will launch a triton instance in each configuration and will loop if there is more.

  • --hf-config Honggfuzz 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.

  • --timeout fuzzing campaign timeout

  • --port Network port on which to listen on

  • --mem-threshold: Memory watchdog in percent, that will kill Triton instances if the limit is reached

Note

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.

Fuzzers

Engines can be launched with theirs appropriate binary:

  • AFL++: pastis-aflpp online [IP] [PORT]

  • Honggfuzz: pastis-honggfuzz online [IP] [PORT]

  • TritonDSE: pastis-tritondse online [IP] [PORT]

If no IP or port is provided, they will automatically connect to localhost:5555.

pastisd

The binary 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 the 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.

Warning

This program is under maintainance, please favor launching each fuzzers explicitely.

Analysing Results

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)