sabia/README.md

<p align="center"><img src="apps/gui/ui/sabia.png" width="300" alt="Sabiá"></p>
<h1 align="center">Sabiá</h1>
<p align="center">Free and open Wi-Fi auditing.<br>Terminal and desktop app · live capture on Linux, offline analysis on Windows too · authorized use.</p>

<p align="center"><a href="docs/cli.md">Terminal</a> · <a href="docs/interface.md">Interface</a> · <a href="docs/architecture.md">Architecture</a> · <a href="ROADMAP.md">Roadmap</a> · <a href="CHANGELOG.md">Changelog</a></p>

<p align="center"><b>English</b> · <a href="README.pt-BR.md">Português</a></p>

---

Sabiá brings together, in a single sweep, what tools like `airodump-ng`, `hcxdumptool`, `aircrack-ng` and `wifite` do separately — in one Rust binary, with no `libpcap` dependency:

- **Network discovery:** hops across the **2.4, 5 and 6 GHz** channels and lists access points and associated clients, with SSID, BSSID, channel, signal, security type, WPS details and vendor.
- **Monitor mode without scripts:** turns the card's monitor mode on and off straight through netlink/`iw`, recovering automatically if NetworkManager tries to reclaim the interface, and shows which channels the radio supports.
- **Handshake capture:** recognizes the **4-way handshake (EAPOL)** and the **PMKID** on the air and keeps only what offline cracking needs; decrypts CCMP traffic for a client once its password is known.
- **Cracking, three ways:** dictionary (9.7M passwords bundled by default, rockyou + Probable-Wordlists), hashcat-style **mutation rules**, and **mask brute force** (`?d?l?u?s?a`) — recomputes the PMK with **PBKDF2-HMAC-SHA1** and checks the **MIC** (4-way) or the **PMKID** — for WPA/WPA2-PSK. Export to **`.hc22000`** to hand the handshake to hashcat/John instead.
- **pcap round-trip:** writes captured frames to `.pcap` and **analyzes a `.pcap` offline** (networks, clients and handshakes), interoperable with the other tools.
- **Deauthentication and WPS:** directional/continuous _deauth_, PMF probing, clientless PMKID hunting, and a WPS PIN/Pixie Dust attack (bundled reaver, or bully when installed) — all gated behind an explicit authorization confirmation (`--yes` / checkbox).
- **Evil Twin:** clones an already-seen AP with a captive portal for WPA/WPA2-PSK — the submitted password is only accepted after it's verified against the real captured handshake, never "accepts anything" — plus an Enterprise (802.1X/EAP) variant that captures credentials automatically, no portal needed.
- **Audit report:** a paginated, printable report (cover, table of contents, findings, channel scoring, audit trail) generated locally.
- **Audit trail:** every monitor-mode activation and capture session is recorded in a local **hash-chained** trail.
- **Diagnostics:** `doctor` checks privileges, tools and interfaces before you start.

## Authorized use

Sabiá is an **auditing** tool — for testing the security of networks you **own** or have **explicit authorization** to assess.

- Capturing handshakes, sending deauthentication or cracking passwords on third-party networks **without permission is illegal** in most countries. The responsibility is the operator's.
- Deauthentication (`deauth`) requires the `--yes` flag, an assertion that you are authorized to test that network.
- Every monitor-mode activation and capture session is **recorded in the local audit trail** (`sabia audit show`), hash-chained to detect tampering.
- **Nothing of yours leaves the machine.** The only network access by default is the update check on startup (which can be disabled).
- Dictionary passwords and handshakes stay on your machine.

## Install

Download the package for your system from **[Releases](../../releases)**:

| | CLI | Desktop app |
|---|---|---|
| Windows | — | `.exe` installer |
| Linux | `sabia-*-linux-{x86_64,aarch64}.tar.gz` | `.AppImage` / `.deb` |

The CLI is Linux-only; the desktop app ships for Linux and Windows. Each CLI
package has a `.sha256` next to it. Build from source: `cargo build --release
-p sabia-cli` (Rust 1.80+, Linux).

**Updates:** the desktop app checks Gitea on startup; when a new version exists, a button offers **Update now**. The CLI updates the same way (`sabia update`); it downloads the right binary for your platform, verifies the **SHA-256** and swaps the running executable — no manual download. The check is a single request to the releases API and sends nothing of yours.

> The binaries are **not signed yet**: Windows SmartScreen will warn. Check the SHA-256.

**Capture and monitor mode require Linux and root** — the only platform the CLI ships for (`CAP_NET_ADMIN`/`CAP_NET_RAW`): raw capture uses `AF_PACKET` and interface control uses netlink. **Offline `.pcap` analysis and cracking** also run on Windows and macOS. The desktop app elevates to administrator on its own at startup.

## Getting started

```bash
sabia doctor                              # privileges, tools and interfaces
sabia iface list                          # Wi-Fi interfaces and their modes
sudo sabia iface monitor wlan0 on         # enable monitor mode

sudo sabia scan wlan0 --band all --out air.pcap # hop channels and record the air
sabia analyze air.pcap                      # read a .pcap offline
sabia crack air.pcap --wordlist list.txt    # crack the handshake by dictionary
```

Authorized deauthentication testing and all other commands (`audit`, `update`, `ui`) are in **[docs/cli.md](docs/cli.md)**.

## Desktop app

Desktop app (Tauri) with an interface sidebar, a capture panel with an animated signal line, and a networks table with signal bars and color-coded security badges. The same front-end runs in the browser with `sabia ui`. More in **[docs/interface.md](docs/interface.md)**.

- Pick the interface, toggle **monitor mode** and start/stop **capture** by button.
- Live **networks seen** table, with signal, channel and security.
- An **authorized-use** notice always in view and automatic privilege elevation on startup.
- One-click **update** button, **Auto, Light and Dark** themes and interface in **Portuguese and English**.

## Known limits

- **Capture is Linux-only**, with a card that supports **monitor mode** (and injection, for `deauth`); the CLI is not built for other platforms. On Windows Sabiá's desktop app only does `.pcap` analysis and offline cracking.
- **WPA3/SAE** does not fall to handshake dictionaries — cracking covers **WPA/WPA2-PSK** (4-way and PMKID).
- **5 and 6 GHz** depend on the card and the regulatory domain; some channels stay passive (no probing).
- **Evil Twin's self-signed certificate:** the Enterprise variant's TLS certificate isn't trusted by clients that validate the chain (common on updated corporate/MDM devices) — that's the correct defense working, not a bug.
- **Windows:** the code compiles and is tested in CI, but live capture does not run there; the desktop app does offline analysis only. There is no macOS build: Tauri needs the macOS SDK and code signing, both tied to Apple hardware and an Apple Developer account, which this project's CI (a single Linux runner) does not have.

## Where it's going

Summary of the [ROADMAP](ROADMAP.md):

| | |
|---|---|
| **Done** | Monitor mode via netlink (with NetworkManager recovery), 2.4/5/6 GHz scanning, 4-way and PMKID capture, CCMP decryption, dictionary/rules/mask cracking (WPA/WPA2-PSK), `.hc22000` export, `.pcap` read/write, authorized `deauth`/PMF/PMKID, WPS attack, Evil Twin (PSK + Enterprise), channel scoring and findings, paginated audit report, hash-chained audit trail, `doctor`, CLI + desktop app, one-click update |
| **Next** | GPU acceleration for cracking, capture on Windows (Npcap) |
| **Not planned** | A macOS build — see [Known limits](#known-limits) |
| **Later** | WPA3/SAE downgrade, validation on varied hardware, signed release binaries |

## Development

```
crates/sabia-core   core: interfaces, netlink, radiotap, 802.11, EAPOL, handshake, capture, crack, audit, update
crates/sabia-cli    the `sabia` binary (CLI + local UI server)
apps/gui            interface (ui/ = HTML, CSS and JS; src-tauri/ = desktop app)
scripts/            CI helpers (cached dependency install, i18n coverage check)
docs/               terminal, interface and architecture
```

```bash
cargo test --workspace
cargo clippy --workspace --all-targets
node scripts/check-ui-i18n.mjs        # UI translation coverage
```

See [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/architecture.md](docs/architecture.md). Versions follow [SemVer](https://semver.org/); changes in [CHANGELOG.md](CHANGELOG.md). To release: `git tag vX.Y.Z && git push --tags` (the `release` workflow builds and publishes everything). Vulnerabilities: [SECURITY.md](SECURITY.md).

## License

[MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE), your choice.