vpndetection-django 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- vpndetection_django-1.0.0/.github/workflows/ci.yml +25 -0
- vpndetection_django-1.0.0/.github/workflows/release.yml +36 -0
- vpndetection_django-1.0.0/.gitignore +17 -0
- vpndetection_django-1.0.0/LICENSE +21 -0
- vpndetection_django-1.0.0/PKG-INFO +148 -0
- vpndetection_django-1.0.0/README.md +119 -0
- vpndetection_django-1.0.0/pyproject.toml +53 -0
- vpndetection_django-1.0.0/src/vpndetection_django/__init__.py +102 -0
- vpndetection_django-1.0.0/src/vpndetection_django/py.typed +0 -0
- vpndetection_django-1.0.0/testdata/bogons.json +60 -0
- vpndetection_django-1.0.0/testdata/testdata.json +1735 -0
- vpndetection_django-1.0.0/tests/test_middleware.py +252 -0
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
test:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
strategy:
|
|
12
|
+
matrix:
|
|
13
|
+
python: ['3.11', '3.12', '3.13']
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v7
|
|
16
|
+
- uses: actions/setup-python@v7
|
|
17
|
+
with:
|
|
18
|
+
python-version: ${{ matrix.python }}
|
|
19
|
+
cache: pip
|
|
20
|
+
cache-dependency-path: pyproject.toml
|
|
21
|
+
- run: pip install -e ".[dev]"
|
|
22
|
+
- run: ruff check .
|
|
23
|
+
- run: ruff format --check .
|
|
24
|
+
- run: mypy src
|
|
25
|
+
- run: pytest
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
name: Release
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
tags: ['v*']
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
publish:
|
|
9
|
+
runs-on: ubuntu-latest
|
|
10
|
+
permissions:
|
|
11
|
+
contents: read
|
|
12
|
+
# PyPI trusted publishing exchanges this OIDC token for a short-lived upload
|
|
13
|
+
# token. No API token in a repository secret.
|
|
14
|
+
id-token: write
|
|
15
|
+
steps:
|
|
16
|
+
- uses: actions/checkout@v7
|
|
17
|
+
- uses: actions/setup-python@v7
|
|
18
|
+
with:
|
|
19
|
+
python-version: '3.13'
|
|
20
|
+
cache: pip
|
|
21
|
+
cache-dependency-path: pyproject.toml
|
|
22
|
+
# The tag only TRIGGERS this; PyPI publishes whatever the built artifact says.
|
|
23
|
+
# Without this check, tagging v1.0.1 against a 1.0.0 package silently
|
|
24
|
+
# republishes 1.0.0, or fails as "already exists" with a confusing message.
|
|
25
|
+
- name: Tag must match the package version
|
|
26
|
+
run: |
|
|
27
|
+
tag="${GITHUB_REF_NAME#v}"
|
|
28
|
+
pkg="$(sed -n 's/^__version__ = "\(.*\)"$/\1/p' src/vpndetection_django/__init__.py)"
|
|
29
|
+
if [ "$tag" != "$pkg" ] ; then
|
|
30
|
+
echo "tag $tag does not match __version__ $pkg" >&2
|
|
31
|
+
exit 1
|
|
32
|
+
fi
|
|
33
|
+
- run: pip install -e ".[dev]" build
|
|
34
|
+
- run: pytest
|
|
35
|
+
- run: python -m build
|
|
36
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
__pycache__/
|
|
2
|
+
*.py[cod]
|
|
3
|
+
|
|
4
|
+
# Build output.
|
|
5
|
+
build/
|
|
6
|
+
dist/
|
|
7
|
+
*.egg-info/
|
|
8
|
+
|
|
9
|
+
# Virtualenvs, including any made to run codegen. Keep them out of the tree entirely.
|
|
10
|
+
.venv/
|
|
11
|
+
venv/
|
|
12
|
+
.venv-*/
|
|
13
|
+
|
|
14
|
+
# Tool caches.
|
|
15
|
+
.pytest_cache/
|
|
16
|
+
.mypy_cache/
|
|
17
|
+
.ruff_cache/
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mslm Dev
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: vpndetection-django
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Official Django middleware for the VPNDetection API. Detect VPNs, proxies, Tor, hosting and CDN visitors on every request.
|
|
5
|
+
Project-URL: Homepage, https://vpndetection.io
|
|
6
|
+
Project-URL: Source, https://github.com/vpndetection-io/sdk-python-django
|
|
7
|
+
Author-email: Mslm Dev <support@vpndetection.io>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: fraud-prevention,ip-intelligence,middleware,proxy-detection,tor,vpn,vpn-detection
|
|
11
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
18
|
+
Classifier: Topic :: Internet
|
|
19
|
+
Classifier: Topic :: Security
|
|
20
|
+
Classifier: Typing :: Typed
|
|
21
|
+
Requires-Python: >=3.11
|
|
22
|
+
Requires-Dist: django>=4.2
|
|
23
|
+
Requires-Dist: vpndetection<4,>=2.1.0
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: mypy>=1.11; extra == 'dev'
|
|
26
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
27
|
+
Requires-Dist: ruff>=0.6; extra == 'dev'
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
# [<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="24"/>](https://vpndetection.io/) VPNDetection Django Middleware
|
|
31
|
+
|
|
32
|
+
[](https://pypi.org/project/vpndetection-django/)
|
|
33
|
+
[](LICENSE)
|
|
34
|
+
|
|
35
|
+
The official Django Middleware for the [VPNDetection](https://vpndetection.io) API.
|
|
36
|
+
|
|
37
|
+
It classifies the visitor behind each request — VPN, residential proxy, Tor, hosting, CDN, relay — and hands the answer to your code. Blocking is opt-in.
|
|
38
|
+
|
|
39
|
+
## Getting Started
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
pip install vpndetection-django
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Requires Python 3.11 or newer.
|
|
46
|
+
|
|
47
|
+
You need an API key. Create one in the [console](https://app.vpndetection.io); the free tier's allowance is counted per source address, and a server is a single source address, so a key is what makes this usable in production rather than optional.
|
|
48
|
+
|
|
49
|
+
Add it to `MIDDLEWARE` and configure it with a `VPNDETECTION` dict:
|
|
50
|
+
|
|
51
|
+
```python
|
|
52
|
+
# settings.py
|
|
53
|
+
MIDDLEWARE = [
|
|
54
|
+
# ...
|
|
55
|
+
"vpndetection_django.VPNDetectionMiddleware",
|
|
56
|
+
]
|
|
57
|
+
|
|
58
|
+
VPNDETECTION = {"api_key": os.environ["VPNDETECTION_API_KEY"]}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
def index(request):
|
|
63
|
+
found = request.vpndetection
|
|
64
|
+
return HttpResponse("Hello, VPN user" if found.result.is_vpn else "Hello")
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
By default nothing is blocked. Every request gets an answer and your own code decides what that means — which is usually what you want, because whether a VPN visitor is a problem depends entirely on what they are doing.
|
|
68
|
+
|
|
69
|
+
## Blocking
|
|
70
|
+
|
|
71
|
+
Pass a `block_condition` and a matching request is answered with `403` and never reaches your code.
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
block_condition = {"is_vpn": True}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
A condition is written in the shape of a result, keyed by the same names the API uses, and only the members you name are considered. That lets it reach the evidence, not just the flags:
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
{"is_vpn": True, "vpn": {"provider": "nordvpn"}} # one provider
|
|
81
|
+
{"is_resproxy": True, "resproxy": {"hits": {"gte": 5}}} # a numeric threshold
|
|
82
|
+
{"vpn": {"confidence": ["high", "medium"]}} # any of these
|
|
83
|
+
[{"is_tor": True}, {"is_resproxy": True}] # a list is OR
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Values are matched by equality, strings without regard to case. A list means any-of. A dict of `gte`/`gt`/`lte`/`lt` compares numbers, and every bound you give must hold, so two of them are a range. Members set to `False` or `None` are ignored, so a condition states the signals you act on; one that constrains nothing would match every request, and is refused when the middleware is built rather than silently blocking all your traffic.
|
|
87
|
+
|
|
88
|
+
Replace the refusal with `on_blocked`.
|
|
89
|
+
|
|
90
|
+
## Where the client address comes from
|
|
91
|
+
|
|
92
|
+
This is the setting that decides whether any of the above works, and it is the one thing only you can get right.
|
|
93
|
+
|
|
94
|
+
By default the middleware uses `REMOTE_ADDR`, which is the socket peer. **Django deliberately does not read `X-Forwarded-For` for you**, because trusting a header without knowing your topology is unsafe. So if your app sits behind nginx, a load balancer, or a CDN, every visitor arrives wearing your proxy's address — which is a datacenter address, so a hosting rule would block all of them.
|
|
95
|
+
|
|
96
|
+
For an edge that writes the address into its own header, name the header:
|
|
97
|
+
|
|
98
|
+
```python
|
|
99
|
+
from python_django import header_ip_selector
|
|
100
|
+
|
|
101
|
+
ip_selector = header_ip_selector("CF-Connecting-IP") # or True-Client-IP, or your own
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`xff_ip_selector()` reads `X-Forwarded-For` directly. Be aware that the left-most entry is whatever the caller sent, because proxies append to that header — it is only trustworthy when an edge you control overwrites it. If you know how many proxies sit in front, count from the right instead: `xff_ip_selector(1)` is the address your nearest proxy saw.
|
|
105
|
+
|
|
106
|
+
Anything else, pass your own callable. It receives the request and returns an address.
|
|
107
|
+
|
|
108
|
+
If the address resolves to a private one, the middleware says so once through the `vpndetection` logger. That is expected on localhost and is the signal to fix your configuration anywhere else.
|
|
109
|
+
|
|
110
|
+
## When a lookup fails
|
|
111
|
+
|
|
112
|
+
The request is let through, and the reason is recorded on the answer's `error`. Our outage should not become yours, so a network failure, an exhausted quota or a rejected key all fail open. Pass `fail_closed=True` to block instead. Private addresses are answered locally and never fail, so this will not lock you out in development.
|
|
113
|
+
|
|
114
|
+
## Cost and latency
|
|
115
|
+
|
|
116
|
+
Answers are cached for an hour, so a returning visitor costs nothing, and private addresses never leave the process. A cache miss is one request to our API, bounded at 2.5 seconds by default and not retried — on a request path, failing open quickly beats holding a visitor while we try again. Both are adjustable, as is the cache, through a `vpndetection` client you build yourself and pass as `client`.
|
|
117
|
+
|
|
118
|
+
Skip what you do not care about:
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
skip = lambda request: request.path.startswith("/static")
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Beyond a few million distinct visitors a day, stop calling the API per request: [download the dataset](https://vpndetection.io/databases) and look addresses up locally instead.
|
|
125
|
+
|
|
126
|
+
## Absent is not false
|
|
127
|
+
|
|
128
|
+
Only `ip` and `is_vpn` come back on every plan. A field your plan does not include is `None`, which means "not in your plan" rather than "checked, and no".
|
|
129
|
+
|
|
130
|
+
```python
|
|
131
|
+
request.vpndetection.result.is_hosting # None when your plan does not include it
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
A `block_condition` naming a member your plan does not serve can never match, so the middleware warns once instead of failing silently. Pass `on_missing_field="raise"` to make it an error.
|
|
135
|
+
|
|
136
|
+
## Other Libraries
|
|
137
|
+
|
|
138
|
+
There are official VPNDetection client libraries available for many languages including PHP, Python, Go, Java, Ruby, and many popular frameworks such as Django, Rails, and Laravel. See our GitHub at https://github.com/vpndetection-io for more.
|
|
139
|
+
|
|
140
|
+
## About VPNDetection
|
|
141
|
+
|
|
142
|
+
VPN Detection API: Accurate anonymity detection identifying VPNs, residential proxies, hosting servers, Tor nodes, CDNs, relays and more.
|
|
143
|
+
|
|
144
|
+
[<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="96"/>](https://vpndetection.io/)
|
|
145
|
+
|
|
146
|
+
## License
|
|
147
|
+
|
|
148
|
+
This project is licensed under the [MIT License](LICENSE).
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# [<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="24"/>](https://vpndetection.io/) VPNDetection Django Middleware
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/vpndetection-django/)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
|
|
6
|
+
The official Django Middleware for the [VPNDetection](https://vpndetection.io) API.
|
|
7
|
+
|
|
8
|
+
It classifies the visitor behind each request — VPN, residential proxy, Tor, hosting, CDN, relay — and hands the answer to your code. Blocking is opt-in.
|
|
9
|
+
|
|
10
|
+
## Getting Started
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
pip install vpndetection-django
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Requires Python 3.11 or newer.
|
|
17
|
+
|
|
18
|
+
You need an API key. Create one in the [console](https://app.vpndetection.io); the free tier's allowance is counted per source address, and a server is a single source address, so a key is what makes this usable in production rather than optional.
|
|
19
|
+
|
|
20
|
+
Add it to `MIDDLEWARE` and configure it with a `VPNDETECTION` dict:
|
|
21
|
+
|
|
22
|
+
```python
|
|
23
|
+
# settings.py
|
|
24
|
+
MIDDLEWARE = [
|
|
25
|
+
# ...
|
|
26
|
+
"vpndetection_django.VPNDetectionMiddleware",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
VPNDETECTION = {"api_key": os.environ["VPNDETECTION_API_KEY"]}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
```python
|
|
33
|
+
def index(request):
|
|
34
|
+
found = request.vpndetection
|
|
35
|
+
return HttpResponse("Hello, VPN user" if found.result.is_vpn else "Hello")
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
By default nothing is blocked. Every request gets an answer and your own code decides what that means — which is usually what you want, because whether a VPN visitor is a problem depends entirely on what they are doing.
|
|
39
|
+
|
|
40
|
+
## Blocking
|
|
41
|
+
|
|
42
|
+
Pass a `block_condition` and a matching request is answered with `403` and never reaches your code.
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
block_condition = {"is_vpn": True}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
A condition is written in the shape of a result, keyed by the same names the API uses, and only the members you name are considered. That lets it reach the evidence, not just the flags:
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
{"is_vpn": True, "vpn": {"provider": "nordvpn"}} # one provider
|
|
52
|
+
{"is_resproxy": True, "resproxy": {"hits": {"gte": 5}}} # a numeric threshold
|
|
53
|
+
{"vpn": {"confidence": ["high", "medium"]}} # any of these
|
|
54
|
+
[{"is_tor": True}, {"is_resproxy": True}] # a list is OR
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Values are matched by equality, strings without regard to case. A list means any-of. A dict of `gte`/`gt`/`lte`/`lt` compares numbers, and every bound you give must hold, so two of them are a range. Members set to `False` or `None` are ignored, so a condition states the signals you act on; one that constrains nothing would match every request, and is refused when the middleware is built rather than silently blocking all your traffic.
|
|
58
|
+
|
|
59
|
+
Replace the refusal with `on_blocked`.
|
|
60
|
+
|
|
61
|
+
## Where the client address comes from
|
|
62
|
+
|
|
63
|
+
This is the setting that decides whether any of the above works, and it is the one thing only you can get right.
|
|
64
|
+
|
|
65
|
+
By default the middleware uses `REMOTE_ADDR`, which is the socket peer. **Django deliberately does not read `X-Forwarded-For` for you**, because trusting a header without knowing your topology is unsafe. So if your app sits behind nginx, a load balancer, or a CDN, every visitor arrives wearing your proxy's address — which is a datacenter address, so a hosting rule would block all of them.
|
|
66
|
+
|
|
67
|
+
For an edge that writes the address into its own header, name the header:
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
from python_django import header_ip_selector
|
|
71
|
+
|
|
72
|
+
ip_selector = header_ip_selector("CF-Connecting-IP") # or True-Client-IP, or your own
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`xff_ip_selector()` reads `X-Forwarded-For` directly. Be aware that the left-most entry is whatever the caller sent, because proxies append to that header — it is only trustworthy when an edge you control overwrites it. If you know how many proxies sit in front, count from the right instead: `xff_ip_selector(1)` is the address your nearest proxy saw.
|
|
76
|
+
|
|
77
|
+
Anything else, pass your own callable. It receives the request and returns an address.
|
|
78
|
+
|
|
79
|
+
If the address resolves to a private one, the middleware says so once through the `vpndetection` logger. That is expected on localhost and is the signal to fix your configuration anywhere else.
|
|
80
|
+
|
|
81
|
+
## When a lookup fails
|
|
82
|
+
|
|
83
|
+
The request is let through, and the reason is recorded on the answer's `error`. Our outage should not become yours, so a network failure, an exhausted quota or a rejected key all fail open. Pass `fail_closed=True` to block instead. Private addresses are answered locally and never fail, so this will not lock you out in development.
|
|
84
|
+
|
|
85
|
+
## Cost and latency
|
|
86
|
+
|
|
87
|
+
Answers are cached for an hour, so a returning visitor costs nothing, and private addresses never leave the process. A cache miss is one request to our API, bounded at 2.5 seconds by default and not retried — on a request path, failing open quickly beats holding a visitor while we try again. Both are adjustable, as is the cache, through a `vpndetection` client you build yourself and pass as `client`.
|
|
88
|
+
|
|
89
|
+
Skip what you do not care about:
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
skip = lambda request: request.path.startswith("/static")
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Beyond a few million distinct visitors a day, stop calling the API per request: [download the dataset](https://vpndetection.io/databases) and look addresses up locally instead.
|
|
96
|
+
|
|
97
|
+
## Absent is not false
|
|
98
|
+
|
|
99
|
+
Only `ip` and `is_vpn` come back on every plan. A field your plan does not include is `None`, which means "not in your plan" rather than "checked, and no".
|
|
100
|
+
|
|
101
|
+
```python
|
|
102
|
+
request.vpndetection.result.is_hosting # None when your plan does not include it
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
A `block_condition` naming a member your plan does not serve can never match, so the middleware warns once instead of failing silently. Pass `on_missing_field="raise"` to make it an error.
|
|
106
|
+
|
|
107
|
+
## Other Libraries
|
|
108
|
+
|
|
109
|
+
There are official VPNDetection client libraries available for many languages including PHP, Python, Go, Java, Ruby, and many popular frameworks such as Django, Rails, and Laravel. See our GitHub at https://github.com/vpndetection-io for more.
|
|
110
|
+
|
|
111
|
+
## About VPNDetection
|
|
112
|
+
|
|
113
|
+
VPN Detection API: Accurate anonymity detection identifying VPNs, residential proxies, hosting servers, Tor nodes, CDNs, relays and more.
|
|
114
|
+
|
|
115
|
+
[<img src="https://s3.vpndetection.io/vpndetection-public/brand/mark.svg" alt="VPNDetection" width="96"/>](https://vpndetection.io/)
|
|
116
|
+
|
|
117
|
+
## License
|
|
118
|
+
|
|
119
|
+
This project is licensed under the [MIT License](LICENSE).
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "vpndetection-django"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Official Django middleware for the VPNDetection API. Detect VPNs, proxies, Tor, hosting and CDN visitors on every request."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.11"
|
|
13
|
+
authors = [{ name = "Mslm Dev", email = "support@vpndetection.io" }]
|
|
14
|
+
keywords = ["vpn", "vpn-detection", "proxy-detection", "tor", "ip-intelligence", "fraud-prevention", "middleware"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 5 - Production/Stable",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Programming Language :: Python :: 3.11",
|
|
20
|
+
"Programming Language :: Python :: 3.12",
|
|
21
|
+
"Programming Language :: Python :: 3.13",
|
|
22
|
+
"Programming Language :: Python :: 3.14",
|
|
23
|
+
"Topic :: Internet",
|
|
24
|
+
"Topic :: Security",
|
|
25
|
+
"Typing :: Typed",
|
|
26
|
+
]
|
|
27
|
+
dependencies = ["vpndetection>=2.1.0,<4", "django>=4.2"]
|
|
28
|
+
|
|
29
|
+
[project.urls]
|
|
30
|
+
Homepage = "https://vpndetection.io"
|
|
31
|
+
Source = "https://github.com/vpndetection-io/sdk-python-django"
|
|
32
|
+
|
|
33
|
+
[project.optional-dependencies]
|
|
34
|
+
dev = ["pytest>=8", "mypy>=1.11", "ruff>=0.6"]
|
|
35
|
+
|
|
36
|
+
[tool.hatch.build.targets.wheel]
|
|
37
|
+
packages = ["src/vpndetection_django"]
|
|
38
|
+
|
|
39
|
+
[tool.hatch.version]
|
|
40
|
+
path = "src/vpndetection_django/__init__.py"
|
|
41
|
+
|
|
42
|
+
[tool.ruff]
|
|
43
|
+
line-length = 96
|
|
44
|
+
|
|
45
|
+
[tool.mypy]
|
|
46
|
+
python_version = "3.11"
|
|
47
|
+
strict = true
|
|
48
|
+
|
|
49
|
+
# Django ships no py.typed marker and no inline stubs. django-stubs exists but pins a
|
|
50
|
+
# Django version range, which would make this package refuse a Django it works fine on.
|
|
51
|
+
[[tool.mypy.overrides]]
|
|
52
|
+
module = ["django.*"]
|
|
53
|
+
ignore_missing_imports = true
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
"""Official Django middleware for the VPNDetection API.
|
|
2
|
+
|
|
3
|
+
Classifies the visitor behind each request and hangs the answer off
|
|
4
|
+
``request.vpndetection``, where your views can read it. Blocking is opt-in.
|
|
5
|
+
|
|
6
|
+
# settings.py
|
|
7
|
+
MIDDLEWARE = [..., "vpndetection_django.VPNDetectionMiddleware"]
|
|
8
|
+
VPNDETECTION = {"api_key": os.environ["VPNDETECTION_API_KEY"]}
|
|
9
|
+
|
|
10
|
+
The framework-agnostic half lives in ``vpndetection.middleware``; this package is
|
|
11
|
+
only the parts that are genuinely Django-shaped.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
from collections.abc import Callable
|
|
17
|
+
from typing import Any
|
|
18
|
+
|
|
19
|
+
from django.conf import settings
|
|
20
|
+
from django.http import HttpRequest, HttpResponse, JsonResponse
|
|
21
|
+
from vpndetection.middleware import (
|
|
22
|
+
Core,
|
|
23
|
+
IpSelector,
|
|
24
|
+
Lookup,
|
|
25
|
+
Options,
|
|
26
|
+
RequestView,
|
|
27
|
+
Selectors,
|
|
28
|
+
bind_selectors,
|
|
29
|
+
)
|
|
30
|
+
|
|
31
|
+
__all__ = [
|
|
32
|
+
"VPNDetectionMiddleware",
|
|
33
|
+
"default_ip_selector",
|
|
34
|
+
"header_ip_selector",
|
|
35
|
+
"xff_ip_selector",
|
|
36
|
+
]
|
|
37
|
+
|
|
38
|
+
__version__ = "1.0.0"
|
|
39
|
+
|
|
40
|
+
_SELECTORS: Selectors[HttpRequest] = bind_selectors(
|
|
41
|
+
lambda request: RequestView(
|
|
42
|
+
header=lambda name: request.headers.get(name),
|
|
43
|
+
framework_ip=lambda: request.META.get("REMOTE_ADDR"),
|
|
44
|
+
)
|
|
45
|
+
)
|
|
46
|
+
|
|
47
|
+
#: ``REMOTE_ADDR``, which is the socket peer.
|
|
48
|
+
#:
|
|
49
|
+
#: Django deliberately does NOT read ``X-Forwarded-For`` for you - it removed
|
|
50
|
+
#: ``SECURE_PROXY_SSL_HEADER``'s address equivalent precisely because trusting a header
|
|
51
|
+
#: without knowing your topology is unsafe. So behind a load balancer this is the load
|
|
52
|
+
#: balancer, a datacenter address a hosting rule would block every visitor for. If you
|
|
53
|
+
#: are behind one, use :func:`header_ip_selector` or :func:`xff_ip_selector`.
|
|
54
|
+
default_ip_selector: IpSelector[HttpRequest] = _SELECTORS.default
|
|
55
|
+
|
|
56
|
+
#: An address from ``X-Forwarded-For``.
|
|
57
|
+
#:
|
|
58
|
+
#: The LEFT-MOST entry (``depth`` 0) is whatever the caller sent, because proxies
|
|
59
|
+
#: append to this header, so a visitor who sets it themselves appears first and this
|
|
60
|
+
#: returns their forgery. It is only trustworthy when an edge you control overwrites
|
|
61
|
+
#: the header. When you know how many proxies sit in front, count from the right:
|
|
62
|
+
#: ``xff_ip_selector(1)`` is the address your nearest proxy saw.
|
|
63
|
+
xff_ip_selector = _SELECTORS.xff
|
|
64
|
+
|
|
65
|
+
#: An address from a single-value header your edge writes -
|
|
66
|
+
#: ``header_ip_selector("CF-Connecting-IP")`` behind Cloudflare. Falls back to
|
|
67
|
+
#: ``REMOTE_ADDR`` when the header is absent.
|
|
68
|
+
header_ip_selector = _SELECTORS.header
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
class VPNDetectionMiddleware:
|
|
72
|
+
"""Classify the visitor, and optionally refuse the request.
|
|
73
|
+
|
|
74
|
+
Configured from ``settings.VPNDETECTION``, a dict taking everything
|
|
75
|
+
:class:`vpndetection.middleware.Options` does plus ``on_blocked``.
|
|
76
|
+
|
|
77
|
+
Without a ``block_condition`` this only enriches the request and never refuses
|
|
78
|
+
one, leaving the decision to your own views. A lookup that fails - network, quota,
|
|
79
|
+
an outage of ours - lets the request through and records why on
|
|
80
|
+
``request.vpndetection.error``, unless you set ``fail_closed``.
|
|
81
|
+
"""
|
|
82
|
+
|
|
83
|
+
def __init__(self, get_response: Callable[[HttpRequest], HttpResponse]) -> None:
|
|
84
|
+
configured: dict[str, Any] = dict(getattr(settings, "VPNDETECTION", {}) or {})
|
|
85
|
+
self._on_blocked: Callable[[HttpRequest, Lookup], HttpResponse] = configured.pop(
|
|
86
|
+
"on_blocked", _refuse
|
|
87
|
+
)
|
|
88
|
+
self._core: Core[HttpRequest] = Core(Options(**configured), default_ip_selector)
|
|
89
|
+
self._get_response = get_response
|
|
90
|
+
|
|
91
|
+
def __call__(self, request: HttpRequest) -> HttpResponse:
|
|
92
|
+
lookup = self._core.evaluate(request)
|
|
93
|
+
if lookup is None:
|
|
94
|
+
return self._get_response(request)
|
|
95
|
+
request.vpndetection = lookup
|
|
96
|
+
if lookup.blocked:
|
|
97
|
+
return self._on_blocked(request, lookup)
|
|
98
|
+
return self._get_response(request)
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def _refuse(_request: HttpRequest, _lookup: Lookup) -> HttpResponse:
|
|
102
|
+
return JsonResponse({"error": "access denied"}, status=403)
|
|
File without changes
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
{
|
|
2
|
+
"v4": [
|
|
3
|
+
"0.0.0.0/8",
|
|
4
|
+
"10.0.0.0/8",
|
|
5
|
+
"100.64.0.0/10",
|
|
6
|
+
"127.0.0.0/8",
|
|
7
|
+
"169.254.0.0/16",
|
|
8
|
+
"172.16.0.0/12",
|
|
9
|
+
"192.0.0.0/24",
|
|
10
|
+
"192.0.2.0/24",
|
|
11
|
+
"192.168.0.0/16",
|
|
12
|
+
"198.18.0.0/15",
|
|
13
|
+
"198.51.100.0/24",
|
|
14
|
+
"203.0.113.0/24",
|
|
15
|
+
"224.0.0.0/4",
|
|
16
|
+
"240.0.0.0/4",
|
|
17
|
+
"255.255.255.255/32"
|
|
18
|
+
],
|
|
19
|
+
"v6": [
|
|
20
|
+
"::/128",
|
|
21
|
+
"::1/128",
|
|
22
|
+
"::ffff:0:0/96",
|
|
23
|
+
"::/96",
|
|
24
|
+
"100::/64",
|
|
25
|
+
"2001:10::/28",
|
|
26
|
+
"2001:db8::/32",
|
|
27
|
+
"fc00::/7",
|
|
28
|
+
"fe80::/10",
|
|
29
|
+
"fec0::/10",
|
|
30
|
+
"ff00::/8",
|
|
31
|
+
"2002::/24",
|
|
32
|
+
"2002:a00::/24",
|
|
33
|
+
"2002:7f00::/24",
|
|
34
|
+
"2002:a9fe::/32",
|
|
35
|
+
"2002:ac10::/28",
|
|
36
|
+
"2002:c000::/40",
|
|
37
|
+
"2002:c000:200::/40",
|
|
38
|
+
"2002:c0a8::/32",
|
|
39
|
+
"2002:c612::/31",
|
|
40
|
+
"2002:c633:6400::/40",
|
|
41
|
+
"2002:cb00:7100::/40",
|
|
42
|
+
"2002:e000::/20",
|
|
43
|
+
"2002:f000::/20",
|
|
44
|
+
"2002:ffff:ffff::/48",
|
|
45
|
+
"2001::/40",
|
|
46
|
+
"2001:0:a00::/40",
|
|
47
|
+
"2001:0:7f00::/40",
|
|
48
|
+
"2001:0:a9fe::/48",
|
|
49
|
+
"2001:0:ac10::/44",
|
|
50
|
+
"2001:0:c000::/56",
|
|
51
|
+
"2001:0:c000:200::/56",
|
|
52
|
+
"2001:0:c0a8::/48",
|
|
53
|
+
"2001:0:c612::/47",
|
|
54
|
+
"2001:0:c633:6400::/56",
|
|
55
|
+
"2001:0:cb00:7100::/56",
|
|
56
|
+
"2001:0:e000::/36",
|
|
57
|
+
"2001:0:f000::/36",
|
|
58
|
+
"2001:0:ffff:ffff::/64"
|
|
59
|
+
]
|
|
60
|
+
}
|