🛡️ ActiveVPN
The Ultimate Network Privacy & VPN Detection Tool
ActiveVPN inspects your system's network interfaces, analyzes running processes, checks your external IP against known hosting providers, and performs DNS leak tests — all in one hacker-style terminal UI. It tells you whether your VPN is actually working.
Screenshot
More screenshots: View all screenshots
Table of Contents
- Key Features
- Installation
- Quick Start
- Usage Examples
- Documentation
- Interface
- Architecture
- Requirements
- Prerequisites
- Development
- Contributing
- Security
- License
- Acknowledgments
Key Features
- Deep scan — detects VPNs via interface names, process names, and IP reputation in one pass.
- Tor detection — specifically checks for active Tor services.
- External IP analysis — queries public IP APIs and flags datacenter/hosting/proxy IPs.
- DNS leak detection — compares your traffic IP with your DNS resolver IP.
- IPv6 leak check — reports your external IPv6 address and warns when IPv6 may leak around a tunnel.
- Overall verdict — combines every signal into a confidence score and a CLEAN / SUSPICIOUS / LIKELY VPN-PROXY / VPN DETECTED label.
- Kill switch — terminates active VPN processes, with a
--kill-forcefallback. - History & export — automatically logs scans to your platform's data directory, viewable with
--historyand exportable as JSON, CSV, or TXT. - Library API — importable as a Python package (
activevpn.scan(),NetworkDetector, typedScanResult), with silent mode and watch callbacks for developers. - Watch mode — continuously re-scans at a configurable interval.
- Configurable — patterns, colors, and API endpoints can be overridden with a JSON config file.
Installation
Requires Python 3.8 or newer and pip.
pip install activevpn
Or install from source:
git clone https://github.com/rkriad585/ActiveVPN.git
cd ActiveVPN
pip install -r requirements.txt
See docs/installation.md for platform-specific notes (Linux, macOS, Windows, Termux).
Quick Start
# Run a full scan
activevpn
You should see a system check, an external IP analysis, a DNS consistency check, and an overall verdict.
Usage Examples
# Standard network scan (interfaces, processes, IP, DNS)
activevpn
# Kill active VPN processes (requires admin/root)
sudo activevpn --kill
# Force-kill stubborn VPN processes
sudo activevpn --kill-force
# Show past scan results
activevpn --history
# Export scan history as CSV
activevpn --export csv
# Clear all saved history
activevpn --clear-history
# Continuously rescan every 30 seconds
activevpn --watch 30
# Verbose debug logging
activevpn --debug
# Show help
activevpn --help
Exit codes: 0 = no VPN detected, 1 = VPN/Tor/Proxy detected, 2 = offline or error. Full reference in docs/cli.md.
Documentation
| Doc | Description |
|---|---|
| docs/getting-started.md | First steps with ActiveVPN |
| docs/installation.md | Install instructions for every platform |
| docs/usage.md | Daily usage and examples |
| docs/cli.md | Full command-line reference |
| docs/configuration.md | Config file and environment variables |
| docs/architecture.md | How the code is organized |
| docs/development.md | Building, testing, and packaging |
| docs/deployment.md | Running on servers and in containers |
| docs/faq.md | Frequently asked questions |
| docs/troubleshooting.md | Common issues and fixes |
| docs/screenshots.md | All screenshots |
| GitHub Pages | Online documentation site |
Interface
ActiveVPN is a command-line tool. It is distributed as the activevpn console script (see [project.scripts] in pyproject.toml) and can also be launched with python main.py.
When run without flags it performs a full scan and prints four sections:
- System Internal Check — detected VPN/Tor interfaces and processes.
- External IP Analysis — public IP, country, ISP/org, IPv4/IPv6, and a verdict.
- DNS Consistency Check — traffic IP vs. DNS resolver IP.
- Overall Verdict — confidence score (
0–100) and label.
The tool returns meaningful exit codes (0/1/2) so it can be used in scripts and CI.
Architecture
ActiveVPN/
├── main.py # Entry point + CLI (argparse) + rich TUI rendering
├── config.py # Legacy shim → re-exports activevpn.config
├── pyproject.toml # Packaging, metadata, console script
├── requirements.txt # Runtime dependencies
├── activevpn/ # The library (importable as a package)
│ ├── __init__.py # Public API: scan(), NetworkDetector, ScanResult, ...
│ ├── config.py # Config dataclass, platformdirs paths, load_config()
│ ├── detector.py # NetworkDetector + typed data model (ScanResult, Verdict, IPInfo, ...)
│ ├── logger.py # History persistence, load/clear, and export helpers
│ ├── logo.py # ASCII banner generation (pyfiglet + rich)
│ └── help.py # Help menu rendering
├── core/ # Backward-compatible shim (deprecated, use activevpn)
├── tests/ # pytest suite (mocked psutil/requests)
├── logo/ # Brand logo
└── docs/ # Documentation
The flow: main.run() parses arguments → NetworkDetector.scan_network() collects system + online signals → _compute_verdict() scores them → save_log() persists the result → tables/panels are rendered with rich.
Using as a Library
import activevpn
# One-shot scan (silent — no TUI)
result = activevpn.scan(console=None)
print(result.verdict.label, result.verdict.score) # CLEAN 0
print(result.to_json()) # serializable output
# Programmatic configuration (stored under ~/.config/neostore/ActiveVPN/config.toml)
cfg = activevpn.load_config()
cfg.vpn_process_names.append("my-vpn-daemon")
# Continuous watch with callbacks
detector = activevpn.NetworkDetector(console=None, config=cfg)
for r in detector.watch(interval=60, on_change=lambda r: print("Verdict changed!", r.verdict.label)):
pass
See docs/architecture.md for details.
Requirements
| Requirement | Minimum |
|---|---|
| OS | Linux, macOS, Windows, or Android (Termux) |
| Runtime | Python 3.8+ |
| Network | Internet access for the public IP and DNS checks |
No special hardware is required. --kill and --kill-force need administrator/root privileges.
Prerequisites
- Python 3.8+ — download from python.org or your package manager.
- pip — bundled with Python on modern installers.
On Linux:
sudo apt update && sudo apt install -y python3 python3-pip
On macOS (Homebrew):
brew install python
Development
# Clone and install dependencies
git clone https://github.com/rkriad585/ActiveVPN.git
cd ActiveVPN
python -m venv .venv
. .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
pip install -r requirements.txt pytest build twine
# Run the test suite
pytest -q
# Build the distributable packages
python -m build
# Verify the built artifacts
python -m twine check dist/*
The CI workflow (.github/workflows/ci.yml) runs pytest on Ubuntu, Windows, and macOS with Python 3.8 and 3.12. See docs/development.md.
Contributing
Contributions are welcome! Please read CONTRIBUTING.md for setup, branch rules, commit style, and the pull request workflow. All participants must follow the CODE_OF_CONDUCT.md.
Security
If you find a security issue, please read SECURITY.md before reporting it. Do not open a public issue for vulnerabilities.
License
Distributed under the MIT License. See LICENSE for the full text.
Acknowledgments
Metadata
Release files for activevpn 2.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| activevpn-2.4.0.tar.gz | 27.8 kB | Without provenance | Details for activevpn-2.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| activevpn-2.4.0-py3-none-any.whl | Python 3 | none | any | Details for activevpn-2.4.0-py3-none-any.whl |
Total release size: 51.2 kB
Release files / activevpn-2.4.0.tar.gz
| Download URL | activevpn-2.4.0.tar.gz |
|---|---|
| Size | 27.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c683d68faa6aead903e4f02417952e45e64a18d8ee1aa0b10d144de8ccf71289
|
|
BLAKE2b-256 checksum How to use checksums |
65f4f2acdf5b4541c93a1cb17b31fd23ece3b9c8a4008e1decb1dea28ba0c980
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.7
|
Release files / activevpn-2.4.0-py3-none-any.whl
| Download URL | activevpn-2.4.0-py3-none-any.whl |
|---|---|
| Size | 23.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
37624f817b6fbe720966aaf8a53f4c3cfbbf1edb5b372b8f398890905261cb01
|
|
BLAKE2b-256 checksum How to use checksums |
3d43030241d039565232f183a78044a49085babcf1d76fdd7ad137cd0638e233
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.7
|
Security for activevpn 2.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.