loguard 2.0.0__tar.gz

loguard-2.0.0/.idea/.gitignore

@@ -0,0 +1,8 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

loguard-2.0.0/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,7 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="Eslint" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="PyPackageRequirementsInspection" enabled="false" level="WARNING" enabled_by_default="false" />
+  </profile>
+</component>

loguard-2.0.0/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

loguard-2.0.0/.idea/loguard_sdk.iml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
+    <orderEntry type="jdk" jdkName="Python 3.14 (loguard_sdk)" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

loguard-2.0.0/.idea/misc.xml

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Black">
+    <option name="sdkName" value="Python 3.14 (loguard_sdk)" />
+  </component>
+  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.14 (loguard_sdk)" project-jdk-type="Python SDK" />
+</project>

loguard-2.0.0/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/loguard_sdk.iml" filepath="$PROJECT_DIR$/.idea/loguard_sdk.iml" />
+    </modules>
+  </component>
+</project>

loguard-2.0.0/.idea/workspace.xml

@@ -0,0 +1,62 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AutoImportSettings">
+    <option name="autoReloadType" value="SELECTIVE" />
+  </component>
+  <component name="ChangeListManager">
+    <list default="true" id="a0f97438-b3be-45c8-83bf-3b6807b3e6cd" name="Changes" comment="" />
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="ProjectColorInfo"><![CDATA[{
+  "associatedIndex": 2
+}]]></component>
+  <component name="ProjectId" id="3B42YJpLQPccVEcva7CCFx0hwwH" />
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.TerminalTabsStorage.copyFrom.TerminalArrangementManager.252": "true",
+    "last_opened_file_path": "/Users/admin/PythonProjects/loguard_sdk",
+    "node.js.detected.package.eslint": "true",
+    "node.js.detected.package.tslint": "true",
+    "node.js.selected.package.eslint": "(autodetect)",
+    "node.js.selected.package.tslint": "(autodetect)",
+    "nodejs_package_manager_path": "npm",
+    "vue.rearranger.settings.migration": "true"
+  }
+}]]></component>
+  <component name="RecentsManager">
+    <key name="CopyFile.RECENT_KEYS">
+      <recent name="$PROJECT_DIR$" />
+    </key>
+  </component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-js-predefined-d6986cc7102b-a71380e98a7c-JavaScript-PY-252.28539.27" />
+        <option value="bundled-python-sdk-07523f343e4f-968fe969f28a-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-252.28539.27" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="a0f97438-b3be-45c8-83bf-3b6807b3e6cd" name="Changes" comment="" />
+      <created>1773734067381</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1773734067381</updated>
+      <workItem from="1773734068457" duration="310000" />
+    </task>
+    <servers />
+  </component>
+  <component name="TypeScriptGeneratedFilesManager">
+    <option name="version" value="3" />
+  </component>
+</project>

loguard-2.0.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: loguard
+Version: 2.0.0
+Summary: LoGuard Python SDK — security event monitoring, alert rules, and blacklisting
+Project-URL: Homepage, https://logguard.io
+Project-URL: Documentation, https://docs.logguard.io/sdk/python
+Project-URL: Repository, https://github.com/logguard/logguard-python
+License: MIT
+Keywords: alerts,blacklist,monitoring,sdk,security
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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 :: Security
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=3.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: starlette>=0.27.0; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# loguard

loguard-2.0.0/README.md

@@ -0,0 +1 @@
+# loguard

loguard-2.0.0/__init__.py

@@ -0,0 +1,84 @@
+"""
+Logguard Python SDK
+~~~~~~~~~~~~~~~~~~~
+
+Official Python SDK for Logguard — lightweight security monitoring
+with user-defined alert rules and IP/user blacklisting.
+
+Quick start:
+    from logguard import monitor
+    from logguard.models import AlertRule, AlertCondition, BlacklistEntry
+
+    monitor.init(api_key="lg_live_xxx", env="production")
+
+    # Track events
+    monitor.event(type="login_failed", ip="1.2.3.4", path="/login", status_code=401)
+
+    # Fire-and-forget (non-blocking, for production traffic)
+    monitor.event_fire_and_forget(type="http_error", ip="1.2.3.4", path="/api", status_code=500)
+
+    # Create an alert rule
+    rule = monitor.alerts.create(AlertRule(
+        name="Brute force",
+        conditions=[
+            AlertCondition(field="type",            op="eq",  value="login_failed"),
+            AlertCondition(field="rate_per_minute", op="gt",  value=10),
+        ],
+        severity="high",
+        actions=["notify", "block"],
+    ))
+
+    # Blacklist an IP
+    monitor.blacklist.block_ip("185.220.101.1", reason="Known scanner")
+
+    # Check if an IP is blacklisted
+    result = monitor.blacklist.check(type="ip", value="185.220.101.1")
+
+Docs: https://docs.logguard.io/sdk/python
+"""
+
+from .monitor import monitor
+from .models import (
+    AlertCondition,
+    AlertRule,
+    AlertOut,
+    BlacklistEntry,
+    Event,
+    IngestResult,
+    UsageInfo,
+)
+from .exceptions import (
+    LogguardError,
+    LogguardNotInitializedError,
+    LogguardAuthError,
+    LogguardQuotaError,
+    LogguardConnectionError,
+    LogguardValidationError,
+    LogguardNotFoundError,
+    LogguardConflictError,
+)
+
+__version__ = "2.0.0"
+
+__all__ = [
+    # Core
+    "monitor",
+    "__version__",
+    # Models
+    "Event",
+    "IngestResult",
+    "AlertOut",
+    "UsageInfo",
+    "AlertRule",
+    "AlertCondition",
+    "BlacklistEntry",
+    # Exceptions
+    "LogguardError",
+    "LogguardNotInitializedError",
+    "LogguardAuthError",
+    "LogguardQuotaError",
+    "LogguardConnectionError",
+    "LogguardValidationError",
+    "LogguardNotFoundError",
+    "LogguardConflictError",
+]

loguard-2.0.0/_transport.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+import httpx
+
+from .exceptions import (
+    LogguardAuthError,
+    LogguardConnectionError,
+    LogguardConflictError,
+    LogguardNotFoundError,
+    LogguardQuotaError,
+    LogguardValidationError,
+)
+from .models import AlertOut, IngestResult
+
+log = logging.getLogger("logguard")
+
+_RETRY_STATUSES = {500, 502, 503, 504}
+
+
+def _safe_json(resp: httpx.Response) -> Tuple[Any, str]:
+    """Returns (parsed_json_or_None, text_snippet). Never raises."""
+    text = ""
+    try:
+        text = resp.text or ""
+    except Exception:
+        pass
+    snippet = text[:400]
+    try:
+        j = resp.json()
+        return j, snippet
+    except Exception:
+        return None, snippet
+
+
+def _raise_for_status(resp: httpx.Response) -> Any:
+    """
+    Raises appropriate LogguardError for non-2xx responses.
+    Returns parsed JSON body on success.
+    """
+    data, snippet = _safe_json(resp)
+    d = data if isinstance(data, dict) else {}
+
+    if resp.status_code == 401:
+        raise LogguardAuthError("Invalid API key")
+
+    if resp.status_code == 402:
+        raise LogguardAuthError("Subscription expired — renew at logguard.io")
+
+    if resp.status_code == 403:
+        detail = d.get("detail", snippet)
+        if detail == "subscription_expired":
+            raise LogguardAuthError("Subscription expired — renew at logguard.io")
+        raise LogguardAuthError(f"Access denied: {detail}")
+
+    if resp.status_code == 404:
+        detail = d.get("detail", snippet)
+        raise LogguardNotFoundError(f"Not found: {detail}")
+
+    if resp.status_code == 409:
+        detail = d.get("detail", snippet)
+        raise LogguardConflictError(f"Conflict: {detail}")
+
+    if resp.status_code == 422:
+        raise LogguardValidationError(f"Validation error: {snippet}")
+
+    if resp.status_code == 429:
+        detail = d.get("detail", {})
+        if isinstance(detail, dict) and detail.get("err") == "usage_limit_exceeded":
+            raise LogguardQuotaError(
+                f"Monthly quota exceeded: {detail.get('used')}/{detail.get('limit')} "
+                f"events on plan '{detail.get('plan')}'. Upgrade at logguard.io"
+            )
+        raise LogguardConnectionError(f"Rate limited: {snippet}")
+
+    if resp.status_code >= 500:
+        raise LogguardConnectionError(f"Server error ({resp.status_code}): {snippet}")
+
+    return data
+
+
+def parse_ingest_response(data: Any) -> IngestResult:
+    d = data if isinstance(data, dict) else {}
+    alerts = [AlertOut(**a) for a in (d.get("alerts") or [])]
+    return IngestResult(
+        ok=bool(d.get("ok", False)),
+        inserted=int(d.get("inserted", 0)),
+        dropped=int(d.get("dropped", 0)),
+        alerts_fired=int(d.get("alerts_fired", 0)),
+        alerts=alerts,
+        plan=str(d.get("plan", "")),
+        usage=dict(d.get("usage", {}) or {}),
+    )
+
+
+def send_sync(
+    url: str,
+    headers: dict,
+    payload: dict,
+    timeout: float,
+    retries: int,
+    method: str = "POST",
+) -> Any:
+    last_exc: Exception = LogguardConnectionError("Unknown error")
+    for attempt in range(1, retries + 1):
+        try:
+            with httpx.Client(timeout=timeout) as client:
+                fn = getattr(client, method.lower())
+                resp = fn(url, json=payload, headers=headers)
+
+            if resp.status_code not in _RETRY_STATUSES:
+                return _raise_for_status(resp)
+
+            last_exc = LogguardConnectionError(f"Server error {resp.status_code}")
+            log.warning("Attempt %d/%d failed status=%d", attempt, retries, resp.status_code)
+
+        except (httpx.RequestError, httpx.TimeoutException) as e:
+            last_exc = LogguardConnectionError(f"Connection error: {e!r}")
+            log.warning("Attempt %d/%d connection error: %r", attempt, retries, e)
+
+        if attempt < retries:
+            time.sleep(0.4 * attempt)
+
+    raise last_exc
+
+
+def send_sync_no_body(
+    url: str,
+    headers: dict,
+    timeout: float,
+    retries: int,
+    method: str = "GET",
+) -> Any:
+    """For GET/DELETE requests without a body."""
+    last_exc: Exception = LogguardConnectionError("Unknown error")
+    for attempt in range(1, retries + 1):
+        try:
+            with httpx.Client(timeout=timeout) as client:
+                fn = getattr(client, method.lower())
+                resp = fn(url, headers=headers)
+
+            if resp.status_code not in _RETRY_STATUSES:
+                return _raise_for_status(resp)
+
+            last_exc = LogguardConnectionError(f"Server error {resp.status_code}")
+
+        except (httpx.RequestError, httpx.TimeoutException) as e:
+            last_exc = LogguardConnectionError(f"Connection error: {e!r}")
+
+        if attempt < retries:
+            time.sleep(0.4 * attempt)
+
+    raise last_exc
+
+
+async def send_async(
+    url: str,
+    headers: dict,
+    payload: dict,
+    timeout: float,
+    retries: int,
+    method: str = "POST",
+) -> Any:
+    last_exc: Exception = LogguardConnectionError("Unknown error")
+    for attempt in range(1, retries + 1):
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                fn = getattr(client, method.lower())
+                resp = await fn(url, json=payload, headers=headers)
+
+            if resp.status_code not in _RETRY_STATUSES:
+                return _raise_for_status(resp)
+
+            last_exc = LogguardConnectionError(f"Server error {resp.status_code}")
+
+        except (httpx.RequestError, httpx.TimeoutException) as e:
+            last_exc = LogguardConnectionError(f"Connection error: {e!r}")
+
+        if attempt < retries:
+            await asyncio.sleep(0.4 * attempt)
+
+    raise last_exc
+
+
+async def send_async_no_body(
+    url: str,
+    headers: dict,
+    timeout: float,
+    retries: int,
+    method: str = "GET",
+) -> Any:
+    last_exc: Exception = LogguardConnectionError("Unknown error")
+    for attempt in range(1, retries + 1):
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                fn = getattr(client, method.lower())
+                resp = await fn(url, headers=headers)
+
+            if resp.status_code not in _RETRY_STATUSES:
+                return _raise_for_status(resp)
+
+            last_exc = LogguardConnectionError(f"Server error {resp.status_code}")
+
+        except (httpx.RequestError, httpx.TimeoutException) as e:
+            last_exc = LogguardConnectionError(f"Connection error: {e!r}")
+
+        if attempt < retries:
+            await asyncio.sleep(0.4 * attempt)
+
+    raise last_exc

loguard-2.0.0/django.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from typing import Callable, Optional, Set
+
+from ..monitor import monitor as _monitor
+from ..exceptions import LogguardError, LogguardNotInitializedError
+
+log = logging.getLogger("logguard.django")
+
+
+class LogguardMiddleware:
+    """
+    Django middleware — auto-tracks HTTP errors and optionally enforces
+    the blacklist on every incoming request.
+
+    Setup in settings.py:
+        MIDDLEWARE = [
+            "logguard.integrations.django.LogguardMiddleware",
+            ...  # put first so blacklist check happens early
+        ]
+
+    And in your app startup (e.g. AppConfig.ready()):
+        from logguard import monitor
+        monitor.init(api_key="lg_live_xxx", env="production")
+
+    With blacklist enforcement:
+        LOGGUARD_ENFORCE_BLACKLIST = True   # in settings.py
+        or pass enforce_blacklist=True to the middleware constructor (via MIDDLEWARE_CONFIG)
+
+    Blocked IPs receive: HTTP 403 JSON response.
+    """
+
+    def __init__(
+        self,
+        get_response: Callable,
+        *,
+        track_statuses: Optional[Set[int]] = None,
+        enforce_blacklist: bool = False,
+    ):
+        self.get_response = get_response
+        self._track_statuses = track_statuses or {400, 401, 403, 404, 429, 500, 502, 503}
+        self._enforce_blacklist = enforce_blacklist
+
+    def __call__(self, request):
+        from django.http import JsonResponse
+
+        ip = (
+            request.META.get("HTTP_X_FORWARDED_FOR", "").split(",")[0].strip()
+            or request.META.get("REMOTE_ADDR", "unknown")
+        )
+
+        # ── Blacklist check ────────────────────────────────────────────────
+        if self._enforce_blacklist:
+            try:
+                result = _monitor.blacklist.check(type="ip", value=ip)
+                if result.get("blacklisted") and result.get("action") == "block":
+                    return JsonResponse(
+                        {"detail": "Forbidden", "reason": result.get("reason", "blacklisted")},
+                        status=403,
+                    )
+            except LogguardNotInitializedError:
+                log.warning("LogguardMiddleware: monitor not initialized")
+            except LogguardError as e:
+                log.debug("LogguardMiddleware blacklist check failed: %r", e)
+
+        # ── Process request ────────────────────────────────────────────────
+        response = self.get_response(request)
+
+        # ── Track errors ───────────────────────────────────────────────────
+        if response.status_code in self._track_statuses:
+            user_id = None
+            if getattr(request, "user", None) and request.user.is_authenticated:
+                user_id = str(request.user.pk)
+
+            event_type = "login_failed" if response.status_code == 401 else "http_error"
+
+            threading.Thread(
+                target=self._fire,
+                args=(event_type, ip, request.path, response.status_code, user_id),
+                daemon=True,
+            ).start()
+
+        return response
+
+    def _fire(self, event_type, ip, path, status_code, user_id):
+        try:
+            _monitor.event(
+                type=event_type,
+                ip=ip,
+                path=path,
+                status_code=status_code,
+                user_id=user_id,
+            )
+        except LogguardNotInitializedError:
+            log.warning("LogguardMiddleware: monitor not initialized")
+        except LogguardError as e:
+            log.debug("LogguardMiddleware track failed: %r", e)

loguard-2.0.0/exceptions.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+
+class LogguardError(Exception):
+    """Base exception for all Logguard SDK errors."""
+
+
+class LogguardNotInitializedError(LogguardError):
+    """Raised when monitor.event() is called before monitor.init()."""
+
+
+class LogguardAuthError(LogguardError):
+    """Raised when API key is invalid, missing, or subscription expired."""
+
+
+class LogguardQuotaError(LogguardError):
+    """Raised when monthly event quota is exceeded."""
+
+
+class LogguardConnectionError(LogguardError):
+    """Raised when the Logguard API is unreachable or returns a server error."""
+
+
+class LogguardValidationError(LogguardError):
+    """Raised when event data fails validation."""
+
+
+class LogguardNotFoundError(LogguardError):
+    """Raised when a requested resource (alert rule, blacklist entry) is not found."""
+
+
+class LogguardConflictError(LogguardError):
+    """Raised when creating a resource that already exists (e.g. duplicate blacklist entry)."""