netpulse-discovery 0.1.0

High-speed network discovery and drift analysis engine

NetPulse Discovery

NetPulse Discovery is a high-performance, asynchronous network mapping and drift-analysis engine. By offloading packet-level networking to a compiled Rust core, it achieves near wire-speed execution while maintaining a flexible, developer-friendly Python API.

🚀 Key Features

• Blazing Fast Scans: Leverages libpcap and raw sockets in Rust to execute ARP and ICMP sweeps orders of magnitude faster than standard Python libraries.
• Asynchronous Port Scanning: Native asyncio TCP connect scanner that can check hundreds of ports across multiple devices concurrently.
• Drift Detection: Built-in intelligence to compare historical scans and calculate exact topological drift (e.g., "Host 192.168.1.5 went offline").
• MAC Vendor Resolution: Automatically translates hardware MAC addresses into human-readable manufacturer names.
• Standalone API & CLI: Usable as a Python library, a Typer-powered CLI, or a FastAPI REST microservice.

📦 Installation

Since NetPulse Discovery is part of the NetPulse workspace, it relies on uv for dependency management and workspace resolution.

uv sync

⚡ Quickstart

As a CLI Tool

The standalone CLI returns structured JSON output perfect for piping into jq or other tools.

# Note: Raw sockets require elevated privileges
sudo uv run netpulse-discovery scan 192.168.1.0/24 --timeout 500

As a Python Library

Embed the high-performance engine directly into your own applications:

import asyncio
from netpulse.discovery.services.discovery import DiscoveryService
from netpulse.discovery.models.discovery import DiscoveryMethod

async def main():
    service = DiscoveryService()
    # Scans the network using ARP resolution
    result = await service.discover_network(
        "10.0.0.0/24", 
        methods=[DiscoveryMethod.ARP]
    )
    
    for device in result.devices:
        print(f"[{device.ip}] {device.mac} - {device.vendor}")

asyncio.run(main())

📚 Documentation

For more detailed guides, check out the docs/ folder:

• Usage Guide
• Architecture Overview
• Contributing Guidelines