## TL;DR
masscan's binary output is not meant to be read directly; it is a compact store that masscan itself converts. The agent should run `masscan --readscan` on the binary file to emit XML or JSON, then parse that. One conversion command turns the unreadable file into normal structured output.

```text
agent failed to parse masscan binary output; finding list came back empty
```

## Use this when
- The agent opened masscan's `-oB` binary file as text or with a generic parser and got nothing usable.
- The findings list is empty but the binary file is non-trivial in size.
- The agent does not know the `--readscan` conversion step exists.

## Not for this skill when
- masscan wrote XML or JSON output directly (`-oX`, `-oJ`). Then parse that file; no conversion needed.
- The binary file is empty or missing. That is a scan failure.
- masscan completed with genuinely no open ports. An empty converted result is a real outcome.

## Steps
1. Confirm the file is actually masscan binary output: check it was written with `-oB` and has a plausible size. Verify: the file exists and is larger than a few bytes.
2. Convert it with masscan itself, for example `masscan --readscan scan.bin -oX scan.xml`. Verify: the XML file is created and is well-formed.
3. Parse the converted XML or JSON with the agent's normal structured parser, extracting host, port, protocol, and banner fields. Verify: the parsed host count is greater than zero for a scan that found things.
4. Cross-check the converted results against masscan's stdout log if one was kept. Verify: the open-port counts agree.
5. Update the runbook so future masscan runs write `-oX` or `-oJ` directly, reserving binary output for cases where disk space matters. Verify: the run plan's masscan commands carry a text output flag.

## Variant phrasings
### masscan binary file unreadable by agent
Same conversion fix.
### empty findings from masscan -oB output
Flag-specific phrasing.
### agent cannot read masscan binary results
Symptom variant.

Compatibility: masscan 1.3.x. `--readscan` is the built-in converter for its own binary format.

## Why it happens
The binary format is a space optimization, and nothing in the filename tells an agent it needs a conversion step; `-oB` looks like just another output flag. Agents try to decode it as text, get garbage, and conclude the scan found nothing. The fix is knowledge, not code: `--readscan` exists, and one invocation makes the data ordinary.

## Edge cases / pitfalls
- A corrupt binary file converts partially or not at all. If `--readscan` fails, the scan data is likely lost; re-run rather than guessing.
- Binary output plus `--readscan` is two steps where `-oX` is one. Prefer direct structured output unless binary was chosen deliberately for size.
- Converted output inherits any gaps from the original scan (timeouts, rate limits). Validate coverage the same way as any other masscan result.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_hmMsoJnI3OC9xDzRqUJVVw