@@ -438,6 +438,7 @@ Internal discovery runs a single masscan sweep (no source-port override) followe
 - **When the record is written and dropped**: on **success paths only**, exactly as `_EMPTY_RESULT_XML` is — a record on a killed scan would assert coverage that never happened. A `KeyboardInterrupt`, a missing binary and a non-zero exit all leave none; `_nmap_udp_discovery()` needs an explicit `proc.returncode == 0` guard for the last of those, because unlike `_nmap_port_discovery()` it does not treat a non-zero exit as fatal and a failing nmap can still leave parseable partial XML. Each phase also calls `_discard_coverage_record()` **before it scans**, not only on failure: a run killed outright never reaches the stamp, and the previous run's record would otherwise sit beside output that run had already replaced. The hazard is specifically a record that covered *more* than the output now on disk, since a subset test accepts it — a narrower leftover can only cause a redundant re-scan. Both halves live in one file written by a single `_atomic_write` for the same reason: as two sidecars written in sequence, a `KeyboardInterrupt` between them (a `BaseException`, so `except Exception` missed it) left a fresh target list beside a stale exclusion list and the gate accepted the pair as an exclusion-free scan. Neither an unreadable input nor a failed write raises on its own account — the scan already succeeded, so unwinding would discard real results — but every failure path, including an interrupt, deletes the record first. A cache whose record is absent or malformed is rejected, so output from before this change re-scans once on the first resume after upgrading; that is the deliberate direction, since a redundant re-scan is visible and an under-scan is not. The `.coverage` suffix is invisible to every result consumer: `masscan_results/` is aggregated by listing the directory, and `_parse_result_xml()` drops anything not ending in `.xml`, the same guard that hides `portN.xml.failed`. `_delete_previous_results()` removes it with the directory, so `--cleanup` and `[d]elete` need no special handling.
 - **config.json validation**: `_load_config()` refuses to start a scan it cannot run correctly. Missing required keys are reported all at once and exit. `target_scan` goes through `_config_target_scan()`, which accepts any case/whitespace spelling of `Internal`/`External` (normalising to the exact literal the ~25 comparison sites use) and exits on anything else — an unvalidated `"internal"` matched neither literal, so the scan ran and looked completely normal while every `target_scan == 'Internal'` gated check was silently skipped. Every numeric goes through `_config_int(key, value, default, minimum=1)`, mirroring `_prompt_int`'s floor: a non-numeric or null value warns and takes the default, and a value below `minimum` is clamped with a warning. `max_rate` is included (defaulting to the interactive prompt's 20000 external / 2000 internal) and only then re-`str()`-ed for Popen.
 - **Hostname support**: hostnames in the target file are resolved once at startup; nmap receives the original hostname (for SNI/vhost), masscan receives the resolved IP
+- **No reverse DNS from nmap**: every nmap command list passes `-n`, unconditionally, so nmap never performs its default per-host reverse (PTR) lookup. SpooNMAP's only DNS call is the one forward `socket.gethostbyname()` in `resolve_hostname()`; nothing in the module ever reads a `<hostname>`/PTR element out of nmap's XML (`_host_elem_to_dict()` and every other consumer build the host record from the in-memory `ip_to_hostname` map, whose only sources are that forward lookup and `_merge_ssl_cert_hostnames()`). Without `-n`, `-Pn` on the banner/NSE passes makes nmap treat every `-iL` host as up and PTR-resolve it once per port scanned — a burst of queries against the client's own resolver on an internal engagement, for output the tool discards. This is the same unrequested-traffic concern as `check_for_updates`/`honeypot_active_confirm`/`scanner_profile`, so it is off by construction rather than configurable: a future feature that actually wants PTR names should add `-n`-removal at its own site, not make the whole tool pay. `TestNmapNeverDoesReverseDns` pins `-n` on every nmap list literal via the module AST (the same technique as the `_DIR`-relative NSE-path guard), so a refactor can't silently drop it — the failure mode is invisible traffic, exactly what these tests exist to catch. The two `_verify_nmap_overlay()` probes are loopback-only and carry `-n` too, for uniformity. (Issue #57.)
 - **TLS certificate hostname discovery**: on External scans, `_extract_ssl_cert_hostnames()` parses the `ssl-cert` NSE output SpooNMAP already collects (commonName off the `Subject:` line, each `DNS:` entry off `Subject Alternative Name:`) and reports every name found as a LOW-severity `TLS Certificate Hostname(s) Identified` finding, wildcards included. Separately, `_merge_ssl_cert_hostnames()` runs right after the NSE script pass (gated on `script_scan`, since that's the only time `nse_results/` exists) and fills gaps in `ip_to_hostname` with the first non-wildcard name per host — never overwriting an operator-supplied hostname from the target file — then rewrites `discovery/ip_hostname_map.json`. It runs before `_aggregate_result_dir()` and `generate_findings()` (which re-reads that file fresh) so `spoonmap_output.*` and the findings report both reflect the merged map for the current run. It does not retroactively change what *this* run's nmap invocations targeted — hostname-based targeting via `create_hostname_target_file()` already happened earlier in the same run using whatever `ip_to_hostname` looked like at that point; the benefit is to this run's reporting. A `--resume` run does not inherit the merged file directly — `main()` calls `preprocess_targets()` unconditionally, including on resume, and it rewrites `discovery/ip_hostname_map.json` from the target file alone with no merge of the existing file's contents — but it re-derives the same cert hostnames from the still-cached `nse_results/*.xml`, since a persisted cert-derived hostname reaching `create_hostname_target_file()` could send nmap after a name-resolved address different from the one actually in scope (a commonName lifted off a shared/CDN certificate can resolve elsewhere entirely). The clobber-on-every-run behavior of `preprocess_targets()` is what accidentally prevents that, and is deliberately left as-is. `'TLS Certificate Hostname(s) Identified'` is also added to `_PER_HOST_DETAIL_TITLES`, since its detail (the actual discovered names) differs per host — without that, `findings.txt` would collapse the group to a single shared description that doesn't exist for this finding.
 - **IPv4-only, enforced at the edges**: the tool scans IPv4 exclusively (masscan/nmap invocations, target expansion, and address sorting all assume it). IPv6 is rejected rather than half-supported, in two places. (1) `_build_discovery_target_file()`'s `_parse_ranges()` skips any entry `ipaddress.ip_network()` resolves to a non-v4 network and prints the offending file, line number, and content — previously the v6 bounds were stored silently and only surfaced hundreds of lines later as `AddressValueError: ... (>= 2**32)` from `summarize_address_range()`, and only when an exclusions file happened to be configured. (2) The masscan/discovery XML parsers (`_parse_masscan_ping_xml()`, `_parse_nmap_sn_xml()`, `_run_masscan_batch()`) select `address[@addrtype='ipv4']` instead of the first `<address>` child, matching what the nmap-side parsers already did, so a dual-stacked host's IPv6 or MAC string can't enter `live_ips`/`port_ips` and become a masscan `-iL` target. Address sorting goes through `_ip_sort_key()`, which orders valid IPv4 numerically and sorts anything unparseable last instead of raising — the three former inline `tuple(int(o) for o in x.split('.'))` keys ran *after* a completed sweep, so one odd entry discarded the whole thing.
 - **XML result parsing is per-element defensive**: every `etree.parse()` site guards the *walk* as well as the parse. Attributes are read with `.attrib.get(...)` and the element is skipped when the identifier is missing — never a bare `attrib['addr']` or `findall('address')[0]`, both of which raise `KeyError`/`IndexError` that `except etree.ParseError` does not catch. Those exceptions escaped the guard and discarded the results for *every other host* in the file (or, in `_host_elem_to_dict()`, lost `spoonmap_output.xml`/`.json` for the whole run) over one truncated element. `<script>` elements with no `id=` are filtered out of the comprehensions for the same reason. Where a fallback to the first `<address>` child is wanted after `address[@addrtype='ipv4']` misses (`generate_findings()`, `_scan_extra_sql_ports()`), it is a `None`-checked `find('address')`.
 
@@ -0,0 +1,211 @@
+# Contributing to SpooNMAP
+
+Thanks for your interest. SpooNMAP orchestrates masscan and nmap, so most useful
+contributions are fixes to how a scan phase drives one of those tools, new or
+corrected NSE scripts under `nse/`, better findings output, or resume/coverage
+correctness.
+
+Please read the three short sections below before you start. One is about
+engagement data, which matters more here than in most projects. One is about
+which branch to target, which is easy to get wrong. One is about regression
+tests, which are not optional here.
+
+## Never include real engagement data
+
+SpooNMAP is run from jumpboxes inside client networks on authorized penetration
+tests, so the files it reads and writes describe somebody else's infrastructure.
+**Do not put any of it in an issue, a pull request, a commit, a test fixture, or
+a screenshot.** That includes client IP ranges, hostnames, resolved DNS names,
+TLS certificate subjects, service banners, masscan and nmap XML output,
+`findings.*`, and anything naming an organization.
+
+When you need example data, invent it. Use documentation ranges
+(`192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`) or RFC1918 addresses and
+made-up hostnames, exactly as the existing tests do. When you need to describe a
+result, report aggregates that cannot be reversed.
+
+`.gitignore` already covers what SpooNMAP writes: `config.json`,
+`discovery/`, `live_hosts/`, `masscan_results/`, `nmap_results/`,
+`nse_results/`, `all_live_hosts.txt`, `spoonmap_output.*`, `findings.*`,
+`resume.cfg` and more. Do not weaken those patterns to commit something, and do
+not `git add -A` past a file that shows up untracked because a local scan
+produced it.
+
+`tests/test_nse_integration.py` binds real local ports and shells out to real
+`nmap` against `127.0.0.1`. Keep it that way — no test in this repo may send a
+packet to an address it does not own.
+
+## Target `nightly`, not `main`
+
+`main` is the default branch, so GitHub will preselect it — **change the base to
+`nightly`.** `main` holds the last released state and receives work only
+through a batch integration merge from `nightly`. A pull request landing on
+`main` directly breaks that and creates cleanup for the maintainers.
+
+```bash
+git clone https://github.com/<you>/spoonmap
+cd spoonmap
+git checkout -b my-change origin/nightly
+# ... work ...
+git push -u origin my-change     # then open a PR with base: nightly
+```
+
+Branch names follow a `type/short-description` pattern matching the prefixes
+already on `origin`: `feat/`, `fix/`, `docs/`, `test/`, `chore/`, `ci/`.
+
+One exception goes straight to `main`: a security fix that must ship
+immediately. Say so in the PR body.
+
+`CLAUDE.md` describes the same flow from the maintainer side under "Release
+Versioning", and it is worth reading if you want the reasoning. The mechanic you
+do not need to do anything about, but should know exists: maintainers integrate
+`nightly` into `main` with a **merge or a fast-forward, never a squash**. CI
+derives every release version from the commits themselves, and a squash merge
+collapses already-released commits into one that no prior tag can reach, which
+silently corrupts every version computed afterward.
+
+## Every bug fix needs a regression test
+
+**A pull request that fixes a bug must add a test that fails before your change
+and passes after it.** This is the one rule reviewers will not waive. Say in the
+PR body which test it is, and confirm you watched it fail on the unfixed code —
+a test written after the fix that has never been seen red is not evidence the
+fix does anything.
+
+This matters more here than the phrase usually implies, because almost every bug
+this project has shipped failed *quietly*. A resume gate that accepts a stale
+cache, a coverage record written on a killed scan, a `task_done()` called twice,
+a masscan sweep aimed at the whole range instead of the live hosts — none of
+them raised, none of them printed anything wrong, and each produced a scan that
+reported itself complete while missing hosts. An operator cannot see that. The
+test suite is the only thing that can, so assert on the *specific* wrong
+behaviour, not merely that the function returns.
+
+Practical guidance:
+
+- Name the test after the behaviour, not the function, and put the reasoning in
+  the docstring. Match what is already in `tests/test_spoonmap.py` — the
+  docstrings there explain why the old behaviour was wrong, which is the part a
+  future reader needs.
+- Prove the failure mode, not the code path. If the bug under-scanned, assert on
+  the target set actually handed to masscan or nmap. If it lost results, assert
+  the retained host is still present in the written file.
+- New features need tests too, including the failure and interrupt paths.
+  `KeyboardInterrupt` is a `BaseException`, and getting that wrong has already
+  cost this repo a correctness bug.
+- If a bug is real but you are not fixing it in this PR, open an issue rather
+  than leaving it undocumented.
+
+Coverage is floored at 95% by pytest's `addopts`, so every job inherits it. Do
+not lower the floor to land a change.
+
+## Setting up
+
+Requires **Python 3.8 or newer**, [uv](https://docs.astral.sh/uv/), and both
+`masscan` and `nmap` installed as system binaries. `spoonmap.py` itself is
+dependency-free stdlib; everything in `uv.lock` is test tooling.
+
+```bash
+git clone https://github.com/<you>/spoonmap
+cd spoonmap
+uv sync
+```
+
+`uv.lock` is deliberately resolved for Python 3.10+ only, so it can hold a
+pytest patched for CVE-2025-71176. `requires-python` stays `>=3.8` because the
+tool itself runs there — if you are developing on 3.8 or 3.9, resolve the test
+tooling outside the project the way CI's `test-legacy` job does:
+
+```bash
+uv run --isolated --no-project --python 3.8 \
+  --with pytest --with pytest-cov --with pyyaml --with packaging \
+  pytest tests/ -v -rs
+```
+
+## Before you open a pull request
+
+Run everything below. These are the same gates CI runs, so running them locally
+is faster than waiting on a red check.
+
+```bash
+# Tests (the 95% coverage floor comes from pyproject.toml's addopts)
+uv run --frozen pytest -rs tests/
+
+# Lint
+uv run --frozen ruff check spoonmap.py tests/ tools/
+
+# Security
+uv run --frozen bandit -r spoonmap.py -c pyproject.toml -b .bandit-baseline.json
+
+# Lock file freshness (only if you touched pyproject.toml)
+uv lock --check
+
+# Workflow files (only if you touched .github/workflows/)
+uvx --from "actionlint-py==1.7.12.24" actionlint
+uvx zizmor==1.29.0 --persona=regular .github/workflows/
+```
+
+Notes on the gates:
+
+- **`ruff format` is deliberately not adopted.** Do not run it. Reformatting the
+  module and the test file would bury every future diff.
+- **`.bandit-baseline.json` is committed**, so only a *new* finding fails the
+  build. Do not add inline `# nosec` suppressions — if your change introduces a
+  finding that is genuinely fine, regenerate the baseline deliberately and
+  justify the addition in the commit message. The same goes for a type or lint
+  error: fix it, do not suppress it.
+- **Pass `-rs`.** Several NSE integration tests skip when the port they need is
+  occupied or when you are not root, and a bare pass count hides a test that
+  started skipping for the wrong reason. CI's `nse-root` job exists precisely
+  because a skip is not a failure.
+- Some NSE tests run only as root (the `-sU` path). You are not expected to run
+  those locally; CI does.
+
+## Commit messages
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org/),
+because the release version is derived from them by `tools/next_version.py`: any
+`feat` in a batch moves the minor version, while `fix`, `docs`, `chore` and
+friends move the patch. A `!` or a `BREAKING CHANGE:` footer counts as a
+feature — the major version is only ever bumped by hand.
+
+This makes your subject line load-bearing. **A feature typo'd as `fix:` ships as
+a patch release**, and there is no file to correct it in afterward: versions are
+tags cut by CI, not a string in the repository.
+
+Keep commits atomic — one logical change each. Reference an issue with `(#NNN)`
+at the end of the subject when one exists.
+
+## Adding or changing an NSE script
+
+Scripts under `nse/` ship inside the built wheel and sdist, and the `build` CI
+job asserts that both contain *exactly* the set of files in that directory —
+not merely a superset. So a script you leave there mid-engagement would ship to
+every install, and the build will tell you. Add only scripts intended for
+release.
+
+Bundled scripts that probe HTTP must send a `User-Agent` and must target
+`host.targetname` rather than `host.ip`, reading
+`stdnse.get_script_args('http.useragent')` first so the `scanner_profile`
+setting reaches them. See the "Scanner Signature Reduction" section of
+`CLAUDE.md` for why both are correctness requirements and not style points.
+
+## Reporting a bug
+
+Useful reports say what you ran, what happened, and what you expected — plus
+your OS, your Python version, and the versions of `masscan` and `nmap`
+(`masscan --version`, `nmap --version`). Include your `config.json` with the
+target paths and any client-identifying values removed, and say which scan type
+and `target_scan` you used.
+
+If the bug involves a crash, the traceback is the most valuable thing you can
+include. Read it for client hostnames and paths before you paste it.
+
+If the bug is a scan that reported itself complete but missed something, say how
+you know — that class of bug is the hardest to reproduce and the most important
+to fix.
+
+## Questions
+
+Open an issue. If you are unsure whether an idea fits, asking first is welcome
+and cheaper than building it.