# Solutions overview

> What a solution file is, in plain language, with a worked example you can follow.

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 English directives. There is no markup to learn.

## A worked example

Here is the Heartbleed solution that ships in the corpus:

```text
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 hex "1603030125010001210303..."
  receive until "0e000000"
  receive 65536 bytes
  timeout 5 seconds
  expect "0e000000" in the response
  # server completes the handshake

tls malformed-heartbeat
  send hex "1803030003014000"
  receive 70000 bytes
  expect the response to match "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 (`receive 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 directives that follow depend on the protocol in `identity`, and each identity page lists what its protocol needs: an `http` step needs a method line, a `tcp`/`tls`/`websocket` step needs `send`, a `process` step needs `run`, and a `file` step needs `read` or `write`.

## 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 `receive until` must be valid hex

## Where to look next

- [Steps](/docs/solution/steps/): what a step is, every step field, and how the runtime runs one
- [Variables](/docs/solution/variables/): values the runtime fills in for you
- [Asserts](/docs/solution/asserts/): the pass or fail tests on each response
- [Identity](/docs/solution/identity/): the protocol each step speaks, with full field detail
- [Authoring guide](/docs/guides/authoring/): build one from scratch, scenario by scenario