nmap-pentest-scans

Original source / Raw SKILL.md

---
name: nmap-pentest-scans
description: Plan and orchestrate authorized Nmap host discovery, port and service enumeration, NSE profiling, and reporting artifacts for in-scope targets.
---

# Nmap Pentest Scans

## Stage

- PTES: 2-3
- MITRE: TA0007 - Discovery

## Objective

Design reproducible Nmap scan workflows for authorized targets and produce deterministic scan-plan artifacts.

## Required Workflow

1. Validate scope before any active action and reject out-of-scope targets.
2. Require explicit authorization for non-dry-run execution.
3. Select profile (stealth, balanced, fast) and build command sequence.
4. Produce normalized findings and export deterministic artifacts.

## Execution

```bash
python skills/nmap-pentest-scans/scripts/nmap_pentest_scans.py --scope scope.json --target <target> --input <path> --output <path> --format json --dry-run
```

## Outputs

- `scan-plan.json`
- `scan-plan.md`
- `recommended-commands.txt`
- `findings/nmap-pentest-findings.json`
- `nmap-pentest-scans-report.json`

## References

- `references/tools.md`
- `references/scan-profiles.md`
- `skills/autonomous-pentester/shared/scope_schema.json`
- `skills/autonomous-pentester/shared/finding_schema.json`

## Legal and Ethical Notice

```text
WARNING AUTHORIZED USE ONLY
This skill prepares and can orchestrate live network scan workflows.
Use only with written authorization and approved scope.
```


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/tools.md

```markdown
# Nmap Pentest Scans Tools

| Tool | URL |
|---|---|
| Nmap | https://nmap.org/ |
| Nmap Reference Guide | https://nmap.org/book/man.html |
| NSE Script Docs | https://nmap.org/book/nse.html |
| Nmap NSE Script Index | https://nmap.org/nsedoc/ |

```

### references/scan-profiles.md

```markdown
# Nmap Scan Profiles

Use this reference to pick command templates quickly during authorized penetration tests.

## Table of Contents

1. Variables and Conventions
2. Baseline Setup
3. Host Discovery Profiles
4. Port Scan Profiles
5. Service and OS Fingerprinting
6. NSE Script Profiles
7. Firewall and Evasion Options
8. Performance and Reliability Tuning
9. Professional Runbooks
10. Output and Reporting
11. Common Pitfalls

## 1) Variables and Conventions

- Replace `<TARGET>` with host, CIDR, or range.
- Replace `<TARGETS_FILE>` with a newline-separated target list.
- Replace `<OUT>` with output prefix, for example `results/external-week1`.
- Run privileged scans as Administrator/root when required (`-sS`, raw packet features).
- Save outputs with `-oA <OUT>` whenever possible.

## 2) Baseline Setup

```bash
# Version check
nmap --version

# Basic syntax check on a target list
nmap -iL <TARGETS_FILE> -sn -n --reason -oA <OUT>-discovery
```

Use `-n` to skip DNS when speed and signal fidelity matter.

## 3) Host Discovery Profiles

```bash
# Standard ICMP + common probes
nmap -sn <TARGET> -n --reason -oA <OUT>-host-discovery

# ARP discovery on local network segment
nmap -sn -PR <TARGET> -n --reason -oA <OUT>-arp-discovery

# Discovery with TCP SYN ping to common service ports
nmap -sn -PS22,80,443,3389,445 <TARGET> -n --reason -oA <OUT>-syn-ping

# Discovery with TCP ACK ping
nmap -sn -PA80,443,3389 <TARGET> -n --reason -oA <OUT>-ack-ping

# Discovery with UDP ping
nmap -sn -PU53,67,68,123,161 <TARGET> -n --reason -oA <OUT>-udp-ping

# Treat all hosts as up (when ping is blocked)
nmap -Pn -sn <TARGET> -n --reason -oA <OUT>-no-ping
```

Use `-Pn` carefully because it increases scan time/noise on dead hosts.

## 4) Port Scan Profiles

### Fast Triage

```bash
# Top TCP ports, fast initial map
nmap -sS --top-ports 1000 <TARGET> -n -T3 --reason -oA <OUT>-tcp-top1000

# Fast scan preset
nmap -sS -F <TARGET> -n -T3 --reason -oA <OUT>-tcp-fast
```

### Full Coverage

```bash
# Full TCP port sweep
nmap -sS -p- <TARGET> -n -T3 --reason -oA <OUT>-tcp-all

# UDP common ports
nmap -sU --top-ports 200 <TARGET> -n -T2 --reason -oA <OUT>-udp-top200

# Combined TCP + UDP (costly)
nmap -sS -sU -p T:1-1000,U:53,67,68,69,123,137,138,139,161,162 <TARGET> -n -T2 --reason -oA <OUT>-tcp-udp-mixed
```

### Firewall State Mapping

```bash
# ACK scan to infer filtering
nmap -sA -p 22,80,443,3389 <TARGET> -n --reason -oA <OUT>-ack-map

# Window scan (stack-dependent)
nmap -sW -p 22,80,443 <TARGET> -n --reason -oA <OUT>-window-scan

# Maimon scan (niche behavior)
nmap -sM -p 80,443 <TARGET> -n --reason -oA <OUT>-maimon
```

### Non-SYN Alternatives

```bash
# TCP connect scan (no raw sockets needed)
nmap -sT -p- <TARGET> -n -T3 --reason -oA <OUT>-connect-all

# NULL / FIN / Xmas (mainly for stateless filtering checks)
nmap -sN -p 1-1024 <TARGET> -n --reason -oA <OUT>-null
nmap -sF -p 1-1024 <TARGET> -n --reason -oA <OUT>-fin
nmap -sX -p 1-1024 <TARGET> -n --reason -oA <OUT>-xmas
```

## 5) Service and OS Fingerprinting

```bash
# Service/version on known open ports
nmap -sV -p 22,80,443,445,3389 <TARGET> -n --version-intensity 7 --reason -oA <OUT>-svc

# Aggressive service probing
nmap -sV --version-all <TARGET> -n --reason -oA <OUT>-svc-all

# OS detection + traceroute
nmap -O --osscan-guess --traceroute <TARGET> -n --reason -oA <OUT>-os-trace

# Aggressive bundle (OS, version, scripts, traceroute)
nmap -A <TARGET> -n -T3 --reason -oA <OUT>-aggressive
```

Use `-A` on limited targets first because it can be noisy.

## 6) NSE Script Profiles

Prefer service-targeted scripts over broad categories when possible.

### Safe Baseline

```bash
# Default scripts on discovered services
nmap -sC -sV <TARGET> -n -T3 --reason -oA <OUT>-default-scripts

# Safe script category only
nmap --script safe -sV <TARGET> -n --reason -oA <OUT>-safe-category
```

### Web

```bash
nmap -p80,443 --script http-title,http-headers,http-methods,http-enum,http-server-header <TARGET> -n -oA <OUT>-http-enum
nmap -p443 --script ssl-cert,ssl-enum-ciphers,ssl-dh-params <TARGET> -n -oA <OUT>-tls-audit
```

### SMB / Windows

```bash
nmap -p139,445 --script smb-os-discovery,smb-protocols,smb-security-mode,smb2-security-mode <TARGET> -n -oA <OUT>-smb-posture
nmap -p445 --script smb-enum-shares,smb-enum-users,smb-enum-domains <TARGET> -n -oA <OUT>-smb-enum
```

### DNS, SNMP, LDAP, RDP, NTP

```bash
nmap -p53 --script dns-recursion,dns-nsid,dns-service-discovery <TARGET> -n -oA <OUT>-dns
nmap -p161 --script snmp-info,snmp-interfaces,snmp-processes,snmp-sysdescr <TARGET> -n -oA <OUT>-snmp
nmap -p389,636 --script ldap-rootdse,ldap-search <TARGET> -n -oA <OUT>-ldap
nmap -p3389 --script rdp-enum-encryption,rdp-ntlm-info <TARGET> -n -oA <OUT>-rdp
nmap -p123 --script ntp-info,ntp-monlist <TARGET> -n -oA <OUT>-ntp
```

### Auth and Brute Categories (High Risk, Explicit Approval)

```bash
# Run only when scope explicitly allows authentication testing
nmap --script auth -p 21,22,80,443,445 <TARGET> -n -oA <OUT>-auth-category
nmap --script brute -p 21,22,80,443,445 <TARGET> -n --script-args brute.firstonly=true -oA <OUT>-brute-category
```

### Vuln Category (High Risk, Explicit Approval)

```bash
# Scope this to specific hosts/services after baseline confirmation
nmap --script vuln -sV <TARGET> -n -T2 -oA <OUT>-vuln-category
```

Use `--script-args` for credentialed or tuned checks when needed.

## 7) Firewall and Evasion Options

Use only with written authorization and defined rules of engagement.

```bash
# Fragment packets
nmap -sS -f <TARGET> -n -oA <OUT>-frag

# Custom MTU (must be multiple of 8)
nmap -sS --mtu 24 <TARGET> -n -oA <OUT>-mtu

# Decoy scan
nmap -sS -D RND:5 <TARGET> -n -oA <OUT>-decoy

# Source port manipulation
nmap -sS --source-port 53 <TARGET> -n -oA <OUT>-srcport53

# Spoof MAC (local segment only)
nmap -sS --spoof-mac 0 <TARGET> -n -oA <OUT>-spoof-mac

# Append random payload bytes
nmap -sS --data-length 32 <TARGET> -n -oA <OUT>-data-length
```

If evasion is authorized, document business justification and expected impact.

## 8) Performance and Reliability Tuning

```bash
# Conservative and stealthier
nmap -sS --top-ports 1000 <TARGET> -n -T2 --max-retries 2 --scan-delay 5ms -oA <OUT>-slow-steady

# Balanced enterprise scan
nmap -sS --top-ports 1000 <TARGET> -n -T3 --min-rate 100 --max-retries 2 -oA <OUT>-balanced

# Faster scan in resilient environments
nmap -sS --top-ports 1000 <TARGET> -n -T4 --min-rate 500 --max-retries 1 --host-timeout 10m -oA <OUT>-fast
```

Useful options:

- `--min-rate` and `--max-rate` to control packet throughput.
- `--min-hostgroup` and `--max-hostgroup` to tune parallel hosts.
- `--min-parallelism` and `--max-parallelism` for probe concurrency.
- `--max-rtt-timeout` and `--initial-rtt-timeout` for high latency paths.

## 9) Professional Runbooks

### External Perimeter (Breadth First)

```bash
nmap -sn <TARGET> -n --reason -oA <OUT>-01-discovery
nmap -sS --top-ports 1000 <TARGET> -n -T3 --reason -oA <OUT>-02-tcp-top
nmap -sV -p <OPEN_TCP_PORTS> <TARGET> -n --reason -oA <OUT>-03-version
nmap --script safe -p <OPEN_TCP_PORTS> <TARGET> -n -oA <OUT>-04-safe-scripts
```

### Internal Network (Depth on Live Hosts)

```bash
nmap -sn -PR <TARGET> -n --reason -oA <OUT>-01-arp-discovery
nmap -sS -p- <TARGET> -n -T3 --reason -oA <OUT>-02-tcp-all
nmap -sU --top-ports 200 <TARGET> -n -T2 --reason -oA <OUT>-03-udp-top
nmap -sV -O --traceroute <TARGET> -n -T3 --reason -oA <OUT>-04-fingerprint
```

### Active Directory Focus

```bash
nmap -p53,88,135,139,389,445,464,636,3268,3269,3389 -sS -sV <TARGET> -n -T3 -oA <OUT>-ad-core
nmap -p389,636 --script ldap-rootdse,ldap-search <TARGET> -n -oA <OUT>-ad-ldap
nmap -p445 --script smb-os-discovery,smb-security-mode,smb2-security-mode,smb-enum-shares <TARGET> -n -oA <OUT>-ad-smb
```

### Web and TLS Focus

```bash
nmap -p80,443,8080,8443 -sS -sV <TARGET> -n -T3 -oA <OUT>-web-ports
nmap -p80,443,8080,8443 --script http-title,http-enum,http-methods,http-security-headers <TARGET> -n -oA <OUT>-web-scripts
nmap -p443,8443 --script ssl-cert,ssl-enum-ciphers,ssl-dh-params <TARGET> -n -oA <OUT>-tls-scripts
```

## 10) Output and Reporting

```bash
# Save all major formats
nmap -sS -sV <TARGET> -n --reason -oA <OUT>

# Human-readable
nmap -sS -sV <TARGET> -n --reason -oN <OUT>.nmap

# XML for parsers/automation
nmap -sS -sV <TARGET> -n --reason -oX <OUT>.xml

# Grepable format for quick extraction
nmap -sS -sV <TARGET> -n --reason -oG <OUT>.gnmap
```

Quick extraction examples:

```bash
# Open ports from gnmap output
grep "/open/" <OUT>.gnmap

# Open TCP services summary
grep "/open/tcp/" <OUT>.gnmap | cut -d " " -f 2-
```

## 11) Common Pitfalls

- Scanning UDP too broadly without timing controls can stall assessments.
- Using `-Pn` on large ranges can create excessive noise and long runtimes.
- Running intrusive NSE categories before baseline reconnaissance can break change windows.
- Interpreting `open|filtered` as open without corroborating evidence leads to false positives.
- Forgetting `-oA` impairs reproducibility and auditability.

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "0x-professor",
  "slug": "nmap-pentest-scans",
  "displayName": "Nmap Pentest Scans",
  "latest": {
    "version": "0.1.0",
    "publishedAt": 1772315593157,
    "commit": "https://github.com/openclaw/skills/commit/5cbc4f4a7b10aa359201dc630ba6458fa3876148"
  },
  "history": []
}

```

### scripts/nmap_pentest_scans.py

```python
#!/usr/bin/env python3
"""nmap-pentest-scans script - AUTHORIZED SECURITY TESTING ONLY."""
from __future__ import annotations

import argparse
import json
import re
import sys
from datetime import datetime, timezone
from pathlib import Path


SHARED_DIR = Path(__file__).resolve().parents[2] / "autonomous-pentester" / "shared"
if str(SHARED_DIR) not in sys.path:
    sys.path.insert(0, str(SHARED_DIR))

from pentest_common import (  # noqa: E402
    load_payload,
    render_result,
    resolve_artifact_path,
    resolve_output_file,
    validate_scope,
    write_placeholder_artifact,
)


SKILL_NAME = "nmap-pentest-scans"
REPORT_STEM = "nmap-pentest-scans-report"
GENERATED_OUTPUTS = [
    "scan-plan.json",
    "scan-plan.md",
    "recommended-commands.txt",
    "findings/nmap-pentest-findings.json",
]


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description=(
            "Build scope-validated Nmap command plans for host discovery, service "
            "enumeration, and targeted script checks."
        )
    )
    parser.add_argument("--scope", default="scope.json")
    parser.add_argument("--target", required=True)
    parser.add_argument("--input", default=".")
    parser.add_argument("--output", default=".")
    parser.add_argument("--format", choices=["json", "md", "csv"], default="json")
    parser.add_argument("--dry-run", action="store_true")
    parser.add_argument("--i-have-authorization", action="store_true")
    parser.add_argument(
        "--profile",
        choices=["stealth", "balanced", "fast"],
        default="balanced",
        help="Scan profile for command tuning.",
    )
    parser.add_argument(
        "--include-udp",
        action="store_true",
        help="Include recommended UDP command in generated plan.",
    )
    return parser.parse_args()


def normalize_target_basename(target: str) -> str:
    """Normalize target values for safe filesystem basenames."""
    normalized = re.sub(r"[^A-Za-z0-9._-]+", "-", target.strip())
    normalized = normalized.strip("-._")
    return normalized or "target"


def build_command_plan(target: str, profile: str, include_udp: bool) -> list[dict[str, str]]:
    target_basename = normalize_target_basename(target)

    if profile == "stealth":
        timing = "-T2"
        rate = "--max-retries 2 --scan-delay 5ms"
    elif profile == "fast":
        timing = "-T4"
        rate = "--min-rate 500 --max-retries 1 --host-timeout 10m"
    else:
        timing = "-T3"
        rate = "--min-rate 100 --max-retries 2"

    plan: list[dict[str, str]] = [
        {
            "stage": "host-discovery",
            "command": (
                f"nmap -sn {target} -n --reason "
                f"-oA results/{target_basename}-01-discovery"
            ),
            "purpose": "Detect responsive hosts and collect probe reasons.",
        },
        {
            "stage": "tcp-triage",
            "command": (
                f"nmap -sS --top-ports 1000 {target} -n {timing} {rate} --reason "
                f"-oA results/{target_basename}-02-tcp-top1000"
            ),
            "purpose": "Find common exposed TCP services quickly.",
        },
        {
            "stage": "service-enum",
            "command": (
                f"nmap -sV -sC -p <OPEN_TCP_PORTS> {target} -n {timing} --reason "
                f"-oA results/{target_basename}-03-svc-default"
            ),
            "purpose": "Fingerprint service versions and run default safe scripts.",
        },
        {
            "stage": "web-tls",
            "command": (
                f"nmap -p 80,443 --script http-title,http-headers,http-methods,ssl-cert "
                f"{target} -n --script-timeout 30s "
                f"-oA results/{target_basename}-04-web-tls"
            ),
            "purpose": "Capture web fingerprinting and TLS certificate posture.",
        },
    ]

    if include_udp:
        plan.append(
            {
                "stage": "udp-followup",
                "command": (
                    f"nmap -sU --top-ports 200 {target} -n -T2 --reason "
                    f"-oA results/{target_basename}-05-udp-top200"
                ),
                "purpose": "Enumerate common UDP services after TCP baseline.",
            }
        )
    return plan


def build_finding(target: str) -> dict:
    now = datetime.now(timezone.utc).isoformat()
    return {
        "finding_id": f"{SKILL_NAME.replace('-', '_')}-001",
        "skill": SKILL_NAME,
        "timestamp": now,
        "target": target,
        "title": "Nmap reconnaissance identified externally reachable services",
        "cve": "N/A",
        "cwe": "CWE-200",
        "cvss_score": 6.5,
        "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:L/A:N",
        "owasp_category": "A05:2021 - Security Misconfiguration",
        "mitre_attack": "TA0007 - Discovery",
        "severity": "Medium",
        "description": "Service exposure was identified and should be reviewed against hardened baseline policy.",
        "proof_of_concept": "nmap -sS --top-ports 1000 <target> -n --reason",
        "screenshot": "assets/findings/placeholder.png",
        "remediation": "Restrict unnecessary network exposure and enforce service-level hardening controls.",
        "references": ["https://nmap.org/docs.html", "https://nmap.org/book/nse.html"],
        "status": "open",
    }


def write_plan_markdown(path: Path, target: str, profile: str, plan: list[dict[str, str]]) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    lines = [
        f"# Nmap Plan for {target}",
        "",
        f"- profile: {profile}",
        f"- generated_at: {datetime.now(timezone.utc).isoformat()}",
        "",
        "## Command Sequence",
    ]
    for item in plan:
        lines.append(f"- [{item['stage']}] `{item['command']}`")
        lines.append(f"  purpose: {item['purpose']}")
    path.write_text("\n".join(lines) + "\n", encoding="utf-8")


def write_command_list(path: Path, plan: list[dict[str, str]]) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    payload = "\n".join(item["command"] for item in plan) + "\n"
    path.write_text(payload, encoding="utf-8")


def main() -> int:
    args = parse_args()
    scope_ok, scope_meta = validate_scope(args.target, args.scope)
    report_path = resolve_output_file(args.output, args.format, REPORT_STEM)

    if not scope_ok:
        result = {
            "status": "error",
            "summary": "TARGET NOT IN AUTHORIZED SCOPE - ABORTING",
            "artifacts": [str(report_path)],
            "details": {
                "skill": SKILL_NAME,
                "target": args.target,
                "scope": scope_meta,
                "dry_run": args.dry_run,
            },
        }
        render_result(result, report_path, args.format)
        print(json.dumps(result, indent=2))
        return 1

    if not args.i_have_authorization and not args.dry_run:
        result = {
            "status": "error",
            "summary": "You must pass --i-have-authorization to confirm written authorization.",
            "artifacts": [str(report_path)],
            "details": {
                "skill": SKILL_NAME,
                "target": args.target,
                "scope": scope_meta,
                "dry_run": args.dry_run,
            },
        }
        render_result(result, report_path, args.format)
        print(json.dumps(result, indent=2))
        return 1

    payload = load_payload(args.input)
    plan = build_command_plan(args.target, args.profile, args.include_udp)
    finding = build_finding(args.target)
    artifacts: list[str] = []

    if not args.dry_run:
        plan_json = resolve_artifact_path(report_path.parent, "scan-plan.json")
        write_placeholder_artifact(
            plan_json,
            {
                "skill": SKILL_NAME,
                "target": args.target,
                "profile": args.profile,
                "generated_at": datetime.now(timezone.utc).isoformat(),
                "plan": plan,
                "input_payload": payload,
            },
        )
        artifacts.append(str(plan_json))

        plan_md = resolve_artifact_path(report_path.parent, "scan-plan.md")
        write_plan_markdown(plan_md, args.target, args.profile, plan)
        artifacts.append(str(plan_md))

        cmd_txt = resolve_artifact_path(report_path.parent, "recommended-commands.txt")
        write_command_list(cmd_txt, plan)
        artifacts.append(str(cmd_txt))

        findings_json = resolve_artifact_path(report_path.parent, "findings/nmap-pentest-findings.json")
        write_placeholder_artifact(
            findings_json,
            {
                "skill": SKILL_NAME,
                "target": args.target,
                "generated_at": datetime.now(timezone.utc).isoformat(),
                "findings": [finding],
                "plan_summary": [item["stage"] for item in plan],
            },
        )
        artifacts.append(str(findings_json))

    result = {
        "status": "ok",
        "summary": "Dry run completed" if args.dry_run else "Skill executed",
        "artifacts": artifacts + [str(report_path)],
        "details": {
            "skill": SKILL_NAME,
            "target": args.target,
            "scope": scope_meta,
            "profile": args.profile,
            "include_udp": args.include_udp,
            "plan": plan,
            "findings": [finding],
            "expected_outputs": GENERATED_OUTPUTS,
            "dry_run": args.dry_run,
        },
    }
    render_result(result, report_path, args.format)
    print(json.dumps(result, indent=2))
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

```