█████╗ ██╗     ███████╗ █████╗
██╔══██╗██║     ██╔════╝██╔══██╗
███████║██║     █████╗  ███████║
██╔══██║██║     ██╔══╝  ██╔══██║
██║  ██║███████╗██║     ██║  ██║
╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝  ╚═╝

 █████╗ ██████╗ ███████╗███████╗███╗   ██╗ █████╗ ██╗
██╔══██╗██╔══██╗██╔════╝██╔════╝████╗  ██║██╔══██╗██║
███████║██████╔╝███████╗█████╗  ██╔██╗ ██║███████║██║
██╔══██║██╔══██╗╚════██║██╔══╝  ██║╚██╗██║██╔══██║██║
██║  ██║██║  ██║███████║███████╗██║ ╚████║██║  ██║███████╗
╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚══════╝╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝

Alfa Arsenal

Wireless network security auditor and resiliency tool.

Warning

Authorized use only. Get explicit written permission before you point this at any network you don't own. Some of the modes here actively transmit — deauth, WPS, rogue-AP simulation, beacon floods — and they will disrupt other people on the air. Doing that to networks you aren't cleared to test is a crime in most places. The authorization checklist is in docs/RESPONSIBLE_USE.md. Read it.

Important

You need an external USB Wi-Fi adapter that can do monitor mode and packet injection. I built and test this against an Alfa AWUS036ACH (RTL8812AU); other injection-capable adapters will probably work but I haven't verified them. Built-in laptop radios are blocked on purpose — they live in the protected_interfaces list and the tool won't touch them.

What it is

This is a Wi-Fi auditing platform for the boring-but-important questions about a wireless deployment: is the encryption weak, is there a rogue AP sitting in the corner, are the passwords guessable. It's for people doing that with permission — an internal team checking its own coverage, an auditor on contract, someone poking at 802.11 in a lab.

The thing I cared about most while building it was control. One radio, one source of truth for channel and mode, and nothing disruptive happening unless a policy explicitly allows it. Anything that transmits is gated behind a rules-of-engagement file, a target allowlist, and a single-instance lock, so a run is repeatable and you can show afterward exactly what it touched.

There are four ways to drive it, all sitting on the same core:

• an interactive text UI plus headless flags — alfa_arsenal.py
• a FastAPI REST API with Prometheus metrics — api/app.py
• an optional gRPC control plane with TLS and an API key — api/grpc_server.py
• a Flask + WebSocket server for when more than one operator is involved — c2/server.py

Where something already does the job well I just call it — Wifite2, the aircrack-ng suite, Kismet, Bettercap, hcxdumptool, mdk4. The Scapy-based modules are mine: scanning, handshake and PMKID capture, and the controlled-validation pieces.

What it does

• Recon — channel-hopping scanner, dual-band, BSSID/ESSID filters, and GPS correlation with KML/GPX export for wardriving.
• Posture checks — PMKID and full 4-way handshake capture, WPS posture checks, and Wifite for the automated runs.
• Controlled validation — rogue-AP simulation, beacon stress tests, and deauth resiliency flows, all behind the policy gate.
• Evidence and reports — findings land in a SQLite store with hashed artifacts, and you can render them to Markdown, HTML, or PDF.
• Policy — JSON rules of engagement, target allowlists, per-operation gates, and a lock so two runs don't fight over the same working directory.

How it fits together

The four front ends (CLI, REST, gRPC, C2) all talk to the same core. The core owns policy, the instance lock, the radio resources, and the evidence database. Above that, the assessment plugins in attacks/ and the chains in orchestrator/ do the actual work, reaching external binaries through thin wrappers in tools/ that are discovered at runtime by integrations/tool_registry.py.

If you want the real detail — data flow, how adapter capabilities get probed, how to bolt on another tool — it's in docs/ARCHITECTURE.md.

Requirements

• Linux, and root for monitor mode and injection.
• Python 3.10 or newer. CI runs 3.10 through 3.13.
• An adapter that does monitor mode and injection. For RTL8812AU you'll want a maintained rtl8812au DKMS driver built against your kernel — reboot after a driver change or it'll bite you.
• Optional, auto-detected if installed: Wifite2, aircrack-ng, Kismet, Bettercap, hcxdumptool, mdk4, tshark, tcpdump.

Install

# System packages + a venv
sudo ./install.sh
source venv/bin/activate

# Sanity-check the adapter (your monitor-capable interface, e.g. wlan1)
sudo ./scripts/validate_adapter.sh wlan1

# For real use, set the master key that encrypts stored credentials
cp .env.example .env
# edit .env, set ALFA_MASTER_KEY

Prefer to do it yourself:

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

Usage

The menu, a scan, and a handshake capture cover most of what you'll do day to day:

# Interactive text UI
sudo python3 alfa_arsenal.py

# Scan for 60 seconds
sudo python3 alfa_arsenal.py --scan --timeout 60

# Handshake against a target you're authorized to test
sudo python3 alfa_arsenal.py --handshake -t AA:BB:CC:DD:EE:FF -c 6

The automated chain scans, ranks what it finds, then works each target through PMKID, handshake, and WPS (pixie first), and finally credential-strength testing when there's something to test against:

# The normal chain
sudo python3 alfa_arsenal.py --autopwn

# Field mode — longer windows, Wifite per target. It's slow and loud; only run it where that's fine.
sudo python3 alfa_arsenal.py --autopwn --field

# Cap the targets, bring your own wordlist
sudo python3 alfa_arsenal.py --autopwn --field --max-targets 5 --wordlist /path/to/list.txt

# Pin a rules-of-engagement file and a config
sudo python3 alfa_arsenal.py --autopwn --field \
  --policy-file ./policies/example_roe.json --config ./config/arsenal.defaults.json

Testing a capture you already have (no radio involved), and rebuilding a report from a stored run:

python3 alfa_arsenal.py --crack --capture-file ./handshake.cap --wordlist /usr/share/wordlists/rockyou.txt
python3 alfa_arsenal.py --report-run 1 --report-format markdown

The services:

sudo python3 -m api.app                          # REST API, OpenAPI at /docs
sudo python3 -m api.grpc_server --port 50051     # gRPC, TLS + API key from config
sudo python3 alfa_arsenal.py --c2 --port 4443    # coordination API / web UI

Full flag list is in docs/CLI_FLAGS.md, or just run python3 alfa_arsenal.py -h.

Configuration and rules of engagement

Config is plain JSON — work directory, interfaces, API binds, keys. Copy config/arsenal.defaults.json, edit it, pass it with --config.

Anything disruptive is gated by a rules-of-engagement file (--policy-file): the operations you allow, an optional BSSID allowlist, and whether an active assessment has to be running first. Start from policies/example_roe.json.

One process owns a working directory at a time. If you really need two, --no-single-instance-lock turns the lock off, but think about why first.

Set ALFA_MASTER_KEY (via .env) and stored credentials get encrypted at rest. .env, captures, and the local database are all git-ignored, so you won't commit them by accident.

Evidence and reporting

Findings go into a SQLite store with hashed artifacts. The reporting engine turns a run into Markdown, HTML, or PDF, and since it builds from a run ID (--report-run) you can re-export an old assessment later without ever powering the radio back up.

Screenshots

Main menu	Scan results

Policy prompt	Report sample

Development

pip install -r requirements.txt -r requirements-dev.txt

# Tests want PYTHONPATH=. ; the hardware-in-the-loop tests skip themselves unless ALFA_HIL=1
PYTHONPATH=. pytest tests/ -q

ruff check .
ruff format --check .

mypy core api attacks utils orchestrator modules integrations tools c2 alfa_arsenal.py

# If you touch proto/alfa_platform.proto, regenerate the stubs
bash scripts/gen_proto.sh

CI does the format check, lint, the test run, a proto-freshness diff, and an sdist build on 3.10–3.13. More in CONTRIBUTING.md.

Layout

alfa_arsenal.py     CLI / interactive entry point
api/                FastAPI REST + gRPC servicer
c2/                 Flask + WebSocket coordination server, token auth
core/               config, DB, resource/MAC/session managers, policy, crypto, evidence
attacks/            Scapy-native plugins (scanner, handshake, pmkid, wps, evil_twin, ...)
orchestrator/       Wifiphisher / Airgeddon / Bettercap chains + mode switching
integrations/       tool registry, task runner, capabilities, recovery, post-ex
tools/              subprocess wrappers (aircrack-ng, kismet, tshark, tcpdump, wifite, ...)
modules/            reporting engine, rogue detector
utils/              anti-forensics, GPS, fingerprinting
proto/              gRPC .proto source + generated stubs
docs/               architecture, CLI flags, deploy, runbook, threat model, responsible use
tests/              pytest suite mirroring the package layout

Docs

• docs/ARCHITECTURE.md — components and data flow
• docs/CLI_FLAGS.md — every command-line flag
• docs/WIFITE.md — the Wifite2 integration
• docs/DEPLOY.md — host, Ansible, Docker, Nix
• docs/RUNBOOK.md — operations, API usage, metrics, recovery
• docs/THREAT_MODEL.md — control-plane threat model
• docs/RESPONSIBLE_USE.md — authorization checklist

Security

If you find a security problem in the control plane, please read SECURITY.md and report it privately instead of opening a public issue.

License

MIT — see LICENSE. There's also an authorized-use NOTICE: how you use it is on you, so follow the law and the authorization rules in docs/RESPONSIBLE_USE.md.

Made in Prishtina, Kosovo.