# VPN & Tunnel Detection CLI Tool
[](https://pypi.org/project/detection_engine/)
[](https://pypi.org/project/detection_engine/)
[](https://opensource.org/licenses/MIT)
[](https://pepy.tech/project/detection_engine)
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](https://ipinfo.io/)
- Optional integration with [AbuseIPDB](https://www.abuseipdb.com/) and [IPQualityScore](https://ipqualityscore.com/)
- 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
1. Clone the repository:
```bash
git clone https://github.com/your-username/vpn-tunnel-detector.git
cd vpn-tunnel-detector
```
2. (Optional) Set up a virtual environment:
```bash
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. Install the tool locally in editable mode:
```bash
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:
1. Create the file:
```bash
cp .env.example .env
```
2. 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:
```bash
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/2smakshaj6/Detection_Engine_VPN_Tunnel/tree/pypi-module",
"name": "detection-engine",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Akshaj S M",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/da/57/ecac7d24a3bcea104a6b08e1304553ee4f635eb3f90281eb8be069288e6b/detection_engine-0.1.6.tar.gz",
"platform": null,
"description": "# VPN & Tunnel Detection CLI Tool\n\n[](https://pypi.org/project/detection_engine/)\n[](https://pypi.org/project/detection_engine/)\n[](https://opensource.org/licenses/MIT)\n[](https://pepy.tech/project/detection_engine)\n\nThis 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.\n\n---\n\n## Features\n\n- Uses ASN and organization name heuristics to flag suspicious infrastructure\n- Geolocation and org data powered by [IPInfo](https://ipinfo.io/)\n- Optional integration with [AbuseIPDB](https://www.abuseipdb.com/) and [IPQualityScore](https://ipqualityscore.com/)\n- Checks against auto-updated threat feeds (Tor exit nodes, botnets, DDoS infra, etc.)\n- Confidence scoring (Low, Moderate, High)\n- Easy to use with `vpnscan --ip <IP>` command\n\n---\n\n## Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/your-username/vpn-tunnel-detector.git\ncd vpn-tunnel-detector\n```\n\n2. (Optional) Set up a virtual environment:\n```bash\npython3 -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n```\n\n3. Install the tool locally in editable mode:\n```bash\npip install --editable .\n```\n\nThis gives you access to the global command `vpnscan`.\n\n---\n\n## API Keys (Optional but Recommended)\n\nTo get deeper reputation data, you can plug in:\n\n- AbuseIPDB API Key\n- IPQualityScore API Key\n\nSet them securely using a `.env` file.\n\n### Example Setup:\n\n1. Create the file:\n```bash\ncp .env.example .env\n```\n\n2. Edit the file:\n```\nABUSEIPDB_API_KEY=your_abuseipdb_key\nIPQUALITYSCORE_API_KEY=your_ipqs_key\n```\n\nThe app will auto-load them without hardcoding into the source.\n\n---\n\n## Usage\n\nRun the scan like this:\n\n```bash\nvpnscan --ip 104.28.228.78\n```\n\nYou\u2019ll get an output like:\n\n```\n------------------------ Welcome to the VPN & Threat Detection CLI Tool ------------------------\n\nThis tool checks if an IP address is associated with VPNs, proxies, abuse sources, or threat feeds (e.g. Tor, Botnets).\nIt uses heuristics, APIs, and auto-updated IP threat feeds for comprehensive detection.\n\nYou can cancel the operation at any time by pressing Ctrl+C.\n\nStarting the detection process...\n\nDetection Result\n------------------\nIP : 104.28.228.78\nORG : Cloudflare, Inc.\nASN : AS13335\nLocation : Washington, US\nIs Suspicious : Yes\nDetection Reason : ASN AS13335 is frequently used by VPN or hosting providers. Org name includes 'cloud', commonly seen in VPN or hosting services.\nAbuse Score : 100\nIPQS Fraud Score : 100\nConfidence Level : High\nDisclaimer : 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.\n\nThreat Feed Matches\n--------------------\nNo matches found in known threat feeds.\n```\n\n---\n\n## Project Structure\n\n```\npymod_detection_engine/\n\u251c\u2500\u2500 detection_engine/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 run_engine.py\n\u2502 \u251c\u2500\u2500 config/\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2514\u2500\u2500 suspicious_asns.json\n\u2502 \u251c\u2500\u2500 engine/\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 detection_engine.py\n\u2502 \u2502 \u251c\u2500\u2500 heuristics.py\n\u2502 \u2502 \u251c\u2500\u2500 ipinfo_wrapper.py\n\u2502 \u2502 \u251c\u2500\u2500 threat_feeds.py\n\u2502 \u2502 \u251c\u2500\u2500 abuseipdb_checker.py\n\u2502 \u2502 \u2514\u2500\u2500 ipqualityscore_checker.py\n\u2502 \u2514\u2500\u2500 feeds/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 fetch_feeds.py\n\u2502 \u2514\u2500\u2500 known_bad_ips.json\n\u251c\u2500\u2500 .env.example\n\u251c\u2500\u2500 requirements.txt\n\u251c\u2500\u2500 setup.py\n\u251c\u2500\u2500 MANIFEST.in\n\u251c\u2500\u2500 README.md\n```\n\n---\n\n## License\n\nMIT License \u2014 use, fork, improve, or share with attribution.\n\n---\n\n## \ud83d\ude4b\u200d\u2642\ufe0f About\n\nThis is a hobby project built for learning, awareness, and experimentation. \nIt\u2019s not a replacement for professional threat intelligence platforms \u2014 but it\u2019s a great start. \nFeedback, ideas, or issues? Feel free to open one on GitHub.\n",
"bugtrack_url": null,
"license": null,
"summary": "Detect VPN, Proxy, Tor, Botnets & abusive IPs using hybrid threat intelligence",
"version": "0.1.6",
"project_urls": {
"Homepage": "https://github.com/2smakshaj6/Detection_Engine_VPN_Tunnel/tree/pypi-module"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2a2db62adf80a9935a3d375864f0e9e5bb4507dadd4e50334e355f3cbea5e9ff",
"md5": "88be421d7b29974c23cf2174cd416627",
"sha256": "5fc02151c2c44981e22d8924b67378b630204f10a75bf9259f43530a2df8e13b"
},
"downloads": -1,
"filename": "detection_engine-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "88be421d7b29974c23cf2174cd416627",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 19592,
"upload_time": "2025-07-12T04:53:10",
"upload_time_iso_8601": "2025-07-12T04:53:10.758217Z",
"url": "https://files.pythonhosted.org/packages/2a/2d/b62adf80a9935a3d375864f0e9e5bb4507dadd4e50334e355f3cbea5e9ff/detection_engine-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "da57ecac7d24a3bcea104a6b08e1304553ee4f635eb3f90281eb8be069288e6b",
"md5": "38cec15d66cd8be0ab1b48243d6e0e83",
"sha256": "a1e29d4fa674700c1ecc153dc11e8df584875fdd05be21aa15bfefd031719917"
},
"downloads": -1,
"filename": "detection_engine-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "38cec15d66cd8be0ab1b48243d6e0e83",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 18451,
"upload_time": "2025-07-12T04:53:12",
"upload_time_iso_8601": "2025-07-12T04:53:12.389376Z",
"url": "https://files.pythonhosted.org/packages/da/57/ecac7d24a3bcea104a6b08e1304553ee4f635eb3f90281eb8be069288e6b/detection_engine-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 04:53:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "2smakshaj6",
"github_project": "Detection_Engine_VPN_Tunnel",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "certifi",
"specs": [
[
"==",
"2025.6.15"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.4.2"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.10"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.4"
]
]
},
{
"name": "tqdm",
"specs": [
[
"==",
"4.67.1"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.5.0"
]
]
}
],
"lcname": "detection-engine"
}
JSON
