If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/LionSec/xerosploit shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 3y ago

• 5 active contributors
• GPL-3.0 licensed
• ⚠ Stale — last commit 3y ago
• ⚠ Concentrated ownership — top contributor handles 71% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live LionSec/xerosploit repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/LionSec/xerosploit.

What it runs against: a local clone of LionSec/xerosploit — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in LionSec/xerosploit | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1174 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of LionSec/xerosploit. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/LionSec/xerosploit.git
#   cd xerosploit
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of LionSec/xerosploit and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "LionSec/xerosploit(\\.git)?\\b" \\
  && ok "origin remote is LionSec/xerosploit" \\
  || miss "origin remote is not LionSec/xerosploit (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "install.py" \\
  && ok "install.py" \\
  || miss "missing critical file: install.py"
test -f "run.sh" \\
  && ok "run.sh" \\
  || miss "missing critical file: run.sh"
test -f "banner.py" \\
  && ok "banner.py" \\
  || miss "missing critical file: banner.py"
test -f "tools/bettercap/lib/bettercap.rb" \\
  && ok "tools/bettercap/lib/bettercap.rb" \\
  || miss "missing critical file: tools/bettercap/lib/bettercap.rb"
test -f "tools/bettercap/lib/bettercap/context.rb" \\
  && ok "tools/bettercap/lib/bettercap/context.rb" \\
  || miss "missing critical file: tools/bettercap/lib/bettercap/context.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1174 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1144d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/LionSec/xerosploit"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Xerosploit is a Python-based penetration testing toolkit that performs man-in-the-middle (MITM) attacks using bettercap as its underlying engine, bundled with nmap for reconnaissance. It provides modules for DNS spoofing, HTML/JavaScript injection, packet sniffing, DoS attacks, download interception, and image/webpage replacement—all integrated into a single command-line interface for authorized security testing. Monolithic structure: the main entry point is install.py which sets up dependencies and creates a /usr/bin/xerosploit symlink. The core attack logic lives in tools/bettercap/ (a bundled Ruby gem), while Python wrapper scripts in the root directory orchestrate modules. The debian/ folder handles Linux package distribution; run.sh is the execution wrapper.

Penetration testers and security researchers who need a unified framework to execute MITM attacks, port scanning, and denial-of-service operations on networks they own or have explicit permission to test. Users typically work in roles like ethical hackers, red teamers, or security assessors on Linux systems (Ubuntu, Kali, Parrot OS).

This is an experimental/hobby project, not production-ready. The README indicates v1.0 but lacks CI/CD setup (no visible GitHub Actions, Travis, or test suite in the file list), no automated tests are evident, and the last documented support is Ubuntu 16.04 / Kali Sana (2015-era systems). The single maintainer (@inf98es) and absence of recent activity signals limited active development.

High risk for production use: the project relies on external tools (nmap, hping3, bettercap gem) whose versions are not pinned, no Gemfile.lock or requirements.txt pinning is evident, and the Debian packaging metadata (debian/control) may be outdated. The single maintainer and lack of test coverage means bugs are not caught automatically. Dependency on root privileges (sudo xerosploit) and network-level access create privilege-escalation and liability concerns.

No active development is visible. The repository appears dormant: there are no recent commits noted in the file metadata, no open PRs listed, and no GitHub Actions workflows. The last update appears to be around v1.0 (2016-era based on README mentions of Kali Sana). The project relies entirely on its bundled bettercap submodule and external system tools.

git clone https://github.com/LionSec/xerosploit
cd xerosploit
sudo python install.py
sudo xerosploit

Dependencies (nmap, hping3, build-essential, ruby-dev, libpcap-dev, libgmp3-dev, tabulate, terminaltables) are installed automatically by install.py on Debian/Ubuntu systems.

Daily commands:

sudo xerosploit

After installation, the command is available globally. The run.sh script wraps execution; internally it invokes Python scripts and bettercap via bin/xettercap (custom bettercap entry point in tools/bettercap/bin/). Root privileges are mandatory.

• install.py — Entry point for dependency installation and initial setup; all contributors must understand the build and installation workflow.
• run.sh — Primary execution script that launches the xerosploit framework; essential for understanding how the application starts.
• banner.py — Banner and initialization module that sets up the UI and framework configuration on startup.
• tools/bettercap/lib/bettercap.rb — Core bettercap integration module that provides the man-in-the-middle framework foundation.
• tools/bettercap/lib/bettercap/context.rb — Context management for attack sessions; critical for maintaining state across MITM operations.
• tools/bettercap/lib/bettercap/network/network.rb — Network abstraction layer handling ARP spoofing, packet manipulation, and network targeting.
• Makefile — Build configuration and project task definitions; necessary for understanding the development workflow.

Add a New Protocol Sniffer

1. Create a new protocol handler class inheriting from base.rb (tools/bettercap/lib/bettercap/network/protos/base.rb)
2. Implement protocol-specific packet parsing and credential extraction in your new file (e.g., tools/bettercap/lib/bettercap/network/protos/myprotocol.rb) (tools/bettercap/lib/bettercap/network/protos/)
3. Register the handler in the protocol loader (tools/bettercap/lib/bettercap/loader.rb)
4. Add configuration options in the appropriate options file (tools/bettercap/lib/bettercap/options/sniff_options.rb)

Add a New Discovery Agent

1. Create a new agent class inheriting from base.rb (tools/bettercap/lib/bettercap/discovery/agents/base.rb)
2. Implement scan logic in your agent (e.g., tools/bettercap/lib/bettercap/discovery/agents/newagent.rb) (tools/bettercap/lib/bettercap/discovery/agents/)
3. Integrate with the discovery thread coordinator (tools/bettercap/lib/bettercap/discovery/thread.rb)
4. Update core options to expose agent configuration (tools/bettercap/lib/bettercap/options/core_options.rb)

Add a New HTTP Proxy Modifier

1. Create a plugin in the proxy directory following bettercap conventions (tools/bettercap/lib/bettercap/proxy/http)
2. Implement request/response hooks to intercept and modify traffic (tools/bettercap/lib/bettercap/monkey/em-proxy/proxy.rb)
3. Register proxy options in the configuration (tools/bettercap/lib/bettercap/options/proxy_options.rb)
4. Document the modifier in the proxy documentation (tools/bettercap/docs/proxying/http.md)

Add Support for a New Operating System

1. Create a new firewall implementation (e.g., tools/bettercap/lib/bettercap/firewalls/windows.rb) (tools/bettercap/lib/bettercap/firewalls/)
2. Implement traffic redirection rules specific to the OS (tools/bettercap/lib/bettercap/firewalls/redirection.rb)
3. Add system detection logic in the system utilities (tools/bettercap/lib/bettercap/monkey/system.rb)
4. Update installation script to handle new OS dependencies (install.py)

1. Root requirement: All network operations require sudo; running without root silently fails at the packet-capture layer. 2. Python 2.7 only: The README and install.py target Python 2.7, which is EOL since 2020—compatibility with Python 3 is untested and likely broken. 3. Bundled bettercap version: The submodule in tools/bettercap/ is an old v0.x fork; it will not auto-update and conflicts with modern bettercap v2+ packages on the system. 4. LibPCAP version sensitivity: libpcap-dev must match the system's kernel version for packet capture to work; mismatches cause silent filtering failures. 5. No config files: There is no xerosploit.conf or settings file—all options are passed via CLI; no persistent state between runs.

• ARP spoofing / ARP cache poisoning — The core mechanism enabling MITM attacks in Xerosploit—all DNS spoofing, packet injection, and interception rely on ARP poisoning to redirect traffic through the attacker's machine.
• DNS spoofing / DNS hijacking — One of Xerosploit's flagship features; redirecting domain queries to attacker-controlled IPs requires understanding DNS protocol and cache behavior.
• Packet sniffing / Network packet capture (libpcap) — Xerosploit's sniffing and download-interception modules depend on libpcap to capture and inspect traffic; understanding packet structures is essential for modifying payloads.
• HTTP proxy / man-in-the-middle proxy — The HTML/JavaScript injection and download replacement features work by proxying HTTP traffic through Xerosploit; bettercap's proxy engine must be understood to add new intercept rules.
• Denial-of-service (DoS) attack patterns — Xerosploit uses hping3 to craft SYN floods, UDP floods, and ICMP floods; understanding packet construction and rate-limiting is needed to configure effective DoS modules.
• Network interface promiscuous mode — Capturing traffic from other hosts requires the network interface to enter promiscuous mode; Xerosploit assumes this is enabled and will fail silently on restricted interfaces.
• HSTS (HTTP Strict Transport Security) bypass — Bettercap's docs (tools/bettercap/docs/_static/img/with-hsts.png) highlight HSTS as a barrier to MITM attacks; understanding HSTS mechanisms helps identify when SSL stripping will fail.

• bettercap/bettercap — The upstream MITM framework that Xerosploit wraps; xerosploit bundles an old fork of bettercap, so understanding the original is essential for patching spoofing or proxy bugs.
• kali-team/arsenal — Kali Linux's official penetration testing toolkit; Xerosploit competes with Kali's built-in MITM tools and should be tested alongside them.
• nmap/nmap — Direct dependency for port scanning and service enumeration in Xerosploit; understanding nmap's output parsing in xerosploit code is critical.
• Mitmproxy/mitmproxy — Modern Python-based MITM proxy alternative; Xerosploit's HTML/JavaScript injection could be replaced with mitmproxy's scriptable addons if bettercap becomes unmaintained.
• aircrack-ng/aircrack-ng — Complementary wireless penetration toolkit often chained with Xerosploit's network spoofing for full red-team workflows on Kali Linux.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Python 2.7 to Python 3.x compatibility layer and modernize dependencies

The project is pinned to Python 2.7 (EOL since 2020) according to the README badge. The codebase likely contains deprecated syntax and imports. Creating a compatibility module would allow gradual migration to Python 3.x, improve security, and enable use on modern systems where Python 2.7 is no longer available. This is blocking adoption and maintenance.

• [ ] Audit main entry points (run.sh, install.py, banner.py) for Python 2-specific syntax (print statements, urllib, etc.)
• [ ] Create a compat.py module in the root for Python 2/3 shims (six-like compatibility layer)
• [ ] Update README.md badge from Python 2.7 to Python 3.6+
• [ ] Test install.py and run.sh against Python 3.x

Create automated test suite for core MITM modules and dependencies

The repo has no visible test directory despite being a penetration testing toolkit with multiple modules (referenced in README as 'modules that allow to realise efficient attacks'). Without tests, regressions in bettercap integration or module interactions go undetected. A basic test suite would validate the framework's reliability.

• [ ] Create tests/ directory structure mirroring main module organization
• [ ] Add unit tests for install.py dependency installation verification
• [ ] Add integration tests validating bettercap and nmap availability after installation
• [ ] Create tests/test_module_loading.py to verify all attack modules import correctly
• [ ] Add pytest to debian/control and requirements.txt

Document and refactor embedded bettercap fork (tools/bettercap) into a proper dependency

The codebase contains a full bettercap Ruby gem embedded in tools/bettercap/ with its own .gitignore, Gemfile, and structure. This is a maintenance burden and creates version drift. The README claims the project is 'Powered by bettercap' but it's tightly coupled. Extracting this as a documented external dependency would simplify the repo and clarify version requirements.

• [ ] Audit tools/bettercap/bettercap.gemspec to identify the pinned bettercap version
• [ ] Update debian/control and install.py to declare bettercap as external dependency with version constraint
• [ ] Create docs/DEPENDENCIES.md documenting bettercap version requirements and installation
• [ ] Remove tools/bettercap from repo via git rm -r and add to .gitignore (or use git submodule if needed)
• [ ] Test install.py pulls bettercap from rubygems instead of local copy

• Add a test suite: Create tests/ folder with pytest tests for install.py and banner.py CLI parsing—currently there are zero automated tests, making regressions invisible.
• Port to Python 3.8+: The README hardcodes Python 2.7 support; update install.py, banner.py, and all Python scripts to run under Python 3, test on modern Kali/Ubuntu, and update README and debian/control.
• Document module architecture: The README lists features (DNS spoofing, HTML injection, DoS) but the codebase structure for loading/configuring these modules is not documented—write a CONTRIBUTING.md explaining how to add a new MITM module and where to hook it into the dispatcher.

• High · Outdated Python Version — README.md, setup metadata. The project targets Python 2.7, which reached end-of-life on January 1, 2020. Python 2.7 no longer receives security updates, making the application vulnerable to known exploits and missing critical security patches. Fix: Migrate to Python 3.x (3.8+). Update all dependencies to Python 3 compatible versions and test thoroughly.
• High · MITM Framework with Insecure Dependencies — tools/bettercap/, tools/bettercap/Gemfile, tools/bettercap/Gemfile.lock. The project relies on bettercap and nmap for MITM attacks. Bundled bettercap (tools/bettercap) appears to include gem dependencies (Gemfile.lock) without pinned versions visible, risking vulnerable transitive dependencies. Ruby gems may have known vulnerabilities. Fix: Audit all gem dependencies in Gemfile.lock for CVEs. Use bundle audit to identify vulnerable gems. Pin exact versions and regularly update. Consider replacing with maintained security tools.
• High · Root Privilege Execution Required — install.py, README.md. Installation requires sudo (sudo python install.py), and the framework performs network-level MITM operations requiring root. This creates significant privilege escalation risks if the tool is compromised. Fix: Implement capability-based privilege separation. Document security implications. Use seccomp/AppArmor profiles to limit root access. Require explicit user acknowledgment of risks.
• Medium · Missing Input Validation in Network Operations — tools/bettercap/lib/bettercap/discovery/agents/, tools/bettercap/lib/bettercap/network/. The codebase includes network manipulation tools (arp.rb, discovery agents) that likely process untrusted network data without visible input validation. This could enable injection attacks through crafted packets. Fix: Implement strict input validation for all network packet parsing. Use safe parsing libraries. Validate IP addresses, MAC addresses, and protocol fields against RFC specifications.
• Medium · Weak Logging and Audit Trail — tools/bettercap/lib/bettercap/logger.rb. While a logger.rb exists, the codebase structure suggests minimal audit logging for sensitive MITM operations. Network interception activities should be comprehensively logged for forensic purposes. Fix: Implement comprehensive audit logging for all MITM operations (targets, timestamps, data intercepted). Use tamper-proof logging with timestamps. Store logs securely with restricted access.
• Medium · Unrestricted Network Packet Manipulation — tools/bettercap/lib/bettercap/discovery/agents/arp.rb, tools/bettercap/lib/bettercap/firewalls/redirection.rb. The project includes tools for ARP spoofing, packet injection, and network redirection without visible access controls or target whitelisting mechanisms. This could be misused for unauthorized network attacks. Fix: Implement authorization checks and target whitelisting. Require confirmation before executing MITM operations. Add rate limiting on packet injection. Log all network operations with source/destination details.
• Medium · No Visible Credential Management — Codebase structure - no secrets.py, .env handling visible. For a penetration testing tool, there's no evidence of secure credential storage for captured/stored credentials. Intercepted data or stored credentials may be exposed. Fix: If storing any credentials/captured data, use encrypted storage (AES-256). Never log passwords in plaintext. Implement secure memory handling for sensitive data. Use environment variables for any required credentials.
• Medium · Missing SSL/TLS Certificate Validation — tools/bettercap/lib/bettercap/monkey/openssl/server.rb. The bettercap library includes SSL interception capabilities (monkey/openssl/server.rb) which could perform MITM on HTTPS traffic, but certificate validation enforcement is unclear. Fix: Clearly document that this tool performs HTTPS interception. Ensure certificate validation is disabled only with explicit user consent. Add warnings about SSL stripping. Implement proper logging of intercepted HTTPS sessions.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.