Metadata-Version: 2.4
Name: fastpluggy-network-node
Version: 0.0.104
Summary: Network discovery and monitoring plugin for FastPluggy
Author: FastPluggy Team
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: python-nmap
Requires-Dist: pydantic>=2.0.0
Requires-Dist: fastpluggy>=0.4.9
Requires-Dist: pydantic-extra-types
Requires-Dist: fastpluggy-tasks-worker>=0.2.44
Requires-Dist: fastpluggy-websocket-tool>=0.1.21
Requires-Dist: psutil>=5.9.0
Requires-Dist: loguru>=0.7.0
Provides-Extra: tests
Requires-Dist: pytest>=7.0; extra == "tests"
Requires-Dist: pytest-cov>=4.0; extra == "tests"
Requires-Dist: psycopg2-binary; extra == "tests"
Requires-Dist: testcontainers[postgresql]>=3.7.0; extra == "tests"
Provides-Extra: e2e
Requires-Dist: playwright>=1.40.0; extra == "e2e"

# Network Node Plugin

![Network Node](https://img.shields.io/badge/FastPluggy-Network%20Node-blue)
[![Release](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/network_node/-/badges/release.svg)](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/network_node/-/releases)
[![Pipeline Status](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/network_node/badges/main/pipeline.svg?key_text=CI)](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/network_node/-/pipelines?ignore_skipped=true)
[![Coverage](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/network_node/badges/main/coverage.svg)](https://gitlab.ggcorp.fr/open/fastpluggy/plugins/network_node/-/pipelines)

## Overview
The Network Node plugin provides network discovery, monitoring, and analysis capabilities. It allows you to scan your local network for devices, identify services running on those devices, and collect information about network interfaces and WiFi networks.


## Installation

```bash
pip install fastpluggy-network-node
```

## Package Structure
This plugin follows the standard fastpluggy plugin structure:
- `pyproject.toml` - Package configuration and metadata
- `.gitlab-ci.yml` - CI/CD configuration
- `src/` - Source code
  - `plugin.py` - Plugin entry point
  - `models.py` - Database models
  - `routers/` - API and frontend routers
  - `schema/` - API schemas
  - `services/` - Business logic
  - `tasks/` - Background tasks
  - `templates/` - HTML templates

## Dependencies
This plugin depends on:
- fastpluggy-tasks-worker (>= 0.0.1) - For asynchronous task execution
- fastpluggy-websocket-tool (>= 0.0.1) - For real-time updates
- python-nmap - For network scanning

## Features

### Network Discovery
- Automatic detection of local network range
- IP address scanning with ping sweep
- MAC address resolution
- Manufacturer identification from MAC addresses (OUI lookup)
- Hostname resolution

### Service Scanning
- Port scanning with configurable ranges
- Service detection and identification
- Version detection
- Banner grabbing
- Vulnerability assessment

### Network Interface Detection
- Comprehensive detection of all network interfaces
- Interface type identification (ethernet, wireless, loopback, bridge, tunnel)
- Real-time status monitoring (up/down)
- Network configuration details (IP address, MAC address, netmask, MTU, speed)

### WiFi Network Scanning
- Detection of available WiFi networks
- Signal strength measurement
- Security type identification
- Channel and frequency information
- Historical tracking of previously detected networks

## Configuration
The plugin can be configured through the `NetworkNodeConfig` class in `config.py`. Key configuration options include:

### Scan Configuration
```python
# Common ports for scanning - most frequently used network service ports
COMMON_PORTS = [21, 22, 23, 25, 53, 80, 110, 111, 135, 139, 143, 443, 445, 993, 995, 1723, 3306, 3389, 5900, 8080]

# Scan configuration defaults
default_port_range: str = "1-1024"
default_scan_intensity: int = 3
default_timeout_seconds: int = 30
```

### Service Detection Configuration
```python
# Service detection configuration
enable_service_detection: bool = True
enable_os_detection: bool = False
enable_version_detection: bool = True
enable_script_scanning: bool = False
```

### Performance Configuration
```python
# Performance configuration
max_concurrent_scans: int = 10
scan_result_cache_ttl_minutes: int = 60
```

### UI Configuration
```python
# UI configuration
default_view_mode: str = "cards"  # cards or table
auto_refresh_interval_seconds: int = 300
```

### OUI Lookup Configuration
The plugin includes functionality to identify device manufacturers from MAC addresses using OUI (Organizationally Unique Identifier) lookup. This feature is configured with the following settings in the `NetworkNodeConfig` class:

```python
# OUI lookup configuration
oui_data_url: str = "https://standards-oui.ieee.org/oui/oui.csv"
oui_data_directory: str = "/data/network_node/oui"
oui_data_refresh_days: int = 30  # How often to refresh the OUI data
```

The OUI data is downloaded from the IEEE's official registry and cached locally in the `/data/network_node/oui/` directory. The cache is refreshed automatically based on the configured TTL.

## Usage

### OUI Lookup
To get the manufacturer of a device from its MAC address:

```python
from fastpluggy_plugin.network_node.services.oui_lookup import OUILookup

# Get the manufacturer for a MAC address
mac_address = "00:11:22:33:44:55"
manufacturer = OUILookup.get_manufacturer_from_mac(mac_address)
print(f"Device manufacturer: {manufacturer}")
```


### Service Scanning
To scan for services on a specific device:

```python
from fastpluggy_plugin.network_node.tasks import service_scan_task

# Scan for services on a specific IP address
ip_address = "192.168.1.100"
port_range = "1-1024"
result = service_scan_task(ip_address, port_range)
print(result)
```

### Full Network Scan
To perform a complete network scan (discovery + service scanning):

```python
from fastpluggy_plugin.network_node.tasks import full_network_scan_task

# Run a full network scan
result = full_network_scan_task()
print(result)
```

## Data Storage
- Network nodes and services are stored in the database using SQLAlchemy models
- OUI data is stored in the `/data/network_node/oui/` directory
- WiFi network data is stored in the database for historical tracking

## API Endpoints
The plugin provides API endpoints for accessing network data:

### Network Nodes
- **Endpoint:** `/api/network/nodes`
- **Method:** GET
- **Description:** Get all network nodes with their services
- **Response:** NetworkNodesResponse containing:
  - nodes: List of network nodes with their services
  - total_nodes: Total count of nodes
  - online_nodes: Count of online nodes
  - offline_nodes: Count of offline nodes
  - total_services: Total count of services across all nodes

### Scan Status
- **Endpoint:** `/api/network/scan/status`
- **Method:** GET
- **Parameters:** 
  - task_id: ID of the scan task
- **Description:** Check the status of a running scan task
- **Response:** ScanStatusResponse containing task status information

### Network Interfaces
- **Endpoint:** `/api/network/interfaces`
- **Method:** GET
- **Description:** Get all network interfaces detected on the local system
- **Response:** NetworkInterfacesResponse containing:
  - interfaces: List of network interfaces
  - total_interfaces: Total count of interfaces
  - active_interfaces: Count of active interfaces

### WiFi Networks
- **Endpoint:** `/api/network/wifi/networks`
- **Method:** GET
- **Parameters:** 
  - show_historical: Whether to include historical networks (default: true)
- **Description:** Scan for available WiFi networks and return both current and historical networks
- **Response:** WiFiNetworksResponse containing:
  - networks: List of all networks (current and historical)
  - current_networks: List of currently active networks
  - historical_networks: List of previously detected networks
  - total_networks: Total count of all networks
  - active_networks: Count of currently active networks
  - historical_networks_count: Count of historical networks
  - security_counts: Count of networks by security type
  - frequency_counts: Count of networks by frequency band

## Web Interface
The plugin provides web interfaces for viewing network data:

- `/network/dashboard` - Network dashboard
- `/network/nodes` - Network nodes
- `/network/services` - Network services
- `/network/interfaces` - Network interfaces
- `/network/wifi` - WiFi networks

## Dependencies
- psutil - For network interface detection
- loguru - For logging
- SQLAlchemy - For database models
