Nmap Scanner

Run real Nmap scans against an IP, hostname, or CIDR range from inside the portal — using preset scan profiles or a sanitized manual command mode. Results are parsed into a port table with per-port risk ratings, and dangerous open ports raise alerts automatically.

Route: /nmap-scanner

How it works

Overview

The Nmap Scanner (shown in-app as Network Recon Scanner) runs the real nmap binary on the GuardFox server. When you start a scan the API spawns an nmap process with a fixed argument list, streams its stdout/stderr, and stores the result against your organization.

Scan lifecycle

You submit a target and a scan type (a preset, or manual with your own flags).
The server records the scan with status running and starts the process.
The browser polls the scan every 2 seconds for status and results.
When the process closes, the server parses the output and sets the status to completed (exit code 0) or failed.

What gets parsed

From the raw Nmap output the server extracts each port line into { port, protocol, service, version, state, risk } and, when present, an OS details line into an OS-detection string. Each known port is assigned a built-in risk rating — for example 23/Telnet, 445/SMB, 3389/RDP, 5900/VNC, 6379/Redis and 27017/MongoDB are rated critical; unknown ports default to info.

When a scan completes, every open port rated critical or high automatically creates an alert (source nmap-scanner, severity Critical or High) and triggers any matching SOAR playbooks.

Scans run against a 5-minute process timeout, and the nmap binary must be installed on the host running the portal. All scan endpoints require an authenticated session and are scoped to your organization.

Running a scan

How to use

Start a scan

Enter a Target — an IP, hostname, or CIDR range (for example 192.168.1.0/24 or scanme.nmap.org). A pasted http:// or https:// URL is reduced to its hostname automatically.
Choose a mode:
- Preset Scans — pick one of the eight profile cards.
- Manual Command — type your own Nmap arguments in the Nmap Arguments field.
The command preview line shows the nmap invocation and can be copied to the clipboard.
Click Scan. While a scan runs the button becomes Stop, which cancels the scan.

Reading the results

A status bar shows the scan status, target, scan type and duration.
Summary tiles count Total Ports, Open, Filtered, and High Risk ports, plus the detected OS when available.
Filter tabs switch between All / Open / Filtered / Closed ports.
Two views are available: a Table View (Port, State, Service, Version, Risk, Notes) and a Topology Map that plots the scanner, the current host, and recent history nodes.
Raw toggles the full Nmap text output; Export downloads the scan as a JSON file.

History

The History button opens a drawer of your recent scans (target, scan type, status, open-port count, timestamp). Selecting one loads it back into the results view.

Scan presets

Reference

The server owns the actual argument list for each preset (the on-screen preview is for display only). Most presets add -Pn to skip host discovery, since many internal hosts block ping/ARP probes while still having open TCP ports.

Preset	scanType	Nmap arguments (server-side)	Noise
Quick Scan	`quick`	`-T4 -F -Pn --open`	Low
Full TCP	`full_tcp`	`-sT -p- -T3 -Pn --open`	Medium
Service Detection	`service`	`-sV --version-intensity 5 -T4 -Pn`	Medium
OS Detection	`os_detect`	`-O --osscan-guess -T4 -Pn`	Medium
Vuln Scan	`vuln_scan`	`--script vuln -sV -T3 -Pn`	High
Stealth Scan	`stealth`	`-sS -T2 -Pn --open`	Low
UDP Top Ports	`udp`	`-sU --top-ports 100 -T4 -Pn`	Medium
Aggressive	`aggressive`	`-A -T4 -Pn --open`	High

Manual command mode

In manual mode your arguments are passed through a fail-closed sanitizer before nmap runs:

Any input containing a shell metacharacter (; & | ` $ ( ) { }) is rejected outright.
Only an allowlisted set of flags is permitted, including -sS, -sT, -sU, -sV, -sC, -O, -A, -Pn, -p, -F, --top-ports, -T0–-T5, --open, --reason, --version-intensity, --osscan-guess, --traceroute, --min-rate and --max-rate. Any other flag is refused.
Output flags (-oN/-oX/-oG/-oA), --script, and -iL are deliberately blocked in manual mode to prevent arbitrary file writes or loading untrusted scripts. (The vuln_scan preset uses --script only through its hardcoded, non-manual argument list.)

API reference

Reference

All endpoints require an authenticated GuardFox session (they return 401 otherwise) and only return scans belonging to your organization.

Method & path	Purpose
`POST /api/nmap/scan`	Start a scan; returns the new scan id and command.
`GET /api/nmap/scan/{id}`	Fetch one scan with parsed ports (used for 2-second polling).
`DELETE /api/nmap/scan/{id}`	Mark a scan as `cancelled`.
`GET /api/nmap/history`	List the 50 most recent scans (with port and open-port counts).

POST request body

Field	Type	Notes
`target`	string (required)	IP, hostname, or CIDR. A leading `http(s)://` is stripped to the hostname; must match the pattern for word characters, dots, dashes, colons and slashes; cannot start with `-`.
`scanType`	string	One of `quick`, `full_tcp`, `service`, `os_detect`, `vuln_scan`, `stealth`, `udp`, `aggressive`, or `manual`. An unknown value falls back to `quick`.
`manualArgs`	string	Only used with `scanType: "manual"`. Nmap flags passed through the allowlist sanitizer described above.

Start a preset scan

curl -X POST https://app.guardfoxsecurity.com/api/nmap/scan \
  -H 'Content-Type: application/json' \
  --cookie 'next-auth.session-token=YOUR_SESSION' \
  -d '{"target":"192.168.1.0/24","scanType":"quick"}'

# → { "scanId": "…", "command": "nmap -T4 -F -Pn --open 192.168.1.0/24", "status": "running" }

Start a manual scan, then poll

curl -X POST https://app.guardfoxsecurity.com/api/nmap/scan \
  -H 'Content-Type: application/json' \
  --cookie 'next-auth.session-token=YOUR_SESSION' \
  -d '{"target":"scanme.nmap.org","scanType":"manual","manualArgs":"-sV -p 1-1000 -T4"}'

# Poll for results using the returned scanId
curl https://app.guardfoxsecurity.com/api/nmap/scan/SCAN_ID \
  --cookie 'next-auth.session-token=YOUR_SESSION'

Scan object fields

A stored scan returns: id, target, command, scanType, status (running / completed / failed / cancelled), duration (seconds), osDetection, rawOutput, createdAt, completedAt, and a parsed ports array. Each port entry contains port, protocol (tcp/udp), state (open/closed/filtered), service, version, and risk (critical / high / medium / low / info).