Metadata-Version: 2.4
Name: py-netrecon
Version: 0.1.0
Summary: Network reconnaissance toolkit — port scanning, service detection, OS fingerprinting, and more. Pure Python API over nmap.
Author-email: ghost <bill.jtrammell@gmail.com>
License: MIT
Project-URL: Homepage, https://pypi.org/project/netrecon/
Keywords: network,scanner,pentest,security,nmap,recon
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-nmap>=0.7.1
Dynamic: license-file

# netrecon

Network reconnaissance toolkit — port scanning, service detection, OS fingerprinting, and vulnerability scanning. Async Python API wrapping nmap.

## Install

```bash
pip install netrecon
```

Requires nmap installed on your system.

## Quick Start

```python
import asyncio
from netrecon import NetRecon

async def main():
    recon = NetRecon()
    result = await recon.quick_scan("192.168.1.1")
    print(result.summary())

asyncio.run(main())
```

## Scan Types

```python
recon = NetRecon()

# Quick scan — top 1000 ports
result = await recon.quick_scan("10.0.0.1")

# Full scan — all 65535 ports
result = await recon.full_scan("10.0.0.1")

# Vulnerability scan
result = await recon.vuln_scan("10.0.0.1")

# Stealth SYN scan
result = await recon.stealth_scan("10.0.0.1")

# UDP scan
result = await recon.udp_scan("10.0.0.1")

# Custom scan
result = await recon.scan("10.0.0.1", ports="80,443,8080", flags="-sV -O")
```

## Working with Results

```python
from netrecon import NetRecon

async def analyze():
    recon = NetRecon()
    result = await recon.scan("192.168.1.0/24")

    for host in result.hosts:
        print(f"{host.address} — {host.os_guess}")
        for port in host.open_ports:
            print(f"  {port.number}/{port.protocol} {port.service_name} {port.service_version}")

    # Summary
    print(result.summary())

    # Filter
    web_hosts = [h for h in result.hosts
                 if any(p.service_name in ('http', 'https') for p in h.open_ports)]

asyncio.run(analyze())
```

## Custom Scanner

```python
from netrecon import PortScanner

scanner = PortScanner()
result = scanner.scan_sync("10.0.0.1", ports="22,80,443")
```

## CTF Mode

Built-in helpers for capture-the-flag competitions:

```python
from netrecon import NetRecon

async def ctf_recon(target):
    recon = NetRecon()

    # Find all open services
    result = await recon.scan(target, ports="1-65535", flags="-sV -sC -O")

    # Look for interesting services
    for host in result.hosts:
        for port in host.open_ports:
            if port.service_version:
                print(f"[!] {port} — possible exploit target")

asyncio.run(ctf_recon("10.10.x.x"))
```

## Requirements

- Python 3.10+
- nmap installed on your system (`sudo apt install nmap`)

## License

MIT
