I shipped an unauthenticated RCE in my own port scanner — here's the whole chain, and how I killed it

I built a web front end for an Nmap-based port scanner: a FastAPI backend, a React

dashboard, background scan jobs, a plugin system, the works. It ran fine. Then I

sat down and actually audited it like an attacker would — and the thing was a

textbook unauthenticated remote-code-execution box.

This is the full chain, why each link existed, and the exact fixes. Every bug

here is one you can ship in any tool that shells out to a subprocess, so the

lessons transfer well beyond this project.

Repo (hardened): https://github.com/DipesThapa/PortScanner

Framing note: this is my own project, audited and fixed by me. No third-party

systems were touched. Scanners are dual-use — only ever point one at hosts you

own or are authorised to test.

The stack in one breath

• 
  POST /api/scans accepts a JSON body (target, ports, scripts, extra nmap args).


• A JobManager runs the scan in a background thread, shelling out to nmap.


• A "deep-dive" feature runs follow-up tools (nmap, nuclei, testssl.sh)
  against an allowlist.


• A React dashboard talks to the API and a /ws/status WebSocket.

Four features, four attack surfaces. Here's how they combined.

Link 0: there was no authentication at all

The foundation of the whole chain: every route and the WebSocket were open.

No API key, no session, nothing. The Dockerfile bound 0.0.0.0:8000 and ran as

root. So everything below is reachable by anyone who can hit the port.

app = FastAPI(...)

api_router = APIRouter()          # no dependencies

# ... every scan/upload/deepdive route hangs off this open router

If your service does anything more privileged than serve static files, "we'll

add auth later" is how you end up here. Auth is link zero.

Link 1: Nmap argument injection (no shell required)

The scan target flowed from the JSON body straight into the Nmap argv:

def build_nmap_command(target, start_port, end_port, ...):

    command = ["nmap", "--reason", "-p", port_range, "-oX", "-"]

    # ...flags...

    command.append(target)        # <-- attacker-controlled, last positional

    return command

It's subprocess.run(command, shell=False), so there's no classic shell

injection. People stop worrying at that point. They shouldn't — you don't need

a shell to abuse a tool as powerful as Nmap. If target is

--script=/path/to/evil.nse, it's no longer a target; it's a flag. Nmap will

happily load and run that NSE (Lua) script. Nmap can also write files

(-oN /etc/cron.d/x), read files via scripts, and more. extra_args was passed

through verbatim too, so you didn't even need the trick.

shell=False protects you from the shell. It does nothing about the program

you're actually invoking interpreting its own arguments.

Link 2: uploaded scripts that authorised themselves

The deep-dive runner executed only allowlisted commands — good instinct. But

there was an upload endpoint:

async def save_script(self, name, content):

    script_path = scripts_dir / Path(name).name   # traversal handled, ok

    self._write_script(script_path, content)       # writes + chmod +x

    return str(script_path)



def _load_allowlist(self, initial):

    # ...

    for item in scripts_dir.glob("*"):

        if item.is_file():

            allowed.add(str(item.absolute()))       # <-- upload allowlists itself

Read those two together: an uploaded file is written, made executable, and then

added to the very allowlist that's supposed to gate execution. The allowlist

was checking a lock whose key it handed out for free. An allowlist that any input

can extend is not an allowlist.

The chain

No auth (link 0) + write-an-executable-and-allowlist-it (link 2) + get Nmap to

load an arbitrary NSE file (link 1) = an unauthenticated network attacker runs

code on the host. Each piece looked defensible in isolation. Chained, it's game

over. That's the thing about appsec: bugs compose.

The bonus one I didn't see coming: XXE

While wiring up CI I ran Bandit and it flagged

the XML parser:

import xml.etree.ElementTree as ET

root = ET.fromstring(xml_output)   # B314: untrusted XML

Nmap emits XML, and I parse it. But that XML describes the host you scanned —

which can be attacker-controlled. A hostile service can shape responses so the

resulting Nmap XML carries an XXE payload (file:///etc/passwd, entity

expansion, SSRF). The stdlib parser resolves external entities. Static analysis

caught a bug my manual review walked straight past.

The fixes

Authentication on everything. An X-API-Key dependency on the whole API

router; the WebSocket validates a token. Key comes from PORTSCANNER_API_KEY or

is generated to web_runs/.api_key (0600) on first boot — never anonymous.

Constant-time comparison.

api_router = APIRouter(dependencies=[Depends(require_api_key)])

Validate input; refuse flag-shaped values. Targets must match a hostname/IP/

CIDR pattern and cannot start with -. Dangerous flags (--script, -oN,

--datadir, …) are rejected in extra_args. And defence in depth: a --

sentinel before the target so Nmap stops parsing options.

command.append("--")      # everything after this is a positional, never a flag

command.append(target)

Stop uploads from self-authorising. Uploaded scripts are no longer added to

the allowlist; an operator must add them explicitly via env. Upload is disabled

entirely unless PORTSCANNER_ENABLE_SCRIPT_UPLOAD=1.

Kill the XXE with defusedxml.

from defusedxml.ElementTree import fromstring as _safe_fromstring

root = _safe_fromstring(xml_output)   # entities/DTDs refused

The rest: redact secrets (passwords, tokens, secret://) before logs hit the

DB; run the container as non-root with cap_net_raw scoped to the Nmap binary

only; pin dependencies. Then I locked it all in with a tests/test_security.py

suite (auth, injection, XXE, redaction) and CI: pytest, Bandit, pip-audit, and

CodeQL on every push.

Five things worth stealing

1. 
   Auth is link zero. Everything else is only as safe as "who can reach it."


2. 
   shell=False ≠ safe. The invoked program parses its own args. Put --
   before positionals and validate anything flag-shaped.


3. 
   An allowlist that inputs can extend isn't one. Authorisation and the data
   being authorised must not share a writer.


4. 
   Untrusted XML is untrusted even when you generate it — if it's derived
   from something an attacker controls, parse it with defusedxml.


5. 
   Automated scanners see what tired eyes miss. Bandit/CodeQL/pip-audit in CI
   caught a real bug I'd read past. Cheap, run them.

Full before/after is in the repo, including the threat model

and CI config. If you spot something I still got wrong, open an issue — that's

the point of publishing it.

https://github.com/DipesThapa/PortScanner