detection-engine

VPN & Tunnel Detection CLI Tool

This project is a Python-based command-line tool that helps you detect whether an IP address is likely coming from a VPN, proxy, or abusive source. It uses a combination of IP metadata, ASN heuristics, and optional third-party API lookups for deeper inspection.

Features

• Uses ASN and organization name heuristics to flag suspicious infrastructure
• Geolocation and org data powered by IPInfo
• Optional integration with AbuseIPDB and IPQualityScore
• Checks against auto-updated threat feeds (Tor exit nodes, botnets, DDoS infra, etc.)
• Confidence scoring (Low, Moderate, High)
• Easy to use with vpnscan --ip <IP> command

Installation

• Clone the repository:

git clone https://github.com/your-username/vpn-tunnel-detector.git
cd vpn-tunnel-detector

• (Optional) Set up a virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

• Install the tool locally in editable mode:

pip install --editable .

This gives you access to the global command vpnscan.

API Keys (Optional but Recommended)

To get deeper reputation data, you can plug in:

• AbuseIPDB API Key
• IPQualityScore API Key

Set them securely using a .env file.

Example Setup:

• Create the file:

cp .env.example .env

• Edit the file:

ABUSEIPDB_API_KEY=your_abuseipdb_key
IPQUALITYSCORE_API_KEY=your_ipqs_key

The app will auto-load them without hardcoding into the source.

Usage

Run the scan like this:

vpnscan --ip 104.28.228.78

You’ll get an output like:

------------------------ Welcome to the VPN & Threat Detection CLI Tool ------------------------

This tool checks if an IP address is associated with VPNs, proxies, abuse sources, or threat feeds (e.g. Tor, Botnets).
It uses heuristics, APIs, and auto-updated IP threat feeds for comprehensive detection.

You can cancel the operation at any time by pressing Ctrl+C.

Starting the detection process...

Detection Result
------------------
IP                : 104.28.228.78
ORG               : Cloudflare, Inc.
ASN               : AS13335
Location          : Washington, US
Is Suspicious     : Yes
Detection Reason  : ASN AS13335 is frequently used by VPN or hosting providers. Org name includes 'cloud', commonly seen in VPN or hosting services.
Abuse Score       : 100
IPQS Fraud Score  : 100
Confidence Level  : High
Disclaimer        : This result indicates whether the IP shows characteristics of VPN/proxy, abuse, or known threat activity. It does not imply malicious intent. Many users use VPNs for privacy or remote work.

Threat Feed Matches
--------------------
No matches found in known threat feeds.

Project Structure

pymod_detection_engine/
├── detection_engine/
│   ├── __init__.py
│   ├── run_engine.py
│   ├── config/
│   │   ├── __init__.py
│   │   └── suspicious_asns.json
│   ├── engine/
│   │   ├── __init__.py
│   │   ├── detection_engine.py
│   │   ├── heuristics.py
│   │   ├── ipinfo_wrapper.py
│   │   ├── threat_feeds.py
│   │   ├── abuseipdb_checker.py
│   │   └── ipqualityscore_checker.py
│   └── feeds/
│       ├── __init__.py
│       ├── fetch_feeds.py
│       └── known_bad_ips.json
├── .env.example
├── requirements.txt
├── setup.py
├── MANIFEST.in
├── README.md

License

MIT License — use, fork, improve, or share with attribution.

🙋‍♂️ About

This is a hobby project built for learning, awareness, and experimentation.
It’s not a replacement for professional threat intelligence platforms — but it’s a great start.
Feedback, ideas, or issues? Feel free to open one on GitHub.