Metadata-Version: 2.4
Name: wifi-profile-inspector
Version: 1.0.0
Summary: Inspect WiFi profiles saved locally on Windows via netsh wlan, in a Rich-powered terminal dashboard.
Author: WiFi Profile Inspector Contributors
License: MIT License
        
        Copyright (c) 2026 WiFi Profile Inspector Contributors
        
        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: Homepage, https://github.com/yourusername/wifi-profile-inspector
Project-URL: Changelog, https://github.com/yourusername/wifi-profile-inspector/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/yourusername/wifi-profile-inspector/issues
Keywords: wifi,netsh,windows,cli,security,soc,network
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich<14,>=13.7
Requires-Dist: pyfiglet<2,>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# WiFi Profile Inspector

A Windows CLI tool for inspecting WiFi profiles already saved on the
**local** machine — authentication type, cipher, connection mode, and
(only when explicitly requested) the stored key — presented through a
Rich-powered terminal dashboard.

Built as a defensive-security / SOC-analyst portfolio project: clean
architecture, full type hints, unit tests, and a strict local-only,
opt-in-only design.

![Python](https://img.shields.io/badge/python-3.12%2B-blue)
![Platform](https://img.shields.io/badge/platform-Windows-lightgrey)
![License](https://img.shields.io/badge/license-MIT-green)

## Disclaimer

This tool only reads WiFi profile data that **Windows already stores
locally** for the current user — the same data exposed by Windows'
own network settings UI and by running `netsh wlan show profile`
directly. It does not:

- connect to any network,
- target or scan remote hosts,
- escalate privilege,
- persist itself, evade detection, or exfiltrate data,
- or reveal any key without an explicit `--reveal-keys` flag.

It is intended for personal use on machines you own or are authorized
to administer, and for educational purposes (understanding how
Windows stores WiFi profile data and how to build a clean CLI tool
around it).

## Features

- **List** every saved WiFi profile in a Rich table (SSID,
  authentication, cipher, connection mode, key presence, security
  level).
- **Show** full detail for a single profile, with keys hidden unless
  `--reveal-keys` is passed.
- **Export** all profiles to JSON, CSV, or TXT.
- **Report** view: profile table plus an aggregate security summary
  (open networks, weak/legacy authentication, stored-key count).
- Security classification (`open` / `weak` / `strong` / `unknown`)
  computed per profile.
- Structured logging, optional `--log-file` output.
- Fully unit-tested parsing and export logic.

## Screenshots

> _Add terminal screenshots here before publishing — e.g._
> `docs/screenshots/list-view.png`, `docs/screenshots/report-view.png`

## Architecture

See [`docs/architecture.md`](docs/architecture.md) for the full layer
breakdown. Summary:

```
wifi-profile-inspector/
├── src/wifi_profile_inspector/
│   ├── cli.py          # CLI entry point (installed as the `wifi-inspector` command)
│   ├── core/            # netsh execution, parsing, reports, export, logging
│   ├── models/          # WifiProfile dataclass, SecurityLevel enum
│   ├── ui/              # Rich banner, tables, panels, dashboard composition
│   └── utils/           # environment helpers, validators, status-tag colors
├── tests/               # unit tests (no Windows/netsh required)
└── reports/             # default export output directory
```

## Installation

Requires Windows and Python 3.9+.

Install directly from PyPI — no cloning or `cd`-ing into the project
folder required:

```bash
pip install wifi-profile-inspector
```

This installs the `wifi-inspector` command onto your `PATH`, so it can
be run from any directory.

### For local development instead

If you're working on the source itself rather than just using the
tool, clone the repo and install it in editable mode:

```bash
git clone https://github.com/<your-username>/wifi-profile-inspector.git
cd wifi-profile-inspector
pip install -e .
```

## Usage

Once installed, use the `wifi-inspector` command from anywhere:

```bash
# List all saved profiles
wifi-inspector list

# Show one profile (keys hidden by default)
wifi-inspector show "Home-WiFi"

# Show one profile with the stored key revealed
wifi-inspector show "Home-WiFi" --reveal-keys

# Export every profile to JSON (keys omitted by default)
wifi-inspector export --format json --output reports/profiles.json

# Export including revealed keys
wifi-inspector export --format csv --output reports/profiles.csv --reveal-keys

# Full dashboard + security summary
wifi-inspector report

# Verbose logging, persisted to a file
wifi-inspector list --verbose --log-file logs/run.log
```

### Example output

```
$ wifi-inspector list

 _       ___ _______    ____             _____ __
| |     / (_) ____(_)  / __ \_________  / __(_) /__
| | /| / / / /_  / /  / /_/ / ___/ __ \/ /_/ / / _ \
| |/ |/ / / __/ / /  / ____/ /  / /_/ / __/ / /  __/
|__/|__/_/_/   /_/  /_/   /_/   \____/_/ /_/_/\___/

v1.0.0 — Windows WiFi Profile Inspection Tool

╭───────── Session Information ──────────╮
│           User:  ammar                 │
│             OS:  Windows-11-10.0.22631  │
│         Python:  3.12.3                 │
│      Timestamp:  2026-08-06 02:30:00    │
│ Profiles found:  3                      │
╰──────────────────────────────────────────╯
────────────────────────────────────────────────────────────
                    Saved WiFi Profiles
┏━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ SSID      ┃ Authentication┃ Cipher ┃ Key Stored ┃ Security ┃
┡━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━┩
│ Home-WiFi │ WPA2-Personal │ CCMP   │ Yes        │ STRONG   │
│ CafeGuest │ Open          │ None   │ No         │ OPEN     │
└───────────┴───────────────┴────────┴────────────┴──────────┘
```

### Export examples

**JSON** (`--format json`):
```json
{
  "generated_at": "2026-08-06T02:30:00+00:00",
  "profile_count": 1,
  "profiles": [
    {
      "ssid": "Home-WiFi",
      "authentication": "WPA2-Personal",
      "cipher": "CCMP",
      "connection_mode": "Connect automatically",
      "key_present": true,
      "security_level": "strong"
    }
  ]
}
```

**CSV** (`--format csv`): one row per profile, columns matching the
JSON keys above.

**TXT** (`--format txt`): a human-readable block per profile, suitable
for pasting into a report.

## Running tests

```bash
git clone https://github.com/<your-username>/wifi-profile-inspector.git
cd wifi-profile-inspector
pip install -e .[dev]
python -m pytest tests/ -v
```

Tests exercise `core/parser.py` and `core/exporter.py` against fixed
sample text and temporary files — no Windows machine or real `netsh`
call is required, so they run in CI on any OS.

## Project structure

```
wifi-profile-inspector/
├── pyproject.toml
├── README.md
├── LICENSE
├── CHANGELOG.md
├── CONTRIBUTING.md
├── .gitignore
├── src/
│   └── wifi_profile_inspector/
│       ├── __init__.py
│       ├── cli.py             # entry point, installed as `wifi-inspector`
│       ├── core/
│       │   ├── wifi_manager.py       # sole owner of subprocess/netsh calls
│       │   ├── parser.py              # raw netsh text → WifiProfile
│       │   ├── report_generator.py    # aggregate security statistics
│       │   ├── exporter.py            # JSON / CSV / TXT export
│       │   └── logger.py              # logging configuration
│       ├── models/
│       │   └── wifi_profile.py        # WifiProfile dataclass, SecurityLevel enum
│       ├── ui/
│       │   ├── banner.py
│       │   ├── dashboard.py
│       │   ├── panels.py
│       │   ├── tables.py
│       │   ├── progress.py
│       │   └── theme.py
│       └── utils/
│           ├── helpers.py
│           ├── validators.py
│           └── colors.py
├── reports/
├── tests/
│   ├── test_parser.py
│   └── test_export.py
└── docs/
    ├── architecture.md
    └── screenshots/
```

## Publishing to PyPI

The project is already set up as an installable package (`pyproject.toml`,
`src/` layout, `wifi-inspector` console script). To publish a new version:

```bash
pip install build twine
python -m build                        # creates dist/*.whl and dist/*.tar.gz
twine upload --repository testpypi dist/*   # optional: try it on TestPyPI first
twine upload dist/*                     # publish to the real PyPI
```

You'll need a PyPI account and an API token (create one under
Account settings → API tokens, then use `__token__` as the username
and the token as the password when `twine` prompts). Bump the
`version` field in `pyproject.toml` before every new upload — PyPI
does not allow re-uploading the same version number.

## Future improvements

- Search and sort flags for the `list` command (by SSID, security
  level, authentication type).
- A `diff` command comparing two exported reports over time.
- Packaging as a standalone `.exe` via PyInstaller for non-technical
  users.
- Optional integration with a SIEM/log-forwarding pipeline for
  periodic WiFi posture snapshots.

## License

MIT — see [LICENSE](LICENSE).
