Wireless assessment, detection, and evidence collection from one Python CLI.
Version: 1.0 · Author: dx73r · License: MIT · Primary platform: Linux
Entity provides a consistent interface around established wireless-security utilities. It combines assessment workflows with passive detection, capture analysis, input validation, evidence logging, and report generation.
- Capabilities
- Requirements
- Installation
- Usage
- Capture analysis and detection
- Evidence and reports
- Security design
- Limitations
- Troubleshooting
- Project structure
- License
| Area | Included workflows |
|---|---|
| Interface control | Start and stop monitor mode |
| Discovery | Network scans and WPS discovery |
| Capture | Handshake, PMKID, and TCP traffic collection |
| Assessment | Wordlist and generated-candidate auditing, WPS testing |
| Controlled disruption | Deauthentication and beacon-flood testing with confirmation |
| Passive detection | Deauthentication-frame and possible rogue-AP detection |
| Offline analysis | PCAP inventory and EAPOL handshake-sequence validation |
| Evidence | Append-only JSONL event logging |
| Reporting | Machine-readable JSON and standalone HTML reports |
Entity does not install Linux packages automatically or modify system files during startup.
- Linux for wireless operations
- Python 3.10 or newer
- A wireless adapter and driver that support monitor mode
- Appropriate privileges for the selected system utilities
Windows can run dependency checks and dry-run previews, but it cannot provide the Linux monitor-mode toolchain used by Entity.
Entity integrates with:
- Aircrack-ng tools:
airmon-ng,airodump-ng,aireplay-ng,aircrack-ng bullycrunchhcxdumptoolmdk3reavertsharkwifite
airgeddon and xterm are optional. Check the current machine with:
entity --checkFrom the project directory:
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install .
entity --checkbash install.sh
entity --checkThe installer installs the Python package only. Install external wireless utilities through the package manager and documentation for your Linux distribution.
Start the interactive interface:
entityRun directly from a source checkout:
python3 entity.pyPreview commands without executing external tools:
entity --dry-runSkip the banner:
entity --no-bannerSelect a custom evidence directory:
entity --evidence-dir ./assessment-outputDisplay version information:
entity --versionWindows commonly exposes Python as python, not python3:
python -m pip install .
python entity.py --dry-runMenu option 15 reads an existing capture with PyShark and reports:
- packet and protocol counts;
- observed SSIDs and BSSIDs;
- deauthentication and disassociation frame counts;
- EAPOL frame counts;
- observed four-way-handshake message numbers;
- BSSIDs advertising a supplied expected SSID.
Supplying an expected SSID and trusted BSSID enables a focused possible rogue-access-point check.
Menu option 16 passively observes a monitor-mode interface for a bounded number of packets. It applies the same deauthentication, rogue-AP, and handshake analysis used by the offline workflow.
The detector does not automatically transmit packets or alter interface state.
Entity reports a complete sequence only when messages 1, 2, 3, and 4 are identifiable in the analyzed EAPOL traffic. If EAPOL traffic exists but message numbers are unavailable, the result is marked inconclusive. Capture validation is not cryptographic proof that credentials can be recovered.
Each interactive session creates an append-only JSONL event log. Capture analysis additionally produces:
- a JSON report for automation and further analysis;
- a standalone HTML report for presentation and submission.
The default output directory is:
entity-evidence/
If the requested directory cannot be created, Entity falls back to the
operating system's temporary entity-evidence directory and prints the full
path.
Sensitive values passed after common password or PIN command flags are redacted from console output and evidence logs.
- External commands are passed as argument lists without
shell=True. - User-controlled values are validated before reaching external utilities.
- File arguments are normalized to absolute paths.
- Option-like interface and character-set values are rejected.
- System dependencies are checked rather than installed automatically.
- Disruptive workflows require an additional confirmation.
- Child processes are terminated when an operation is cancelled.
--dry-runprovides command visibility without execution.
- Wireless operations depend on Linux drivers, adapter capabilities, and versions of external tools.
- Multiple BSSIDs for one SSID can be legitimate on mesh, roaming, or enterprise deployments; rogue-AP findings require human validation.
- Deauthentication frames can occur during normal network operation. Counts alone do not prove an attack.
- PyShark requires a functioning TShark installation.
- Live capture behavior cannot be fully verified without compatible hardware.
Use:
python -m pip install .For full wireless functionality, run Entity on Linux or an appropriate Linux environment with direct access to a compatible adapter.
Run:
entity --checkInstall the reported utilities using your distribution's package manager.
Entity automatically selects a temporary fallback directory and displays its location. You can also select a known-writable path:
entity --evidence-dir /path/to/outputReview the packet-capture permissions recommended by your Linux distribution or Wireshark package. Avoid changing system permissions without understanding their security impact.
Entity/
├── entity.py # Complete application
├── pyproject.toml # Package metadata and console entry point
├── requirements.txt # Python runtime dependency
├── install.sh # Python package installer
├── README.md # Project documentation
├── LICENSE # MIT license
├── .gitignore
└── .gitattributes
The installable application intentionally remains in one Python source file.
Entity is released under the MIT License.
Copyright © 2026 dx73r.