Skip to content

feat: add interface/source_ip/router_ip config overrides for masscan and nmap - #66

Merged
Spoonman1091 merged 2 commits into
nightlyfrom
feature/network-override-interface-source-ip
Oct 13, 2026
Merged

Spoonman1091 merged 2 commits into
nightlyfrom
feature/network-override-interface-source-ip

Conversation

@Spoonman1091

Copy link
Copy Markdown
Collaborator

Summary

  • On hosts with more than one default route (NAT/VPN split-tunnel setups are the common case), masscan and nmap's own interface/next-hop auto-detection can fail outright (could not determine default interface) or silently pick the wrong path, so a scan goes out an interface that never reaches the target.
  • Adds three optional, independent config.json keys — interface, source_ip, router_ip — that pin masscan's --interface/--source-ip/--router-ip and nmap's -e/-S (with --disable-arp-ping auto-added whenever source_ip is set) explicitly. No interactive prompt, same posture as scanner_profile/honeypot_active_confirm — absent/empty means today's auto-detect behavior, byte-for-byte.
  • NetworkOverride is threaded as an explicit net_override=None parameter through all 3 masscan and 9 nmap command-building call sites (the loopback-only scanner_profile overlay-verify probes are deliberately excluded). New _config_network_override() validator exits on an invalid interface name or non-IPv4 address, matching _config_scanner_profile()'s posture.
  • CLAUDE.md documents the mechanism and failure mode; config.json.sample documents the three fields.

Test plan

  • uv run pytest tests/ — 1560 passed, 4 skipped (pre-existing environment skips), 99.97% coverage
  • tests/test_nse_integration.py (real nmap, root) — 23 passed, 3 skipped (pre-existing port-conflict skips)
  • ruff check spoonmap.py tests/ — clean
  • bandit -r spoonmap.py -b .bandit-baseline.json — no new findings
  • uv lock --check — lock is fresh
  • Manually validated against a real host with an ambiguous dual-default-route setup — masscan/nmap both failed/misrouted without the override and succeeded once interface/source_ip were pinned

🤖 Generated with Claude Code

larry.spohn and others added 2 commits October 12, 2026 20:36
…and nmap

On a host with more than one default route (NAT/VPN split-tunnel setups),
masscan and nmap's own interface/route auto-detection can fail outright or
silently pick the wrong path, scanning from an interface that never reaches
the target. These optional config.json knobs pin the interface, source IP,
and (masscan-only) router IP explicitly, threaded through every masscan and
nmap invocation.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…ride tests

macOS names its loopback interface lo0, not lo, so the valid-interface test
cases failed the real socket.if_nametoindex() check on macOS CI. Mock the
existence check instead of depending on any specific OS's real interfaces.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@Spoonman1091
Spoonman1091 merged commit b8df7ac into nightly Oct 13, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant