NetRecon

A lean, production-quality network reconnaissance CLI tool with an optional local web dashboard. Built for authorized security testing on private infrastructure and authorized targets.

Current Version: 0.1.0

Key Features

• Port Scanning — TCP connect scans on common ports (top 100 by default) with concurrent connection handling
• Service Identification — Service detection by port number and optional banner grabbing
• DNS Enumeration — A/AAAA/MX/NS/TXT/CNAME/SOA record resolution, subdomain bruteforcing, and zone transfer detection
• Risk Annotation — Flagging of well-known risky services (FTP, Telnet, RDP, unauth databases, etc.)
• Multiple Report Formats — JSON, CSV, and Markdown output for both CLI and web dashboard
• Local Web Dashboard — Optional Flask-based local dashboard for interactive scanning (127.0.0.1-only, no auth required)

Design Principles

Production-Quality Code

• Type hints on all public functions
• Comprehensive Google-style docstrings
• Structured data returned from core modules (no direct printing from scanner/dns_enum)
• Full unit test coverage with mocked network calls

Lean Dependencies

• Required: dnspython, flask
• Optional: scapy (for SYN scans), rich (for pretty output)
• Core CLI (scan, dns, full commands) works without Flask

Separation of Concerns

The project maintains strict separation between layers:

CLI (main.py) ─┐
               ├─→ Core Modules ──→ Reporter ──→ Output (JSON/CSV/MD)
Web (app.py) ──┘   (scanner.py)
               └─→ (dns_enum.py)

Both CLI and web dashboard use the same core scanning and DNS modules. The web layer is purely a presentation layer—it imports and calls the same functions the CLI uses.

Security by Design

Authorized Use Only

• Startup banner on both CLI and web dashboard reminding users of legal requirements
• Automatic checks prevent scanning non-private/non-loopback targets without explicit --confirm-authorized flag (CLI) or checkbox acknowledgment (web)
• This mirrors best practices from tools like nmap — a legal safeguard, not a technical restriction

Local-Only Web Dashboard

• Binds to 127.0.0.1 by default (loopback-only)
• No authentication system (single-user, local tool)
• No CORS or public deployment support
• No persistent database (session history only, cleared on restart)
• Designed as an interactive local tool, not a hosted service

Installation

Requirements

• Python 3.9+
• pip or conda

From Source

git clone <repo>
cd netrecon
pip install -e .

Optional Dependencies

For SYN scanning and rich terminal output:

pip install -e ".[extras]"

For development (tests):

pip install -e ".[dev]"

Usage

CLI: Port Scanning

Scan the top 100 ports on a target:

netrecon scan 192.168.1.1 -o reports/scan1

Scan a specific port range:

netrecon scan 192.168.1.1 --ports 80,443,8080 -o reports/scan2

Scan the top 1000 ports with custom timeout:

netrecon scan 192.168.1.1 --top-ports 1000 --timeout 2.0 -o reports/scan3

Scan a network (CIDR):

netrecon scan 192.168.1.0/24 --confirm-authorized -o reports/network

CLI: DNS Enumeration

Enumerate DNS records:

netrecon dns example.com -o reports/dns1

Bruteforce subdomains:

netrecon dns example.com --wordlist wordlists/subdomains-small.txt -o reports/dns2

Attempt zone transfer:

netrecon dns example.com --zone-transfer -o reports/dns3

CLI: Full Reconnaissance

Run a complete reconnaissance pipeline (discovery → port scan → DNS):

netrecon full example.com --confirm-authorized -o reports/full_example

CLI: Output Formats

Generate reports in multiple formats:

netrecon scan 192.168.1.1 --format all -o reports/

Supported formats:

• json — Structured JSON output
• csv — Flat CSV table of open ports
• markdown — Human-readable markdown report (portfolio-friendly)
• all — Generate all three formats

Web Dashboard

Launch the local web dashboard:

netrecon web

This will:

1. Print the authorization banner
2. Start the Flask server on 127.0.0.1:5000
3. Automatically open your browser (use --no-browser to skip)

Then:

1. Enter a target (IP, CIDR, or domain)
2. Choose port range (top 100 or top 1000)
3. Optionally enable DNS enumeration
4. Check the authorization box
5. Click "Start Scan"

Results can be viewed in-browser or downloaded as JSON/CSV/Markdown.

Ethical Use

⚠️ AUTHORIZED USE ONLY

This tool is designed for authorized security testing only. Unauthorized access to computer networks is illegal in most jurisdictions. Before using this tool:

1. Get Written Permission — Ensure you have explicit written authorization from the network owner or administrator
2. Understand the Law — Unauthorized network scanning may violate laws like the Computer Fraud and Abuse Act (CFAA) in the US and similar laws globally
3. Test on Your Own Infrastructure — Use this tool on networks you own or have authority to test
4. Respect Scope — Only scan targets explicitly authorized in your testing agreement
5. Report Findings Responsibly — If you discover security issues, disclose them responsibly to the affected organization

The tool includes safeguards (authorization banners, confirmation flags) as a reminder, not as a complete legal safeguard. You are responsible for ensuring legal compliance.

Common authorized use cases:

• Testing your own infrastructure
• Penetration testing under contract
• Educational labs and CTF competitions (with explicit permission)
• Security research on systems you own or have permission to test

Architecture

┌────────────────────────────────────────────────────────┐
│ netrecon/                                              │
│ ├── __init__.py                                        │
│ ├── main.py              (CLI entrypoint, argparse)    │
│ ├── config.py            (defaults, port lists)        │
│ ├── utils.py             (validation, logging)         │
│ ├── scanner.py           (port scanning, host disco.)  │
│ ├── dns_enum.py          (DNS resolution, bruteforce)  │
│ ├── reporter.py          (ScanResult, report formats)  │
│ └── web/                                               │
│     ├── app.py           (Flask factory, routes)       │
│     ├── templates/       (Jinja2 templates)            │
│     │   ├── base.html    (layout)                      │
│     │   ├── index.html   (scan form)                   │
│     │   ├── results.html (results display)             │
│     │   └── history.html (past scans)                  │
│     └── static/                                        │
│         └── style.css    (responsive styling)          │
│                                                         │
├── tests/                                               │
│ ├── test_scanner.py      (port scan logic)             │
│ ├── test_dns_enum.py     (DNS functions)               │
│ ├── test_reporter.py     (report generation)           │
│ └── test_web.py          (Flask routes, mocked scans)  │
│                                                         │
├── wordlists/                                           │
│ └── subdomains-small.txt (for bruteforcing)            │
│                                                         │
├── reports/               (gitignored, output dir)      │
├── pyproject.toml         (project metadata, deps)      │
├── README.md              (this file)                   │
└── .gitignore             (ignore compiled, reports)    │

Data Flow

1. Scanner Module → Returns {port: state} dict, never prints
2. DNS Module → Returns {record_type: [values]} dict
3. Reporter Module → Consumes dicts, generates structured ScanResult
4. CLI → Formats and prints results, writes files
5. Web → Passes ScanResult to Jinja2 templates for rendering

This separation ensures:

• Core logic is testable without I/O
• Both CLI and web reuse the same scanning code
• Adding new output formats is trivial (add a method to reporter.py)
• No cross-module dependencies or circular imports

Testing

Run all tests:

pytest

Run tests with coverage:

pytest --cov=netrecon

Run a specific test file:

pytest tests/test_scanner.py -v

Test Coverage

• scanner.py — Port scanning, banner grabbing, service identification (mocked sockets)
• dns_enum.py — DNS resolution, subdomain bruteforce, zone transfer (mocked DNS resolver)
• reporter.py — ScanResult creation, report generation (JSON/CSV/MD)
• web/app.py — Flask routes, form validation, result rendering (test client, mocked scanner)

All tests use unittest.mock to mock network calls — the test suite runs completely offline.

Debugging

Enable verbose logging:

netrecon -v scan 192.168.1.1

Suppress non-error output:

netrecon -q scan 192.168.1.1

Known Limitations (v1)

• No active vulnerability scanning (port/service discovery only)
• SYN scans require root privileges and scapy (opt-in via --syn flag, currently not implemented)
• Long-running scans (full port range, large CIDR blocks) may timeout on the web UI — CLI is recommended for large scans
• Scan history is in-memory only (cleared on restart)
• No multi-user support or authentication on web dashboard
• No scheduled/automated scans

These are intentionally out of scope for v1. The tool is designed to be lean and focused on core reconnaissance functionality.

Future Considerations (v2+)

• WebSocket-based progress updates for long scans
• Persistent scan history (SQLite)
• SYN scan support with privilege escalation prompts
• Vulnerability database lookups for discovered services
• Massscan integration for high-speed scanning
• Multi-user web interface with authentication
• Automated scan scheduling and reporting
• Integration with external APIs (Shodan, VirusTotal, etc.)

License

MIT License

Contributing

This is a portfolio project. If you'd like to suggest improvements or report bugs, please open an issue or submit a PR.

Disclaimer

This tool is provided for authorized security testing and educational purposes only. Users are solely responsible for complying with all applicable laws and regulations. The author is not responsible for misuse of this tool.