A Python-based tool for scanning, auditing, and performing penetration tests on Wi-Fi networks and connected devices. This project automates network scanning, reconnaissance, and security testing using custom scripts and external tools. The purpose of this tool is to teach you what weaknesses there are within your own network and for you to harden that network in order to better defend and protect it.

• Wi-Fi Scanning and Connection Management

  • Automatically connects to Wi-Fi networks based on provided credentials (/home/pi/xeno/config/wifi_credentials.json).
  • Scans nearby networks and retries connections if necessary.
  • Supports automatic MAC address randomization.

• Network Scanning and Enumeration

  • Uses nmap to discover devices on the network.
  • Collects information on open ports, services, and possible vulnerabilities.

• Automated Reconnaissance

  • Identifies operating systems and running services on discovered devices.
  • Performs detailed port scanning and OS fingerprinting.

• Exploit Testing

  • Uses searchsploit to identify and test exploits against discovered vulnerabilities.
  • Supports downloading and executing payloads for penetration testing.

• File Harvesting

  • Uses SSH, FTP, and SMB to retrieve sensitive files from target devices.
  • Dynamically targets OS-specific directories and file types.

• HTML and JSON Logging

  • Logs scan and attack results in both JSON (/home/pi/xeno/utils/json_logs) and HTML (/home/pi/xeno/utils/html_logs) formats for detailed review.
  • Hosts flask server to allow users to see their logs without having to download them from the pi itself, uses IP:8080

• Dynamic E-Paper Display Updates

  • Displays workflow progress and stats on an e-paper display using custom images (/home/pi/xeno/images).

• Raspberry Pi (Recommended: Raspberry Pi 5, 4, 3B+, 0W)
• MicroSD Card (Minimum: 16GB)
• Wi-Fi Adapter (Optional but Recommended)
• Power Supply or Battery bank for portable (5V, 3A Recommended)
• waveshare 2.13inch E-Ink Display HAT V4

If you are using the official Xeno Community Image (pre-installed with everything), most components are already configured — including the default pet name: "Xeno".

• All Python dependencies, tools, and services.
• state.json initialized with default values.
• e-Paper display drivers installed.
• Systemd service for Xeno is enabled.

To personalize your Xeno’s identity:

1. Open the state file:

   sudo nano /home/pi/xeno/state.json

2. Locate the line:

   "pet_name": "Xeno"

3. Change "Xeno" to your preferred name:

   "pet_name": "CyberDog"

4. Save and exit:

   • Press CTRL + X
   • Then press Y
   • Then press Enter

After booting for the first time:

• Connect to Wi-Fi: Edit your networks in /home/pi/xeno/config/wifi_credentials.json.

• Customize Password Lists: Add your own to /home/pi/xeno/config/password_list.txt.

• Start Xeno Manually (only if you stopped the xeno service) (optional):

  sudo python3 /home/pi/xeno/main.py

• Or View Logs:

  sudo journalctl -u xeno.service -f

Be sure to use the Raspberry Pi OS lite 64 bit version!!!! (Unless RPi0)

1. Be sure to have your settings set this way:

2. Clone the repository and run the installation script:

   git clone https://github.com/ia-usgs/Xeno.git
   cd Xeno
   sudo chmod 777 install_file.sh
   sudo ./install_file.sh

   If you don't have git do the following:

    sudo apt update --fix-missing
    sudo apt install git -y
   

3. The script will:

   • Install all dependencies (Python libraries, tools like nmap, and e-paper display drivers).
   • Clone required repositories (e.g., ExploitDB).
   • Configure services and environment variables for the Xeno project.
   • Set up logging directories (logs/, utils/json_logs, utils/html_logs).
   • Set up the e-paper display.
   • It will install theharvester and shodan, it is for a future update.

4. Follow any on-screen prompts during the installation process.

Be sure to have your settings set this way:

git clone https://github.com/ia-usgs/Xeno.git
cd Xeno

Install required system and Python dependencies:

sudo apt-get update && sudo apt-get install -y git python3 python3-pip python3-venv curl dnsutils macchanger smbclient libjpeg-dev libpng-dev nmap fbi network-manager

sudo pip3 install -r requirements.txt --break-system-packages

• Wi-Fi Credentials: Create a file at /home/pi/xeno/config/wifi_credentials.json with the following structure:

  [
      {"SSID": "NetworkName", "Password": "NetworkPassword"},
      {"SSID": "AnotherNetwork", "Password": "AnotherPassword"}
  ]

• SSH Credentials: Create a file at /home/pi/xeno/config/ssh_default_credentials.txt with the following format:

  username:password
  anotheruser:anotherpassword
  

• Password List: Add any custom password lists for brute-force attempts in /home/pi/xeno/config/password_list.txt.

Ensure SPI is enabled:

sudo raspi-config nonint do_spi 0

sudo python3 main.py

To run the script continuously on system startup:

1. Create a service file at /etc/systemd/system/xeno.service:

   [Unit]
   Description=Xeno Wi-Fi Companion Service
   After=network.target
   
   [Service]
   ExecStart=/usr/bin/python3 /home/pi/xeno/main.py
   WorkingDirectory=/home/pi/xeno
   Restart=always
   User=pi
   Group=pi
   StandardOutput=inherit
   StandardError=inherit
   Restart=always
   User=pi
   Group=pi
   Environment="PYTHONUNBUFFERED=1"
   Environment="HOME=/home/pi"
   Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
   Environment="SDL_FBDEV=/dev/fb1"
   Environment="SDL_VIDEODRIVER=fbcon"
   
   [Install]
   WantedBy=multi-user.target
   

2. Enable and start the service:

   sudo systemctl daemon-reload
   sudo systemctl enable xeno.service
   sudo systemctl start xeno.service

• View live service logs:

  sudo journalctl -u xeno.service -f

• Log directories:

  • Scan Logs: /home/pi/xeno/logs/scan.log
  • JSON Logs: /home/pi/xeno/utils/json_logs/
  • HTML Logs: /home/pi/xeno/utils/html_logs/

.
├── attacks/
│   ├── exploit_tester.py         # Exploit testing module
│   ├── file_stealer.py           # File stealing module
│   ├── recon.py                  # Reconnaissance module
│   └── vulnerability_scan.py     # Vulnerability scanning module
├── config/
│   ├── password_list.txt         # Password list for brute-forcing
│   ├── ssh_default_credentials.txt  # Default SSH credentials
│   └── wifi_credentials.json     # Wi-Fi credentials
├── images/                       # Workflow state images (for e-paper & web UI)
├── logs/                         # General log output directory
├── scans/
│   └── nmap_scanner.py           # Nmap scanning module
├── services/                     # High-level “service” wrappers  
│   ├── display_service.py        # E-paper display orchestrator  
│   ├── exploit_service.py        # Exploit testing orchestrator  
│   ├── file_stealer_service.py   # File-stealer orchestrator  
│   ├── log_service.py            # Logger/html-logger orchestration  
│   ├── nmap_service.py           # Nmap scan orchestration  
│   ├── recon_service.py          # Reconnaissance orchestration  
│   ├── vulnerability_service.py  # Vulnerability scanning orchestration  
│   └── wifi_service.py           # Wi-Fi connect/disconnect orchestration  
├── stolen_files/                 # Directory for exfiltrated files
├── utils/
│   ├── display.py                # E-paper display manager
│   ├── html_logger.py            # HTML log generator
│   ├── image_state_manager.py    # Workflow state manager
│   ├── logger.py                 # Core logging utility
│   ├── html_logs/                # Generated HTML logs
│   ├── json_logs/                # Generated JSON logs
│   ├── waveshare_epd/            # EPD driver code
│   └── webInterface/
│       └── wifiLogTemplate.html  # Override HTML template
├── wifi/
│   └── wifi_manager.py           # Wi-Fi connection manager
├── static/                       # Static web assets
│   ├── images/                   # PNGs & icons for the web UI
│   ├── index.css                 # Main stylesheet
│   └── logTheme.css              # Theme stylesheet
├── templates/                    # Jinja2 templates for Flask
│   └── index.html                # HTML template for rendering logs
├── install_file.sh               # One-shot install & setup script
├── main.py                       # Slimmed-down orchestrator entry point
└── README.md                     # Project overview & instructions

• Add Wi-Fi networks in /home/pi/xeno/config/wifi_credentials.json.
• Set default SSH credentials in /home/pi/xeno/config/ssh_default_credentials.txt.
• Include a password list in /home/pi/xeno/config/password_list.txt.

• Manually:

  sudo python3 main.py

• As a service: Follow the "Service Mode" instructions above.

• View service logs:

  sudo journalctl -u xeno.service -f

• Review reports in:
  • /home/pi/xeno/utils/json_logs/
  • /home/pi/xeno/utils/html_logs/

• Add new attack modules in the /home/pi/xeno/attacks directory.
• Modify workflows in main.py.

The latest update introduces a streamlined and visually enhanced HTML Logging Interface, making it easier than ever to review scan results.

Xeno now automatically launches a lightweight Flask server to serve your log reports through a styled HTML interface

No manual setup required on most models—just run Xeno, and your log viewer is ready to go!

1. Ensure Xeno is running:

2. Open a web browser on your PC or mobile device.

3. Visit:

   http://insert-your-pi-ip:8080

4. On the landing page, click the link under Xeno Reports to view your HTML log.

Due to hardware limitations, the automatic Flask launch may not work reliably on Pi Zero models. You can start the server manually:

1. Navigate to the Xeno project directory:

cd /home/pi/xeno/

2. Start the Flask web server:

 sudo python3 web_server.py

Your terminal output should resemble the following:

3. While the server is running, open a web browser and visit:

http://insert-your-pi-ip:8080

4. Click the link under Xeno Reports on the landing page to open your HTML log.

Details displayed:

• IP Address
• MAC Address
• Vendor/Manufacturer

Use this panel to quickly identify devices on the network and verify expected vs. unexpected clients

Each row includes:

• Target IP
• Port
• Service Name
• Version
• Matched Exploit
• Exploit Title
• Exploit Path

• If you get GPIO Busy while running manually in CLI it is because the service is running.
• Run sudo systemctl stop xeno.service the from /xeno directory run sudo python main.py
• Check logs at xeno/logs/scan.log
• If Xeno is not getting anything via scans, it could be that it is taking longer than 60 seconds.
• To increase timeout go to /xeno/attacks/recon.py and modify line 42 def scan_ports(self, target, timeout=60): and change from 60 seconds to desired amount.
• If any part of xeno is having permission issues, do sudo chown root:pi filename and then sudo chmod 770 filename

This project is open for contributions! Feel free to fork the repository and submit pull requests. Contact me on Reddit for discussions and suggestions.

This project is intended for educational and ethical penetration testing only. Unauthorized use on networks or devices is illegal and punishable by law.

I, the creator, am not responsible for any actions, and or damages, caused by this software. You bear the full responsibility of your actions and acknowledge that this software was created for educational purposes only. This software's main purpose is NOT to be used maliciously, or on any system that you do not own, or have the right to use.

By using this software, you automatically agree to the above.

Use responsibly.

(back to top)