Network Scanner

intent

run authorized network reconnaissance: host discovery, port scanning, service fingerprinting, CVE matching, SSL/TLS grading, traceroute, and subdomain enumeration. use this when you need to audit infrastructure you own or have explicit written permission to scan. pure python, no nmap, works on linux/wsl/windows. illegal to scan networks without authorization.

inputs

Required:

• target (string): single IP (e.g. 192.168.1.1), CIDR block (e.g. 192.168.1.0/24), domain name (e.g. example.com), or --local for local subnet discovery.
• scan depth (string): one of quick (9 ports), normal (20 ports), intense (100 ports), full (1-1024 ports), deep (1-65535 ports), or custom (requires --port-range).

Optional:

• --port-range START-END: custom port range (e.g. 1-10000). only with custom depth.
• --traceroute: enable network path analysis (shows hops to target). linux/wsl only; windows falls back to ipv4 ping.
• --subdomains: enumerate 35+ common subdomain prefixes via DNS lookup against discovered hosts.
• --workers N: thread pool size (default 10, max 150). higher = faster but louder; lower = stealthier.
• --rate-delay SECONDS: pause between requests (e.g. 0.05 for 50ms delay). stealth mode.
• --timeout SECONDS: per-connection timeout (default 3.0s). lower = faster but may miss slow services.
• --proxy PROXY_URL: http or socks5 proxy (e.g. socks5://127.0.0.1:1080). pro tier only.
• --format FORMAT: output style: discord (emoji-rich), simple (cli), json (machine), html (report). default simple.
• --output FILE: write results to file (e.g. report.html, scan.json). default stdout.
• --quiet: suppress progress output. exit codes only (0/2/3/4).

Environment/Setup:

• python 3.6+. pure stdlib; no required external deps. cryptography library optional for enhanced ssl cert parsing (auto-skipped if missing).
• network access to target(s): firewall, nat, vpn must permit icmp and tcp outbound.
• local root/admin privs (linux/wsl): icmp ping requires elevated perms; tcp connect scan does not.
• authorization: written permission from network owner before scanning.

procedure

1. parse cli arguments and validate target.

   • input: target string, depth string, optional flags.
   • output: normalized target list (ips or domains), scan config dict (workers, timeout, rate-delay, proxy, etc.).
   • edge case: invalid cidr notation (e.g. 192.168.1.0/33) fails with explicit error message.

2. resolve hostnames to ip addresses (if needed).

   • input: target list.
   • output: list of ipv4 addresses to scan.
   • edge case: dns lookup timeout or nxdomain (domain does not exist) logs warning, skips that target.

3. perform host discovery (icmp ping + tcp connect probe on port 80/443).

   • input: ip list, workers, timeout.
   • output: list of alive hosts with rtt_ms (round-trip time), ttl (time-to-live for os fingerprinting).
   • edge case: firewall blocks icmp. fallback: tcp connect probe on port 80 only. if both fail, host marked as down but still scanned if user insists.

4. os fingerprinting via ttl, window size, and port pattern heuristics.

   • input: alive hosts, icmp/tcp responses.
   • output: os_guess string (e.g. "Linux/Unix (TTL≈64)", "Windows (TTL≈128)").
   • edge case: ttl inconclusive (e.g. nat gateway obscures true ttl). os_guess marked as "unknown".

5. scan ports based on depth tier.

   • input: alive hosts, port range (from depth tier or custom), workers, timeout, rate-delay.
   • output: dict of open ports per host, keyed by port number. includes state (open/closed/filtered).
   • edge case: network timeout mid-scan. scanner logs error per host, continues. graceful Ctrl+C finishes current batch then exits (code 2).

6. banner grab and service fingerprinting on each open port.

   • input: open ports, timeout.
   • output: service name (http, ssh, mysql, etc.), version string (e.g. "Apache/2.4.41"), raw banner.
   • edge case: service does not respond to banner grab. version set to "unknown". scanner does not hang (timeout enforced).

7. http/https fingerprinting (if port 80 or 443 open).

   • input: target host, port 80/443.
   • output: server header, tech stack (wordpress, nginx, iis, etc.), page title, redirect chain.
   • edge case: http redirect chain loops or exceeds 5 hops. scanner stops and logs truncated chain. https with self-signed cert: ssl error caught, still reports server version from tls handshake.

8. ssl/tls analysis (if port 443 or custom https port open).

   • input: target host, port, timeout.
   • output: certificate subject/issuer, expiry date, protocol version (tls 1.2, 1.3, etc.), cipher list, grade (a-f), warnings (self-signed, expired, weak cipher).
   • edge case: certificate invalid or unparseable. cryptography lib missing: fallback to minimal tls handshake (no cert chain validation). grade defaults to "c".

9. cve matching against local database.

   • input: service name, version string.
   • output: list of matching cves. each cve: id, severity (critical/high/medium/low), description, cvss score (if available).
   • edge case: version string ambiguous (e.g. "Apache" with no minor version). scanner matches only major version. free tier: 40 cves. pro tier: 200 cves. bundle tier: 500 cves.

10. vulnerability severity classification per port.

    • input: cve list for port.
    • output: vuln_level (critical > high > medium > low > none). if no cves, level = none.
    • edge case: multiple cves with different severities. vuln_level is the max (e.g. if one critical + two medium, level = critical).

11. subdomain enumeration (if --subdomains flag set).

    • input: discovered hostname(s), 35+ subdomain prefixes (www, mail, api, admin, staging, etc.).
    • output: list of live subdomains (dns resolves and responds).
    • edge case: wildcard dns (*.example.com resolves to catch-all ip). scanner detects and logs "wildcard detected", includes all matching names anyway.

12. traceroute to target (if --traceroute flag set and linux/wsl).

    • input: target ip, timeout.
    • output: list of hops (ip, rtt_ms, rdns hostname if available).
    • edge case: windows platform. fallback to ipv4 ping only (no full traceroute). linux/wsl requires icmp privs (root); fails gracefully with warning.

13. format output (discord, simple, json, or html).

    • input: scan results dict (hosts, ports, cves, timings).
    • output: formatted string (console) or file written to disk.
    • edge case: json: large scan (100+ hosts, 1000s ports) may exceed memory. file written in streaming mode if available. html: requires html template; auto-fallback to json if template missing.

14. log summary stats and exit with appropriate code.

    • input: scan results, any errors.
    • output: exit code (0, 1, 2, 3, or 4), summary printed to stdout (unless --quiet).

decision points

• if target is --local or --local-scan flag: scan the local subnet (e.g. 192.168.1.0/24) using arp/icmp discovery. else: treat target as explicit ip/domain/cidr.

• if icmp ping succeeds on a host: mark host as alive, use ttl for os fingerprinting. else if tcp connect probe on port 80/443 succeeds: mark host as alive (firewall blocks icmp). else: mark host as down, skip scanning (unless user overrides with --force).

• if port is 80 or 443: perform http/https fingerprinting (server header, tech stack, title). else if banner grab succeeds: record service + version only.

• if port is 443 or custom https port: perform ssl/tls analysis and grading. else: skip ssl checks.

• if service version is identified: query cve database for matches. else: skip cve matching for that port, mark vuln_level as none.

• if --subdomains flag set: enumerate subdomains against each discovered hostname. else: skip subdomain enum.

• if --traceroute flag set and (linux or wsl): run traceroute. else if windows: fallback to ping only. else if not set: skip traceroute.

• if --format is json: output machine-readable json. else if html: output html report (requires template, fallback to json if missing). else if discord: output emoji-rich discord markdown. else (simple): output plain cli text.

• if --output FILE specified: write results to file. else: write to stdout.

• if --quiet flag set: suppress all progress output during scan, print only summary and exit code. else: print per-host progress and timings.

• if critical or high cve found during scan: exit code 3 or 4 respectively. else if scan interrupted: code 2. else if scan completes clean: code 0.

• if --workers > 150: cap at 150 (hard limit). warn user.

• if --rate-delay specified and --workers high: rate-delay may be ignored per thread (threads still run concurrent). document: rate-delay applies per worker, not global.

• if cryptography lib missing: ssl cert parsing degraded; tls handshake still works. warn once, continue.

• if proxy specified but free tier: error (pro tier feature). else: use proxy for all outbound connections.

• if dns lookup for hostname fails: log warning, skip that hostname. if all targets fail dns, exit code 1.

• if network timeout mid-port-scan: log error per host, continue to next host.

output contract

Exit codes:

• 0: scan complete, no critical or high cves found.
• 1: general error (invalid args, dns failure, etc.).
• 2: scan interrupted (ctrl+c).
• 3: critical cve detected.
• 4: high cve detected.

Data format (JSON output example):

{
  "target": "192.168.1.1",
  "scan_type": "intense",
  "timestamp": "2026-04-22 14:38:00",
  "duration_s": 12.3,
  "hosts": [
    {
      "ip": "192.168.1.1",
      "hostname": "server.example.com",
      "is_alive": true,
      "rtt_ms": 2.1,
      "ttl": 64,
      "os_guess": "Linux/Unix (TTL≈64)",
      "ports": {
        "80": {
          "port": 80,
          "state": "open",
          "service": "http",
          "version": "Apache/2.4.41",
          "banner": "Apache/2.4.41 (Ubuntu)",
          "vuln_level": "HIGH",
          "cves": [
            {
              "cve": "CVE-2017-15710",
              "severity": "MEDIUM",
              "description": "..."
            }
          ],
          "http_fingerprint": {
            "server": "Apache/2.4.41",
            "tech_stack": ["PHP", "WordPress"],
            "title": "My Site"
          }
        },
        "443": {
          "port": 443,
          "state": "open",
          "service": "https",
          "version": "nginx/1.18.0",
          "ssl": {
            "subject": "CN=example.com",
            "issuer": "CN=Let's Encrypt",
            "expiry": "2027-05-15",
            "protocol": "TLSv1.3",
            "grade": "A",
            "warnings": []
          },
          "vuln_level": "NONE"
        }
      },
      "subdomains": ["www.example.com", "mail.example.com"],
      "traceroute": [
        {"hop": 1, "ip": "192.168.1.1", "rtt_ms": 2.1, "hostname": "gateway"},
        {"hop": 2, "ip": "10.0.0.1", "rtt_ms": 5.3, "hostname": "isp-router"}
      ]
    }
  ],
  "stats": {
    "hosts_scanned": 1,
    "hosts_alive": 1,
    "ports_scanned": 100,
    "ports_open": 5,
    "critical_cves": 0,
    "high_cves": 1
  }
}

File locations:

• if --output report.html: html report written to report.html (in current dir).
• if --output scan.json: json written to scan.json.
• if no --output: results printed to stdout.

Discord format (emoji-rich example):

🔍 EdgeIQ Scan Report ,  `192.168.1.1`
Mode: `intense` | Risk: 🟠 HIGH | Duration: `12.3s`

🟢 192.168.1.1 ,  server.example.com `2.1ms` | 5 ports | HIGH
   └ OS: `Linux/Unix (TTL≈64)`
   └ Subdomains: `www.example.com`, `mail.example.com`
   80    http          Apache/2.4.41 🟠 HIGH
 443    https         nginx/1.18.0 [SSL: A]

─── Stats: 1 hosts | 100 ports scanned

outcome signal

• scanner completes and prints summary to console (or file if --output set).
• exit code matches expectation (0 for clean, 3/4 for cve found, 2 for interrupt).
• if --quiet: only exit code and final summary shown.
• if --format json: machine can parse results (curl to webhook, import to siem, etc.).
• if --format html: browser opens polished report with charts.
• if --format discord: webhook post appears in slack/discord channel with emoji-rich formatting.
• rtt_ms and port counts confirm scan ran fully (e.g. 100 ports scanned for intense depth).
• any critical or high cves listed and flagged with color/emoji.

credits: edgeiq-labs. original design and cve database. support: gpalmieri21@gmail.com, discord.gg/aPhSnrU9, edgeiqlabs.com.