Merge pull request #7 from CyberRoute/timeout_progress

chore: format Python code and update README

Author: CyberRoute

.pylintrc

@@ -1,3 +1,13 @@
 [MASTER]
 init-hook='import sys; sys.path.append(".")'
-extension-pkg-allow-list=netifaces
+extension-pkg-allow-list=netifaces,scapy,setuptools
+
+[DESIGN]
+max-args=11
+max-positional-arguments=11
+max-attributes=15
+max-locals=18
+max-statements=80
+
+[MESSAGES CONTROL]
+disable=too-few-public-methods,import-outside-toplevel

README.md

@@ -1,117 +1,169 @@
 <p align="center">
   <img alt="Phantom" src="https://raw.githubusercontent.com/CyberRoute/phantom/main/images/phantom_logo.png"/>
-  <p align="center">
-  </p>
 </p>
 
 ---
 
 # Phantom
 
 ## Overview
-Phantom is an **ARP Scanner** mostly designed to detect directly connected IoT devices. The tool provides details like IP addresses, MAC addresses, hostnames, and the manufacturers of the devices based on their MAC addresses.
-The tool features a graphical user interface (GUI) built with **PySide6** (Qt framework) and utilizes **scapy** for ARP scanning.
 
----
+Phantom is a **network reconnaissance and security auditing tool** designed for directly connected networks. It discovers devices via ARP scanning, tracks their history, detects ARP spoofing attacks, and can perform MITM interception with live packet analysis powered by a local LLM.
+
+The GUI is built with **PySide6** (Qt framework) and uses **Scapy** for all packet-level operations.
 
-## Features
-- **Network Scanning**: Identifies devices on the network via ARP requests.
-- **Device Details**: Displays IP address, MAC address, hostname, and vendor information.
-- **Graphical User Interface**: Easy-to-use UI to display the scanned devices and packet information.
-- **Multithreading**: Ensures non-blocking scans using Python's `QThread`.
-- **C extension**: for MacOSX there is a C extension that allows slow sequential but very accurate arp scanning
 ---
 
-## Prerequisites
+## Features
 
-Ensure the following dependencies are installed:
+- **ARP Network Scanning**: Discovers devices via ARP requests, displaying IP, MAC, hostname, and vendor.
+- **Device History & Persistence**: Stores scan results in a local SQLite database; previously seen devices are shown on startup.
+- **New Device & MAC Change Detection**: Highlights new devices (green) and IP-to-MAC binding changes (red) — a classic ARP spoofing indicator.
+- **ARP Spoof Detection**: Passive background sniffer that alerts on conflicting ARP bindings and gateway MAC changes.
+- **MITM Interception**: ARP-spoof a target to intercept its traffic; captured packets are displayed in real time with a full layer-by-layer breakdown.
+- **LLM Packet Analysis**: Send any captured packet to a local [Ollama](https://ollama.com) instance for AI-assisted analysis (protocol identification, risk assessment, credential spotting).
+- **PCAP Export**: Save captured packets from a MITM session as a `.pcap` file for offline analysis in Wireshark.
+- **Scan Export**: Export scan results to JSON or CSV.
+- **Progress Bar**: Live progress feedback during scanning.
+- **Custom CIDR Target**: Scan a specific subnet instead of the local interface network.
+- **Multithreading**: All network operations run in `QThread` workers — the UI stays responsive throughout.
+- **C Extension (macOS)**: A native C extension provides accurate, sequential ARP scanning on macOS where Scapy bulk-send is unreliable.
 
-1. **Python 3.12 or higher**
-2. **scapy**: Used for ARP scanning.
-3. **PySide6**: For building the GUI.
-4. **netifaces**: To retrieve network interface details.
+---
 
 ## Requirements
 
 - **Python 3.12+**
-- **scapy**: For ARP scanning and packet manipulation.
-- **PySide6**: For building the graphical user interface.
-- **netifaces**: To retrieve network interface details.
+- **scapy** — ARP scanning and packet manipulation
+- **PySide6** — graphical user interface
+- **netifaces** — network interface introspection
+- **requests** — Ollama API streaming
+- **Ollama** (optional) — local LLM for packet analysis (`ollama serve`)
 
 ---
 
 ## Installation
 
 1. **Clone the repository**:
 
-    Clone the repository to your local machine:
-
     ```bash
     git clone https://github.com/CyberRoute/phantom.git
     cd phantom
     ```
 
-2. **Install the dependencies with Pipenv**:
-
-    Install `pip` if it's not already installed:
+2. **Create a virtual environment and install dependencies**:
 
     ```bash
     virtualenv env
     source env/bin/activate
     pip install -r requirements.txt
     ```
 
-3. **Run the application**:
-
-    Run the ARP Scanner using the following command. You need to provide the network interface (like `eth0`, `wlan0`, or `wlp0s20f3`) for your system:
+3. **(macOS only) Build the native C extension**:
 
     ```bash
-    sudo `which python3` main.py --interface <interface> --timeout 500
-    ```
-
-    On Ubuntu in case you run into this error:
-    ```
-    (env) alessandro@alessandro-XPS-9315:~/Development/phantom$ sudo /home/alessandro/Development/phantom/env/bin/python3 main.py --interface wlp0s20f3
-    qt.qpa.plugin: From 6.5.0, xcb-cursor0 or libxcb-cursor0 is needed to load the Qt xcb platform plugin.
-    qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
-    This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.
-    Available platform plugins are: eglfs, minimal, wayland, vkkhrdisplay, offscreen, linuxfb, xcb, wayland-egl, minimalegl, vnc.
-    ```
-    Solution:
-    ```
-    sudo apt install libxcb-cursor0
-    ```
-    On Macos there is a C extension that allows accurate but slow arpscan. To build and install the extension:
-    ```
     pip install setuptools
     cd c_extension
     python setup.py build
     python setup.py install
+    cd ..
     ```
 
-## Usage Instructions
+4. **Run the application** (root/sudo is required for raw packet operations):
 
-1. **Start the Application**:
+    ```bash
+    sudo `which python3` main.py --interface <interface> --timeout 500
+    ```
+
+    Optional arguments:
 
-    After running the application with the correct interface, the GUI will launch.
+    | Argument | Default | Description |
+    |---|---|---|
+    | `--interface` | *(required)* | Network interface name (e.g. `eth0`, `wlan0`) |
+    | `--timeout` | `1000` | ARP scan timeout in milliseconds |
+    | `--target` | interface network | Custom CIDR range to scan (e.g. `10.0.0.0/24`) |
 
-<div align="center">
-    <img src="/images/phantom.png" width="800px"</img>
-</div>
+### Troubleshooting (Ubuntu / xcb plugin error)
 
-2. **Scanning the Network**:
+```
+qt.qpa.plugin: Could not load the Qt platform plugin "xcb"
+```
 
-    - Click on the **"Scan"** button in the UI to initiate a network scan.
-    - The tool will display a list of all detected devices in the network, including their IP addresses, MAC addresses, hostnames, and vendors.
+Fix:
 
-3. **Device Details**:
+```bash
+sudo apt install libxcb-cursor0
+```
+
+---
 
-    - Click on any device in the list to open a detailed window that shows more information about that particular device.
+## Usage
 
-4. **Stopping the Scan**:
+### 1. Scan the network
 
-    - Press the **"Quit"** button to stop the ARP scan and close the application.
+Click **Scan** to start an ARP sweep of the local network (or a custom CIDR if `--target` was specified). Devices appear as they respond:
+
+- **White** — previously seen device, confirmed live
+- **Green** — new device (first time seen)
+- **Red** — IP address answered with a different MAC than before (possible ARP spoofing)
+- **Grey** — device from the database not yet confirmed live in this scan
+
+A progress bar tracks scan completion. Results can be exported to JSON or CSV with **Export Results**.
+
+### 2. Inspect a device
+
+Click any device in the list to open its detail window, which shows:
+
+- IP, MAC, hostname, vendor
+- First seen / last seen timestamps
+- Full MAC address history (useful for spoofing audits)
+- MITM controls
+
+### 3. MITM interception
+
+From the device detail window, click **Start MITM** to:
+
+1. ARP-spoof the target and the gateway (Phantom inserts itself in the traffic path).
+2. Enable IP forwarding so the target's internet access is preserved.
+3. Capture all non-ARP traffic to/from the target in real time.
+
+Click any captured packet to see a full hex dump and layer-by-layer field breakdown.  
+Click **Save PCAP** to write the captured session to a `.pcap` file.
+
+> **Note:** MITM requires root/sudo. IP forwarding is restored automatically when MITM is stopped.
+
+### 4. LLM packet analysis (Ollama)
+
+With [Ollama](https://ollama.com) running locally (`ollama serve`) and a model pulled (default: `deepseek-r1:1.5b`):
+
+1. Select a captured packet in the MITM window.
+2. Optionally add context in the **Context** field (e.g. `"this is a smart TV"`).
+3. Click **Analyse with LLM** — the analysis streams in token by token.
+
+The LLM identifies protocol/service, describes what the endpoints are doing, flags security-relevant observations, and provides a risk rating.
+
+---
+
+## Architecture
+
+```
+main.py                  — entry point, CLI args, QApplication bootstrap
+core/
+  arp_scanner.py         — ARPScannerThread, DeviceDiscoveryDialog, DeviceDetailsWindow
+  arp_spoofer.py         — low-level ARP spoof / restore primitives
+  mitm.py                — MitmThread (spoof loop + sniffer), IP forwarding management
+  spoof_detector.py      — passive ARP sniff-based spoof detection
+  ollama_analyst.py      — OllamaThread for streaming LLM packet analysis
+  db.py                  — SQLite persistence (device history, MAC audit trail)
+  networking.py          — CIDR calculation, hostname resolution helpers
+  vendor.py              — OUI/MAC vendor lookup
+  platform.py            — OS detection helper
+c_extension/             — native C ARP scanner for macOS
+ui/                      — PySide6 .ui compiled files
+```
+
+---
 
 ## Contribute
-Fork the repo and send PRs if you like :)
 
+Fork the repo and send PRs if you like :)

c_extension/setup.py

@@ -1,6 +1,8 @@
-from setuptools import setup, Extension
-import sysconfig
+"""Build configuration for the native arpscanner C extension."""
 import os
+import sysconfig
+
+from setuptools import setup, Extension  # pylint: disable=import-error
 
 # For macOS, we need to explicitly include libpcap
 extra_compile_args = []
@@ -20,4 +22,4 @@
     name='ArpScanner',
     version='1.0',
     ext_modules=[module]
-)
+)