Skip to content

A tool to manage, conduct, and assess dictionary-based fuzz testing

License

Notifications You must be signed in to change notification settings

test-pipeline/orthrus

Repository files navigation

Orthrus Build Status License Coverage Status

Orthrus is a tool for managing, conducting, and assessing dictionary-based security (fuzz) testing for autotools projects. At the moment, it supports Clang/LLVM instrumentation and the AFL ecosystem (afl-fuzz, afl-utils, afl-cov). The ultimate aim is for Orthrus to be a generic wrapper around state-of-the-art fuzz and instrumentation tools on the one hand, and disparate build systems on the other.

NEW: The dictionary-based fuzzing feature is new. Do orthrus create -dict to generate a fuzzing dictionary and orthrus add --jobconf to specify fuzz options (e.g., -x dict) for making use of the generated dictionary for fuzzing.

Installation

Please read docs/Getting_started.md.

Workflow

Orthrus currently supports two workflows. In a routine workflow, you work with a single fuzzing job end-to-end i.e., from source code instrumentation, until crash triage. In a A/B test workflow, you work with a single A/B test end-to-end.

Routine

Please read docs/Workflow.md.

A/B testing

Please read docs/Workflow_abtests.md.

Full usage

$ orthrus -h
usage: Orthrus 1.1 by Bhargava Shastry, and Markus Leutner <https://github.com/test-pipeline/orthrus> 
       [-h] [-v]
       {create,add,remove,start,stop,show,triage,coverage,spectrum,runtime,destroy,validate}
       ...

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         Verbose mode, print information about the progress

subcommands:
  Orthrus subcommands

  {create,add,remove,start,stop,show,triage,coverage,spectrum,runtime,destroy,validate}
    create              Create an orthrus workspace
    add                 Add a fuzzing job
    remove              Remove a fuzzing job
    start               Start a fuzzing jobs
    stop                Stop a fuzzing jobs
    show                Show what's currently going on
    triage              Triage crash corpus
    coverage            Run afl-cov on existing AFL corpus
    spectrum            Run spectrum based analysis on existing AFL corpus
    runtime             Perform dynamic analysis of existing AFL corpus
    destroy             Destroy an orthrus workspace
    validate            Check if all Orthrus dependencies are met

Issues and PRs

  • Feel free to file an issue if something doesn't work as expected :-)
    • Attaching logs from .orthrus/logs would be helpful
  • PRs for interesting workflows are much appreciated!

Credits

Orthrus was possible due to excellent work by

  • lcamtuf (afl-fuzz)
  • rc0r (afl-utils)
  • Michael Rash (afl-cov)
  • Clang/LLVM sanitization projects
  • Folks at afl users community and beyond