nu-recon

Single-host passive reconnaissance: one IPv4 in, one JSON report out.

Features • Installation • Usage • Report Fields • Example • Scope

---

nu-recon takes one IPv4 address and writes a JSON report. It queries four sources without sending an active scan: reverse DNS via gethostbyaddr, the Shodan host API for open ports and service banners, a single TLS certificate grab via stdlib ssl on a chosen port, and crt.sh certificate-transparency by hostname. The output is a flat JSON document with a per-service threat graph and a low / medium / high risk summary. Without a Shodan key, the tool substitutes labeled placeholder values and sets simulated: true.

This is the single-host deep read, not the population sweep. One IP, every source nu-recon knows, one document.

Features

• One IPv4 in, one JSON report out
• Four sources: reverse DNS, Shodan host API, TLS certificate, crt.sh certificate transparency
• Per-service threat graph (ssh, web, mysql, rdp) with threat, impact, likelihood, mitigation
• Three-tier risk summary (low / medium / high) with explicit rule: any exposed database port becomes high
• Offline mode (--no-network) loads simulated data for testing
• simulated: true flag set automatically when Shodan key is missing
• One runtime dependency (requests), Python 3.10 or later
• Pytest test suite

Installation

pip install -r requirements.txt
pip install -e .

The entry point nu-recon is registered via pyproject.toml. Python 3.10 or later.

Usage

nu-recon 192.0.2.10
nu-recon 192.0.2.10 -o report.json
nu-recon 192.0.2.10 --ssl-port 8443 --crtsh-identity example.com
nu-recon 192.0.2.10 --no-network
nu-recon 192.0.2.10 -v

Flag	Default	Effect
target	required	IPv4 address, validated at parse time
-o, --output	host-report.json	output JSON path
--shodan-key	SHODAN_API_KEY env	override the env var
--ssl-port	443	TLS port for certificate grab
--crtsh-identity	PTR name	domain to query on crt.sh (overrides the resolved PTR)
-v, --verbose	off	debug logging
--no-network	off	skip all network calls, load simulated data

Report fields

Field	Content
target_ip	input address
hostname	PTR record, or first Shodan hostname
geolocation	country, city, org, isp from Shodan
open_ports	sorted list of integers
services	list of {port, product, version, transport, banner}
web_technologies	{port, server, version} for ports 80, 443, 8080, 8443
ssl_certificate	port, subject, issuer, not_before, not_after, serial_number, san, der_sha256_bytes
crtsh_domains	sorted unique domain names from crt.sh
threat_graph	per-service {threat, impact, likelihood, mitigation} entries
risk_summary	overall_risk, open_ports_count, vulnerability_count, exposed_databases, exposed_management, recommendation
simulated	true when Shodan data was substituted

Risk level rule: any exposed database port (3306, 5432, 27017, 6379, 9200, 1433) becomes high. Two or more vulnerabilities, or management ports with more than five total open ports, becomes medium. Otherwise low.

Example

$ nu-recon 192.0.2.10 -o report.json
INFO nurecon.mapper: reverse DNS: host.example.com
INFO nurecon.mapper: crt.sh: 3 unique names
[+] report: report.json

{
  "timestamp": "2026-06-03T12:00:00+00:00",
  "target_ip": "192.0.2.10",
  "hostname": "host.example.com",
  "geolocation": {"country": "US", "city": "Anytown", "org": "Example Corp", "isp": "Example ISP"},
  "open_ports": [22, 443],
  "services": [
    {"port": 22, "product": "OpenSSH", "version": "8.9", "transport": "tcp", "banner": null},
    {"port": 443, "product": "nginx", "version": "1.24", "transport": "tcp", "banner": null}
  ],
  "ssl_certificate": {
    "port": 443,
    "subject": {"commonName": "host.example.com"},
    "issuer": {"organizationName": "Let's Encrypt"},
    "san": ["host.example.com"]
  },
  "crtsh_domains": ["host.example.com", "mail.example.com", "www.example.com"],
  "risk_summary": {
    "overall_risk": "low",
    "open_ports_count": 2,
    "exposed_databases": [],
    "exposed_management": [22],
    "recommendation": "reduce attack surface; verify each exposed service is intended"
  },
  "simulated": false
}

Tests

pip install -r requirements-dev.txt
pytest

Scope

nu-recon reads four passive sources and opens one TLS socket. It does not sweep ports, brute-force credentials, or run exploit traffic. The TLS certificate grab creates a single TCP connection to retrieve the peer certificate. Shodan and crt.sh queries generate log entries at those services. Use on assets you own or are explicitly authorized to test.

Our other projects

• aimap — AI/ML infrastructure fingerprint scanner
• scanner — fast banner stage for population sweeps
• tiptoe — quiet, congestion-controlled scanner for sensitive targets
• recongraph — typed provenance graph for multi-source recon
• BARE — semantic exploit-module ranking over scanner findings

License

MIT. Part of the NuClide toolchain. Contact: nuclide-research.com