Skip to content

CLI_FLAGS.md

Latest commit

 

History

History
172 lines (119 loc) · 7.43 KB

CLI_FLAGS.md

File metadata and controls

172 lines (119 loc) · 7.43 KB
Raw

Alfa Arsenal — CLI flags reference

Authorized Use Only

Many flags below cause active RF transmission or disruptive behavior. Use them only on networks and systems for which you have explicit written authorization. See docs/RESPONSIBLE_USE.md for the authorization checklist.

🔴 EXTERNAL HIGH-GAIN ADAPTER REQUIRED

All live RF modes require an external high-gain USB Wi-Fi adapter with Monitor Mode and Packet Injection support. Built-in laptop wireless is not supported.

This document describes every command-line flag for alfa_arsenal.py. For the live list from your install, run:

python3 alfa_arsenal.py -h

Most RF operations need root (sudo) for monitor mode and injection.

No flags — interactive menu

sudo python3 alfa_arsenal.py

Starts the full text UI: assessment runs, policy, reports, rogue analysis, session resume, etc. Does not require one of the mode flags below.

Mutually exclusive modes (pick at most one)

These flags select a single primary behavior. You cannot combine two of them in one invocation.

Flag What it does
--scan Discover nearby networks and store results; duration from --timeout (default 30s unless you override).
--handshake Capture a WPA/WPA2 4-way handshake against --target (BSSID) on --channel.
--pmkid Attempt PMKID capture against the target AP.
--wps WPS posture check (Pixie / brute phases per plugin) against the target.
--evil-twin Rogue access-point simulation workflow (needs target context; may use --password if you already have the PSK).
--beacon-flood Transmit a beacon stress test (DoS-class; ROE-gated). Use only where explicitly authorized.
--crack Offline credential-strength test using --capture-file and optional --wordlist (no live RF required for the test itself).
--autopwn Automated assessment chain: scan → ranked targets → PMKID → handshake → WPS (pixie-first), then credential-strength testing when material exists. See Automated assessment chain options below.
--c2 Start the remote coordination API / web UI server only (see --port; config may set host/port).
--diag Run diagnostics only (no assessment).

Reports (no radio)

Flag Argument What it does
--report-run ID Build a report for assessment run ID from the database. Does not use the wireless adapter.
--report-out path Output file for --report-run (default: work_dir/report_<ID>.<ext>).
--report-format markdown | html | pdf Output format for --report-run (default: markdown).

If --report-run is set, it runs first and the process exits after generating the report (other modes are not combined in one run).

Policy and process safety

Flag What it does
--policy-file Path to JSON rules of engagement (ROE): allowed operations, optional BSSID allowlist, require_active_assessment, etc. See policies/example_roe.json.
--no-single-instance-lock Allow two processes to use the same work_dir at once (default is a single-instance lock). Not recommended unless you know why.

Platform REST API

The FastAPI surface runs as a separate module (not a flag on alfa_arsenal.py):

sudo python3 -m api.app
# OpenAPI: http://127.0.0.1:8787/docs  (host/port from config: api_host, api_port)

Bind address, port, and api_secret_key are set in your JSON config or config/arsenal.defaults.json.

gRPC control plane

sudo python3 -m api.grpc_server --port 50051

Configure grpc_cert_path, grpc_key_path, and grpc_api_key in config for TLS and API-key auth.

Target selection (for operations that need a target)

Flag Short What it does
--target -t BSSID (MAC) of the access point, e.g. AA:BB:CC:DD:EE:FF.
--essid -e ESSID (network name) when the tool supports name-based selection.
--channel -c Channel number (e.g. 6, 36) to lock the radio for the operation.

General options (combine with modes)

Flag Default What it does
--timeout 30 Operation timeout in seconds (e.g. scan duration, operation phase limits — exact use depends on the plugin).
--wordlist — Path to a wordlist file for credential-strength testing (--crack, --autopwn test phase).
--capture-file — Capture file for --crack (e.g. .cap, hash file).
--config — Path to JSON config (work dir, interfaces, API keys, etc.).
--iface — Force a specific wireless interface name (overrides auto-detection when supported).
--port 4443 Port for --c2 remote coordination API server.
--no-stealth off Disable MAC randomization / stealth behavior where applicable.
--debug off Verbose logging.
--password — WPA PSK for modes that need it (e.g. rogue AP simulation when supplying the known password).

Automated assessment chain options

Flag Default What it does
--max-targets 15 How many top-scored APs to try after the scan (ranked list). Lower = shorter run, fewer APs.
(any --autopwn) — On WPS-capable targets: Pixie, then full WPS (bully phases + Reaver fallback inside the WPS plugin). Wifite as a subprocess runs per target only with --field unless you set autopwn_wifite_without_field in JSON config.
--field off Field assessment mode: longer scan, longer PMKID/handshake windows, Wifite per target, then last-resort Wifite on the best-scored AP. Long and noisy — authorized testing only.
--field-evil-twin off With --autopwn --field: after a successful credential-strength test, attempt rogue access-point simulation using the recovered PSK. Only add if rogue AP simulation is in scope.

Typical combinations

# Interactive menu
sudo python3 alfa_arsenal.py

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

# Handshake on a known BSSID/channel
sudo python3 alfa_arsenal.py --handshake -t AA:BB:CC:DD:EE:FF -c 6

# Offline credential-strength test
python3 alfa_arsenal.py --crack --capture-file ./handshake.cap --wordlist /usr/share/wordlists/rockyou.txt

# Default automated assessment chain
sudo python3 alfa_arsenal.py --autopwn

# Broadest built-in assessment chain (field mode)
sudo python3 alfa_arsenal.py --autopwn --field

# Field mode + rogue AP simulation only after credential-strength test
sudo python3 alfa_arsenal.py --autopwn --field --field-evil-twin

# Field mode + fewer APs + custom wordlist
sudo python3 alfa_arsenal.py --autopwn --field --max-targets 5 --wordlist /path/to/list.txt

# ROE file + config
sudo python3 alfa_arsenal.py --autopwn --field --policy-file ./policies/example_roe.json --config ./my_config.json

# REST API (OpenAPI /docs)
sudo python3 -m api.app

# gRPC on port 50051
sudo python3 -m api.grpc_server --port 50051

Legal and safety note

Use these tools only on networks and systems you are authorized to test. Many flags cause active transmission (deauthentication, WPS, rogue AP simulation, beacon stress tests) that can affect third parties and may be illegal without permission.