TCP Recon Scanner by Nazariy Buryak (C00305614)

Command-line Python reconnaissance tool recon.py that probes targets, enumerates services and HTTP apps, inspects TLS, fingerprints web stacks, and emits machine-readable reports.

---

Project Overview

This tool performs a TCP connect scan against one or more hosts and a configurable set of ports. For each open port it optionally grabs service banners, probes HTTP and HTTPS services, and analyses TLS certificates to provide a more information about exposed services. It is intended for use in controlled environments such as labs or with explicit permission on target systems. The scanner outputs a human‑readable summary to the terminal and also writes structured JSON and CSV files for later analysis, scripting, or importing into other tools.

---

Requirements

Environment

• Python 3.10+ (uses modern type hints such as str | None)
• Network access to the target hosts and ports
• A Unix‑like environment (Linux/macOS) is recommended for easiest CLI usage

Python Dependencies

Install from requirements.txt:

requests>2.32.5
cryptography>46.0.3

Create a virtual environment and install:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

---

Running the Code

Targets file

--targets should point to a text file with one hostname or IP address per line, for example:

192.168.1.10
192.168.1.11
example.com
nmap.scanme.org

Empty lines and lines starting with # are ignored.

Basic usage

Example command:

python3 recon.py \
  --targets targets.txt \
  --ports 80,443,8000-8010 \
  --workers 50 \
  --http \
  --tls \
  --output lab1 \
  --timeout 3

Command‑line arguments

• --targets PATH
  Path to a file containing one host/IP per line (required).

• --ports SPEC
  Ports to scan (required). Supported formats:

  • Single port: 80
  • Comma‑separated: 80,443,8000
  • Ranges: 1-1024
  • Mixed: 80,443,8000-8010

• --timeout SECONDS
  Connection timeout in seconds (default: 2.0).

• --workers N
  Maximum number of concurrent worker threads (default: 20).

• --http
  Enable HTTP(S) probing and web fingerprinting on discovered open ports or ports that look like HTTP.

• --tls
  Enable TLS certificate retrieval and analysis on ports that likely speak TLS (e.g. 443, 8443, 9443 or TLS‑looking banners).

• --output PREFIX
  Path prefix for results. Writes:

  • PREFIX.results.json
  • PREFIX.results.csv

• --retry N
  Retries per host:port on unexpected errors (default: 1), with simple backoff between attempts.

• --resume
  Resume from an existing PREFIX.results.json if present. Only missing host:port combinations will be scanned.

• -v, --verbose
  Enable verbose debug logging to stderr.

Outputs

• Console summary:
  A simple overview of open, closed, and filtered ports per host.

• JSON: PREFIX.results.json
  Contains:

  • meta block with run metadata and CLI arguments
  • targets[host].ports[port] with:
    • Port status (open, closed, filtered, error)
    • Banner
    • HTTP block (status, headers, methods, favicon hash, fingerprint)
    • TLS block (subject, issuer, SAN, validity, key type/size, weak params)
    • Fingerprint tags and timestamps

• CSV: PREFIX.results.csv
  One row per open host:port with columns:

  • host
  • port
  • open
  • status_code
  • title
  • server_header
  • cert_subject_cn
  • cert_notAfter
  • banner_snippet
  • fingerprint_tags
  • http_methods_allowed
  • http_methods_unsafe

---

Features

TCP connect scan

• Multi‑host, multi‑port TCP connect scanning using socket and a thread pool.
• Classifies each port as:
  • open (connect success)
  • closed (connect refused/error)
  • filtered (timeout)
• Optional retries per host:port with simple exponential backoff.

Banner grabbing

• For each open TCP port, the scanner:
  • Opens a TCP connection and attempts to read up to 4096 bytes.
  • Tries to decode the banner as text; if that fails, stores base64‑encoded data instead.
• Banners are stored per port and a short prefix is used in CSV output.

HTTP(S) probe and web fingerprinting (--http)

For ports that look like HTTP or when --http is enabled:

• Tries http://host:port and (where appropriate) https://host:port.
• Follows redirects and records:
  • Final URL
  • HTTP status code
  • Server and Set-Cookie headers
  • Page <title> and <meta name="description">
  • First 4 KiB of the HTML body as a sample

Basic fingerprinting includes:

• CMS detection

  • WordPress: body markers and common paths such as /wp-login.php and /xmlrpc.php
  • Drupal: presence of drupal.settings
  • Joomla: characteristic meta tag

• Framework hints

  • From X-Powered-By, e.g. PHP, ASP.NET, Express, Django.

• WAF hints

  • Headers such as Sucuri, Cloudflare, ModSecurity.

• Auxiliary endpoints

  • Checks for robots.txt and sitemap.xml and records basic status.
  • Fetches /favicon.ico, stores a SHA‑256 hash for potential favicon‑based fingerprinting.

HTTP methods analysis(EXTRA REQUIREMENT)

• Sends an OPTIONS request and parses the Allow header if present.
• If Allow is missing, tests common methods (GET, POST, PUT, DELETE, PATCH) and considers 2xx/3xx as “allowed”.
• Identifies "unsafe" methods (currently PUT, DELETE, PATCH) to highlight potentially risky write operations.

TLS certificate analysis (--tls)

For likely TLS ports or TLS‑looking banners:

• Performs a TLS handshake using system CAs (verification enabled, but hostname checking disabled to support “host:port” scans).

• Extracts:

  • Subject CN
  • Issuer CN
  • Subject Alternative Name (SAN) DNS entries
  • Validity window (not_before, not_after) and an expired boolean
  • Public key type (e.g. RSA, ECDSA) and key size
  • Signature hash algorithm

• Flags weak parameters, such as:

  • RSA keys smaller than 2048 bits
  • EC curves considered weaker than secp256r1 / prime256v1
  • MD5‑based signature algorithms

Rate limiting

• All HTTP and TLS operations share a global rate limiter (MAX_REQUESTS_PER_SECOND).
• A lock and monotonic timestamps enforce a minimum delay between outbound HTTP/TLS requests across threads.
• This helps avoid flooding targets when scanning with many workers.

Resume support

• When --resume is used with --output PREFIX, the tool:
  • Reads PREFIX.results.json if it exists.
  • Skips host:port combinations that already have results.
  • Appends new results and writes an updated JSON/CSV.

---

Reflection

This project was more complex than a simple port scanner because it combines several parts into one CLI tool: TCP checks, multi‑threading, HTTP(S) analysis, and TLS certificate parsing. Making them all work together reliably meant carefully handling timeouts, errors, and shared state like the rate limiter and logging.

What went well / key learnings:

• Turning raw socket data into simple JSON/CSV output went well.
• Using cryptography to read TLS certs and understand their key details.
• Creating CLI flags that enable or disable features(HTTP,TLS, plain TCP) without making the tool hard and confusing to use

What was challenging:

• Making the scan handle slow or broken services without getting stuck.
• Cleaning up HTTP data (cookies, favicon hashes, methods) so it is easy to use later.
• Keeping scans fast with multiple workers while still limiting request rate to avoid sending too much traffic

Possible future improvements:

• Asynchronous (asyncio‑based) scanning instead of thread pools for better scalability.
• IPv6 support and optional UDP scanning.