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

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.

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