# janidu-dm/net_scanner architecture

> Architecture diagram of the GitHub repository janidu-dm/net_scanner, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/janidu-dm/net_scanner
- Repository: https://github.com/janidu-dm/net_scanner

## Overview

##### Project type and purpose
- This is a Python-based command-line network scanner utility (net_scn.py) whose purpose is to discover live hosts on the local network, collect their IP/MAC addresses, look up their vendor details (either via a local CSV file or an online API), and render the results in a human-readable table.

##### File structure
- Top-level files:
– net_scn.py: orchestrator script containing CLI, scanning logic, vendor lookup logic, and output formatting.
– mac-vendors-export.csv: static dataset for “fast” (offline) vendor lookups.
– query/ : likely a package or module that encapsulates calls to the external MAC lookup API.
- Config/build/deployment files (.gitattributes, LICENSE, README.md) are present but do not affect runtime architecture.

##### README for additional insights
- Two scan modes:
– Fast Scan (local CSV lookup)
– Advanced Scan (one-second-throttled API calls via the external service)
- Dependencies: scapy (for ARP scanning), requests (for API calls), psutil/socket/ipaddress (for interface detection), pyfiglet (optional UI flourish), csv/time.

##### Main components
a. User Interface (CLI)
– Accepts user input (mode selection, exit).
– Displays prompts and renders final results.
b. Network Discovery Engine
– Uses scapy (ARP requests) plus psutil/socket/ipaddress to enumerate local IP range and detect live hosts.
c. Vendor Lookup Engine
– Local Lookup Module
- Reads mac-vendors-export.csv using the csv library.
– Remote API Module (query/)
- Issues HTTP requests via requests.
- Honors the API rate limit (time.sleep to enforce 1s interval).
d. Data Stores & External Services
– Local Dataset: mac-vendors-export.csv
– External MAC Vendor API (over HTTP/HTTPS)
e. Output Formatter
– Formats and prints a table of IP, MAC, Vendor.
– Optionally uses pyfiglet for headers/styling.

##### Interactions and data flows
1. User runs “python net_scn.py” → CLI component starts.
2. CLI queries user for scan mode selection.
3. CLI invokes Network Discovery Engine:
- Scans IP range → returns list of (IP, MAC).
4. For each detected host, CLI passes MAC address to Vendor Lookup Engine:
- If Fast Scan → Local Lookup Module queries CSV.
- If Advanced Scan → Remote API Module calls external service.
5. Vendor Lookup Engine returns vendor string(s) → aggregator collects results.
6. Output Formatter renders final table to the console.

##### Architectural patterns & design principles
- Single-process, modular design—separate functional concerns into:
– Input (CLI)
– Processing (Scanning + Lookup)
– Data Access (CSV file, HTTP API)
– Presentation (Console output)
- Clear separation of offline vs. online lookup paths.
- Rate-limiting logic isolated in the Remote API Module.

##### Essential elements
- Clear component labels (CLI, Scanner, Local Lookup, Remote Lookup, Formatter).
– Internal modules
– Local dataset
– External API

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Application"
        direction TB
        CLI["User Interface (CLI)"]:::ui
        Scanner["Network Discovery Engine"]:::network
        LocalLookup["Local Lookup Module"]:::data
        RemoteLookup["Remote API Module"]:::external
        Formatter["Output Formatter"]:::ui
    end

    subgraph "Local Resources"
        direction TB
        CSV[(mac-vendors-export.csv)]:::dataStore
    end

    subgraph "External Services"
        direction TB
        API["External MAC Vendor API"]:::externalService
    end

    CLI -->|"select mode"| Scanner
    Scanner -->|"List of (IP,MAC)"| LocalLookup
    Scanner -->|"List of (IP,MAC)"| RemoteLookup
    LocalLookup -->|"MAC address lookup"| CSV
    LocalLookup -->|"VendorName"| Formatter
    RemoteLookup -->|"HTTP request"| API
    API -->|"VendorName"| RemoteLookup
    RemoteLookup -->|"VendorName"| Formatter
    Formatter -->|"render table"| CLI

    click CLI "https://github.com/janidu-dm/net_scanner/blob/main/net_scn.py"
    click Scanner "https://github.com/janidu-dm/net_scanner/blob/main/net_scn.py"
    click LocalLookup "https://github.com/janidu-dm/net_scanner/blob/main/mac-vendors-export.csv"
    click RemoteLookup "https://github.com/janidu-dm/net_scanner/tree/main/query/"
    click Formatter "https://github.com/janidu-dm/net_scanner/blob/main/net_scn.py"

    classDef ui fill:#dddddd,stroke:#333,stroke-width:1px
    classDef network fill:#add8e6,stroke:#333,stroke-width:1px
    classDef data fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px
    classDef dataStore fill:#98fb98,stroke:#333,stroke-width:1px
    classDef externalService fill:#ffcc99,stroke:#333,stroke-width:1px
```
