API Documentation

Rode0day provides an API where users can view the current competition, download challenge corpora and submit inputs. The latest corpus can be downloaded without an account, but only authenticated users can submit inputs for scoring.

An example consumer of this API is available on GitHub.

Quick Start:

1) Get Status 
Get the YAML file describing:
  • Competition duration
  • Corpus download link
2) Get Corpus 
Get the archive containing:
  • Challenge programs
  • Metadata to run challenges
3) Find Bugs
Use your bug-finding skills to generate inputs that trigger bugs
4) Submit Inputs
Submit inputs with your API token. Get points for each unique bug you trigger


Get Status

View the status of the active Rode0day competition. Send a GET request to https://rode0day.mit.edu/api/1.0/latest.yaml.

Status Fields and Descriptions

PropertyDescription
download_linkLink to download corpus
rode0day_idUnique ID for the competition. Null if no competition is running
challenge_idsList of unique IDs for challenge in the competition
startUTC timestamp for competition start
endUTC timestamp for competition end
next_startUTC timestamp for when the next competition begins (optional)

Example Status

download_link: 'http://rode0day.mit.edu/static/corpora/XYZ.tar.gz'
rode0day_id: 1
challenge_ids:
    - 1
    - 2
start: !!timestamp '2018-04-02 12:00:00.000000'
end: !!timestamp '2018-05-04 12:00:00.000000'

Get Corpus

Download the current corpus from the URL provided by the status endpoint, or follow the redirect at https://rode0day.mit.edu/api/1.0/corpora/latest.tar.gz. Each corpus will consist of a gzipped tarball containing directories for each challenge plus an info.yaml file describing the challenges and how they can be run.

Info.yaml Fields and Descriptions

Property Description
rode0day_id A unique ID describing this competition
challenges A dictionary of dictionaries for the challenges with keys of the challenge name and values of:
challenges.[challenge_name].challenge_id A unique numerical ID describing this challenge
challenges.[challenge_name].architecture The architecture the challenge has been compiled for either x86 or x86_64
challenges.[challenge_name].install_dir The subdirectory in the corpora directory to that the following paths are relative to
challenges.[challenge_name].binary_path A relative path to the challenge
challenges.[challenge_name].binary_arguments A string of argument(s) that, when provided to the challenge can trigger all the bugs we have injected (may contain format strings, see below)
challenges.[challenge_name].library_dir A relative path to the library directory (may contain format strings, see below)
challenges.[challenge_name].sample_inputs A list of relative paths to sample input files we have provided
challenges.[challenge_name].libraries_modified A list of relative paths to library files we have potentially injected bugs into
challenges.[challenge_name].source_provided A boolean indicating if the source code is provided for this challenge
challenges.[challenge_name].source_path A relative path to the source code, if source code is provided
Important Details

The format string {input_file} should be replaced with a path to an input file to be processed by the binary. The format string {install_dir} should be replaced with a path to the install_dir.

One correct way to run the example challenge described above is with LD_LIBRARY_PATH=example1/libs example1/bin/example_challenge1 -e example1/share/config.bin example1/inputs/sample_file1.

There may or may not be multiple challenges within a competition. Challenge names and IDs will not be reused between competitions. A minimum of one input file will be provided. Multiple libraries may be modified to contain bugs.

Example info.yaml File

rode0day_id: 1
challenges:
    example1:
        challenge_id: 1
        architecture: "x86"
        install_dir: "example1"
        binary_path: "bin/example_challenge1"
        binary_arguments: "-e {install_dir}/share/config.bin {input_file}"
        library_dir: "libs"
        sample_inputs: ["inputs/sample_file1", "inputs/sample_file2"]
        libraries_modified: ["libs/lib1.so", "libs/lib2.so"]
        source_provided: false
    example2:
        challenge_id: 2
        architecture: "x86_64"
        install_dir: "example2"
        binary_path: "bin/challenge_two"
        binary_arguments: "{input_file}"
        library_dir: "libs"
        sample_inputs: ["inputs/sample_file3", "inputs/sample_file4"]
        libraries_modified: ["libs/lib3.so", "libs/lib4.so"]
        source_provided: true
        source_path: "src"

Submit Inputs

Upload each input you find that causes a challenge to crash. POST a multipart request to https://rode0day.mit.edu/api/1.0/submit. An account is required.

Request Fields

Parameter Description
input The input file you have generated
challenge_id The id of the challenge that this input should crash
auth_token An account-specific authorization token (log in to show).

Response Fields

Key Description
bug_ids A list of challenge-unique ID(s) we have assigned to the bug(s) your input triggers, or an empty list if the program does not crash
first_ids Bug_id values that were first discovered by your submission
score Your score after this submission
requests_remaining The number of additional API requests you are allowed to make during the active competition
status An integer describing any error with your request. If this field indicates an error, other fields may be missing
status_str A human-friendly string representation of the status message

To upload a file with curl

curl -F "challenge_id=1" -F "auth_token=YOURTOKEN" -F "input=@your_input" https://rode0day.mit.edu/api/1.0/submit

.

YAML Response

bug_ids: [1234]
first_ids: [1234]
requests_remaining: 9941
score: 32
status: 0
status_s: Your input successfully caused the program to a crash

Status and Errors

Requests to submit solutions will also have a status and status_str fields. Possible values for these fields are:

Status Status_str
0 Your input successfully caused the program to crash
1 The input you uploaded failed to make the program to crash
2 Your request is missing a required field
3 Your API token is not recognized
4 The challenge ID you specified is not a part of an active rode0day
5 Your input is too large
6 You are over the per-minute rate limit
7 You are over the competition rate limit
8 The endpoint you have requested cannot be found
9 No active rode0day
10 Unrecognized API version
11 An internal error has occured