From 3c64ac881bc5203c183d71a6e37bc2866926825a Mon Sep 17 00:00:00 2001 From: bhushan4work Date: Sun, 18 Oct 2026 13:59:59 +0530 Subject: [PATCH] Add missing python-scripts readmes and repair sequence-diagram fences (#34) - add monitor-mode-toggle.md and netwwork_scanner_tutorial.md covering usage, prerequisites, inputs/outputs, code flow and a mermaid sequence diagram - close the unclosed ```mermaid fences in 12 script readmes so the sequence diagrams render instead of swallowing the rest of the file - restructure arp_spoof_detector.md (close bash fence, fence the diagram as mermaid, correct script name, include the root check branch) - add a sequence diagram to bettercap_arp_spoofing_script_auto.md - drop a stray trailing fence in mitm_attack_automation_readme.md --- python-scripts/arp_spoof_detector.md | 52 ++++--- python-scripts/async_port_scanner.md | 3 +- .../bettercap_arp_spoofing_script_auto.md | 53 +++++++ python-scripts/deauth_attack.md | 1 + .../https_data_fetcher_bettercap.md | 3 +- python-scripts/ids_probe.md | 3 +- .../mitm_attack_automation_readme.md | 3 - python-scripts/mitm_attack_automator.md | 3 +- python-scripts/monitor-mode-toggle.md | 143 ++++++++++++++++++ python-scripts/network_scanner.md | 1 + python-scripts/netwwork_scanner_tutorial.md | 91 +++++++++++ python-scripts/portscanner_test.md | 3 +- python-scripts/remote_collect_via_ssh.md | 3 +- python-scripts/wep_wifi_hacking.md | 3 +- python-scripts/wordlist_generator.md | 3 +- python-scripts/wpa2_dictionary_attack.md | 3 +- python-scripts/wpa_wps_hack.md | 1 + 17 files changed, 338 insertions(+), 34 deletions(-) create mode 100644 python-scripts/monitor-mode-toggle.md create mode 100644 python-scripts/netwwork_scanner_tutorial.md diff --git a/python-scripts/arp_spoof_detector.md b/python-scripts/arp_spoof_detector.md index 644359c..838bfc2 100644 --- a/python-scripts/arp_spoof_detector.md +++ b/python-scripts/arp_spoof_detector.md @@ -20,39 +20,47 @@ If a mismatch is detected, it alerts the user to a potential spoofing attempt. - **How to Run:** ```bash - sudo python3 arp_detector.py + sudo python3 arp_spoof_detector.py + ``` + ## Sequence Diagram — ARP Spoof Detector (Code Flow) - sequenceDiagram +```mermaid +sequenceDiagram participant User participant Script as ARP_Script + participant OS as Operating System participant Sniffer participant Handler as process_packet participant ARPUtil as get_mac/arping participant Console - User->>Script: sudo python3 arp_detector.py - Script->>Console: Print startup messages - Script->>Sniffer: Start sniff(store=False, prn=process_packet) - Sniffer-->>Handler: Pass each captured packet - Handler->>Handler: Check if packet has ARP layer and op == 2 - alt Is ARP reply - Handler->>ARPUtil: arping(packet[ARP].psrc) - ARPUtil-->>Handler: Return real_mac (or None) - Handler->>Handler: response_mac = packet[ARP].hwsrc - alt real_mac exists and real_mac != response_mac - Handler->>Console: Print ALERT with IP, Real MAC, Fake MAC - else - Handler->>Console: Ignore (no alert) + User->>Script: sudo python3 arp_spoof_detector.py + Script->>OS: Root check with id -u + alt Not running as root + Script->>User: Print root-privilege error and exit (1) + else Running as root + Script->>Console: Print startup messages + Script->>Sniffer: Start sniff(store=False, prn=process_packet) + Sniffer-->>Handler: Pass each captured packet + Handler->>Handler: Check if packet has ARP layer and op == 2 + alt Is ARP reply + Handler->>ARPUtil: arping(packet[ARP].psrc) + ARPUtil-->>Handler: Return real_mac (or None) + Handler->>Handler: response_mac = packet[ARP].hwsrc + alt real_mac exists and real_mac != response_mac + Handler->>Console: Print ALERT with IP, Real MAC, Fake MAC + else MAC matches or lookup failed + Handler->>Console: No alert printed + end + else Not an ARP reply + Handler->>Sniffer: Ignore non-ARP packets end - else - Handler->>Sniffer: Ignore non-ARP packets + User->>Script: Ctrl+C (stop) + Script->>Console: Print Detector stopped by user + Script->>User: Exit program end - User->>Script: Ctrl+C (stop) - Script->>Console: Print "Detector stopped by user." - Script->>User: Exit program - - +``` --- diff --git a/python-scripts/async_port_scanner.md b/python-scripts/async_port_scanner.md index 335f9a2..b36956c 100644 --- a/python-scripts/async_port_scanner.md +++ b/python-scripts/async_port_scanner.md @@ -118,4 +118,5 @@ sequenceDiagram alt Output File Requested CLI->>CLI: Write all results to --output JSON file end - CLI-->>User: Display output and Exit (0) \ No newline at end of file + CLI-->>User: Display output and Exit (0) +``` diff --git a/python-scripts/bettercap_arp_spoofing_script_auto.md b/python-scripts/bettercap_arp_spoofing_script_auto.md index eb42438..5a4c674 100644 --- a/python-scripts/bettercap_arp_spoofing_script_auto.md +++ b/python-scripts/bettercap_arp_spoofing_script_auto.md @@ -37,6 +37,59 @@ The README below focuses on the script's actual behavior and implementation deta --- +## Sequence Diagram (code flow) + +```mermaid +sequenceDiagram + autonumber + participant User as Operator + participant Main as main() + participant Cap as Bettercap process + participant Reader as stdout reader thread + + User->>Main: sudo python3 bettercap_arp_spoofing_script_auto.py + alt Interface argument missing + Main->>User: Print usage line and exit (1) + else Interface argument provided + Main->>Cap: Popen sudo bettercap -iface + alt bettercap binary not found or spawn error + Cap-->>Main: FileNotFoundError / Exception + Main->>User: Print install hint and exit (1) + else Bettercap started + Main->>Reader: Start daemon thread read_output() + Reader-->>User: Print every stdout line live while buffering it + Main->>Cap: net.probe on + Main->>User: Prompt: press Enter when discovery is complete + User-->>Main: Enter + Main->>Cap: net.probe off then net.show (with short waits) + Main->>Reader: stop_reading.set() and join thread + Main->>Main: parse_devices_log() and parse_devices_table(), dedupe by IP and MAC + alt No devices discovered + Main->>Cap: terminate() + Main->>User: Print no devices found and exit (1) + else Devices discovered + Main->>User: Print numbered device list + loop Until indices are valid + User-->>Main: Target selection such as 0 or 1,3 + Main->>Main: Validate range and build comma separated IPs + end + loop Until answer is y or n + User-->>Main: Enable full-duplex ARP spoofing + end + Main->>Cap: set fullduplex and targets, then arp.spoof on and net.sniff on + loop Until Ctrl+C + Reader-->>User: Stream bettercap output line by line + end + User->>Main: Ctrl+C raises KeyboardInterrupt + Main->>Cap: terminate() + Main->>User: Print stopping message and exit + end + end + end +``` + +--- + ## Important implementation notes - The script strips ANSI escape sequences from Bettercap output before parsing (this avoids parsing errors caused by color codes). diff --git a/python-scripts/deauth_attack.md b/python-scripts/deauth_attack.md index f8d711b..8da3ad0 100644 --- a/python-scripts/deauth_attack.md +++ b/python-scripts/deauth_attack.md @@ -84,3 +84,4 @@ sequenceDiagram Script->>User: Display "[+] Deauthentication attack completed" Script->>OS: Exit +``` diff --git a/python-scripts/https_data_fetcher_bettercap.md b/python-scripts/https_data_fetcher_bettercap.md index c0af104..155deca 100644 --- a/python-scripts/https_data_fetcher_bettercap.md +++ b/python-scripts/https_data_fetcher_bettercap.md @@ -141,4 +141,5 @@ sequenceDiagram Main->>User: Print final confirmation - deactivate Main \ No newline at end of file + deactivate Main +``` diff --git a/python-scripts/ids_probe.md b/python-scripts/ids_probe.md index 85699df..653afc9 100644 --- a/python-scripts/ids_probe.md +++ b/python-scripts/ids_probe.md @@ -115,4 +115,5 @@ sequenceDiagram end User->>Script: Manual Termination (Ctrl+C) - Script->>Script: Exit \ No newline at end of file + Script->>Script: Exit +``` diff --git a/python-scripts/mitm_attack_automation_readme.md b/python-scripts/mitm_attack_automation_readme.md index d820962..e719962 100644 --- a/python-scripts/mitm_attack_automation_readme.md +++ b/python-scripts/mitm_attack_automation_readme.md @@ -227,6 +227,3 @@ MIT License - Educational and authorized testing purposes only --- **Disclaimer**: This tool is designed for educational purposes and authorized security testing only. Users are solely responsible for complying with applicable laws and obtaining proper authorization before use. -``` - - diff --git a/python-scripts/mitm_attack_automator.md b/python-scripts/mitm_attack_automator.md index 41854b3..4f7eafb 100644 --- a/python-scripts/mitm_attack_automator.md +++ b/python-scripts/mitm_attack_automator.md @@ -90,4 +90,5 @@ sequenceDiagram Bettercap-->>OS: Process Exit OS->>Script: Return from subprocess.run() Script->>User: Display "[+] Attack stopped by user. Exiting." - Script->>OS: Exit \ No newline at end of file + Script->>OS: Exit +``` diff --git a/python-scripts/monitor-mode-toggle.md b/python-scripts/monitor-mode-toggle.md new file mode 100644 index 0000000..259e279 --- /dev/null +++ b/python-scripts/monitor-mode-toggle.md @@ -0,0 +1,143 @@ +# Monitor Mode Toggle — Overview, Usage, Code Explanation, and Sequence Diagram + +## What It Does (High-Level) + +This script switches a wireless network adapter between **monitor mode** and **managed mode** using `iwconfig`/`ifconfig`. It can auto-detect the available wireless interfaces when no interface name is supplied, and it verifies the resulting mode at the end of the run. + +--- + +## Usage Scenario + +- **When to Use:** + Prepare a USB/PCI Wi-Fi adapter for packet capture (monitor mode) during an authorized wireless lab, then switch it back to normal connectivity (managed mode) when the exercise is over. + +- **Why:** + Tools such as aircrack-ng, bettercap, and scapy sniffing require the adapter to be in monitor mode; everyday network use requires managed mode. + +- **Prerequisites:** + - Linux with `wireless-tools` (`iwconfig`) and net-tools (`ifconfig`) + - `aircrack-ng` (the script calls `airmon-ng check kill` before entering monitor mode) + - Root privileges (the mode changes are executed through `sudo`) + - A driver that actually supports the requested mode + - Python 3 (standard library only: `argparse`, `re`, `subprocess`) + +- **How to Run:** + + ```bash + sudo python3 monitor-mode-toggle.py --interface wlan0 --mode monitor + sudo python3 monitor-mode-toggle.py --interface wlan0 --mode managed + ``` + + Both flags are optional. Without `--interface` the script lists the detected wireless interfaces and asks for a name; without `--mode` it asks which mode to switch to. + +--- + +## Inputs and Outputs + +| | | +|---|---| +| **Inputs** | `-i/--interface` (e.g. `wlan0`), `-m/--mode` (`monitor` or `managed`), or interactive answers when the flags are omitted | +| **Outputs** | Console status messages, any errors returned by `ifconfig`/`iwconfig`, and a final `iwconfig ` listing that shows the current mode | +| **Exit codes** | `1` when the interface name is empty or the mode is not `monitor`/`managed`; otherwise `0` after the verification step | + +--- + +## Code Explanation + +### `list_wireless_interfaces()` +Runs `iwconfig` and splits the output into blocks separated by blank lines. Blocks whose first line contains `no wireless extensions` are skipped; the first token of every remaining block is collected as an interface name. If `iwconfig` is missing (`FileNotFoundError`) it prints an install hint and returns an empty list. + +### `current_mode(interface)` +Runs `iwconfig ` and extracts the current mode with the regular expression `Mode:(\S+)`. Returns `None` when the mode cannot be determined (including a missing `iwconfig`). + +### `kill_interfering_processes()` +Runs `sudo airmon-ng check kill` so that NetworkManager and similar services do not interfere with monitor mode. It is only invoked when the target mode is `monitor`. + +### `set_mode(interface, mode)` +The core sequence, with a failure branch after every privileged command: + +1. `sudo ifconfig down` — on failure it prints a permission/name hint and returns `False`. +2. If the target mode is `monitor`, kill interfering processes. +3. `sudo iwconfig mode ` — on failure it brings the interface back up, prints a driver-support hint and returns `False`. +4. `sudo ifconfig up` — on failure it prints an error and returns `False`. +5. Prints ` is now in mode` and returns `True`. + +### `__main__` block +Parses the arguments, auto-detects interfaces when `--interface` is missing (empty input aborts with exit code `1`), resolves the target mode from `-m` or a prompt (anything other than `monitor`/`managed` aborts with exit code `1`), calls `set_mode()`, and on success runs `iwconfig ` once more to display the verified state. + +--- + +## Sequence Diagram (Code Flow) + +```mermaid +sequenceDiagram + autonumber + participant U as Operator + participant S as monitor-mode-toggle.py + participant IW as iwconfig + participant SC as sudo ifconfig / iwconfig / airmon-ng + + U->>S: python3 monitor-mode-toggle.py [-i wlan0] [-m monitor] + alt --interface omitted + S->>IW: iwconfig (list adapters) + alt iwconfig not installed + IW-->>S: FileNotFoundError + S->>U: Print install wireless-tools hint + else iwconfig available + IW-->>S: Full iwconfig output + S->>S: Drop blocks marked no wireless extensions + alt Wireless interfaces detected + S->>U: Print each interface with its current mode + else No wireless interfaces detected + S->>U: Print manual-entry hint + end + end + S->>U: Prompt for the interface name + U-->>S: wlan0 + alt Interface name is empty + S->>U: Print error and exit (1) + else Interface name provided + S->>S: Keep the entered name as the target interface + end + end + alt --mode omitted + S->>U: Prompt for monitor or managed + U-->>S: monitor + end + alt Mode is neither monitor nor managed + S->>U: Print invalid mode and exit (1) + else Mode is valid + S->>SC: ifconfig wlan0 down + alt Bring-down failed + SC-->>S: Non-zero return code + S->>U: Print name/permission error (set_mode returns False) + else Interface is down + alt Target mode is monitor + S->>SC: airmon-ng check kill + end + S->>SC: iwconfig wlan0 mode monitor + alt Adapter or driver refuses the mode + SC-->>S: Non-zero return code + S->>SC: ifconfig wlan0 up (restore interface) + S->>U: Print unsupported-mode error (set_mode returns False) + else Mode accepted + S->>SC: ifconfig wlan0 up + alt Bring-up failed + SC-->>S: Non-zero return code + S->>U: Print bring-up error (set_mode returns False) + else Interface is up + S->>U: Print wlan0 is now in monitor mode + S->>IW: iwconfig wlan0 (verification) + IW-->>S: Current settings including Mode + S->>U: Print verification complete + end + end + end + end +``` + +--- + +## Safety and Legal Notice + +Only use monitor mode on networks and hardware you own or are explicitly authorized to test. Killing interfering processes with `airmon-ng check kill` disconnects the machine from its current Wi-Fi network. diff --git a/python-scripts/network_scanner.md b/python-scripts/network_scanner.md index 9bf102f..b97f2b1 100644 --- a/python-scripts/network_scanner.md +++ b/python-scripts/network_scanner.md @@ -106,3 +106,4 @@ sequenceDiagram Script-->>User: end end end +``` diff --git a/python-scripts/netwwork_scanner_tutorial.md b/python-scripts/netwwork_scanner_tutorial.md new file mode 100644 index 0000000..b99f0eb --- /dev/null +++ b/python-scripts/netwwork_scanner_tutorial.md @@ -0,0 +1,91 @@ +# Network Scanner Tutorial — Overview, Usage, Code Explanation, and Sequence Diagram + +This document describes `netwwork_scanner_tutorial.py`, the minimal ARP scan demo used to introduce network discovery. (The file name keeps the original `netwwork` spelling; it is intentionally not renamed here.) + +--- + +## What It Does (High-Level) + +The script builds an ARP request for a single IP, expands it to the whole `/24` subnet, broadcasts it at layer 2 with Scapy, and prints a summary of every host that answered within the timeout. It is the smallest possible version of a network scanner: no root check, no output file, no vendor lookup. + +--- + +## Usage Scenario + +- **When to Use:** + First practical lesson of a LAN discovery module — showing how an ARP "who-has" broadcast and its replies enumerate live hosts, before moving on to `network_scanner.py` (which wraps `netdiscover`) or `async_port_scanner.py`. + +- **Prerequisites:** + - Python 3 with `scapy` (`pip install scapy`) + - Root privileges — `scapy.srp()` needs raw packet sockets + - An interface in the same L2 segment as the targets, inside a lab network you own or are authorized to test + +- **How to Run:** + + ```bash + sudo python3 netwwork_scanner_tutorial.py + ``` + + The script prompts for an IP address; the `/24` suffix is appended automatically, so entering `192.168.1.1` scans `192.168.1.1/24`. + +--- + +## Inputs and Outputs + +| | | +|---|---| +| **Input** | One interactive prompt: the base IP address (`Enter the IP to scan:`) | +| **Output** | `Answered Packets:` followed by Scapy's `answered.summary()` lines (one per responding host); empty when nobody replies | +| **Side effects** | Sends one broadcast ARP request per address in the `/24` range; nothing is written to disk | + +--- + +## Code Explanation + +### `scan(ip)` +1. Creates the ARP layer: `scapy.ARP(pdst=ip, op=1)` — `op=1` is the ARP *request* ("who-has"). +2. Creates the Ethernet layer: `scapy.Ether(dst="ff:ff:ff:ff:ff:ff")` — layer 2 broadcast. +3. Stacks them with `broadcast/arp_request` to form a complete frame. +4. Sends the frame and collects replies with `scapy.srp(..., timeout=10)`, which returns the `(answered, unanswered)` pair. +5. Prints `Answered Packets:` plus `answered.summary()`. + +### `__main__` block +Reads the target IP from `input()`, appends `"/24"` to widen the scan to the whole subnet, and calls `scan()`. There is no argument parsing, validation, or privilege check — those are deliberately left as exercises. + +--- + +## Sequence Diagram (Code Flow) + +```mermaid +sequenceDiagram + autonumber + participant U as Operator + participant S as netwwork_scanner_tutorial.py + participant Scapy as scapy.srp + participant LAN as Lab LAN (L2 broadcast) + + U->>S: sudo python3 netwwork_scanner_tutorial.py + S->>U: Prompt: Enter the IP to scan + U-->>S: 192.168.1.1 + S->>S: Append /24 to build the target range + S->>Scapy: ARP request (op=1) inside Ethernet broadcast, srp timeout 10 s + Scapy->>LAN: Send frame to ff:ff:ff:ff:ff:ff for every address in 192.168.1.1/24 + alt Host answers before the timeout + LAN-->>Scapy: ARP replies collected into answered + Scapy-->>S: (answered, unanswered) + S->>U: Print Answered Packets with one summary line per host + else No host answers before the timeout + LAN--xScapy: Nothing received + Scapy-->>S: (empty answered, all unanswered) + S->>U: Print Answered Packets with an empty summary + end + S-->>U: Process exits +``` + +--- + +## Notes and Safety + +- The script exits after a single scan; rerun it to repeat. +- Because it broadcasts ARP requests, only run it against networks you own or are explicitly authorized to test. +- Related, more complete scripts: `network_scanner.py` (netdiscover wrapper) and `async_port_scanner.py` (TCP service probing with banner grabbing). diff --git a/python-scripts/portscanner_test.md b/python-scripts/portscanner_test.md index d797fed..b1c5705 100644 --- a/python-scripts/portscanner_test.md +++ b/python-scripts/portscanner_test.md @@ -98,4 +98,5 @@ sequenceDiagram Demo->>ServerSetup: await s.wait_closed() end - Main-->>Main: Fim da execução \ No newline at end of file + Main-->>Main: Fim da execução +``` diff --git a/python-scripts/remote_collect_via_ssh.md b/python-scripts/remote_collect_via_ssh.md index 90b4265..0a3c116 100644 --- a/python-scripts/remote_collect_via_ssh.md +++ b/python-scripts/remote_collect_via_ssh.md @@ -120,4 +120,5 @@ sequenceDiagram LocalScript->>LocalScript: 13. Aggregate full result (JSON Dict) LocalScript-->>User: 14. Print final result (JSON to stdout) - LocalScript->>LocalOS: 15. Exit (Code 0 or 1) \ No newline at end of file + LocalScript->>LocalOS: 15. Exit (Code 0 or 1) +``` diff --git a/python-scripts/wep_wifi_hacking.md b/python-scripts/wep_wifi_hacking.md index 49c9907..2f144a8 100644 --- a/python-scripts/wep_wifi_hacking.md +++ b/python-scripts/wep_wifi_hacking.md @@ -113,4 +113,5 @@ sequenceDiagram Script->>OS: Run: killall (Stop all Aircrack processes) OS-->>Script: Processes Terminated Script->>Script: Final File Cleanup - Script->>OS: Exit \ No newline at end of file + Script->>OS: Exit +``` diff --git a/python-scripts/wordlist_generator.md b/python-scripts/wordlist_generator.md index 38c3870..448205a 100644 --- a/python-scripts/wordlist_generator.md +++ b/python-scripts/wordlist_generator.md @@ -120,4 +120,5 @@ sequenceDiagram Script->>FS: write_wordlist(args.out, final_list) FS-->>Script: File successfully written Script->>User: Wrote X entries to mylist.txt - Script->>OS: Exit with code 0 (Success) \ No newline at end of file + Script->>OS: Exit with code 0 (Success) +``` diff --git a/python-scripts/wpa2_dictionary_attack.md b/python-scripts/wpa2_dictionary_attack.md index 7ca8f8f..53f9861 100644 --- a/python-scripts/wpa2_dictionary_attack.md +++ b/python-scripts/wpa2_dictionary_attack.md @@ -122,4 +122,5 @@ sequenceDiagram MainScript->>User: Display Error Message end - MainScript->>OS: Exit \ No newline at end of file + MainScript->>OS: Exit +``` diff --git a/python-scripts/wpa_wps_hack.md b/python-scripts/wpa_wps_hack.md index cc1446e..e0fe101 100644 --- a/python-scripts/wpa_wps_hack.md +++ b/python-scripts/wpa_wps_hack.md @@ -100,3 +100,4 @@ sequenceDiagram Script->>Reaver: Terminate Process (proc.terminate()) Script->>OS: Process cleanup (proc.wait()) Script->>OS: Exit +```