Skip to content

CHANGELOG.md

Latest commit

 

History

History
193 lines (143 loc) · 13 KB

CHANGELOG.md

File metadata and controls

193 lines (143 loc) · 13 KB
Raw

Changelog — Spoof Toolkit

All notable changes to this project are documented here. Format follows Keep a Changelog.

[Unreleased]

Added

Authorization / scope control (rules of engagement)

  • core/authorization.py — EngagementScope + load_scope(). Declares a single authorized engagement (id, client, operator, authorizing party, time window) and its exact permitted targets: IPv4/IPv6 ranges, MAC/SSID/BSSID allowlists, and no-strike (denied) lists that always override allows. Fail-closed: an empty scope authorizes nothing. SHA-256 fingerprint() anchors non-repudiation.
  • core/session.py — Session.scope + Session.safe_mode, plus is_live() and a guard(...) helper every attack calls before touching a target. Live fire now requires a loaded, in-window scope; with no scope the toolkit runs dry-run only — packets are crafted and validated but never transmitted. to_dict() records the engagement mode and authorization fingerprint into every session report.
  • attacks/arp_spoof.py — reference integration: authorization gate in start() (refuses out-of-scope target/gateway), a single _transmit() chokepoint that is a no-op unless the session is authorized for live fire, and dry-run–aware packet accounting (new PacketStats.simulated counter).
  • core/preflight.py — new "Engagement scope loaded" check reading $SPOOF_TOOLKIT_SCOPE.
  • rules/engagement.example.json — annotated ROE template.
  • tests/test_authorization.py — 40 tests (IP/IPv6/MAC/SSID scope, no-strike precedence, time window, guard refusals, fingerprint stability, file/env loading, session integration).

[2.1.0] — 2026-08-14

Added

Wireless attacks

  • attacks/deauth.py — 802.11 deauth attack (targeted / broadcast) with AP + client scanners, burst counting, and timing jitter.
  • attacks/beacon_flood.py — 802.11 beacon flood with 5 SSID modes (random / funny / sequential / wordlist / list), ~100 beacons/sec.

Name-resolution poisoning

  • attacks/llmnr_nbt.py — LLMNR + NBT-NS + mDNS poisoner. CapturedHash dataclass and hashcat export.

IPv6

  • attacks/icmpv6_ra.py — ICMPv6 Router Advertisement spoofer (periodic / responsive / flood modes) with RDNSS option support.
  • attacks/ndp_spoof.py — NDP Neighbor Advertisement poisoning, IPv6 MitM setup/restore, and an NS sniffer for auto-poisoning.

Credential capture surfaces

  • attacks/captive_portal.py — async HTTP captive portal with 4 templates (hotel / corporate / cafe / isp) wired into credential capture.
  • attacks/wpad.py — WPAD PAC-file server with wpad.* DNS injection for auto-proxy hijack.

Core

  • core/platform_compat.py — cross-platform firewall abstraction (Linux / macOS / Windows).
  • core/session.py — PacketStats extended with 7 counters (deauth / beacon / ra / ndp / llmnr / portal / wpad) and a timing_jitter field.

UI

  • spoof_toolkit.py — 9 new submenus (wireless, LLMNR, IPv6 RA/NDP/MitM, captive portal, WPAD, combined portal+WPAD, evasion settings).

Tests / CI / packaging

  • tests/test_deauth.py (14) and tests/test_llmnr.py (16) — 65 tests total.
  • GitHub Actions CI (pytest + mypy + ruff + Docker matrix across Python 3.10/3.11/3.12), coverage ≥80% gate.
  • Dockerfile + docker-compose.yml (python3.11-slim + aircrack-ng + iptables, NET_RAW), pyproject.toml.

Changed

  • attacks/arp_spoof.py, attacks/dns_spoof.py — added timing jitter before forged responses for evasion; ARP now uses platform_compat.get_firewall() for cross-platform IP forwarding.
  • Dependencies bumped to current releases: scapy ≥2.7.0, rich ≥15.0.0, aiofiles ≥25.1.0, structlog ≥26.1.0, aiohttp ≥3.14.3; dev: pytest ≥9.1.1, pytest-asyncio ≥1.4.0, pytest-cov ≥7.1.0, mypy ≥2.3.0, ruff ≥0.16.3, types-aiofiles ≥25.1.0.

Fixed

  • attacks/combined_mitm.py — SyntaxError: mixed except and except* on one try, which failed to parse on every Python version, so the combined-MitM module never imported. Rewritten to flatten ExceptionGroups with a plain handler (also valid on 3.10).
  • attacks/llmnr_nbt.py — _decode_netbios_name() returned the space-padded NetBIOS name (e.g. "WORKSTATION "); now strips trailing padding and suffix bytes correctly.
  • attacks/ndp_spoof.py — restore step resolved the gateway MAC but never sent it, so after an IPv6 MitM the victim's neighbour cache still pointed the gateway at the attacker. Now sends genuine NAs for both the target and the gateway.
  • attacks/icmpv6_ra.py — responsive mode leaked its periodic-RA background task; it is now cancelled when the mode exits.
  • attacks/combined_mitm.py — the stop-watcher task is now tracked and cancelled during cleanup instead of being fire-and-forget.
  • Replaced deprecated asyncio.get_event_loop() with asyncio.get_running_loop() across all attack/capture modules (27 call sites) — removes the 3.12+ deprecation warning and future breakage.
  • pyproject.toml — corrected the build backend (setuptools.backends.legacy:build → setuptools.build_meta); the previous value was invalid and broke pip install ..
  • tests/test_llmnr.py — fixed a patch target that referenced a symbol the module imports lazily, so test_stop_terminates_loop no longer errors. Full suite is green (65/65).

Removed

  • Deleted dead v1.0 leftovers unreachable from the entry point: attacks/menu.py, attacks/spoof_utils.py, and utils/spoof_utils.py (superseded by core/menu.py and the core/ package). They also dragged the coverage gate down as uncovered source.

Housekeeping

  • Cleared all Ruff findings (unused imports/variables, unsorted imports, empty f-strings, ambiguous names) across the live codebase; added a scoped E402 ignore for the entry point's sys.path bootstrap.

Licensing

  • Relicensed from MIT to GPLv3 (LICENSE, pyproject.toml).

[2.0.0] — 2026-06-12

Complete rewrite — god-level async architecture

This version is a ground-up rewrite of the original spoofing toolkit. Everything from the architecture to the UI has been replaced.

Added

Core Infrastructure

  • core/session.py — Shared session state dataclass. Single source of truth passed to all modules. Includes CapturedCredential, PacketStats, and Session types with full serialization support.
  • core/logger.py — HMAC-SHA256-chained structlog audit logger. Each log entry is chained to the previous via HMAC, creating a tamper-evident evidence trail for forensic use.
  • core/banner.py — Animated 256-color ASCII art banner spelling "SPOOF" in large block letters with wave color cycling. Detects terminal width, 256-color support, and UTF-8 locale. Falls back to compact mode automatically.
  • core/preflight.py — Comprehensive preflight check system (16 checks): root privileges, Python version, all dependencies, iptables, airmon-ng, network interfaces, wireless adapters, terminal capabilities.
  • core/menu.py — Reusable numbered menu engine with submenus, breadcrumbs, and PromptHelper for consistent input collection.
  • core/reporter.py — Session report generator producing JSON, Markdown, and HTML from session state. HTML reports are self-contained, styled, dark-themed. Each report includes HMAC integrity checksum.

Attack Modules (fully async)

  • attacks/arp_spoof.py — Async ARP cache poisoner. Modes: mitm, dos, oneway, gateway_only. New features: ARP storm detection (auto-pause at >500 pkt/s), MAC randomization, gratuitous ARP mode, CIDR range targeting, asyncio.sleep poison loop (no threading.Thread), IP forwarding enable/disable, 5x genuine ARP restore on exit.
  • attacks/dns_spoof.py — Async DNS response injector. Modes: selective, spoof_all, rules_file, nxdomain. New features: wildcard domain matching (*.google.com), per-domain fake IP, DNSSEC bypass (strip RRSIG), DoH detection warning, AsyncSniffer bridged to asyncio queue.
  • attacks/combined_mitm.py — Full MitM orchestrator running ARP + DNS + credential sniffer as concurrent asyncio tasks via TaskGroup (Python 3.11+) or asyncio.gather (3.10). Phase-based display. Auto-generates report on stop.
  • attacks/ssl_strip.py — NEW — Transparent HTTPS-downgrade proxy. Uses iptables REDIRECT to intercept port-80 traffic, rewrites Location: https:// to http://, strips Strict-Transport-Security headers. Async aiohttp-based proxy. Warns about HSTS-preloaded sites. Cleans iptables rules in finally block.
  • attacks/rogue_dhcp.py — NEW — Rogue DHCP server. Races legitimate DHCP server with offers that advertise the attacker as default gateway and DNS server. Race condition mode. Lease table with rich display. No ARP poisoning required — stealthier on monitored networks.

Wireless

  • wireless/adapter.py — Full wireless adapter manager. Auto-detects via /sys/class/net, iw dev, iwconfig. Enables monitor mode via airmon-ng (with airmon-ng check kill) or iw/ip link fallback. Async channel hopping. Rich table report with name/MAC/mode/driver/chipset columns.

Capture

  • capture/credential_sniffer.py — Async credential extractor. Protocols: HTTP Basic Auth, HTTP POST forms, HTTP session cookies, FTP USER/PASS, Telnet login reconstruction, SMTP AUTH PLAIN/LOGIN (base64 decode), IMAP LOGIN, POP3 USER/PASS. Uses AsyncSniffer bridged to asyncio via run_coroutine_threadsafe.

Dashboard

  • dashboard/prism.py — PRISM live TUI dashboard. Three-panel rich.Live layout: Attack Log (scrolling with color-coded events) | Packet Stats (counters + uptime + session info) | Captured Credentials (last 20, colored by severity). Updates every 0.5s. Accessible via menu option 7 or --prism flag.

Entry Point

  • spoof_toolkit.py — Interactive entry point with animated banner, wireless auto-detection, language auto-detection, full main menu with submenus for all modules, Ctrl+C handling, exit summary with optional report generation.

i18n / Localization

  • i18n/en.json — English UI strings
  • i18n/hi.json — Hindi UI strings (हिन्दी)
  • i18n/ar.json — Arabic stub
  • i18n/zh.json — Chinese stub
  • i18n/fr.json — French stub
  • i18n/es.json — Spanish stub
  • Auto-detect from LANG environment variable. Switch via menu option L.

Installation

  • install.sh — Auto-detect OS (apt/pacman/dnf), install system deps, create venv at ~/.spoof-toolkit/venv, pip install Python deps, symlink to /usr/local/bin/spoof-toolkit.
  • requirements.txt — scapy, rich, aiofiles, structlog, aiohttp, pytest, pytest-asyncio

Tests

  • tests/test_arp.py — ARP packet construction, MAC randomization, mode selection, stop-event termination
  • tests/test_dns.py — Rule matching (exact, wildcard, spoof_all), rules file parsing, edge cases
  • tests/test_session.py — Session creation, credential storage, packet stats, DNS log, serialization

Other

  • wordlists/domains.txt — Top ~170 domains for spoof-all mode
  • rules/spoof_rules.txt — Updated example DNS rules with wildcard examples
  • .gitignore — Excludes output/, pcaps/, logs, venv, pycache
  • CHANGELOG.md — This file

Changed

  • attacks/arp_spoof.py — Complete rewrite. Threading replaced with asyncio. All scapy send calls run in executor. Storm detection added. Restore sends 5x genuine replies.
  • attacks/dns_spoof.py — Complete rewrite. Full async with AsyncSniffer. DoH detection. DNSSEC bypass.
  • attacks/combined_mitm.py — Complete rewrite. TaskGroup orchestration. Phase display. Auto-report.
  • rules/spoof_rules.txt — Expanded with wildcard examples and comments.

Removed

  • utils/spoof_utils.py — Functionality absorbed into core/ modules.
  • attacks/menu.py — Replaced by core/menu.py with full reusable engine.
  • All threading.Thread usage — replaced with asyncio throughout.
  • All time.sleep() in attack loops — replaced with asyncio.sleep().

Architecture Notes

  • Single language: Python 3.10+ only. No Go/C shims. Scapy handles raw packets; asyncio handles concurrency.
  • Async bridge pattern: AsyncSniffer (thread-based) bridges to asyncio via run_coroutine_threadsafe() + asyncio.Queue.
  • Always restore: Every attack module has finally blocks that restore ARP tables and clean iptables rules.
  • Session state: All runtime data lives in Session and is serialized to reports on exit.
  • Evidence integrity: HMAC-chained audit log — any post-hoc modification breaks the chain.

[1.0.0] — 2025-01-01

Initial release

  • attacks/arp_spoof.py — ARP cache poisoning (MitM, DoS, one-way) using threading.Thread
  • attacks/dns_spoof.py — DNS response injection with domain hijacking
  • attacks/combined_mitm.py — Combined ARP + DNS chain with threading
  • utils/spoof_utils.py — Shared utilities (WirelessChecker, MAC resolution, credential sniffer)
  • rules/spoof_rules.txt — Basic DNS spoof rules file
  • Wireless adapter auto-detection via WirelessChecker class
  • Basic credential capture: HTTP, FTP, Telnet
  • Clean ARP table restore on Ctrl+C