Metadata-Version: 2.4
Name: teamdev-dcblock
Version: 2.1.0
Summary: DC/VPN/Proxy/Tor IP Detector — TeamDev DCBlock @TEAM_X_OG On Telegram
Author-email: TeamDev <TeamDevMail@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/teamdev-sbs/dcblock
Project-URL: Repository, https://github.com/teamdev-sbs/dcblock
Project-URL: Issues, https://github.com/teamdev-sbs/dcblock/issues
Project-URL: Telegram, https://t.me/Team_X_Og
Project-URL: Donate, https://pay.teamdev.sbs
Keywords: datacenter,ip,vpn,proxy,tor,security,blocking,firewall,cidr,geolocation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking :: Firewalls
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Requires-Dist: aiohttp>=3.8
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == "fastapi"
Requires-Dist: starlette>=0.27; extra == "fastapi"
Requires-Dist: uvicorn>=0.22; extra == "fastapi"
Provides-Extra: flask
Requires-Dist: flask>=2.3; extra == "flask"
Requires-Dist: flask-cors>=4.0; extra == "flask"
Provides-Extra: django
Requires-Dist: django>=4.0; extra == "django"
Provides-Extra: bot
Requires-Dist: pyTelegramBotAPI>=4.14; extra == "bot"
Provides-Extra: all
Requires-Dist: fastapi>=0.100; extra == "all"
Requires-Dist: starlette>=0.27; extra == "all"
Requires-Dist: uvicorn>=0.22; extra == "all"
Requires-Dist: flask>=2.3; extra == "all"
Requires-Dist: flask-cors>=4.0; extra == "all"
Requires-Dist: pyTelegramBotAPI>=4.14; extra == "all"

# 🛡 TeamDev DCBlock v2.1

**The most complete DC / VPN / Proxy / Tor IP detection engine for Python.**

30+ live CIDR sources · Binary-search O(log n) lookup · Full geo enrichment · Built-in REST API · CLI · Multi-framework support

---

## What is DCBlock?

DCBlock is a Python library (and CLI tool) that tells you whether an IP address belongs to a datacenter, VPN, proxy, Tor exit node, or cloud provider. It does this by loading CIDR ranges from 30+ official sources (AWS, GCP, Azure, Hetzner, Cloudflare, etc.) and matching the IP against them in microseconds. On top of that, it enriches results with geo/ASN data, risk scores, reverse DNS, and more.

It's built for developers who need to:

- Block bots, scrapers, and automated traffic from their apps
- Detect datacenter IPs in fraud detection pipelines
- Build IP intelligence APIs
- Add security middleware to Flask / FastAPI / Django

---

## Install

```bash
pip install teamdev-dcblock
```

With Flask API support:
```bash
pip install "teamdev-dcblock[flask]"
```

With FastAPI support:
```bash
pip install "teamdev-dcblock[fastapi]"
```

Install everything:
```bash
pip install "teamdev-dcblock[all]"
```

---

## CLI

After installing, the `dcblock` command is available globally.

### Check a single IP

```bash
dcblock check 3.108.66.217
```

```
  IP           3.108.66.217
  Status        HOSTING
  Risk Score    █████░░░░░ 50%
  Reason        hosting_flag
  Org / ISP     AWS EC2 (ap-south-1)
  ASN           AS16509 Amazon.com, Inc.
  Location      Mumbai, Maharashtra, India
  Reverse DNS   ec2-3-108-66-217.ap-south-1.compute.amazonaws.com
  Tags          hosting, datacenter-asn
```

### Check multiple IPs (table view)

```bash
dcblock check 1.2.3.4 8.8.8.8 45.33.32.156
```

### Check from a file

```bash
# ips.txt — one IP per line, # for comments
dcblock batch ips.txt
```

### Export to JSON or CSV

```bash
dcblock check 1.2.3.4 8.8.8.8 --json
dcblock check 1.2.3.4 8.8.8.8 --csv --out results.csv
dcblock batch ips.txt --json --out results.json
```

### Deep WHOIS-style enrichment

```bash
dcblock whois 8.8.8.8
```

### Start the REST API server

```bash
dcblock serve --port 5000
```

### Other commands

```bash
dcblock update        # Force refresh all CIDR lists
dcblock stats         # Show source statistics
dcblock check 1.2.3.4 --no-enrich   # CIDR-only, no geo lookup (faster)
dcblock check 1.2.3.4 --card        # Detailed card view
```

---

## Python API

### Basic usage

```python
from dcblock import DatacenterBlocker

blocker = DatacenterBlocker(enrich_asn=True).load()

result = blocker.check("3.108.66.217")

print(result.status_label())   # → HOSTING
print(result.risk_score)       # → 50
print(result.org)              # → Amazon.com
print(result.country)          # → India
print(result.is_datacenter)    # → True
print(result.to_dict())        # → full JSON-serializable dict
```

### Bulk check

```python
ips = ["1.2.3.4", "8.8.8.8", "45.33.32.156"]
results = blocker.check_bulk(ips)

for r in results:
    print(r.ip, r.status_label(), r.risk_score)
```

### Async bulk check

```python
import asyncio
from dcblock import DatacenterBlocker

blocker = DatacenterBlocker().load()

async def main():
    results = await blocker.async_check_bulk(["1.2.3.4", "8.8.8.8"])
    for r in results:
        print(r.ip, r.status_label())

asyncio.run(main())
```

### Whitelist trusted IPs

```python
blocker = DatacenterBlocker(
    whitelist={"10.0.0.0/8", "192.168.0.0/16"}
).load()
```

### CIDR-only mode (no geo calls, fastest)

```python
blocker = DatacenterBlocker(enrich_asn=False).load()
result  = blocker.check("3.108.66.217", enrich=False)
```

---

## Built-in REST API (Flask)

DCBlock ships with a fully-featured IP Intelligence REST API. You can start it in one line.

### Option 1 — CLI (easiest)

```bash
dcblock serve --port 5000
```

### Option 2 — Python

```python
from dcblock import run_server

run_server(host="0.0.0.0", port=5000)
```

### Option 3 — Integrate into your own Flask app

```python
from flask import Flask
from dcblock import DatacenterBlocker, create_app

blocker = DatacenterBlocker(enrich_asn=True).load()
app = create_app(blocker=blocker)

# Add your own routes on top
@app.route("/my-route")
def my_route():
    return "hello"

app.run(port=5000)
```

### API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/v1/check?ip=1.2.3.4` | Check a single IP (query param) |
| `GET` | `/api/v1/check/<ip>` | Check a single IP (path param) |
| `POST` | `/api/v1/bulk` | Bulk check up to 50 IPs |
| `GET` | `/api/v1/myip` | Check the caller's own IP |
| `GET` | `/api/v1/validate?ip=1.2.3.4` | Validate IP format |
| `GET` | `/api/v1/enrich?ip=1.2.3.4` | Raw geo + ASN enrichment |
| `GET` | `/api/v1/sources` | List all 30+ CIDR sources |
| `GET` | `/api/v1/stats` | Engine statistics |
| `GET` | `/api/v1/health` | Health check + all endpoints list |

### Example responses

**GET /api/v1/check?ip=3.108.66.217**
```json
{
  "ip": "3.108.66.217",
  "status": "HOSTING",
  "is_datacenter": true,
  "risk_score": 50,
  "reason": "hosting_flag",
  "org": "Amazon Technologies Inc.",
  "isp": "Amazon.com",
  "asn_number": "AS16509",
  "country": "India",
  "country_code": "IN",
  "city": "Mumbai",
  "region": "Maharashtra",
  "latitude": 19.076,
  "longitude": 72.8777,
  "reverse_dns": "ec2-3-108-66-217.ap-south-1.compute.amazonaws.com",
  "tags": ["hosting", "datacenter-asn"],
  "timestamp": "2026-04-20T06:20:44Z"
}
```

**POST /api/v1/bulk**
```bash
curl -X POST http://localhost:5000/api/v1/bulk \
  -H "Content-Type: application/json" \
  -d '{"ips": ["3.108.66.217", "8.8.8.8"], "enrich": true}'
```
```json
{
  "total": 2,
  "checked": 2,
  "blocked": 1,
  "clean": 1,
  "results": [...]
}
```

---

## Framework Middleware

### Flask — block datacenter IPs

```python
from flask import Flask
from dcblock import DatacenterBlocker, make_flask_middleware

blocker = DatacenterBlocker().load()
app     = Flask(__name__)
app     = make_flask_middleware(app, blocker, trusted_proxies={"127.0.0.1"})
```

Datacenter IPs get a `403 Forbidden` JSON response automatically:
```json
{"error": "access_denied", "reason": "hosting_flag", "status": "HOSTING"}
```

### FastAPI

```python
from fastapi import FastAPI
from dcblock import DatacenterBlocker, make_fastapi_middleware

blocker = DatacenterBlocker().load()
app     = FastAPI()
app.add_middleware(make_fastapi_middleware(blocker))
```

### Django

```python
# middleware.py
from dcblock import DatacenterBlocker, make_django_middleware

blocker = DatacenterBlocker().load()
DatacenterMiddleware = make_django_middleware(blocker)

# settings.py
MIDDLEWARE = [
    "myapp.middleware.DatacenterMiddleware",
    ...
]
```

---

## CheckResult fields

| Field | Type | Description |
|-------|------|-------------|
| `ip` | str | Input IP address |
| `is_datacenter` | bool | True if blocked |
| `status_label()` | str | `CLEAN` / `DATACENTER` / `HOSTING` / `PROXY` / `VPN` / `TOR` |
| `risk_score` | int | 0–100 risk score |
| `reason` | str | `cidr_match` / `hosting_flag` / `proxy` / `asn_keyword` / `tor` |
| `source` | str | Which source list matched |
| `org` | str | Organization name |
| `isp` | str | ISP name |
| `asn` | str | ASN name |
| `asn_number` | str | ASN number (e.g. `AS16509`) |
| `country` | str | Country full name |
| `country_code` | str | 2-letter ISO code |
| `city` | str | City |
| `region` | str | Region / state |
| `latitude` | float | Geo latitude |
| `longitude` | float | Geo longitude |
| `reverse_dns` | str | rDNS hostname |
| `is_tor` | bool | Tor exit node |
| `is_proxy` | bool | Proxy detected |
| `is_vpn` | bool | VPN detected |
| `is_hosting` | bool | Cloud hosting flag |
| `tags` | list | e.g. `["proxy", "hosting", "cidr-blocklist"]` |
| `checked_at` | float | Unix timestamp |

---

## Sources (30+)

| Provider | Category |
|----------|----------|
| Amazon AWS | cloud |
| Google Cloud | cloud |
| Microsoft Azure | cloud |
| DigitalOcean | cloud |
| Vultr | cloud |
| Oracle Cloud | cloud |
| Linode / Akamai | cloud |
| Hetzner | cloud |
| OVH / OVHcloud | cloud |
| Contabo | cloud |
| Leaseweb | cloud |
| IBM Cloud / SoftLayer | cloud |
| Alibaba Cloud | cloud |
| Tencent Cloud | cloud |
| Huawei Cloud | cloud |
| Scaleway | cloud |
| Choopa / Virtus Strong | cloud |
| ColoCrossing | cloud |
| Cloudflare IPv4 + IPv6 | cdn |
| Fastly CDN | cdn |
| Heroku (Salesforce) | paas |
| Render.com | paas |
| Railway.app | paas |
| Vercel | paas |
| Netlify | paas |
| GitHub Actions / Pages | devops |
| M247 / VPN Hosting | vpn_hosting |
| Tor Exit Nodes | anonymizer |
| Spamhaus DROP (hijacked) | abuse |

All sources auto-refresh every 24 hours and are cached locally. Fallback CIDRs are bundled for sources that occasionally go offline.

---

## Docker

```bash
docker-compose up -d
# REST API available at http://localhost:8000
```

---

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `DC_BLOCK_CACHE` | `/tmp/dc_block_cache` | Cache directory |
| `DC_BLOCK_TTL_HOURS` | `24` | Cache TTL in hours |

---

## Support & Issues

Having trouble? Found a bug? Something not working?

Please **send a message with your error + a screenshot** to:

👉 **https://t.me/Team_X_Og**

We're active on Telegram and will help you out.

---

## Donate

If DCBlock has saved you time or is part of your project, consider supporting the work:

💸 **https://pay.teamdev.sbs**

---

**TeamDev** · [@MR_ARMAN_08](https://t.me/MR_ARMAN_08) · [@TEAM_X_OG](https://t.me/Team_X_Og)
