NetSleuth

A fast, multi-threaded TCP port scanner with service fingerprinting, CVE vulnerability detection, and MITRE ATT&CK framework mapping.

Features

• Multi-threaded scanning - Configurable concurrency for fast scans
• Multi-target support - Single hosts, CIDR ranges, comma-separated lists, or file input
• Service fingerprinting - Detects SSH, HTTP, SMTP, FTP services with version info
• CVE vulnerability detection - Maps detected services to known CVEs with CVSS scores
• MITRE ATT&CK mapping - Links scan operations to ATT&CK techniques
• Banner grabbing - Captures service identification strings
• Structured exports - JSON/NDJSON output for automation
• Zero dependencies - Pure Python 3.10+ standard library

Installation

git clone <repository-url>
cd NetSleuth
pip install -e .

Development with tests:

pip install -e ".[dev]"
pytest  # 127 tests

Quick Start

Basic scan:

netsleuth scanme.nmap.org 22,80,443

Multiple targets:

netsleuth "host1.com,192.168.1.1" 22,80
netsleuth 192.168.1.0/24 80,443       # CIDR
netsleuth targets.txt 22,80,443       # File (one host per line)

Service fingerprinting:

netsleuth scanme.nmap.org 22,80 --fingerprint

CVE vulnerability detection:

# Create sample CVE database
python -c "from NetSleuth.vuln import create_sample_cve_db; create_sample_cve_db('cve_db.json')"

# Scan with CVE detection
netsleuth scanme.nmap.org 22,80 --fingerprint --cve-db cve_db.json

MITRE ATT&CK mapping:

netsleuth scanme.nmap.org 22,80 --fingerprint --cve-db cve_db.json --mitre

Export results:

netsleuth example.com 22,80,443 --json results.json
netsleuth example.com 22,80,443 --ndjson results.ndjson

Usage

Command Line

netsleuth <target> <ports> [OPTIONS]

Options

Flag	Description	Default
--timeout SECONDS	Connection timeout	0.5
--workers COUNT	Concurrent threads	100
--fingerprint	Enable service fingerprinting	off
--cve-db PATH	CVE database JSON file	-
--mitre	Show MITRE ATT&CK techniques	off
--json PATH	Export to JSON	-
--ndjson PATH	Export to NDJSON	-

Target Formats

• Single: example.com, 192.168.1.1
• Multiple: host1.com,host2.com,192.168.1.1
• CIDR: 192.168.1.0/24
• File: targets.txt (one per line, # for comments)

Port Formats

• Individual: 22,80,443
• Ranges: 1-1024
• Combined: 22,80,443,8000-9000

Output Examples

Basic scan:

Target: scanme.nmap.org (45.33.32.156)
PORT    STATE       LAT(ms)  BANNER
22      open        156.7    SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2.13
80      open        156.5    HTTP/1.1 200 OK...

With fingerprinting:

Target: scanme.nmap.org (45.33.32.156)
PORT    STATE       LAT(ms)  SERVICE     VERSION
22      open        156.7    ssh         6.6.1p1 Ubuntu-2ubuntu2.13
80      open        156.5    http        2.4.7

With CVE detection:

Target: scanme.nmap.org (45.33.32.156)
PORT    STATE       LAT(ms)  SERVICE     VERSION             VULNS
22      open        156.7    ssh         6.6.1p1 Ubuntu-2ubun 2 CVE(s)
        ⚠ CVE-2016-0777 [HIGH] CVSS: 7.5
          SSH client information leak and buffer overflow
        ⚠ CVE-2023-38408 [CRITICAL] CVSS: 9.8
          Remote Code Execution in OpenSSH forwarding

With MITRE ATT&CK:

============================================================
MITRE ATT&CK Techniques
==================================================

[T1595.002] Active Scanning: Vulnerability Scanning
  Tactic: Reconnaissance
  Description: Adversaries may scan victims for vulnerabilities...
  Reference: https://attack.mitre.org/techniques/T1595/002/

[T1190] Exploit Public-Facing Application
  Tactic: Initial Access
  Description: Adversaries may attempt to exploit a weakness...
  Reference: https://attack.mitre.org/techniques/T1190/
============================================================

Python API

Basic Scanning

from NetSleuth import resolve_host, scan_ports, parse_ports

# Resolve target
ip = resolve_host("example.com")

# Parse ports
ports = parse_ports("80,443,8000-8010")

# Scan
results = scan_ports(ip, ports, timeout=0.5, workers=100)

# Process results
for result in results:
    if result.state == "open":
        print(f"Port {result.port}: {result.banner or 'No banner'}")

Multi-Target Scanning

from NetSleuth import parse_targets, scan_targets, parse_ports

# Parse targets (CIDR, comma-separated, or file)
targets = parse_targets("192.168.1.0/30")

# Scan all targets
results_by_target = scan_targets(targets, parse_ports("22,80,443"), timeout=0.5)

for target, results in results_by_target.items():
    print(f"Target: {target}")
    for result in results:
        if result.state == "open":
            print(f"  Port {result.port}: {result.state}")

Service Fingerprinting

from NetSleuth import scan_ports, fingerprint_service

results = scan_ports("192.168.1.1", [22, 80], timeout=0.5)

for result in results:
    if result.state == "open" and result.banner:
        fp = fingerprint_service(result.port, result.banner)
        print(f"{fp.service} {fp.product} {fp.version}")

CVE Vulnerability Detection

from NetSleuth.vuln import create_sample_cve_db, load_cve_db, find_vulnerabilities

# Create sample database
create_sample_cve_db("cve_db.json")

# Load database
cve_db = load_cve_db("cve_db.json")

# Find vulnerabilities for detected product/version
vulns = find_vulnerabilities("OpenSSH", "6.6.1p1", cve_db)

for vuln in vulns:
    print(f"{vuln.cve} [{vuln.severity}] CVSS: {vuln.cvss}")
    print(f"  {vuln.description}")

Export Results

from NetSleuth import results_to_dict, write_json, write_ndjson

# Generate structured payload
payload = results_to_dict(targets, results_by_target, timeout=0.5, workers=100)

# Export
write_json("report.json", payload)
write_ndjson("report.ndjson", payload)

JSON Output Schema

{
  "tool": "NetSleuth",
  "version": "0.2.0",
  "timestamp": "2026-03-08T12:34:56.789012+00:00",
  "scan_config": {"timeout_seconds": 0.5, "workers": 100},
  "targets": [
    {
      "host": "example.com",
      "ip": "93.184.216.34",
      "results": [
        {
          "target": "example.com",
          "host": "93.184.216.34",
          "port": 22,
          "state": "open",
          "latency": 45.23,
          "banner": "SSH-2.0-OpenSSH_8.2p1",
          "service": "ssh",
          "version": "8.2p1",
          "product": "OpenSSH",
          "vulnerabilities": [
            {
              "cve": "CVE-2023-38408",
              "severity": "CRITICAL",
              "cvss": 9.8,
              "description": "Remote Code Execution",
              "references": ["https://nvd.nist.gov/vuln/detail/CVE-2023-38408"]
            }
          ],
          "error": null
        }
      ]
    }
  ]
}

Architecture

NetSleuth/
├── __init__.py      # Public API exports
├── models.py        # ScanResult dataclass
├── scanner.py       # Multi-threaded scanning engine
├── ports.py         # Port specification parser
├── targets.py       # Target parser (CIDR, files, etc.)
├── banner.py        # Service banner detection
├── fingerprint.py   # Service fingerprinting
├── vuln.py          # CVE vulnerability detection
├── mitre.py         # MITRE ATT&CK mapping
├── reporter.py      # JSON/NDJSON export
├── cli.py           # Command-line interface
└── utils.py         # Utility functions

Scanning Methodology

NetSleuth uses TCP connect scanning - the most reliable technique that completes the full three-way handshake (SYN → SYN-ACK → ACK).

Advantages:

• No elevated privileges required
• Works on all operating systems
• Highly reliable

Trade-offs:

• Leaves connection logs
• Cannot bypass simple firewalls

Port States:

• open - Connection successful
• closed - Connection refused
• filtered - Connection timeout
• error - Socket error

Service Fingerprinting

NetSleuth identifies services using banner analysis with regex patterns:

Supported Services:

• SSH - Extracts product (OpenSSH, Dropbear) and version from SSH-2.0- banners
• HTTP - Detects Apache, nginx, Microsoft-IIS with version numbers
• SMTP - Identifies Postfix, Exim, Microsoft ESMTP
• FTP - Recognizes vsFTPd, ProFTPD, Microsoft FTP

CVE Database Format

{
  "OpenSSH": {
    "7.4": [
      {
        "cve": "CVE-2018-15473",
        "severity": "MEDIUM",
        "cvss": 5.3,
        "description": "Username enumeration vulnerability",
        "references": ["https://nvd.nist.gov/vuln/detail/CVE-2018-15473"]
      }
    ],
    "*": [
      {
        "cve": "CVE-2023-38408",
        "severity": "CRITICAL",
        "cvss": 9.8,
        "description": "Remote Code Execution",
        "references": ["https://nvd.nist.gov/vuln/detail/CVE-2023-38408"]
      }
    ]
  }
}

Version matching supports:

• Exact: "7.4" matches "7.4"
• Prefix: "7.4p1" matches "7.4"
• Wildcard: "*" matches all versions

MITRE ATT&CK Techniques

NetSleuth maps operations to 6 ATT&CK techniques:

Technique ID	Name	Tactic	Scope
T1046	Network Service Discovery	Discovery	network_recon, service_enum, banner_grab
T1018	Remote System Discovery	Discovery	network_recon
T1595.001	Active Scanning: IP Blocks	Reconnaissance	network_recon
T1595.002	Active Scanning: Vulnerability	Reconnaissance	service_enum, vuln_detection
T1592.002	Gather Victim Host Information	Reconnaissance	banner_grab
T1190	Exploit Public-Facing Application	Initial Access	vuln_detection

Scope automatically selected based on flags:

• --cve-db → vuln_detection
• --fingerprint → service_enum
• Default → network_recon

Testing

pytest                           # Run all tests (127 tests)
pytest --cov=NetSleuth           # With coverage
pytest tests/test_ports.py -v    # Specific module

Test coverage:

• Port/target parsing
• Service fingerprinting
• CVE vulnerability matching
• MITRE ATT&CK mapping
• JSON/NDJSON serialization
• Multi-target scanning

Performance

Default: 100 concurrent workers. Increase for large scans:

netsleuth target.com 1-65535 --workers 500 --timeout 0.3

Limitations

NetSleuth is an educational tool with intentional limitations:

Feature	NetSleuth	Nmap
Scan types	TCP connect	TCP SYN/ACK/FIN, UDP, etc.
OS detection	No	Yes
Service versioning	Basic	Comprehensive
Firewall evasion	No	Yes
Performance	Good (Python)	Excellent (C)

Use NetSleuth for:

• Learning TCP networking
• Quick authorized checks
• Python workflow integration
• Educational demonstrations

Use Nmap for:

• Professional security assessments
• Comprehensive reconnaissance
• Stealth scanning
• Production operations

Legal & Ethical Usage

AUTHORIZATION REQUIRED - Only scan systems you own or have explicit written permission to test.

Unauthorized scanning may violate:

• Computer Fraud and Abuse Act (CFAA - US)
• Computer Misuse Act (UK)
• Local computer crime laws

Safe practice targets:

• scanme.nmap.org - Nmap's official test server
• localhost/127.0.0.1 - Your own machine
• Virtual machines you control
• Bug bounty programs (follow rules)

Disclaimer: Users are solely responsible for ensuring compliance with all applicable laws. This tool is provided "AS IS" without warranty.

Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/improvement)
3. Add tests for new functionality
4. Run test suite (pytest)
5. Submit pull request

License

Educational use only. See LICENSE file for details.