souleyez 2.43.29__py3-none-any.whl → 3.0.0__py3-none-any.whl

souleyez/plugins/nmap.py

@@ -10,7 +10,7 @@ from .plugin_base import PluginBase
 from souleyez.security.validation import (
     validate_target,
     validate_nmap_args,
-    ValidationError
+    ValidationError,
 )
 
 HELP = {
@@ -33,13 +33,13 @@ HELP = {
         "- Combine Nmap output with service-specific checks (banner grabs, vuln scanners) for richer context.\n"
         "- Always scan with permission — loud scans get noticed.\n"
     ),
-    "usage": "souleyez jobs enqueue nmap <target> --args \"<nmap flags>\"",
+    "usage": 'souleyez jobs enqueue nmap <target> --args "<nmap flags>"',
     "examples": [
-        "souleyez jobs enqueue nmap 10.0.0.0/24 --args \"-vv -sn\"",
-        "souleyez jobs enqueue nmap 10.0.0.82 --args \"-v -PS -F\"",
-        "souleyez jobs enqueue nmap 10.0.0.82 --args \"-vv -sV -O -p1-65535\"",
-        "souleyez jobs enqueue nmap 10.0.0.82 --args \"-sU -sV --top-ports 100\"",
-        "souleyez jobs enqueue nmap 10.0.0.82 --args \"--script vuln\"",
+        'souleyez jobs enqueue nmap 10.0.0.0/24 --args "-vv -sn"',
+        'souleyez jobs enqueue nmap 10.0.0.82 --args "-v -PS -F"',
+        'souleyez jobs enqueue nmap 10.0.0.82 --args "-vv -sV -O -p1-65535"',
+        'souleyez jobs enqueue nmap 10.0.0.82 --args "-sU -sV --top-ports 100"',
+        'souleyez jobs enqueue nmap 10.0.0.82 --args "--script vuln"',
     ],
     "flags": [
         ["-sn", "Ping scan (no port scan)"],
@@ -52,141 +52,304 @@ HELP = {
         ["-p1-65535", "Scan all TCP ports"],
         ["--top-ports N", "Scan N most common ports"],
         ["-sC/--script", "Run default/specific NSE scripts"],
-        ["-T0 to -T5", "Timing template (0=slowest, 5=fastest)"]
+        ["-T0 to -T5", "Timing template (0=slowest, 5=fastest)"],
     ],
     "preset_categories": {
         "discovery": [
             {
                 "name": "Ping Sweep",
                 "args": ["-vv", "-sn"],
-                "desc": "Host discovery (no port scan)"
+                "desc": "Host discovery (no port scan)",
             }
         ],
         "port_scanning": [
             {
                 "name": "Fast Scan",
-                "args": ["-v", "-PS", "-F", "-T4", "--host-timeout", "90s"],
-                "desc": "Top 100 ports, quick sweep"
+                "args": ["-Pn", "-v", "-PS", "-F", "-T4", "--host-timeout", "90s"],
+                "desc": "Top 100 ports, quick sweep",
             },
             {
                 "name": "Stealth Scan",
-                "args": ["-sS", "-T4", "--open"],
-                "desc": "SYN scan only (quiet, no version detection)"
+                "args": ["-Pn", "-sS", "-T4", "--open"],
+                "desc": "SYN scan only (quiet, no version detection)",
             },
             {
                 "name": "Full TCP Scan",
-                "args": ["-vv", "-sS", "-sV", "-sC", "-O", "-p-", "--script", "vuln", "-T4", "--host-timeout", "20m", "--open"],
-                "desc": "All 65535 ports with versions, OS, vulns"
-            }
+                "args": [
+                    "-Pn",
+                    "-vv",
+                    "-sS",
+                    "-sV",
+                    "-sC",
+                    "-O",
+                    "-p-",
+                    "--script",
+                    "vuln",
+                    "-T4",
+                    "--host-timeout",
+                    "20m",
+                    "--open",
+                ],
+                "desc": "All 65535 ports with versions, OS, vulns",
+            },
         ],
         "service_detection": [
             {
                 "name": "Service & Version",
-                "args": ["-sV", "-sC", "--open", "-T4"],
-                "desc": "Service detection + safe NSE scripts"
+                "args": ["-Pn", "-sV", "-sC", "--open", "-T4"],
+                "desc": "Service detection + safe NSE scripts",
             },
             {
                 "name": "Vulnerability Scan",
-                "args": ["-sV", "--script", "vuln", "--open"],
-                "desc": "Detect known vulnerabilities (CVEs)"
-            }
+                "args": ["-Pn", "-sV", "--script", "vuln", "--open"],
+                "desc": "Detect known vulnerabilities (CVEs)",
+            },
         ],
         "udp_scanning": [
             {
                 "name": "UDP Quick",
-                "args": ["-sU", "-sV", "--top-ports", "100"],
-                "desc": "Top 100 UDP ports"
+                "args": ["-Pn", "-sU", "-sV", "--top-ports", "100"],
+                "desc": "Top 100 UDP ports",
             },
             {
                 "name": "UDP Deep",
-                "args": ["-sU", "-sV", "--top-ports", "1000", "-T4", "--host-timeout", "20m", "--open"],
-                "desc": "Top 1000 UDP ports (slow)"
-            }
+                "args": [
+                    "-sU",
+                    "-sV",
+                    "--top-ports",
+                    "1000",
+                    "-T4",
+                    "--host-timeout",
+                    "20m",
+                    "--open",
+                ],
+                "desc": "Top 1000 UDP ports (slow)",
+            },
         ],
         "protocol_enumeration": [
             {
                 "name": "SMB Enumeration",
-                "args": ["-p445", "--script", "smb-enum-shares,smb-enum-users,smb-os-discovery"],
-                "desc": "Shares, users, OS discovery"
+                "args": [
+                    "-p445",
+                    "--script",
+                    "smb-enum-shares,smb-enum-users,smb-os-discovery",
+                ],
+                "desc": "Shares, users, OS discovery",
             },
             {
                 "name": "HTTP Enumeration",
-                "args": ["-p80,443,8080,8443", "--script", "http-enum,http-headers,http-methods,http-title"],
-                "desc": "Web server info, directories, headers"
-            }
-        ]
+                "args": [
+                    "-p80,443,8080,8443",
+                    "--script",
+                    "http-enum,http-headers,http-methods,http-title",
+                ],
+                "desc": "Web server info, directories, headers",
+            },
+        ],
     },
     "presets": [
         # Flattened list for backward compatibility - matches preset_categories order
         # Discovery
-        {"name": "Ping Sweep", "args": ["-vv", "-sn"], "desc": "Host discovery (no port scan)"},
-        # Port Scanning
-        {"name": "Fast Scan", "args": ["-v", "-PS", "-F", "-T4", "--host-timeout", "90s"], "desc": "Top 100 ports, quick sweep"},
-        {"name": "Stealth Scan", "args": ["-sS", "-T4", "--open"], "desc": "SYN scan only (quiet, no version detection)"},
-        {"name": "Full TCP Scan", "args": ["-vv", "-sS", "-sV", "-sC", "-O", "-p-", "--script", "vuln", "-T4", "--host-timeout", "20m", "--open"], "desc": "All 65535 ports with versions, OS, vulns"},
+        {
+            "name": "Ping Sweep",
+            "args": ["-vv", "-sn"],
+            "desc": "Host discovery (no port scan)",
+        },
+        # Port Scanning (all include -Pn to skip host discovery - many targets block ICMP)
+        {
+            "name": "Fast Scan",
+            "args": ["-Pn", "-v", "-PS", "-F", "-T4", "--host-timeout", "90s"],
+            "desc": "Top 100 ports, quick sweep",
+        },
+        {
+            "name": "Stealth Scan",
+            "args": ["-Pn", "-sS", "-T4", "--open"],
+            "desc": "SYN scan only (quiet, no version detection)",
+        },
+        {
+            "name": "Full TCP Scan",
+            "args": [
+                "-Pn",
+                "-vv",
+                "-sS",
+                "-sV",
+                "-sC",
+                "-O",
+                "-p-",
+                "--script",
+                "vuln",
+                "-T4",
+                "--host-timeout",
+                "20m",
+                "--open",
+            ],
+            "desc": "All 65535 ports with versions, OS, vulns",
+        },
         # Service Detection
-        {"name": "Service & Version", "args": ["-sV", "-sC", "--open", "-T4"], "desc": "Service detection + safe NSE scripts"},
-        {"name": "Vulnerability Scan", "args": ["-sV", "--script", "vuln", "--open"], "desc": "Detect known vulnerabilities (CVEs)"},
+        {
+            "name": "Service & Version",
+            "args": ["-Pn", "-sV", "-sC", "--open", "-T4"],
+            "desc": "Service detection + safe NSE scripts",
+        },
+        {
+            "name": "Vulnerability Scan",
+            "args": ["-Pn", "-sV", "--script", "vuln", "--open"],
+            "desc": "Detect known vulnerabilities (CVEs)",
+        },
         # UDP Scanning
-        {"name": "UDP Quick", "args": ["-sU", "-sV", "--top-ports", "100"], "desc": "Top 100 UDP ports"},
-        {"name": "UDP Deep", "args": ["-sU", "-sV", "--top-ports", "1000", "-T4", "--host-timeout", "20m", "--open"], "desc": "Top 1000 UDP ports (slow)"},
+        {
+            "name": "UDP Quick",
+            "args": ["-Pn", "-sU", "-sV", "--top-ports", "100"],
+            "desc": "Top 100 UDP ports",
+        },
+        {
+            "name": "UDP Deep",
+            "args": [
+                "-sU",
+                "-sV",
+                "--top-ports",
+                "1000",
+                "-T4",
+                "--host-timeout",
+                "20m",
+                "--open",
+            ],
+            "desc": "Top 1000 UDP ports (slow)",
+        },
         # Protocol Enumeration
-        {"name": "SMB Enumeration", "args": ["-p445", "--script", "smb-enum-shares,smb-enum-users,smb-os-discovery"], "desc": "Shares, users, OS discovery"},
-        {"name": "HTTP Enumeration", "args": ["-p80,443,8080,8443", "--script", "http-enum,http-headers,http-methods,http-title"], "desc": "Web server info, directories, headers"},
+        {
+            "name": "SMB Enumeration",
+            "args": [
+                "-p445",
+                "--script",
+                "smb-enum-shares,smb-enum-users,smb-os-discovery",
+            ],
+            "desc": "Shares, users, OS discovery",
+        },
+        {
+            "name": "HTTP Enumeration",
+            "args": [
+                "-p80,443,8080,8443",
+                "--script",
+                "http-enum,http-headers,http-methods,http-title",
+            ],
+            "desc": "Web server info, directories, headers",
+        },
         # Router/IoT Discovery
-        {"name": "UPnP Discovery", "args": ["-sU", "-sS", "-p", "U:1900,T:49152-49156,5000,2869", "--script", "upnp-info", "-T4", "--open"], "desc": "UPnP services on routers/IoT"},
-        {"name": "TR-069 Detection", "args": ["-sV", "-p", "7547,4567,5555,8089", "-T4", "--open"], "desc": "ISP remote management (CWMP)"},
+        {
+            "name": "UPnP Discovery",
+            "args": [
+                "-sU",
+                "-sS",
+                "-p",
+                "U:1900,T:49152-49156,5000,2869",
+                "--script",
+                "upnp-info",
+                "-T4",
+                "--open",
+            ],
+            "desc": "UPnP services on routers/IoT",
+        },
+        {
+            "name": "TR-069 Detection",
+            "args": ["-sV", "-p", "7547,4567,5555,8089", "-T4", "--open"],
+            "desc": "ISP remote management (CWMP)",
+        },
         # macOS Discovery
-        {"name": "macOS Services", "args": ["-sV", "-p", "548,5900,3283,5353", "--script", "afp-serverinfo,vnc-info", "-T4", "--open"], "desc": "AFP, VNC, ARD, Bonjour"},
-        {"name": "mDNS/Bonjour", "args": ["-sU", "-p", "5353", "--script", "dns-service-discovery,broadcast-dns-service-discovery", "-T4", "--open"], "desc": "Discover Apple devices via mDNS"}
+        {
+            "name": "macOS Services",
+            "args": [
+                "-sV",
+                "-p",
+                "548,5900,3283,5353",
+                "--script",
+                "afp-serverinfo,vnc-info",
+                "-T4",
+                "--open",
+            ],
+            "desc": "AFP, VNC, ARD, Bonjour",
+        },
+        {
+            "name": "mDNS/Bonjour",
+            "args": [
+                "-sU",
+                "-p",
+                "5353",
+                "--script",
+                "dns-service-discovery,broadcast-dns-service-discovery",
+                "-T4",
+                "--open",
+            ],
+            "desc": "Discover Apple devices via mDNS",
+        },
     ],
     "help_sections": [
         {
             "title": "What is Nmap?",
             "color": "cyan",
             "content": [
-                {"title": "Overview", "desc": "Nmap is the industry-standard network scanner for host discovery, port scanning, service detection, and OS fingerprinting."},
-                {"title": "Use Cases", "desc": "Essential for network reconnaissance and security assessments", "tips": [
-                    "Discover live hosts on the network",
-                    "Identify open ports and running services",
-                    "Fingerprint operating systems and service versions",
-                    "Find potential vulnerabilities with NSE scripts"
-                ]}
-            ]
+                {
+                    "title": "Overview",
+                    "desc": "Nmap is the industry-standard network scanner for host discovery, port scanning, service detection, and OS fingerprinting.",
+                },
+                {
+                    "title": "Use Cases",
+                    "desc": "Essential for network reconnaissance and security assessments",
+                    "tips": [
+                        "Discover live hosts on the network",
+                        "Identify open ports and running services",
+                        "Fingerprint operating systems and service versions",
+                        "Find potential vulnerabilities with NSE scripts",
+                    ],
+                },
+            ],
         },
         {
             "title": "How to Use",
             "color": "green",
             "content": [
-                {"title": "Basic Workflow", "desc": "1. Start with discovery sweep (-sn) to find live hosts\n     2. Run fast scan (-F) to identify open ports\n     3. Deep scan with version detection (-sV -O) for detailed info\n     4. Run vulnerability scripts (--script vuln) on targets"},
-                {"title": "Scan Types", "desc": "Different scans for different needs", "tips": [
-                    "Discovery: Quick ping sweep (no ports)",
-                    "Fast Scan: Top 100 ports with 90s timeout",
-                    "Full Scan: All 65535 ports with OS/version detection",
-                    "UDP Scan: Check for UDP services (slower)"
-                ]}
-            ]
+                {
+                    "title": "Basic Workflow",
+                    "desc": "1. Start with discovery sweep (-sn) to find live hosts\n     2. Run fast scan (-F) to identify open ports\n     3. Deep scan with version detection (-sV -O) for detailed info\n     4. Run vulnerability scripts (--script vuln) on targets",
+                },
+                {
+                    "title": "Scan Types",
+                    "desc": "Different scans for different needs",
+                    "tips": [
+                        "Discovery: Quick ping sweep (no ports)",
+                        "Fast Scan: Top 100 ports with 90s timeout",
+                        "Full Scan: All 65535 ports with OS/version detection",
+                        "UDP Scan: Check for UDP services (slower)",
+                    ],
+                },
+            ],
         },
         {
             "title": "Tips & Best Practices",
             "color": "yellow",
             "content": [
-                ("Best Practices:", [
-                    "Start with quick discovery before deep scans",
-                    "Use --host-timeout to skip slow/dead hosts",
-                    "Save XML output for parsing (-oX output.xml)",
-                    "Match scan intensity to your authorization level",
-                    "Combine with service-specific checks for full coverage"
-                ]),
-                ("Common Issues:", [
-                    "Slow scans: Use -F for fast mode or increase -T timing",
-                    "UDP timeout: Add --host-timeout 10m for UDP scans",
-                    "Missed hosts: Try different ping techniques (-PS, -PA, -PU)",
-                    "Permission denied: Some scan types require root/sudo"
-                ])
-            ]
-        }
-    ]
+                (
+                    "Best Practices:",
+                    [
+                        "Start with quick discovery before deep scans",
+                        "Use --host-timeout to skip slow/dead hosts",
+                        "Save XML output for parsing (-oX output.xml)",
+                        "Match scan intensity to your authorization level",
+                        "Combine with service-specific checks for full coverage",
+                    ],
+                ),
+                (
+                    "Common Issues:",
+                    [
+                        "Slow scans: Use -F for fast mode or increase -T timing",
+                        "UDP timeout: Add --host-timeout 10m for UDP scans",
+                        "Missed hosts: Try different ping techniques (-PS, -PA, -PU)",
+                        "Permission denied: Some scan types require root/sudo",
+                    ],
+                ),
+            ],
+        },
+    ],
 }
 
 
@@ -199,15 +362,28 @@ class NmapPlugin(PluginBase):
     def _requires_root(self, args: List[str]) -> bool:
         """Check if the nmap arguments require root/sudo privileges."""
         # UDP scans (-sU) and some other scan types require root
-        root_required_flags = ['-sU', '-sS', '-sA', '-sW', '-sM', '-sN', '-sF', '-sX', '-O']
+        root_required_flags = [
+            "-sU",
+            "-sS",
+            "-sA",
+            "-sW",
+            "-sM",
+            "-sN",
+            "-sF",
+            "-sX",
+            "-O",
+        ]
         return any(flag in args for flag in root_required_flags)
 
     def _is_root(self) -> bool:
         """Check if running as root."""
         import os
+
         return os.geteuid() == 0
 
-    def build_command(self, target: str, args: List[str] = None, label: str = "", log_path: str = None):
+    def build_command(
+        self, target: str, args: List[str] = None, label: str = "", log_path: str = None
+    ):
         """Build nmap command for background execution with PID tracking."""
         args = args or []
 
@@ -241,12 +417,11 @@ class NmapPlugin(PluginBase):
         if self._requires_root(args) and not self._is_root():
             cmd = ["sudo", "-n"] + cmd  # -n = non-interactive (no password prompt)
 
-        return {
-            'cmd': cmd,
-            'timeout': 3600  # 1 hour timeout
-        }
+        return {"cmd": cmd, "timeout": 3600}  # 1 hour timeout
 
-    def run(self, target: str, args: List[str] = None, label: str = "", log_path: str = None) -> int:
+    def run(
+        self, target: str, args: List[str] = None, label: str = "", log_path: str = None
+    ) -> int:
         """Execute nmap scan and write output to log_path."""
         args = args or []
 
@@ -293,7 +468,9 @@ class NmapPlugin(PluginBase):
         try:
             with open(log_path, "a", encoding="utf-8", errors="replace") as fh:
                 fh.write(f"Command: {' '.join(cmd)}\n")
-                fh.write(f"Started: {time.strftime('%Y-%m-%d %H:%M:%S UTC', time.gmtime())}\n\n")
+                fh.write(
+                    f"Started: {time.strftime('%Y-%m-%d %H:%M:%S UTC', time.gmtime())}\n\n"
+                )
                 fh.flush()
 
                 proc = subprocess.run(
@@ -301,10 +478,12 @@ class NmapPlugin(PluginBase):
                     stdout=fh,
                     stderr=subprocess.STDOUT,
                     timeout=3600,  # 1 hour timeout
-                    check=False
+                    check=False,
                 )
 
-                fh.write(f"\nCompleted: {time.strftime('%Y-%m-%d %H:%M:%S UTC', time.gmtime())}\n")
+                fh.write(
+                    f"\nCompleted: {time.strftime('%Y-%m-%d %H:%M:%S UTC', time.gmtime())}\n"
+                )
                 fh.write(f"Exit Code: {proc.returncode}\n")
 
                 return proc.returncode
@@ -328,14 +507,19 @@ class NmapPlugin(PluginBase):
         """Old-style execution for backward compatibility."""
         try:
             from ..scanner import run_nmap
-            logpath, rc, xmlpath, summary = run_nmap(target, args, label, save_xml=False)
+
+            logpath, rc, xmlpath, summary = run_nmap(
+                target, args, label, save_xml=False
+            )
             return rc
         except ImportError:
             # Split target on whitespace to handle multiple IPs/hosts
             target_list = target.split()
             cmd = ["nmap"] + (args or []) + target_list
             try:
-                proc = subprocess.run(cmd, capture_output=True, timeout=3600, check=False)
+                proc = subprocess.run(
+                    cmd, capture_output=True, timeout=3600, check=False
+                )
                 return proc.returncode
             except Exception:
                 return 1