<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: automating-nmap-scanning-workflows
description: >-
  Automate Nmap scanning workflows with Python-nmap bindings, scheduled scans,
  result parsing, diff-based change detection, and integration into CI/CD and
  asset inventory pipelines. Covers NSE scripting and XML/JSON output processing.
domain: cybersecurity
subdomain: automation-scripting
tags:
  - nmap
  - network-scanning
  - asset-discovery
  - nse
  - vulnerability-scanning
  - automation
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: ["T1046"]
---

# Automating Nmap Scanning Workflows

## Overview

Nmap is the standard for network discovery and security auditing. This skill
covers automating Nmap scans with Python bindings, parsing XML output into
structured data, detecting infrastructure changes between scans, and integrating
scan results into asset management and vulnerability tracking workflows.

Mode: `[MODE: RECON]` — Automated reconnaissance and asset discovery.

## Prerequisites

| Requirement | Details |
|---|---|
| Nmap 7.90+ installed (`nmap --version`) | Required |
| `python-nmap` bindings (`pip install python-nmap`) | Required |
| Root/sudo for SYN scans and OS detection | Required |
| Network authorization for target ranges | Required |

## Key Concepts

### Python-Nmap Wrapper

```python
import nmap

def service_scan(target: str, ports: str = "1-1024") -> dict:
    """Run Nmap service version scan and return structured results."""
    nm = nmap.PortScanner()
    nm.scan(hosts=target, ports=ports, arguments="-sV -sC --open -T4")
    results = []
    for host in nm.all_hosts():
        for proto in nm[host].all_protocols():
            for port in nm[host][proto]:
                info = nm[host][proto][port]
                results.append({
                    "host": host,
                    "port": port,
                    "protocol": proto,
                    "state": info["state"],
                    "service": info.get("name", ""),
                    "version": info.get("version", ""),
                    "product": info.get("product", ""),
                })
    return {"target": target, "hosts_scanned": len(nm.all_hosts()), "services": results}
```

### Scan Diffing for Change Detection

```python
def diff_scans(previous: list[dict], current: list[dict]) -> dict:
    """Compare two scan results to find new/removed services."""
    prev_set = {(s["host"], s["port"], s["protocol"]) for s in previous}
    curr_set = {(s["host"], s["port"], s["protocol"]) for s in current}
    return {
        "new_services": [s for s in current if (s["host"], s["port"], s["protocol"]) not in prev_set],
        "removed_services": [s for s in previous if (s["host"], s["port"], s["protocol"]) not in curr_set],
    }
```

### NSE Script Automation

```bash
# Vulnerability detection
nmap --script vuln -sV -p 80,443 target

# SSL/TLS audit
nmap --script ssl-enum-ciphers,ssl-cert -p 443 target

# SMB enumeration
nmap --script smb-enum-shares,smb-enum-users -p 445 target

# HTTP enumeration
nmap --script http-enum,http-headers,http-methods -p 80,443 target
```

## Workflow

### Step 1: Run Discovery Scan

```bash
node scripts/agent.js --action discover --target 192.168.1.0/24 --output /tmp/nmap-discover.json
```

### Step 2: Service Version Scan

```bash
node scripts/agent.js --action service-scan --target 192.168.1.0/24 --ports 22,80,443,3389,8080
```

### Step 3: Diff Against Baseline

```bash
node scripts/agent.js --action diff --target 192.168.1.0/24 --baseline /tmp/nmap-baseline.json
```

## Verification

- [ ] Discovery scan identifies all live hosts on target network
- [ ] Service scan returns version info for open ports
- [ ] Diff correctly identifies new and removed services
- [ ] XML output parses without errors
- [ ] Scheduled scans complete within timeout window

## References

- [Nmap Documentation](https://nmap.org/book/)
- [NSE Script Library](https://nmap.org/nsedoc/)
- [python-nmap Documentation](https://xael.org/pages/python-nmap-en.html)
- [MITRE ATT&CK T1046 — Network Service Scanning](https://attack.mitre.org/techniques/T1046/)
