sentinelsup 0.1.0__tar.gz

sentinelsup-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/

sentinelsup-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sentinel Edge Networks LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sentinelsup-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: sentinelsup
+Version: 0.1.0
+Summary: Sentinel — real-time fraud, VPN, proxy, and bot detection API. Free tier, sub-40ms response.
+Project-URL: Homepage, https://sntlhq.com
+Project-URL: Documentation, https://sntlhq.com/api
+Project-URL: Repository, https://github.com/sentinelsup/sentinel-python
+Project-URL: Issues, https://github.com/sentinelsup/sentinel-python/issues
+Author-email: Sentinel Edge Networks LTD <support@sntlhq.com>
+License: MIT
+License-File: LICENSE
+Keywords: antidetect-browser,api,bot-detection,device-fingerprinting,fraud-detection,proxy-detection,sentinel,vpn-detection
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Sentinel Python SDK
+
+Real-time fraud, VPN, proxy, and bot detection — free tier, sub-40ms global response.
+
+Zero dependencies. Just the standard library.
+
+## Install
+
+```bash
+pip install sentinelsup
+```
+
+## Quick start
+
+```python
+import os
+from sentinel import Sentinel
+
+s = Sentinel(api_key=os.environ["SENTINEL_API_KEY"])
+
+result = s.evaluate(token=request.json["sentinelToken"])
+
+if result.is_suspicious:
+    return abort(403, "Sentinel flagged this session")
+
+print(result.decision)        # 'allow' | 'review' | 'block'
+print(result.risk_score)      # 0..100
+print(result.network)         # {'vpn': True, 'proxy': False, 'datacenter': True, ...}
+print(result.reasons)         # ['ip_in_known_vpn_range', 'datacenter_asn', ...]
+```
+
+## Get your API key
+
+Sign up at [sntlhq.com/signup](https://sntlhq.com/signup) — free, no credit card.
+
+## Flask example — block VPN/proxy signups
+
+```python
+from flask import Flask, request, abort, jsonify
+from sentinel import Sentinel, SentinelError
+
+app = Flask(__name__)
+sentinel = Sentinel()  # reads SENTINEL_API_KEY from env
+
+@app.route("/signup", methods=["POST"])
+def signup():
+    data = request.get_json()
+    try:
+        result = sentinel.evaluate(token=data["sentinelToken"])
+    except SentinelError as e:
+        # Fail open OR fail closed — your call. Logged either way.
+        app.logger.warning("Sentinel error: %s", e)
+        result = None
+
+    if result and result.is_blocked:
+        abort(403, "Signup blocked")
+
+    # ... your normal signup flow
+    return jsonify({"ok": True})
+```
+
+## Django example — middleware for high-value endpoints
+
+```python
+from django.http import JsonResponse
+from sentinel import Sentinel
+
+sentinel = Sentinel()  # reads SENTINEL_API_KEY from env
+
+class FraudCheckMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        if request.path.startswith("/api/checkout"):
+            token = request.META.get("HTTP_X_SENTINEL_TOKEN")
+            if token:
+                try:
+                    result = sentinel.evaluate(token=token)
+                    if result.is_blocked:
+                        return JsonResponse({"error": "blocked"}, status=403)
+                except Exception:
+                    pass  # fail open
+        return self.get_response(request)
+```
+
+## Configuration
+
+```python
+Sentinel(
+    api_key="sk_live_...",          # required (or via SENTINEL_API_KEY env var)
+    endpoint="https://sntlhq.com",  # override for testing
+    timeout=5.0,                    # seconds
+)
+```
+
+## Response shape
+
+```python
+@dataclass
+class EvaluateResult:
+    decision: str | None        # 'allow' | 'review' | 'block'
+    risk_score: int | None      # 0..100
+    ip: str | None
+    country: str | None         # ISO-2
+    asn: str | None             # 'AS16509'
+    asn_org: str | None         # 'Amazon.com, Inc.'
+    network: dict               # {vpn, proxy, datacenter, anonymous, residential}
+    device: dict                # {headless, automation, fingerprint_age_days}
+    reasons: list[str]
+    raw: dict                   # full upstream response
+
+    is_suspicious: bool         # True if decision != 'allow'
+    is_blocked: bool            # True if decision == 'block'
+```
+
+## Errors
+
+All failures raise `SentinelError`. The exception carries `.status` (HTTP code) and `.body` (parsed error body) when available.
+
+```python
+from sentinel import Sentinel, SentinelError
+
+try:
+    result = sentinel.evaluate(token=tok)
+except SentinelError as e:
+    if e.status == 429:
+        # back off
+        pass
+    elif e.status and 400 <= e.status < 500:
+        # bad input, won't recover by retrying
+        pass
+    else:
+        # transient — retry once or fail open
+        pass
+```
+
+## Try the API without signing up
+
+```bash
+curl https://sntlhq.com/v1/evaluate/sample?scenario=vpn
+```
+
+Or use the [interactive playground](https://sntlhq.com/api#playground).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

sentinelsup-0.1.0/README.md

@@ -0,0 +1,148 @@
+# Sentinel Python SDK
+
+Real-time fraud, VPN, proxy, and bot detection — free tier, sub-40ms global response.
+
+Zero dependencies. Just the standard library.
+
+## Install
+
+```bash
+pip install sentinelsup
+```
+
+## Quick start
+
+```python
+import os
+from sentinel import Sentinel
+
+s = Sentinel(api_key=os.environ["SENTINEL_API_KEY"])
+
+result = s.evaluate(token=request.json["sentinelToken"])
+
+if result.is_suspicious:
+    return abort(403, "Sentinel flagged this session")
+
+print(result.decision)        # 'allow' | 'review' | 'block'
+print(result.risk_score)      # 0..100
+print(result.network)         # {'vpn': True, 'proxy': False, 'datacenter': True, ...}
+print(result.reasons)         # ['ip_in_known_vpn_range', 'datacenter_asn', ...]
+```
+
+## Get your API key
+
+Sign up at [sntlhq.com/signup](https://sntlhq.com/signup) — free, no credit card.
+
+## Flask example — block VPN/proxy signups
+
+```python
+from flask import Flask, request, abort, jsonify
+from sentinel import Sentinel, SentinelError
+
+app = Flask(__name__)
+sentinel = Sentinel()  # reads SENTINEL_API_KEY from env
+
+@app.route("/signup", methods=["POST"])
+def signup():
+    data = request.get_json()
+    try:
+        result = sentinel.evaluate(token=data["sentinelToken"])
+    except SentinelError as e:
+        # Fail open OR fail closed — your call. Logged either way.
+        app.logger.warning("Sentinel error: %s", e)
+        result = None
+
+    if result and result.is_blocked:
+        abort(403, "Signup blocked")
+
+    # ... your normal signup flow
+    return jsonify({"ok": True})
+```
+
+## Django example — middleware for high-value endpoints
+
+```python
+from django.http import JsonResponse
+from sentinel import Sentinel
+
+sentinel = Sentinel()  # reads SENTINEL_API_KEY from env
+
+class FraudCheckMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        if request.path.startswith("/api/checkout"):
+            token = request.META.get("HTTP_X_SENTINEL_TOKEN")
+            if token:
+                try:
+                    result = sentinel.evaluate(token=token)
+                    if result.is_blocked:
+                        return JsonResponse({"error": "blocked"}, status=403)
+                except Exception:
+                    pass  # fail open
+        return self.get_response(request)
+```
+
+## Configuration
+
+```python
+Sentinel(
+    api_key="sk_live_...",          # required (or via SENTINEL_API_KEY env var)
+    endpoint="https://sntlhq.com",  # override for testing
+    timeout=5.0,                    # seconds
+)
+```
+
+## Response shape
+
+```python
+@dataclass
+class EvaluateResult:
+    decision: str | None        # 'allow' | 'review' | 'block'
+    risk_score: int | None      # 0..100
+    ip: str | None
+    country: str | None         # ISO-2
+    asn: str | None             # 'AS16509'
+    asn_org: str | None         # 'Amazon.com, Inc.'
+    network: dict               # {vpn, proxy, datacenter, anonymous, residential}
+    device: dict                # {headless, automation, fingerprint_age_days}
+    reasons: list[str]
+    raw: dict                   # full upstream response
+
+    is_suspicious: bool         # True if decision != 'allow'
+    is_blocked: bool            # True if decision == 'block'
+```
+
+## Errors
+
+All failures raise `SentinelError`. The exception carries `.status` (HTTP code) and `.body` (parsed error body) when available.
+
+```python
+from sentinel import Sentinel, SentinelError
+
+try:
+    result = sentinel.evaluate(token=tok)
+except SentinelError as e:
+    if e.status == 429:
+        # back off
+        pass
+    elif e.status and 400 <= e.status < 500:
+        # bad input, won't recover by retrying
+        pass
+    else:
+        # transient — retry once or fail open
+        pass
+```
+
+## Try the API without signing up
+
+```bash
+curl https://sntlhq.com/v1/evaluate/sample?scenario=vpn
+```
+
+Or use the [interactive playground](https://sntlhq.com/api#playground).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

sentinelsup-0.1.0/examples/django_middleware.py

@@ -0,0 +1,48 @@
+"""Django middleware example — score every request to high-value endpoints.
+
+Add to settings.py MIDDLEWARE:
+    "yourapp.middleware.SentinelMiddleware",
+
+Then ensure your frontend forwards the Sentinel token via the
+X-Sentinel-Token header (set after the SDK injects it on the client).
+"""
+
+import logging
+
+from django.http import JsonResponse
+
+from sentinel import Sentinel, SentinelError
+
+log = logging.getLogger(__name__)
+_GUARDED_PATHS = ("/api/checkout", "/api/withdraw", "/api/transfer")
+
+
+class SentinelMiddleware:
+    def __init__(self, get_response):
+        self.get_response = get_response
+        self.sentinel = Sentinel()  # reads SENTINEL_API_KEY
+
+    def __call__(self, request):
+        if not request.path.startswith(_GUARDED_PATHS):
+            return self.get_response(request)
+
+        token = request.META.get("HTTP_X_SENTINEL_TOKEN")
+        if not token:
+            return JsonResponse({"error": "missing X-Sentinel-Token"}, status=400)
+
+        try:
+            result = self.sentinel.evaluate(token=token)
+        except SentinelError as e:
+            log.warning("Sentinel error: %s", e)
+            # Fail open on infra problems; switch to fail-closed for finance flows.
+            return self.get_response(request)
+
+        if result.is_blocked:
+            return JsonResponse(
+                {"error": "blocked", "risk_score": result.risk_score, "reasons": result.reasons},
+                status=403,
+            )
+
+        # Stash on request so the view can read decision/score
+        request.sentinel = result
+        return self.get_response(request)

sentinelsup-0.1.0/examples/flask_signup_guard.py

@@ -0,0 +1,46 @@
+"""Flask example — block VPN/proxy signups using Sentinel.
+
+Run:
+    pip install flask sentinelsup
+    export SENTINEL_API_KEY=sk_live_...
+    python flask_signup_guard.py
+"""
+
+import os
+from flask import Flask, abort, jsonify, request
+
+from sentinel import Sentinel, SentinelError
+
+app = Flask(__name__)
+sentinel = Sentinel()  # reads SENTINEL_API_KEY
+
+
+@app.route("/signup", methods=["POST"])
+def signup() -> object:
+    payload = request.get_json(force=True) or {}
+    email = (payload.get("email") or "").strip().lower()
+    token = payload.get("sentinelToken")
+
+    if not email or not token:
+        abort(400, "missing email or sentinelToken")
+
+    try:
+        result = sentinel.evaluate(token=token)
+    except SentinelError as e:
+        # Fail open if Sentinel is down — log and continue.
+        app.logger.warning("Sentinel unavailable: %s", e)
+        result = None
+
+    if result and result.is_blocked:
+        return jsonify({"error": "Signup blocked", "reasons": result.reasons}), 403
+
+    if result and result.decision == "review":
+        # Soft challenge: email verification, manual review, slower onboarding, etc.
+        return jsonify({"ok": True, "needs_verification": True})
+
+    # Normal signup flow
+    return jsonify({"ok": True})
+
+
+if __name__ == "__main__":
+    app.run(port=int(os.environ.get("PORT", 5000)), debug=False)

sentinelsup-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# NOTE: "sentinel-sdk" on PyPI is squatted by an unrelated third party
+# ("NAST0R"). Never publish or document that name — users following it
+# would install a stranger's code. "sentinelsup" matches the npm scope
+# (@sentinelsup/sdk).
+name = "sentinelsup"
+version = "0.1.0"
+description = "Sentinel — real-time fraud, VPN, proxy, and bot detection API. Free tier, sub-40ms response."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+    { name = "Sentinel Edge Networks LTD", email = "support@sntlhq.com" }
+]
+keywords = [
+    "fraud-detection", "vpn-detection", "proxy-detection", "bot-detection",
+    "antidetect-browser", "device-fingerprinting", "sentinel", "api"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://sntlhq.com"
+Documentation = "https://sntlhq.com/api"
+Repository = "https://github.com/sentinelsup/sentinel-python"
+Issues = "https://github.com/sentinelsup/sentinel-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sentinel"]

sentinelsup-0.1.0/sentinel/__init__.py

@@ -0,0 +1,156 @@
+"""
+Sentinel Python SDK — thin, dependency-free wrapper around the Sentinel
+fraud detection API at https://sntlhq.com/v1/evaluate.
+
+Usage:
+    from sentinel import Sentinel
+    s = Sentinel(api_key=os.environ["SENTINEL_KEY"])
+    result = s.evaluate(token=request.json["sentinelToken"])
+    if result.is_suspicious:
+        abort(403)
+"""
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+from urllib import error, request
+
+DEFAULT_ENDPOINT = "https://sntlhq.com"
+DEFAULT_TIMEOUT = 5.0
+__version__ = "0.1.0"
+
+
+class SentinelError(Exception):
+    """Raised on any Sentinel API or transport failure."""
+
+    def __init__(
+        self,
+        message: str,
+        status: Optional[int] = None,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body or {}
+
+
+@dataclass
+class EvaluateResult:
+    """Structured response from /v1/evaluate."""
+
+    decision: Optional[str] = None
+    risk_score: Optional[int] = None
+    ip: Optional[str] = None
+    country: Optional[str] = None
+    asn: Optional[str] = None
+    asn_org: Optional[str] = None
+    network: Dict[str, Any] = field(default_factory=dict)
+    device: Dict[str, Any] = field(default_factory=dict)
+    reasons: list = field(default_factory=list)
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_suspicious(self) -> bool:
+        """True if the decision is anything other than 'allow'."""
+        return self.decision is not None and self.decision != "allow"
+
+    @property
+    def is_blocked(self) -> bool:
+        return self.decision == "block"
+
+
+class Sentinel:
+    """Sentinel API client. Pass an API key from https://sntlhq.com/dashboard."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        endpoint: str = DEFAULT_ENDPOINT,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        api_key = api_key or os.environ.get("SENTINEL_API_KEY")
+        if not api_key or not isinstance(api_key, str):
+            raise SentinelError(
+                "Sentinel: api_key is required. "
+                "Pass it explicitly or set SENTINEL_API_KEY. "
+                "Get one free at https://sntlhq.com/signup"
+            )
+        self.api_key = api_key
+        self.endpoint = endpoint.rstrip("/")
+        self.timeout = timeout
+
+    def evaluate(
+        self,
+        token: str,
+        fingerprint_event_id: Optional[str] = None,
+    ) -> EvaluateResult:
+        """Evaluate a visitor session for fraud signals.
+
+        Args:
+            token: Sentinel client-side token from the frontend SDK.
+            fingerprint_event_id: Optional Fingerprint event id for device signals.
+
+        Returns:
+            EvaluateResult with decision, risk_score, network, device, and reasons.
+
+        Raises:
+            SentinelError: on network failure, timeout, or non-2xx response.
+        """
+        if not token or not isinstance(token, str):
+            raise SentinelError(
+                "Sentinel.evaluate: token (client-side Sentinel token) is required"
+            )
+
+        payload: Dict[str, Any] = {"token": token}
+        if fingerprint_event_id:
+            payload["fingerprintEventId"] = fingerprint_event_id
+
+        body = json.dumps(payload).encode("utf-8")
+        req = request.Request(
+            f"{self.endpoint}/v1/evaluate",
+            data=body,
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "User-Agent": f"sentinel-python/{__version__}",
+            },
+        )
+
+        try:
+            with request.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read().decode("utf-8")
+                data = json.loads(raw) if raw else {}
+        except error.HTTPError as e:
+            try:
+                err_body = json.loads(e.read().decode("utf-8"))
+            except Exception:
+                err_body = {}
+            msg = err_body.get("error") if isinstance(err_body, dict) else None
+            raise SentinelError(
+                f"Sentinel: API returned {e.code}"
+                + (f" — {msg}" if msg else ""),
+                status=e.code,
+                body=err_body,
+            ) from None
+        except error.URLError as e:
+            raise SentinelError(f"Sentinel: network error — {e.reason}") from None
+        except Exception as e:
+            raise SentinelError(f"Sentinel: unexpected error — {e}") from None
+
+        return EvaluateResult(
+            decision=data.get("decision"),
+            risk_score=data.get("risk_score"),
+            ip=data.get("ip"),
+            country=data.get("country"),
+            asn=data.get("asn"),
+            asn_org=data.get("asn_org"),
+            network=data.get("network") or {},
+            device=data.get("device") or {},
+            reasons=data.get("reasons") or [],
+            raw=data,
+        )
+
+
+__all__ = ["Sentinel", "SentinelError", "EvaluateResult", "__version__"]