Solutions overview

A solution is a file that describes an attack. The runtime reads the file and replays the attack against a target, one step at a time. That is the whole idea: write the attack down once, replay it any time, read the result.

The file format in one paragraph

The file is plain text, one instruction per line. Lines that start with # are comments. A solution has two parts: a few lines at the top that name the attack, then the steps, each one a small block of name: value lines. There is no markup to learn.

A worked example

Here is the Heartbleed solution that ships in the corpus:

id: openssl/heartbleed-mem-leak
summary: CVE-2014-0160 Heartbleed: a vulnerable TLS server leaks memory from its heap.
ref: CVE-2014-0160

tls clienthello-heartbeat
  send: 1603030125010001210303...
  recv_until: 0e000000
  recv: 65536
  timeout: 5
  assert: contains "0e000000"
  meaning: server completes the handshake

tls malformed-heartbeat
  send: 1803030003014000
  recv: 70000
  assert: regex "18030[123]40"

Reading it top to bottom:

• id and summary name the attack; ref records the CVE it maps to.
• Each block is one step. A step starts with its identity and a name on the same line.
• Step 1, clienthello-heartbeat: a tls step that sends the normal handshake advertising the heartbeat extension, waits until the server finishes its hello (recv_until is the marker for ServerHelloDone), and tests that the response contains that marker, which proves the server completed the handshake.
• Step 2, malformed-heartbeat: sends the malformed heartbeat request, the actual exploit. It asks for far more data than it sends. The test looks for a heartbeat response record in the reply, which is exactly what a vulnerable server leaks.

If both tests pass, the run reports verified. The target server is vulnerable to Heartbleed.

What the top of the file holds

line	what it is
id	a name for the attack, in vendor/product style
summary	one sentence about the attack, for humans
ref	a reference such as a CVE number, repeat the line for more
param	the input parameter name, used by http steps
vars	starting values the attack can reuse, see Variables
oob	an out-of-band listener, for attacks that phone home

What is required

Only two things are required: id, a name for the attack, and at least one step block. Everything else at the top of the file is optional.

Within a step, the identity and the step name are always required. The fields that follow depend on the protocol in identity, and each identity page lists what its protocol needs: an http step needs encoding, a tcp/tls/websocket step needs send, a process step needs command, and a file step needs op and path.

Rules that apply to every solution

• step names must be unique within a solution
• a vars or set block must not repeat a name
• the built-in names flag_path, oob_host, and oob_port are reserved and cannot be declared
• for tcp, tls, and the byte-session services (including dns and snmp), send and recv_until must be valid hex

Where to look next

• Steps: what a step is, every step field, and how the runtime runs one
• Variables: values the runtime fills in for you
• Asserts: the pass or fail tests on each response
• Identity: the protocol each step speaks, with full field detail
• Authoring guide: build one from scratch, scenario by scenario