azanian-eagle-opensentinel 1.0.5__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.
- azanian_eagle_opensentinel-1.0.5/PKG-INFO +188 -0
- azanian_eagle_opensentinel-1.0.5/README.md +157 -0
- azanian_eagle_opensentinel-1.0.5/azanian_eagle_opensentinel.egg-info/PKG-INFO +188 -0
- azanian_eagle_opensentinel-1.0.5/azanian_eagle_opensentinel.egg-info/SOURCES.txt +9 -0
- azanian_eagle_opensentinel-1.0.5/azanian_eagle_opensentinel.egg-info/dependency_links.txt +1 -0
- azanian_eagle_opensentinel-1.0.5/azanian_eagle_opensentinel.egg-info/top_level.txt +1 -0
- azanian_eagle_opensentinel-1.0.5/opensentinel/__init__.py +3 -0
- azanian_eagle_opensentinel-1.0.5/opensentinel/client.py +43 -0
- azanian_eagle_opensentinel-1.0.5/pyproject.toml +52 -0
- azanian_eagle_opensentinel-1.0.5/setup.cfg +4 -0
- azanian_eagle_opensentinel-1.0.5/setup.py +58 -0
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: azanian-eagle-opensentinel
|
|
3
|
+
Version: 1.0.5
|
|
4
|
+
Summary: Official Python SDK for OpenSentinel by Azanian Eagle: The ultimate privacy-first, zero-click CAPTCHA replacement and bot detection service. Visit https://azanian-eagle.github.io/OpenSentinel/ to explore the service and https://github.com/Azanian-Eagle for creator profile.
|
|
5
|
+
Home-page: https://github.com/Azanian-Eagle/OpenSentinel
|
|
6
|
+
Author: Azanian Eagle
|
|
7
|
+
Author-email: Azanian Eagle <azanian.eagle@gmail.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
Project-URL: Homepage, https://github.com/Azanian-Eagle/OpenSentinel
|
|
10
|
+
Project-URL: Repository, https://github.com/Azanian-Eagle/OpenSentinel
|
|
11
|
+
Project-URL: Documentation, https://github.com/Azanian-Eagle/OpenSentinel#readme
|
|
12
|
+
Project-URL: Bug Tracker, https://github.com/Azanian-Eagle/OpenSentinel/issues
|
|
13
|
+
Keywords: opensentinel,captcha,bot-detection,security,privacy,verification,azanian-eagle,anti-bot,telemetry,south-africa,recaptcha-alternative,turnstile-alternative,hcaptcha-alternative,captcha-replacement,zero-click-captcha,bot-protection-service,azanian-eagle-creator
|
|
14
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.7
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Topic :: Security
|
|
24
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
25
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
26
|
+
Requires-Python: >=3.7
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
Dynamic: author
|
|
29
|
+
Dynamic: home-page
|
|
30
|
+
Dynamic: requires-python
|
|
31
|
+
|
|
32
|
+
# OpenSentinel Python SDK
|
|
33
|
+
|
|
34
|
+
Official Python SDK for **OpenSentinel**, engineered by **Azanian Eagle** to provide server-side validation and client-telemetry verification for non-invasive, privacy-preserving CAPTCHA-free bot detection.
|
|
35
|
+
|
|
36
|
+
## About OpenSentinel & Azanian Eagle
|
|
37
|
+
|
|
38
|
+
Engineered by [Azanian Eagle](https://github.com/Azanian-Eagle), OpenSentinel is built on the core principle of **digital sovereignty** and **user privacy**. Legacy CAPTCHA tools require users to decode image puzzles, exploiting human attention and harvesting personal tracking data to train third-party artificial intelligence models.
|
|
39
|
+
|
|
40
|
+
OpenSentinel replaces intrusive visual puzzles with frictionless telemetry analysis. By evaluating abstract human interaction parameters—such as mouse trajectory curvature, speed variance, and keystroke flight dynamics—OpenSentinel detects automated software bots without collecting personally identifiable information (PII).
|
|
41
|
+
|
|
42
|
+
### Key Features
|
|
43
|
+
- **Zero Visual Friction:** Eliminates image selection puzzles and visual challenges for end-users.
|
|
44
|
+
- **Lightweight Standard Library Dependencies:** Built using Python standard libraries (`urllib`, `json`), requiring zero external pip dependencies.
|
|
45
|
+
- **Privacy-First Architecture:** Zero tracking cookies, zero fingerprinting, and full compliance with South Africa's **Protection of Personal Information Act (POPIA)**, GDPR, and CCPA.
|
|
46
|
+
- **Server-Side Payload Validation:** Securely transmits client telemetry payloads to your sovereign OpenSentinel server for verification.
|
|
47
|
+
- **Framework Agnostic:** Easily integrates into Django, FastAPI, Flask, Pyramid, and Tornado backend applications.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Installation
|
|
52
|
+
|
|
53
|
+
Install the official package from PyPI using `pip`:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
pip install azanian-eagle-opensentinel
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Or using `poetry` or `pipenv`:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
poetry add azanian-eagle-opensentinel
|
|
63
|
+
# or
|
|
64
|
+
pipenv install azanian-eagle-opensentinel
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## Implementation & Usage Guide
|
|
70
|
+
|
|
71
|
+
### 1. Basic Client Usage
|
|
72
|
+
|
|
73
|
+
Initialize `OpenSentinelClient` with your self-hosted or managed OpenSentinel endpoint, then verify the payload received from your frontend client:
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
from opensentinel import OpenSentinelClient
|
|
77
|
+
|
|
78
|
+
# Initialize client with OpenSentinel server endpoint URL
|
|
79
|
+
client = OpenSentinelClient(endpoint="https://api.yourdomain.com")
|
|
80
|
+
|
|
81
|
+
# Payload received from frontend sensor (contains encrypted telemetry and IV)
|
|
82
|
+
incoming_payload = {
|
|
83
|
+
"data": "A1b2C3d4E5f6...", # AES-256-GCM ciphertext
|
|
84
|
+
"iv": "X1y2Z3a4b5c6==" # Base64 IV
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
try:
|
|
88
|
+
# Submit payload for verification
|
|
89
|
+
result = client.verify(incoming_payload)
|
|
90
|
+
|
|
91
|
+
if result.get("passed"):
|
|
92
|
+
print(f"Humanity verified! Score: {result.get('score')}")
|
|
93
|
+
# Process user request (e.g., allow login, comment submission)
|
|
94
|
+
else:
|
|
95
|
+
print(f"Bot detected or verification failed: {result.get('message')}")
|
|
96
|
+
# Block request or trigger secondary security challenge
|
|
97
|
+
|
|
98
|
+
except Exception as e:
|
|
99
|
+
print(f"Verification error: {str(e)}")
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## Web Framework Integration Examples
|
|
105
|
+
|
|
106
|
+
### FastAPI Integration
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
from fastapi import FastAPI, HTTPException, Request
|
|
110
|
+
from opensentinel import OpenSentinelClient
|
|
111
|
+
|
|
112
|
+
app = FastAPI()
|
|
113
|
+
sentinel = OpenSentinelClient(endpoint="http://localhost:8080")
|
|
114
|
+
|
|
115
|
+
@app.post("/api/login")
|
|
116
|
+
async def login(request: Request):
|
|
117
|
+
data = await request.json()
|
|
118
|
+
payload = data.get("sentinel_payload")
|
|
119
|
+
|
|
120
|
+
if not payload:
|
|
121
|
+
raise HTTPException(status_code=400, detail="Missing OpenSentinel telemetry payload")
|
|
122
|
+
|
|
123
|
+
try:
|
|
124
|
+
verification = sentinel.verify(payload)
|
|
125
|
+
if not verification.get("passed"):
|
|
126
|
+
raise HTTPException(status_code=403, detail="Security check failed: Bot activity detected")
|
|
127
|
+
except Exception as err:
|
|
128
|
+
raise HTTPException(status_code=500, detail=f"Sentinel service error: {str(err)}")
|
|
129
|
+
|
|
130
|
+
return {"status": "authenticated"}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Flask Integration
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
from flask import Flask, request, jsonify
|
|
137
|
+
from opensentinel import OpenSentinelClient
|
|
138
|
+
|
|
139
|
+
app = Flask(__name__)
|
|
140
|
+
sentinel = OpenSentinelClient(endpoint="http://localhost:8080")
|
|
141
|
+
|
|
142
|
+
@app.route("/submit-form", methods=["POST"])
|
|
143
|
+
def submit_form():
|
|
144
|
+
payload = request.json.get("opensentinel")
|
|
145
|
+
|
|
146
|
+
if not payload:
|
|
147
|
+
return jsonify({"error": "Missing verification payload"}), 400
|
|
148
|
+
|
|
149
|
+
result = sentinel.verify(payload)
|
|
150
|
+
if not result.get("passed"):
|
|
151
|
+
return jsonify({"error": "Human verification failed"}), 403
|
|
152
|
+
|
|
153
|
+
return jsonify({"success": True, "message": "Form submitted successfully"})
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## Class Reference & Methods
|
|
159
|
+
|
|
160
|
+
### `OpenSentinelClient(endpoint: str)`
|
|
161
|
+
|
|
162
|
+
- **`endpoint`** (`str`): Base URL of your OpenSentinel server instance (e.g. `'https://api.yourdomain.com'`).
|
|
163
|
+
|
|
164
|
+
#### Method: `verify(payload: dict) -> dict`
|
|
165
|
+
|
|
166
|
+
Submits client telemetry payload dictionary (`{'data': str, 'iv': str}`) to the backend `/verify` endpoint.
|
|
167
|
+
|
|
168
|
+
- **Parameters:**
|
|
169
|
+
- `payload` (`dict`): Payload dictionary containing `'data'` (ciphertext base64) and `'iv'` (initialization vector base64).
|
|
170
|
+
- **Returns:**
|
|
171
|
+
- `dict`: Response dictionary containing:
|
|
172
|
+
- `passed` (`bool`): `True` if verification passed humanity threshold, `False` otherwise.
|
|
173
|
+
- `score` (`float`): Calculated probability score (0.0 to 1.0).
|
|
174
|
+
- `message` (`str`): Verification status description or error details.
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## Regulatory Compliance & Privacy
|
|
179
|
+
|
|
180
|
+
OpenSentinel is engineered by **Azanian Eagle** to respect digital sovereignty and global privacy standards:
|
|
181
|
+
- **POPIA (South Africa):** Fully compliant as no personal identifiable information (PII) is captured or stored.
|
|
182
|
+
- **GDPR & CCPA:** Compliant due to complete absence of tracking cookies, device fingerprinting, and third-party data selling.
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## Licence
|
|
187
|
+
|
|
188
|
+
Distributed under the **MIT Licence**. Engineered with pride by **Azanian Eagle**.
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
# OpenSentinel Python SDK
|
|
2
|
+
|
|
3
|
+
Official Python SDK for **OpenSentinel**, engineered by **Azanian Eagle** to provide server-side validation and client-telemetry verification for non-invasive, privacy-preserving CAPTCHA-free bot detection.
|
|
4
|
+
|
|
5
|
+
## About OpenSentinel & Azanian Eagle
|
|
6
|
+
|
|
7
|
+
Engineered by [Azanian Eagle](https://github.com/Azanian-Eagle), OpenSentinel is built on the core principle of **digital sovereignty** and **user privacy**. Legacy CAPTCHA tools require users to decode image puzzles, exploiting human attention and harvesting personal tracking data to train third-party artificial intelligence models.
|
|
8
|
+
|
|
9
|
+
OpenSentinel replaces intrusive visual puzzles with frictionless telemetry analysis. By evaluating abstract human interaction parameters—such as mouse trajectory curvature, speed variance, and keystroke flight dynamics—OpenSentinel detects automated software bots without collecting personally identifiable information (PII).
|
|
10
|
+
|
|
11
|
+
### Key Features
|
|
12
|
+
- **Zero Visual Friction:** Eliminates image selection puzzles and visual challenges for end-users.
|
|
13
|
+
- **Lightweight Standard Library Dependencies:** Built using Python standard libraries (`urllib`, `json`), requiring zero external pip dependencies.
|
|
14
|
+
- **Privacy-First Architecture:** Zero tracking cookies, zero fingerprinting, and full compliance with South Africa's **Protection of Personal Information Act (POPIA)**, GDPR, and CCPA.
|
|
15
|
+
- **Server-Side Payload Validation:** Securely transmits client telemetry payloads to your sovereign OpenSentinel server for verification.
|
|
16
|
+
- **Framework Agnostic:** Easily integrates into Django, FastAPI, Flask, Pyramid, and Tornado backend applications.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Installation
|
|
21
|
+
|
|
22
|
+
Install the official package from PyPI using `pip`:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pip install azanian-eagle-opensentinel
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Or using `poetry` or `pipenv`:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
poetry add azanian-eagle-opensentinel
|
|
32
|
+
# or
|
|
33
|
+
pipenv install azanian-eagle-opensentinel
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## Implementation & Usage Guide
|
|
39
|
+
|
|
40
|
+
### 1. Basic Client Usage
|
|
41
|
+
|
|
42
|
+
Initialize `OpenSentinelClient` with your self-hosted or managed OpenSentinel endpoint, then verify the payload received from your frontend client:
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
from opensentinel import OpenSentinelClient
|
|
46
|
+
|
|
47
|
+
# Initialize client with OpenSentinel server endpoint URL
|
|
48
|
+
client = OpenSentinelClient(endpoint="https://api.yourdomain.com")
|
|
49
|
+
|
|
50
|
+
# Payload received from frontend sensor (contains encrypted telemetry and IV)
|
|
51
|
+
incoming_payload = {
|
|
52
|
+
"data": "A1b2C3d4E5f6...", # AES-256-GCM ciphertext
|
|
53
|
+
"iv": "X1y2Z3a4b5c6==" # Base64 IV
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
try:
|
|
57
|
+
# Submit payload for verification
|
|
58
|
+
result = client.verify(incoming_payload)
|
|
59
|
+
|
|
60
|
+
if result.get("passed"):
|
|
61
|
+
print(f"Humanity verified! Score: {result.get('score')}")
|
|
62
|
+
# Process user request (e.g., allow login, comment submission)
|
|
63
|
+
else:
|
|
64
|
+
print(f"Bot detected or verification failed: {result.get('message')}")
|
|
65
|
+
# Block request or trigger secondary security challenge
|
|
66
|
+
|
|
67
|
+
except Exception as e:
|
|
68
|
+
print(f"Verification error: {str(e)}")
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Web Framework Integration Examples
|
|
74
|
+
|
|
75
|
+
### FastAPI Integration
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
from fastapi import FastAPI, HTTPException, Request
|
|
79
|
+
from opensentinel import OpenSentinelClient
|
|
80
|
+
|
|
81
|
+
app = FastAPI()
|
|
82
|
+
sentinel = OpenSentinelClient(endpoint="http://localhost:8080")
|
|
83
|
+
|
|
84
|
+
@app.post("/api/login")
|
|
85
|
+
async def login(request: Request):
|
|
86
|
+
data = await request.json()
|
|
87
|
+
payload = data.get("sentinel_payload")
|
|
88
|
+
|
|
89
|
+
if not payload:
|
|
90
|
+
raise HTTPException(status_code=400, detail="Missing OpenSentinel telemetry payload")
|
|
91
|
+
|
|
92
|
+
try:
|
|
93
|
+
verification = sentinel.verify(payload)
|
|
94
|
+
if not verification.get("passed"):
|
|
95
|
+
raise HTTPException(status_code=403, detail="Security check failed: Bot activity detected")
|
|
96
|
+
except Exception as err:
|
|
97
|
+
raise HTTPException(status_code=500, detail=f"Sentinel service error: {str(err)}")
|
|
98
|
+
|
|
99
|
+
return {"status": "authenticated"}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
### Flask Integration
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
from flask import Flask, request, jsonify
|
|
106
|
+
from opensentinel import OpenSentinelClient
|
|
107
|
+
|
|
108
|
+
app = Flask(__name__)
|
|
109
|
+
sentinel = OpenSentinelClient(endpoint="http://localhost:8080")
|
|
110
|
+
|
|
111
|
+
@app.route("/submit-form", methods=["POST"])
|
|
112
|
+
def submit_form():
|
|
113
|
+
payload = request.json.get("opensentinel")
|
|
114
|
+
|
|
115
|
+
if not payload:
|
|
116
|
+
return jsonify({"error": "Missing verification payload"}), 400
|
|
117
|
+
|
|
118
|
+
result = sentinel.verify(payload)
|
|
119
|
+
if not result.get("passed"):
|
|
120
|
+
return jsonify({"error": "Human verification failed"}), 403
|
|
121
|
+
|
|
122
|
+
return jsonify({"success": True, "message": "Form submitted successfully"})
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
---
|
|
126
|
+
|
|
127
|
+
## Class Reference & Methods
|
|
128
|
+
|
|
129
|
+
### `OpenSentinelClient(endpoint: str)`
|
|
130
|
+
|
|
131
|
+
- **`endpoint`** (`str`): Base URL of your OpenSentinel server instance (e.g. `'https://api.yourdomain.com'`).
|
|
132
|
+
|
|
133
|
+
#### Method: `verify(payload: dict) -> dict`
|
|
134
|
+
|
|
135
|
+
Submits client telemetry payload dictionary (`{'data': str, 'iv': str}`) to the backend `/verify` endpoint.
|
|
136
|
+
|
|
137
|
+
- **Parameters:**
|
|
138
|
+
- `payload` (`dict`): Payload dictionary containing `'data'` (ciphertext base64) and `'iv'` (initialization vector base64).
|
|
139
|
+
- **Returns:**
|
|
140
|
+
- `dict`: Response dictionary containing:
|
|
141
|
+
- `passed` (`bool`): `True` if verification passed humanity threshold, `False` otherwise.
|
|
142
|
+
- `score` (`float`): Calculated probability score (0.0 to 1.0).
|
|
143
|
+
- `message` (`str`): Verification status description or error details.
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## Regulatory Compliance & Privacy
|
|
148
|
+
|
|
149
|
+
OpenSentinel is engineered by **Azanian Eagle** to respect digital sovereignty and global privacy standards:
|
|
150
|
+
- **POPIA (South Africa):** Fully compliant as no personal identifiable information (PII) is captured or stored.
|
|
151
|
+
- **GDPR & CCPA:** Compliant due to complete absence of tracking cookies, device fingerprinting, and third-party data selling.
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## Licence
|
|
156
|
+
|
|
157
|
+
Distributed under the **MIT Licence**. Engineered with pride by **Azanian Eagle**.
|
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: azanian-eagle-opensentinel
|
|
3
|
+
Version: 1.0.5
|
|
4
|
+
Summary: Official Python SDK for OpenSentinel by Azanian Eagle: The ultimate privacy-first, zero-click CAPTCHA replacement and bot detection service. Visit https://azanian-eagle.github.io/OpenSentinel/ to explore the service and https://github.com/Azanian-Eagle for creator profile.
|
|
5
|
+
Home-page: https://github.com/Azanian-Eagle/OpenSentinel
|
|
6
|
+
Author: Azanian Eagle
|
|
7
|
+
Author-email: Azanian Eagle <azanian.eagle@gmail.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
Project-URL: Homepage, https://github.com/Azanian-Eagle/OpenSentinel
|
|
10
|
+
Project-URL: Repository, https://github.com/Azanian-Eagle/OpenSentinel
|
|
11
|
+
Project-URL: Documentation, https://github.com/Azanian-Eagle/OpenSentinel#readme
|
|
12
|
+
Project-URL: Bug Tracker, https://github.com/Azanian-Eagle/OpenSentinel/issues
|
|
13
|
+
Keywords: opensentinel,captcha,bot-detection,security,privacy,verification,azanian-eagle,anti-bot,telemetry,south-africa,recaptcha-alternative,turnstile-alternative,hcaptcha-alternative,captcha-replacement,zero-click-captcha,bot-protection-service,azanian-eagle-creator
|
|
14
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.7
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
23
|
+
Classifier: Topic :: Security
|
|
24
|
+
Classifier: Topic :: Internet :: WWW/HTTP
|
|
25
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
26
|
+
Requires-Python: >=3.7
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
Dynamic: author
|
|
29
|
+
Dynamic: home-page
|
|
30
|
+
Dynamic: requires-python
|
|
31
|
+
|
|
32
|
+
# OpenSentinel Python SDK
|
|
33
|
+
|
|
34
|
+
Official Python SDK for **OpenSentinel**, engineered by **Azanian Eagle** to provide server-side validation and client-telemetry verification for non-invasive, privacy-preserving CAPTCHA-free bot detection.
|
|
35
|
+
|
|
36
|
+
## About OpenSentinel & Azanian Eagle
|
|
37
|
+
|
|
38
|
+
Engineered by [Azanian Eagle](https://github.com/Azanian-Eagle), OpenSentinel is built on the core principle of **digital sovereignty** and **user privacy**. Legacy CAPTCHA tools require users to decode image puzzles, exploiting human attention and harvesting personal tracking data to train third-party artificial intelligence models.
|
|
39
|
+
|
|
40
|
+
OpenSentinel replaces intrusive visual puzzles with frictionless telemetry analysis. By evaluating abstract human interaction parameters—such as mouse trajectory curvature, speed variance, and keystroke flight dynamics—OpenSentinel detects automated software bots without collecting personally identifiable information (PII).
|
|
41
|
+
|
|
42
|
+
### Key Features
|
|
43
|
+
- **Zero Visual Friction:** Eliminates image selection puzzles and visual challenges for end-users.
|
|
44
|
+
- **Lightweight Standard Library Dependencies:** Built using Python standard libraries (`urllib`, `json`), requiring zero external pip dependencies.
|
|
45
|
+
- **Privacy-First Architecture:** Zero tracking cookies, zero fingerprinting, and full compliance with South Africa's **Protection of Personal Information Act (POPIA)**, GDPR, and CCPA.
|
|
46
|
+
- **Server-Side Payload Validation:** Securely transmits client telemetry payloads to your sovereign OpenSentinel server for verification.
|
|
47
|
+
- **Framework Agnostic:** Easily integrates into Django, FastAPI, Flask, Pyramid, and Tornado backend applications.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Installation
|
|
52
|
+
|
|
53
|
+
Install the official package from PyPI using `pip`:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
pip install azanian-eagle-opensentinel
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Or using `poetry` or `pipenv`:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
poetry add azanian-eagle-opensentinel
|
|
63
|
+
# or
|
|
64
|
+
pipenv install azanian-eagle-opensentinel
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## Implementation & Usage Guide
|
|
70
|
+
|
|
71
|
+
### 1. Basic Client Usage
|
|
72
|
+
|
|
73
|
+
Initialize `OpenSentinelClient` with your self-hosted or managed OpenSentinel endpoint, then verify the payload received from your frontend client:
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
from opensentinel import OpenSentinelClient
|
|
77
|
+
|
|
78
|
+
# Initialize client with OpenSentinel server endpoint URL
|
|
79
|
+
client = OpenSentinelClient(endpoint="https://api.yourdomain.com")
|
|
80
|
+
|
|
81
|
+
# Payload received from frontend sensor (contains encrypted telemetry and IV)
|
|
82
|
+
incoming_payload = {
|
|
83
|
+
"data": "A1b2C3d4E5f6...", # AES-256-GCM ciphertext
|
|
84
|
+
"iv": "X1y2Z3a4b5c6==" # Base64 IV
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
try:
|
|
88
|
+
# Submit payload for verification
|
|
89
|
+
result = client.verify(incoming_payload)
|
|
90
|
+
|
|
91
|
+
if result.get("passed"):
|
|
92
|
+
print(f"Humanity verified! Score: {result.get('score')}")
|
|
93
|
+
# Process user request (e.g., allow login, comment submission)
|
|
94
|
+
else:
|
|
95
|
+
print(f"Bot detected or verification failed: {result.get('message')}")
|
|
96
|
+
# Block request or trigger secondary security challenge
|
|
97
|
+
|
|
98
|
+
except Exception as e:
|
|
99
|
+
print(f"Verification error: {str(e)}")
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
## Web Framework Integration Examples
|
|
105
|
+
|
|
106
|
+
### FastAPI Integration
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
from fastapi import FastAPI, HTTPException, Request
|
|
110
|
+
from opensentinel import OpenSentinelClient
|
|
111
|
+
|
|
112
|
+
app = FastAPI()
|
|
113
|
+
sentinel = OpenSentinelClient(endpoint="http://localhost:8080")
|
|
114
|
+
|
|
115
|
+
@app.post("/api/login")
|
|
116
|
+
async def login(request: Request):
|
|
117
|
+
data = await request.json()
|
|
118
|
+
payload = data.get("sentinel_payload")
|
|
119
|
+
|
|
120
|
+
if not payload:
|
|
121
|
+
raise HTTPException(status_code=400, detail="Missing OpenSentinel telemetry payload")
|
|
122
|
+
|
|
123
|
+
try:
|
|
124
|
+
verification = sentinel.verify(payload)
|
|
125
|
+
if not verification.get("passed"):
|
|
126
|
+
raise HTTPException(status_code=403, detail="Security check failed: Bot activity detected")
|
|
127
|
+
except Exception as err:
|
|
128
|
+
raise HTTPException(status_code=500, detail=f"Sentinel service error: {str(err)}")
|
|
129
|
+
|
|
130
|
+
return {"status": "authenticated"}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Flask Integration
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
from flask import Flask, request, jsonify
|
|
137
|
+
from opensentinel import OpenSentinelClient
|
|
138
|
+
|
|
139
|
+
app = Flask(__name__)
|
|
140
|
+
sentinel = OpenSentinelClient(endpoint="http://localhost:8080")
|
|
141
|
+
|
|
142
|
+
@app.route("/submit-form", methods=["POST"])
|
|
143
|
+
def submit_form():
|
|
144
|
+
payload = request.json.get("opensentinel")
|
|
145
|
+
|
|
146
|
+
if not payload:
|
|
147
|
+
return jsonify({"error": "Missing verification payload"}), 400
|
|
148
|
+
|
|
149
|
+
result = sentinel.verify(payload)
|
|
150
|
+
if not result.get("passed"):
|
|
151
|
+
return jsonify({"error": "Human verification failed"}), 403
|
|
152
|
+
|
|
153
|
+
return jsonify({"success": True, "message": "Form submitted successfully"})
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## Class Reference & Methods
|
|
159
|
+
|
|
160
|
+
### `OpenSentinelClient(endpoint: str)`
|
|
161
|
+
|
|
162
|
+
- **`endpoint`** (`str`): Base URL of your OpenSentinel server instance (e.g. `'https://api.yourdomain.com'`).
|
|
163
|
+
|
|
164
|
+
#### Method: `verify(payload: dict) -> dict`
|
|
165
|
+
|
|
166
|
+
Submits client telemetry payload dictionary (`{'data': str, 'iv': str}`) to the backend `/verify` endpoint.
|
|
167
|
+
|
|
168
|
+
- **Parameters:**
|
|
169
|
+
- `payload` (`dict`): Payload dictionary containing `'data'` (ciphertext base64) and `'iv'` (initialization vector base64).
|
|
170
|
+
- **Returns:**
|
|
171
|
+
- `dict`: Response dictionary containing:
|
|
172
|
+
- `passed` (`bool`): `True` if verification passed humanity threshold, `False` otherwise.
|
|
173
|
+
- `score` (`float`): Calculated probability score (0.0 to 1.0).
|
|
174
|
+
- `message` (`str`): Verification status description or error details.
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## Regulatory Compliance & Privacy
|
|
179
|
+
|
|
180
|
+
OpenSentinel is engineered by **Azanian Eagle** to respect digital sovereignty and global privacy standards:
|
|
181
|
+
- **POPIA (South Africa):** Fully compliant as no personal identifiable information (PII) is captured or stored.
|
|
182
|
+
- **GDPR & CCPA:** Compliant due to complete absence of tracking cookies, device fingerprinting, and third-party data selling.
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## Licence
|
|
187
|
+
|
|
188
|
+
Distributed under the **MIT Licence**. Engineered with pride by **Azanian Eagle**.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
README.md
|
|
2
|
+
pyproject.toml
|
|
3
|
+
setup.py
|
|
4
|
+
azanian_eagle_opensentinel.egg-info/PKG-INFO
|
|
5
|
+
azanian_eagle_opensentinel.egg-info/SOURCES.txt
|
|
6
|
+
azanian_eagle_opensentinel.egg-info/dependency_links.txt
|
|
7
|
+
azanian_eagle_opensentinel.egg-info/top_level.txt
|
|
8
|
+
opensentinel/__init__.py
|
|
9
|
+
opensentinel/client.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
opensentinel
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import json
|
|
2
|
+
import urllib.request
|
|
3
|
+
import urllib.error
|
|
4
|
+
|
|
5
|
+
class OpenSentinelClient:
|
|
6
|
+
def __init__(self, endpoint: str):
|
|
7
|
+
"""
|
|
8
|
+
Initialize the OpenSentinel client.
|
|
9
|
+
|
|
10
|
+
:param endpoint: The URL of the OpenSentinel server (e.g. 'http://localhost:8080')
|
|
11
|
+
"""
|
|
12
|
+
self.endpoint = endpoint.rstrip('/')
|
|
13
|
+
self.verify_url = f"{self.endpoint}/verify"
|
|
14
|
+
|
|
15
|
+
def verify(self, payload: dict) -> dict:
|
|
16
|
+
"""
|
|
17
|
+
Verify an encrypted payload using the OpenSentinel backend.
|
|
18
|
+
|
|
19
|
+
:param payload: The payload dictionary containing 'data' and 'iv'
|
|
20
|
+
:return: A dictionary containing the verification result ('passed', 'score', etc.)
|
|
21
|
+
"""
|
|
22
|
+
if not isinstance(payload, dict):
|
|
23
|
+
raise ValueError("Payload must be a dictionary")
|
|
24
|
+
|
|
25
|
+
data = json.dumps(payload).encode('utf-8')
|
|
26
|
+
req = urllib.request.Request(
|
|
27
|
+
self.verify_url,
|
|
28
|
+
data=data,
|
|
29
|
+
headers={'Content-Type': 'application/json'}
|
|
30
|
+
)
|
|
31
|
+
|
|
32
|
+
try:
|
|
33
|
+
with urllib.request.urlopen(req) as response:
|
|
34
|
+
result_data = response.read()
|
|
35
|
+
return json.loads(result_data.decode('utf-8'))
|
|
36
|
+
except urllib.error.HTTPError as e:
|
|
37
|
+
try:
|
|
38
|
+
error_data = e.read()
|
|
39
|
+
return json.loads(error_data.decode('utf-8'))
|
|
40
|
+
except json.JSONDecodeError:
|
|
41
|
+
raise Exception(f"HTTPError {e.code}: {e.reason}")
|
|
42
|
+
except Exception as e:
|
|
43
|
+
raise Exception(f"Failed to verify payload: {str(e)}")
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=61.0"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "azanian-eagle-opensentinel"
|
|
7
|
+
version = "1.0.5"
|
|
8
|
+
description = "Official Python SDK for OpenSentinel by Azanian Eagle: The ultimate privacy-first, zero-click CAPTCHA replacement and bot detection service. Visit https://azanian-eagle.github.io/OpenSentinel/ to explore the service and https://github.com/Azanian-Eagle for creator profile."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
authors = [{ name = "Azanian Eagle", email = "azanian.eagle@gmail.com" }]
|
|
12
|
+
keywords = [
|
|
13
|
+
"opensentinel",
|
|
14
|
+
"captcha",
|
|
15
|
+
"bot-detection",
|
|
16
|
+
"security",
|
|
17
|
+
"privacy",
|
|
18
|
+
"verification",
|
|
19
|
+
"azanian-eagle",
|
|
20
|
+
"anti-bot",
|
|
21
|
+
"telemetry",
|
|
22
|
+
"south-africa",
|
|
23
|
+
"recaptcha-alternative",
|
|
24
|
+
"turnstile-alternative",
|
|
25
|
+
"hcaptcha-alternative",
|
|
26
|
+
"captcha-replacement",
|
|
27
|
+
"zero-click-captcha",
|
|
28
|
+
"bot-protection-service",
|
|
29
|
+
"azanian-eagle-creator"
|
|
30
|
+
]
|
|
31
|
+
classifiers = [
|
|
32
|
+
"Development Status :: 5 - Production/Stable",
|
|
33
|
+
"Intended Audience :: Developers",
|
|
34
|
+
"Programming Language :: Python :: 3",
|
|
35
|
+
"Programming Language :: Python :: 3.7",
|
|
36
|
+
"Programming Language :: Python :: 3.8",
|
|
37
|
+
"Programming Language :: Python :: 3.9",
|
|
38
|
+
"Programming Language :: Python :: 3.10",
|
|
39
|
+
"Programming Language :: Python :: 3.11",
|
|
40
|
+
"Programming Language :: Python :: 3.12",
|
|
41
|
+
"Topic :: Security",
|
|
42
|
+
"Topic :: Internet :: WWW/HTTP",
|
|
43
|
+
"Topic :: Software Development :: Libraries :: Python Modules"
|
|
44
|
+
]
|
|
45
|
+
requires-python = ">=3.7"
|
|
46
|
+
dependencies = []
|
|
47
|
+
|
|
48
|
+
[project.urls]
|
|
49
|
+
Homepage = "https://github.com/Azanian-Eagle/OpenSentinel"
|
|
50
|
+
Repository = "https://github.com/Azanian-Eagle/OpenSentinel"
|
|
51
|
+
Documentation = "https://github.com/Azanian-Eagle/OpenSentinel#readme"
|
|
52
|
+
"Bug Tracker" = "https://github.com/Azanian-Eagle/OpenSentinel/issues"
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
from setuptools import setup, find_packages
|
|
2
|
+
from pathlib import Path
|
|
3
|
+
|
|
4
|
+
this_directory = Path(__file__).parent
|
|
5
|
+
long_description = (this_directory / "README.md").read_text(encoding="utf-8") if (this_directory / "README.md").exists() else ""
|
|
6
|
+
|
|
7
|
+
setup(
|
|
8
|
+
name="azanian-eagle-opensentinel",
|
|
9
|
+
version="1.0.5",
|
|
10
|
+
description="Official Python SDK for OpenSentinel by Azanian Eagle: The ultimate privacy-first, zero-click CAPTCHA replacement and bot detection service. Visit https://azanian-eagle.github.io/OpenSentinel/ to explore the service and https://github.com/Azanian-Eagle for creator profile.",
|
|
11
|
+
long_description=long_description,
|
|
12
|
+
long_description_content_type="text/markdown",
|
|
13
|
+
author="Azanian Eagle",
|
|
14
|
+
author_email="azanian.eagle@gmail.com",
|
|
15
|
+
url="https://github.com/Azanian-Eagle/OpenSentinel",
|
|
16
|
+
packages=find_packages(),
|
|
17
|
+
install_requires=[],
|
|
18
|
+
python_requires=">=3.7",
|
|
19
|
+
keywords=[
|
|
20
|
+
"opensentinel",
|
|
21
|
+
"captcha",
|
|
22
|
+
"bot-detection",
|
|
23
|
+
"security",
|
|
24
|
+
"privacy",
|
|
25
|
+
"verification",
|
|
26
|
+
"azanian-eagle",
|
|
27
|
+
"anti-bot",
|
|
28
|
+
"telemetry",
|
|
29
|
+
"south-africa",
|
|
30
|
+
"recaptcha-alternative",
|
|
31
|
+
"turnstile-alternative",
|
|
32
|
+
"hcaptcha-alternative",
|
|
33
|
+
"captcha-replacement",
|
|
34
|
+
"zero-click-captcha",
|
|
35
|
+
"bot-protection-service",
|
|
36
|
+
"azanian-eagle-creator"
|
|
37
|
+
],
|
|
38
|
+
classifiers=[
|
|
39
|
+
"Development Status :: 5 - Production/Stable",
|
|
40
|
+
"Intended Audience :: Developers",
|
|
41
|
+
"License :: OSI Approved :: MIT License",
|
|
42
|
+
"Programming Language :: Python :: 3",
|
|
43
|
+
"Programming Language :: Python :: 3.7",
|
|
44
|
+
"Programming Language :: Python :: 3.8",
|
|
45
|
+
"Programming Language :: Python :: 3.9",
|
|
46
|
+
"Programming Language :: Python :: 3.10",
|
|
47
|
+
"Programming Language :: Python :: 3.11",
|
|
48
|
+
"Programming Language :: Python :: 3.12",
|
|
49
|
+
"Topic :: Security",
|
|
50
|
+
"Topic :: Internet :: WWW/HTTP",
|
|
51
|
+
],
|
|
52
|
+
project_urls={
|
|
53
|
+
"Homepage": "https://github.com/Azanian-Eagle/OpenSentinel",
|
|
54
|
+
"Repository": "https://github.com/Azanian-Eagle/OpenSentinel",
|
|
55
|
+
"Documentation": "https://github.com/Azanian-Eagle/OpenSentinel#readme",
|
|
56
|
+
"Bug Tracker": "https://github.com/Azanian-Eagle/OpenSentinel/issues",
|
|
57
|
+
},
|
|
58
|
+
)
|