Metadata-Version: 2.4
Name: airshark
Version: 0.1.0
Summary: Terminal Wi-Fi monitor for macOS. Puts the interface into monitor mode, hops channels, with support for WPA/WPA2 decryption.
Author: chiroyce
License: MIT License
        
        Copyright (c) chiroyce
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/chiroyce1/airshark
Project-URL: Issues, https://github.com/chiroyce1/airshark/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: MacOS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=0.40.0
Requires-Dist: rich>=13.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyobjc-framework-CoreWLAN; sys_platform == "darwin"
Dynamic: license-file

# AirShark

![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue) ![macOS](https://img.shields.io/badge/platform-macOS-lightgrey) ![License](https://img.shields.io/badge/license-MIT-green)

Terminal Wi-Fi monitor for macOS. Puts the interface into monitor mode, hops channels, with support for WPA/WPA2 decryption.

> [!NOTE]
> Currently in early development. Only been tested on Apple Silicon (M1) with Wi-Fi 5.

- **Capture:** `dumpcap` while the interface is in monitor mode and captures raw frames, which are piped into `tshark` (`-T ek`) to generate JSON, which is fed into a background thread for the TUI to read off of.
- **Channel hopping:** Implemented using CoreWLAN via PyObjC. The interface is disassociated once at startup to allow raw packet capture.
- **UI:** [Textual](https://github.com/Textualize/textual).

## Requirements

- macOS
- Python 3.10+
- [Wireshark](https://www.wireshark.org/download.html) / tshark  
  During install, make sure to enable the **ChmodBPF** capture permissions. This allows AirShark to capture packets entirely **without `sudo`**.

## Installation

```bash
pip install airshark
```

Or clone from source and install in editable mode:

```bash
git clone <repo-url>
cd airshark
pip install -e .
```

## Configuration

Credentials for decryption can come from the CLI or a .env file:

```env
SSID="YourNetworkName"
PASSWORD="YourPassphrase"
```

CLI flags (`-s`/`-k`) can override `.env`.

## Usage

```bash
# Monitor channel 6
airshark -i en0 -c 6

# Hop 2.4 GHz, 0.5 s per channel
airshark -i en0 --band 2.4 --dwell 0.5

# 5 GHz hop + live decryption
airshark -i en0 --band 5 -s HomeNet -k s3cr3t
```

Keybindings while running:

| Key       | Action                                 |
| --------- | -------------------------------------- |
| `h`       | Toggle channel hopping on / off        |
| `,` / `.` | Previous / Next channel (when hopping) |
| `=` / `-` | Increase / decrease channel dwell time |
| `q`       | Quit                                   |

## Known Limitations

### EAPOL (4-Way Handshake) Capture

For reliable EAPOL capture (and subsequent WPA decryption), it is recommended to **lock AirShark to the target AP's specific channel** (e.g., `airshark -c 60`) rather than sweeping an entire band, or use the `h` keybind and select the channel using `,` and `.` keys.

### Multi-Band Hopping (2.4 + 5 GHz + 6 GHz)

The macOS `CoreWLAN` framework imposes hardware limitations that prevent the Wi-Fi radio from transparently hopping across different frequency bands. If attempted, the initial cross-band hop may succeed, but subsequent hops are silently ignored by the macOS Wi-Fi driver. Therefore, AirShark restricts channel hopping to a single band at a time (e.g., 2.4 GHz, 5 GHz, or 6 GHz).
Refer to this [post](https://developer.apple.com/forums/thread/818603?answerId=881663022#881663022) on the Apple developer forums for additional technical context.

## Named pipe support

You can stream packets from AirShark to other tools like Wireshark using Unix named pipes.

1. **Create the named pipe:**
   ```bash
   mkfifo /tmp/airshark.pipe
   ```
2. **Start Wireshark reading from the pipe first:**

   ```bash
   wireshark -k -i /tmp/airshark.pipe &
   ```

3. **Run AirShark and output to the pipe:**
   ```bash
   airshark --band 5 -o /tmp/airshark.pipe
   ```

## CLI Reference

```
capture:
  -i IFACE, --interface   Wireless interface (default: en0)
  -I, --monitor           Enable monitor mode (default: on)
  -o FILE, --output       Output PCAP file or named pipe (default: airshark_capture.pcap)
  -c N, --channel         Channel for single mode (default: 6)
  --band BAND             Band to sweep: single | 2.4 | 5 | 6
  --dwell SECS            Seconds per channel when hopping (default: 0.75)

decryption:
  -s, -S, --ssid SSID     Network SSID for WPA decryption
  -k PASSPHRASE, --key    WPA/WPA2 passphrase
```
