UGOS 1.0.0__tar.gz

ugos-1.0.0/LICENSE

@@ -0,0 +1,16 @@
+MIT No Attribution
+
+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.
+
+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.

ugos-1.0.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: UGOS
+Version: 1.0.0
+Summary: Python client for the UserGate NGFW web-console API
+Project-URL: Repository, https://codeberg.org/owldog/ugos
+License-Expression: MIT-0
+License-File: LICENSE
+Keywords: api,firewall,httpx,ngfw,ugos
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Networking :: Firewalls
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<0.29,>=0.27
+Description-Content-Type: text/markdown
+
+# UGOS
+
+Synchronous Python client for the UserGate NGFW web-console API.
+
+- Python 3.10+
+- `httpx` transport
+- compatible with UserGate NGFW 7.x
+- typed resources plus exact access to every catalog action
+
+## Install
+
+```bash
+uv add UGOS
+```
+
+From a local wheel:
+
+```bash
+uv add ./dist/ugos-*.whl
+```
+
+## Quick start
+
+### Environment variables
+
+```bash
+export UGOS_URL=https://ngfw.example:8001
+export UGOS_USERNAME=Admin
+export UGOS_PASSWORD=...
+export UGOS_VERIFY=true
+export UGOS_TIMEOUT=30
+```
+
+```python
+from ugos import UGOSClient
+
+with UGOSClient.from_env() as client:
+    client.login()
+
+    print(client.licensing.get_info())
+    print(client.users.list(limit=20).total)
+
+    for user in client.users.iter_all(page_size=100):
+        print(user["name"])
+```
+
+`from_env()` reads:
+
+| Parameter | Environment variable | Default |
+|---|---|---|
+| `base_url` | `UGOS_URL` | required |
+| `username` | `UGOS_USERNAME` | `None` |
+| `password` | `UGOS_PASSWORD` | `None` |
+| `verify` | `UGOS_CA_BUNDLE`, `UGOS_VERIFY` | `True` |
+| `timeout` | `UGOS_TIMEOUT` | `30.0` |
+| `allow_insecure_http` | `UGOS_ALLOW_INSECURE_HTTP` | `False` |
+
+`UGOS_CA_BUNDLE` takes precedence over `UGOS_VERIFY` and accepts a path to a
+CA bundle. `UGOS_VERIFY` accepts `true`, `false`, `1`, `0`, `yes`, `no`,
+`on`, `off`, or a CA path.
+
+### Explicit configuration
+
+```python
+with UGOSClient(
+    base_url="https://ngfw.example:8001",
+    username="Admin",
+    password="...",
+    verify="/path/to/ca.pem",
+    timeout=30,
+) as client:
+    client.login()
+    print(client.users.list(limit=20).total)
+```
+
+`from_env()` also accepts keyword overrides, which take precedence over
+environment variables:
+
+```python
+with UGOSClient.from_env(password="...", verify=False) as client:
+    client.login()
+```
+
+## Generic and typed access
+
+```python
+client.users.list(limit=50)                 # typed helper
+client.users.actions.UsersList(limit=50)    # exact action
+client.call("users", "UsersList", limit=50) # raw call
+client.dhcp.list()                          # generic resource
+```
+
+## Errors
+
+```python
+from ugos import NotFoundError, UGOSError
+
+try:
+    client.users.get(999)
+except NotFoundError as exc:
+    print(exc.code, exc.message)
+except UGOSError as exc:
+    print(exc)
+```
+
+## Compatibility
+
+Compatible with UserGate NGFW 7.x. For builds with a different action set, pass
+`catalog_check=False` or `strict=False`.
+
+## License
+
+MIT-0. See `LICENSE`.

ugos-1.0.0/README.md

@@ -0,0 +1,113 @@
+# UGOS
+
+Synchronous Python client for the UserGate NGFW web-console API.
+
+- Python 3.10+
+- `httpx` transport
+- compatible with UserGate NGFW 7.x
+- typed resources plus exact access to every catalog action
+
+## Install
+
+```bash
+uv add UGOS
+```
+
+From a local wheel:
+
+```bash
+uv add ./dist/ugos-*.whl
+```
+
+## Quick start
+
+### Environment variables
+
+```bash
+export UGOS_URL=https://ngfw.example:8001
+export UGOS_USERNAME=Admin
+export UGOS_PASSWORD=...
+export UGOS_VERIFY=true
+export UGOS_TIMEOUT=30
+```
+
+```python
+from ugos import UGOSClient
+
+with UGOSClient.from_env() as client:
+    client.login()
+
+    print(client.licensing.get_info())
+    print(client.users.list(limit=20).total)
+
+    for user in client.users.iter_all(page_size=100):
+        print(user["name"])
+```
+
+`from_env()` reads:
+
+| Parameter | Environment variable | Default |
+|---|---|---|
+| `base_url` | `UGOS_URL` | required |
+| `username` | `UGOS_USERNAME` | `None` |
+| `password` | `UGOS_PASSWORD` | `None` |
+| `verify` | `UGOS_CA_BUNDLE`, `UGOS_VERIFY` | `True` |
+| `timeout` | `UGOS_TIMEOUT` | `30.0` |
+| `allow_insecure_http` | `UGOS_ALLOW_INSECURE_HTTP` | `False` |
+
+`UGOS_CA_BUNDLE` takes precedence over `UGOS_VERIFY` and accepts a path to a
+CA bundle. `UGOS_VERIFY` accepts `true`, `false`, `1`, `0`, `yes`, `no`,
+`on`, `off`, or a CA path.
+
+### Explicit configuration
+
+```python
+with UGOSClient(
+    base_url="https://ngfw.example:8001",
+    username="Admin",
+    password="...",
+    verify="/path/to/ca.pem",
+    timeout=30,
+) as client:
+    client.login()
+    print(client.users.list(limit=20).total)
+```
+
+`from_env()` also accepts keyword overrides, which take precedence over
+environment variables:
+
+```python
+with UGOSClient.from_env(password="...", verify=False) as client:
+    client.login()
+```
+
+## Generic and typed access
+
+```python
+client.users.list(limit=50)                 # typed helper
+client.users.actions.UsersList(limit=50)    # exact action
+client.call("users", "UsersList", limit=50) # raw call
+client.dhcp.list()                          # generic resource
+```
+
+## Errors
+
+```python
+from ugos import NotFoundError, UGOSError
+
+try:
+    client.users.get(999)
+except NotFoundError as exc:
+    print(exc.code, exc.message)
+except UGOSError as exc:
+    print(exc)
+```
+
+## Compatibility
+
+Compatible with UserGate NGFW 7.x. For builds with a different action set, pass
+`catalog_check=False` or `strict=False`.
+
+## License
+
+MIT-0. See `LICENSE`.

ugos-1.0.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.27.0,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "UGOS"
+dynamic = ["version"]
+description = "Python client for the UserGate NGFW web-console API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT-0"
+license-files = ["LICENSE"]
+keywords = ["ugos", "ngfw", "firewall", "api", "httpx"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+  "Topic :: System :: Networking :: Firewalls",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["httpx>=0.27,<0.29"]
+
+[project.urls]
+Repository = "https://codeberg.org/owldog/ugos"
+
+[tool.hatch.version]
+path = "src/ugos/__about__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ugos"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/README.md",
+  "/LICENSE",
+  "/pyproject.toml",
+]

ugos-1.0.0/src/ugos/__about__.py

@@ -0,0 +1,6 @@
+"""Package metadata."""
+
+__version__ = "1.0.0"
+
+SUPPORTED_MAJOR_VERSION = 7
+SUPPORTED_NGFW = f"{SUPPORTED_MAJOR_VERSION}.x"

ugos-1.0.0/src/ugos/__init__.py

@@ -0,0 +1,92 @@
+"""Python client for the UGOS NGFW web-console API."""
+
+from .__about__ import SUPPORTED_MAJOR_VERSION, SUPPORTED_NGFW, __version__
+from .catalog import Catalog, load_catalog
+from .client import UGOSClient
+from .exceptions import (
+    AccessDeniedError,
+    APIError,
+    AuthenticationError,
+    CatalogError,
+    CleanupError,
+    ConfigurationError,
+    ConflictError,
+    CSRFError,
+    DecodeError,
+    DownloadError,
+    DuplicateError,
+    HTTPStatusError,
+    NotFoundError,
+    ProtocolError,
+    ReadOnlyListError,
+    RequestTimeoutError,
+    ServerError,
+    SessionExpiredError,
+    TransportError,
+    UnknownActionError,
+    UnknownControllerError,
+    UGOSError,
+    ValidationError,
+)
+from .models.common import DownloadedFile, ListResult, SessionInfo
+from .models.entities import (
+    Administrator,
+    Certificate,
+    FirewallRule,
+    Group,
+    Interface,
+    LicenseInfo,
+    NetworkList,
+    PcapFilter,
+    PcapRule,
+    Tag,
+    Zone,
+)
+from .resources.base import Resource
+
+__all__ = [
+    "SUPPORTED_MAJOR_VERSION",
+    "SUPPORTED_NGFW",
+    "APIError",
+    "AccessDeniedError",
+    "Administrator",
+    "AuthenticationError",
+    "CSRFError",
+    "Catalog",
+    "CatalogError",
+    "Certificate",
+    "CleanupError",
+    "ConfigurationError",
+    "ConflictError",
+    "DecodeError",
+    "DownloadError",
+    "DownloadedFile",
+    "DuplicateError",
+    "FirewallRule",
+    "Group",
+    "HTTPStatusError",
+    "Interface",
+    "LicenseInfo",
+    "ListResult",
+    "NetworkList",
+    "NotFoundError",
+    "PcapFilter",
+    "PcapRule",
+    "ProtocolError",
+    "ReadOnlyListError",
+    "RequestTimeoutError",
+    "Resource",
+    "ServerError",
+    "SessionExpiredError",
+    "SessionInfo",
+    "Tag",
+    "TransportError",
+    "UnknownActionError",
+    "UnknownControllerError",
+    "UGOSClient",
+    "UGOSError",
+    "ValidationError",
+    "Zone",
+    "__version__",
+    "load_catalog",
+]

ugos-1.0.0/src/ugos/_auth.py

@@ -0,0 +1,293 @@
+"""Console authentication, CSRF handling and session lifecycle."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from collections.abc import Mapping
+from typing import Any, cast
+
+import httpx
+
+from ._codec import is_error_payload, parse_response
+from ._encoding import encode_params
+from ._redaction import redact_mapping
+from ._transport import FORM_HEADERS, HTML_HEADERS, HttpTransport
+from .exceptions import (
+    AuthenticationError,
+    CSRFError,
+    DecodeError,
+    HTTPStatusError,
+    ProtocolError,
+    SessionExpiredError,
+    UGOSError,
+)
+from .models.common import SessionInfo
+
+_CSRF_RE = re.compile(r"CSRF_TOKEN\s*=\s*['\"]([^'\"]+)['\"]")
+_CSRF_INPUT_RE = re.compile(
+    r"name=['\"]csrfmiddlewaretoken['\"][^>]*value=['\"]([^'\"]+)['\"]",
+    re.IGNORECASE,
+)
+_CSRF_META_RE = re.compile(
+    r"name=['\"]csrf-token['\"][^>]*content=['\"]([^'\"]+)['\"]",
+    re.IGNORECASE,
+)
+
+
+class AuthManager:
+    """Owns login/logout, cookies and the CSRF token."""
+
+    def __init__(
+        self,
+        transport: HttpTransport,
+        *,
+        username: str | None = None,
+        password: str | None = None,
+        login_path: str = "utm/login",
+        logout_path: str = "utm/CoreLogout",
+        auto_reauth: bool = True,
+    ) -> None:
+        self._transport = transport
+        self._username = username
+        self._password = password
+        self._login_path = login_path
+        self._logout_path = logout_path
+        self._auto_reauth = auto_reauth
+        self._session: SessionInfo | None = None
+        self._csrf: str | None = None
+        self._generation = 0
+
+    @property
+    def session(self) -> SessionInfo | None:
+        return self._session
+
+    @property
+    def authenticated(self) -> bool:
+        return self._session is not None
+
+    @property
+    def csrf_token(self) -> str | None:
+        return self._csrf
+
+    @property
+    def generation(self) -> int:
+        return self._generation
+
+    def invalidate(self) -> None:
+        self._session = None
+        self._csrf = None
+        self._generation += 1
+        self._transport.clear_cookies(("_console_session", "csrf_token"))
+
+    @property
+    def auto_reauth(self) -> bool:
+        return self._auto_reauth
+
+    def ensure_csrf(self) -> str:
+        if self._csrf:
+            return self._csrf
+        token = self._transport.get_cookie("csrf_token")
+        if token:
+            self._csrf = token
+            return token
+        return self.refresh_csrf()
+
+    @staticmethod
+    def _is_login_redirect(status_code: int, location: str) -> bool:
+        if status_code not in {301, 302, 303, 307, 308}:
+            return False
+        return "utm/login" in location or location.rstrip("/").endswith("/login")
+
+    def _raise_csrf_status(self, response: httpx.Response) -> None:
+        location = response.headers.get("location", "")
+        login_redirect = self._is_login_redirect(response.status_code, location)
+        if response.status_code == 401 or login_redirect:
+            raise SessionExpiredError(
+                "session expired while refreshing CSRF",
+                status_code=response.status_code,
+            )
+        if response.status_code >= 400:
+            raise CSRFError(
+                f"CSRF refresh failed with HTTP {response.status_code}",
+                status_code=response.status_code,
+            )
+
+    def _extract_csrf_token(self, response: httpx.Response) -> str:
+        token = self._transport.get_cookie("csrf_token") or _extract_csrf(response.text)
+        if not token:
+            raise CSRFError("the login page did not contain a CSRF token")
+        return token
+
+    def refresh_csrf(self) -> str:
+        path = "/" if self.authenticated else self._login_path
+        try:
+            response = self._transport.request(
+                "GET",
+                path,
+                headers=HTML_HEADERS,
+                idempotent=True,
+            )
+        except UGOSError:
+            raise
+        except Exception as exc:
+            raise CSRFError(f"failed to obtain a CSRF token: {exc}") from exc
+        self._raise_csrf_status(response)
+        self.note_response(response)
+        self._csrf = self._extract_csrf_token(response)
+        return self._csrf
+
+    def _reset_session(self) -> None:
+        self._transport.clear_cookies(("_console_session", "csrf_token"))
+        self._session = None
+        self._csrf = None
+
+    def _login_page_token(self) -> str:
+        page = self._transport.request(
+            "GET", self._login_path, headers=HTML_HEADERS, idempotent=True
+        )
+        self.note_response(page)
+        return self._extract_csrf_token(page)
+
+    def _post_login(self, token: str) -> httpx.Response:
+        body = encode_params(
+            {
+                "username": self._username,
+                "password": self._password,
+                "csrfmiddlewaretoken": token,
+            }
+        )
+        response = self._transport.request(
+            "POST",
+            self._login_path,
+            data=body,
+            headers=FORM_HEADERS,
+            idempotent=False,
+            follow_redirects=False,
+        )
+        self.note_response(response)
+        return response
+
+    def _parse_login_response(self, response: httpx.Response) -> Mapping[str, Any]:
+        try:
+            payload = parse_response(response, expect="json")
+        except DecodeError as exc:
+            raise AuthenticationError(
+                "login returned a non-JSON response",
+                status_code=response.status_code,
+            ) from exc
+        except (HTTPStatusError, ProtocolError) as exc:
+            raise AuthenticationError(
+                f"login failed: {exc}",
+                status_code=getattr(exc, "status_code", response.status_code),
+                payload=getattr(exc, "payload", None),
+            ) from exc
+        if not isinstance(payload, Mapping) or not payload.get("auth_token"):
+            raise AuthenticationError("login was rejected by the appliance")
+        return payload
+
+    def _build_session(self, payload: Mapping[str, Any], token: str) -> SessionInfo:
+        session_cookie = self._transport.get_cookie("_console_session")
+        if not session_cookie:
+            raise ProtocolError("login succeeded but _console_session cookie is absent")
+        self._csrf = self._transport.get_cookie("csrf_token") or token
+        self._session = SessionInfo(
+            username=cast(str, self._username),
+            admin_id=_as_int(payload.get("admin_id")),
+            product=_as_str(payload.get("product")),
+            version=_as_str(payload.get("version")),
+            auth_token=_as_bool(payload.get("auth_token")),
+            fingerprint=hashlib.sha256(session_cookie.encode()).hexdigest()[:12],
+            raw=redact_mapping(payload),
+        )
+        self._generation += 1
+        return self._session
+
+    def _has_reusable_session(self, force: bool) -> bool:
+        return self._session is not None and not force
+
+    def _credentials_missing(self) -> bool:
+        return not self._username or self._password is None
+
+    def _should_reset_session(self, force: bool) -> bool:
+        return force or self._session is not None
+
+    def login(self, *, force: bool = False) -> SessionInfo:
+        if self._has_reusable_session(force):
+            return self._session  # type: ignore[return-value]
+        if self._credentials_missing():
+            raise AuthenticationError("username and password are required for login")
+        if self._should_reset_session(force):
+            self._reset_session()
+        token = self._login_page_token()
+        response = self._post_login(token)
+        return self._build_session(self._parse_login_response(response), token)
+
+    def _logout_request(self) -> httpx.Response:
+        token = self._csrf or self.ensure_csrf()
+        response = self._transport.request(
+            "POST",
+            self._logout_path,
+            data=encode_params({"csrfmiddlewaretoken": token}),
+            headers=FORM_HEADERS,
+            idempotent=False,
+        )
+        self.note_response(response)
+        return response
+
+    def _logout_result(self, response: httpx.Response) -> bool:
+        try:
+            payload = parse_response(response, expect="auto")
+        except SessionExpiredError:
+            return True
+        return not is_error_payload(payload)
+
+    def logout(self, *, best_effort: bool = True) -> bool:
+        if self._session is None:
+            self._generation += 1
+            self._transport.clear_cookies(("_console_session", "csrf_token"))
+            return True
+        ok = False
+        try:
+            ok = self._logout_result(self._logout_request())
+        except UGOSError:
+            if not best_effort:
+                raise
+        finally:
+            self._generation += 1
+            self._reset_session()
+        return ok
+
+    def note_response(self, response: httpx.Response) -> None:
+        token = self._transport.get_cookie("csrf_token")
+        if token:
+            self._csrf = token
+        # Session state is invalidated by the guarded re-auth path, not here:
+        # a stale response from another thread must not wipe a fresh session.
+
+
+def _extract_csrf(html: str) -> str | None:
+    for pattern in (_CSRF_RE, _CSRF_INPUT_RE, _CSRF_META_RE):
+        match = pattern.search(html)
+        if match:
+            return match.group(1)
+    return None
+
+
+def _as_int(value: Any) -> int | None:
+    try:
+        return int(value) if value is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _as_str(value: Any) -> str | None:
+    return str(value) if value is not None else None
+
+
+def _as_bool(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "on"}
+    return bool(value)