Created scanning.py (markdown)

scanning.py.md

@@ -0,0 +1,131 @@
+# scanning.py NetworkScanner 
+
+This document describes the detailed step-by-step process of how the `NetworkScanner` class works, including the specific methods, classes, and functions used at each step.
+
+## Initialization and Start of Scan
+
+### Creating `NetworkScanner` Instance
+- **Code**:
+    ```python
+    self.scanner = NetworkScanner(self.shared_data)
+    ```
+- **Purpose**: Initializes the `NetworkScanner` with shared data.
+
+### Starting the Scan
+- **Code**:
+    ```python
+    with self.semaphore:
+        self.scanner.scan()
+    ```
+- **Purpose**: Acquires a semaphore to limit the number of concurrent threads and calls the `scan` method to start the scanning process.
+
+## `NetworkScanner` Class
+
+### `__init__` Method
+- **Purpose**: Initializes various attributes such as `shared_data`, `logger`, `console`, `semaphore`, and `nmap.PortScanner`.
+
+### `scan` Method
+- **Purpose**: Main method that coordinates the entire scanning process.
+- **Key Steps**:
+    1. Set scanner status.
+    2. Call `get_network` to retrieve network information.
+    3. Initialize `ScanPorts` and start scanning ports.
+    4. Call `update_netkb` to update the network knowledge base.
+    5. Optionally call `display_csv` to display results.
+    6. Use `LiveStatusUpdater` to update live status and clean scan results.
+
+### `get_network` Method
+- **Purpose**: Retrieves the network's default gateway and subnet.
+
+### `get_mac_address` Method
+- **Purpose**: Retrieves the MAC address for a given IP and hostname.
+
+### `check_if_csv_scan_file_exists` Method
+- **Purpose**: Prepares necessary CSV files for the scan.
+
+### `sort_and_write_csv` Method
+- **Purpose**: Sorts and writes the scanned results to a CSV file.
+
+### `update_netkb` Method
+- **Purpose**: Updates the network knowledge base with scan results.
+
+### `display_csv` Method
+- **Purpose**: Displays the CSV file content using the Rich library for enhanced visualization.
+
+## `ScanPorts` Class
+
+### `__init__` Method
+- **Purpose**: Initializes attributes including file paths, lists for IP data, and open ports.
+
+### `scan_network_and_write_to_csv` Method
+- **Purpose**: Scans the network and writes the results to a CSV file.
+- **Key Steps**:
+    1. Call `check_if_csv_scan_file_exists` to prepare CSV files.
+    2. Use `nmap` to scan the network for live hosts.
+    3. Start threads to scan each host.
+
+### `scan_host` Method
+- **Purpose**: Scans a specific host to check if it is alive and retrieves its hostname and MAC address.
+
+### `start` Method
+- **Purpose**: Starts the network and port scanning process.
+
+## `PortScanner` Class
+
+### `__init__` Method
+- **Purpose**: Initializes the `PortScanner` with the target IP, open ports list, and port ranges.
+
+### `scan` Method
+- **Purpose**: Uses sockets to check if a specific port is open.
+
+### `start` Method
+- **Purpose**: Starts scanning ports within the specified range and additional ports using threads.
+
+### `scan_with_semaphore` Method
+- **Purpose**: Scans a port using a semaphore to limit concurrent threads.
+
+## `LiveStatusUpdater` Class
+
+### `__init__` Method
+- **Purpose**: Initializes the `LiveStatusUpdater` with source and output CSV paths.
+
+### `read_csv` Method
+- **Purpose**: Reads the source CSV file into a DataFrame.
+
+### `calculate_open_ports` Method
+- **Purpose**: Calculates the total number of open ports for alive hosts.
+
+### `calculate_hosts_counts` Method
+- **Purpose**: Calculates the total and alive host counts.
+
+### `save_results` Method
+- **Purpose**: Saves the calculated results to the output CSV file.
+
+### `update_livestatus` Method
+- **Purpose**: Updates the live status of hosts and saves the results.
+
+### `clean_scan_results` Method
+- **Purpose**: Cleans up old scan result files.
+
+## Usage
+
+1. **Create `NetworkScanner` Instance**:
+    ```python
+    scanner = NetworkScanner(shared_data)
+    ```
+
+2. **Start the Scan**:
+    ```python
+    with scanner.semaphore:
+        scanner.scan()
+    ```
+
+## Summary
+
+The `NetworkScanner` class orchestrates a comprehensive network scanning process, using various helper methods and classes to:
+- Retrieve network information.
+- Scan the network for live hosts and open ports.
+- Update and display scan results.
+- Maintain a network knowledge base and live status of hosts.
+
+This detailed breakdown should help in understanding the functioning and usage of the `NetworkScanner` class.