sonicwall-sdk 0.1.0__tar.gz

sonicwall_sdk-0.1.0/.gitignore

@@ -0,0 +1,73 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+ENV/
+env/
+dist/
+build/
+*.egg-info/
+.eggs/
+*.egg
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+.hypothesis/
+
+# Local pnpm tool cache (CI uses PNPM_CACHE_DIR)
+.pnpm-home/
+
+# Project-local uv binary (shell CI; UV_INSTALL_DIR)
+.uv-install/
+
+# Contract captures from local devices (optional tooling)
+packages/python/contract-captures/
+
+# Node / TypeScript
+node_modules/
+packages/typescript/dist/
+packages/typescript/coverage/
+packages/typescript/*.tsbuildinfo
+.turbo/
+.pnpm-store/
+.pnpm-tool/
+.pnpm-home/
+
+# Local contract captures (live device debugging)
+packages/python/contract-captures/
+
+# Go
+packages/go/bin/
+packages/go/vendor/
+.golangci-bin/
+.go-toolchain/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Secrets
+.env
+.env.*
+!.env.example
+*.key
+*.pem
+*.p12
+*.pfx
+secrets/
+
+# Build artifacts
+*.tar.gz
+*.whl
+dist-info/

sonicwall_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: sonicwall-sdk
+Version: 0.1.0
+Summary: Python SDK for the SonicOS REST API
+Project-URL: Homepage, https://gitlab.com/gandiva-tech/sonicwall-sdk
+Project-URL: Documentation, https://gitlab.com/gandiva-tech/sonicwall-sdk/-/tree/main/docs
+Project-URL: Repository, https://gitlab.com/gandiva-tech/sonicwall-sdk
+Project-URL: Bug Tracker, https://gitlab.com/gandiva-tech/sonicwall-sdk/-/issues
+Author-email: Gandiva Tech <engineering@gandiva.tech>
+License: Apache-2.0
+Keywords: api,firewall,sdk,sonicos,sonicwall
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Networking :: Firewalls
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SonicWall SDK for Python
+
+Python client for SonicOS REST API with async-first APIs, sync wrapper, pending
+config transaction helpers, and typed exceptions.
+
+## Install
+
+```bash
+pip install sonicwall-sdk
+# or
+uv add sonicwall-sdk
+```
+
+## Quick start (async)
+
+```python
+import asyncio
+from sonicwall import SonicWallClient
+
+async def main() -> None:
+    async with SonicWallClient(
+        host="192.168.1.1",
+        username="admin",
+        password="secret",
+        verify_ssl=False,
+    ) as client:
+        objs = await client.address_objects.list()
+        print(f"address objects: {len(objs)}")
+
+asyncio.run(main())
+```
+
+## Authentication
+
+On SonicOS 7.x, the SDK performs Digest `auth-int` login handshake on
+`POST /auth`, then sends `Authorization: Bearer <token>` for authenticated API
+calls. This is automatic; no manual auth header or cookie handling is needed.
+
+## Transactions
+
+SonicOS stages writes in pending config. Use `pending()` to auto-commit on
+success and auto-rollback on exceptions:
+
+```python
+async with client.pending():
+    await client.address_objects.create(obj)
+```
+
+## More docs
+
+- Root guide: `README.md`
+- Python guide: `docs/python.md`
+- SonicOS quirks: `docs/sonicwall-quirks.md`

sonicwall_sdk-0.1.0/README.md

@@ -0,0 +1,53 @@
+# SonicWall SDK for Python
+
+Python client for SonicOS REST API with async-first APIs, sync wrapper, pending
+config transaction helpers, and typed exceptions.
+
+## Install
+
+```bash
+pip install sonicwall-sdk
+# or
+uv add sonicwall-sdk
+```
+
+## Quick start (async)
+
+```python
+import asyncio
+from sonicwall import SonicWallClient
+
+async def main() -> None:
+    async with SonicWallClient(
+        host="192.168.1.1",
+        username="admin",
+        password="secret",
+        verify_ssl=False,
+    ) as client:
+        objs = await client.address_objects.list()
+        print(f"address objects: {len(objs)}")
+
+asyncio.run(main())
+```
+
+## Authentication
+
+On SonicOS 7.x, the SDK performs Digest `auth-int` login handshake on
+`POST /auth`, then sends `Authorization: Bearer <token>` for authenticated API
+calls. This is automatic; no manual auth header or cookie handling is needed.
+
+## Transactions
+
+SonicOS stages writes in pending config. Use `pending()` to auto-commit on
+success and auto-rollback on exceptions:
+
+```python
+async with client.pending():
+    await client.address_objects.create(obj)
+```
+
+## More docs
+
+- Root guide: `README.md`
+- Python guide: `docs/python.md`
+- SonicOS quirks: `docs/sonicwall-quirks.md`

sonicwall_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sonicwall-sdk"
+version = "0.1.0"
+description = "Python SDK for the SonicOS REST API"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.10"
+authors = [
+  { name = "Gandiva Tech", email = "engineering@gandiva.tech" },
+]
+keywords = ["sonicwall", "sonicos", "firewall", "sdk", "api"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: System :: Networking :: Firewalls",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27",
+  "pydantic>=2.0",
+  "anyio>=4.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "pytest-cov>=5.0",
+  "respx>=0.21",
+  "ruff>=0.6",
+  "mypy>=1.10",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/gandiva-tech/sonicwall-sdk"
+Documentation = "https://gitlab.com/gandiva-tech/sonicwall-sdk/-/tree/main/docs"
+Repository = "https://gitlab.com/gandiva-tech/sonicwall-sdk"
+"Bug Tracker" = "https://gitlab.com/gandiva-tech/sonicwall-sdk/-/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sonicwall"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "N", "ANN", "RUF"]
+ignore = ["ANN401", "E501", "RUF022", "RUF100", "UP037", "E402"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["ANN", "S"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = ["integration: tests requiring a real SonicWall device"]
+
+[tool.coverage.run]
+source = ["src/sonicwall"]
+omit = ["*/tests/*"]
+
+[tool.coverage.report]
+show_missing = true

sonicwall_sdk-0.1.0/src/sonicwall/__init__.py

@@ -0,0 +1,71 @@
+"""SonicWall SDK — Python client for the SonicOS REST API."""
+
+from ._client import SonicWallClient, SonicWallClientSync
+from ._exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    CommitError,
+    ConflictError,
+    ConnectionError,
+    NotFoundError,
+    RateLimitError,
+    RollbackError,
+    SessionExpiredError,
+    SonicWallError,
+    SonicWallHTTPError,
+)
+from .models import (
+    AccessRule,
+    AccessRuleAction,
+    AddressObject,
+    AddressObjectType,
+    DhcpLease,
+    IcmpSpec,
+    Interface,
+    IPAssignment,
+    NatPolicy,
+    PortRange,
+    RuleAddress,
+    RulePriority,
+    RuleService,
+    ServiceObject,
+    ServiceProtocol,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Version
+    "__version__",
+    # Clients
+    "SonicWallClient",
+    "SonicWallClientSync",
+    # Exceptions
+    "SonicWallError",
+    "SonicWallHTTPError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "SessionExpiredError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "CommitError",
+    "RollbackError",
+    "ConnectionError",
+    # Models
+    "AddressObject",
+    "AddressObjectType",
+    "AccessRule",
+    "AccessRuleAction",
+    "RuleAddress",
+    "RulePriority",
+    "RuleService",
+    "Interface",
+    "IPAssignment",
+    "NatPolicy",
+    "ServiceObject",
+    "ServiceProtocol",
+    "PortRange",
+    "IcmpSpec",
+    "DhcpLease",
+]

sonicwall_sdk-0.1.0/src/sonicwall/_auth.py

@@ -0,0 +1,316 @@
+"""Session authentication manager for the SonicOS REST API."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import logging
+import os
+import re
+from urllib.parse import urlparse
+
+import httpx
+
+from ._exceptions import AuthenticationError, SessionExpiredError
+
+logger = logging.getLogger(__name__)
+
+# SonicOS status code indicating the session has expired
+_SESSION_EXPIRED_CODE = 1085
+
+
+# ---------------------------------------------------------------------------
+# Digest auth-int implementation
+# httpx supports qop=auth but NOT qop=auth-int (body-included integrity).
+# SonicWall TZ270 (SonicOS 7.x) requires auth-int, so we implement it here.
+# ---------------------------------------------------------------------------
+
+
+def _parse_digest_challenge(www_auth: str) -> dict[str, str]:
+    """Parse a single WWW-Authenticate: Digest ... header into a dict."""
+    # Strip leading 'Digest ' token
+    body = re.sub(r"^[Dd]igest\s+", "", www_auth.strip())
+    params: dict[str, str] = {}
+    for m in re.finditer(r'(\w+)=(?:"([^"]*?)"|([^,\s]+))', body):
+        params[m.group(1)] = m.group(2) if m.group(2) is not None else m.group(3)
+    return params
+
+
+def _pick_challenge(response: httpx.Response) -> dict[str, str] | None:
+    """Return the best Digest challenge from WWW-Authenticate headers.
+
+    Prefers SHA-256 over SHA-256-sess over MD5. Requires qop to include
+    auth-int (SonicOS requirement).
+    """
+    challenges: list[dict[str, str]] = []
+    for value in response.headers.get_list("www-authenticate"):
+        if value.lower().startswith("digest"):
+            c = _parse_digest_challenge(value)
+            if "auth-int" in c.get("qop", ""):
+                challenges.append(c)
+
+    if not challenges:
+        return None
+
+    def _priority(c: dict[str, str]) -> int:
+        alg = c.get("algorithm", "MD5").upper()
+        if alg == "SHA-256":
+            return 0
+        if alg == "SHA-256-SESS":
+            return 1
+        return 2
+
+    return min(challenges, key=_priority)
+
+
+def _build_digest_auth_header(
+    method: str,
+    url: str,
+    body: bytes,
+    username: str,
+    password: str,
+    challenge: dict[str, str],
+) -> str:
+    """Build an Authorization: Digest header for qop=auth-int."""
+    algorithm = challenge.get("algorithm", "MD5").upper()
+    realm = challenge["realm"]
+    nonce = challenge["nonce"]
+    opaque = challenge.get("opaque", "")
+
+    # URI is path + query only
+    parsed = urlparse(url)
+    uri = parsed.path + (f"?{parsed.query}" if parsed.query else "")
+
+    # Choose hash function
+    if "SHA-256" in algorithm:
+
+        def h(s: str) -> str:
+            return hashlib.sha256(s.encode()).hexdigest()
+
+        def hb(b: bytes) -> str:
+            return hashlib.sha256(b).hexdigest()
+    else:
+
+        def h(s: str) -> str:
+            return hashlib.md5(s.encode()).hexdigest()  # noqa: S324
+
+        def hb(b: bytes) -> str:
+            return hashlib.md5(b).hexdigest()  # noqa: S324
+
+    cnonce = os.urandom(8).hex()
+    nc = "00000001"
+
+    # HA1
+    ha1 = h(f"{username}:{realm}:{password}")
+    if "SESS" in algorithm:
+        ha1 = h(f"{ha1}:{nonce}:{cnonce}")
+
+    # HA2 — auth-int includes hash of request body
+    ha2 = h(f"{method}:{uri}:{hb(body)}")
+
+    # Final response
+    digest_response = h(f"{ha1}:{nonce}:{nc}:{cnonce}:auth-int:{ha2}")
+
+    header = (
+        f'Digest username="{username}", realm="{realm}", '
+        f'nonce="{nonce}", uri="{uri}", '
+        f"algorithm={algorithm}, "
+        f'qop=auth-int, nc={nc}, cnonce="{cnonce}", '
+        f'response="{digest_response}"'
+    )
+    if opaque:
+        header += f', opaque="{opaque}"'
+    return header
+
+
+# ---------------------------------------------------------------------------
+# Cookie / session helpers
+# ---------------------------------------------------------------------------
+
+
+def _extract_bearer_token(response: httpx.Response) -> str | None:
+    """Extract the bearer_token from a successful SonicOS /auth response body."""
+    try:
+        body = response.json()
+        info_list = body.get("status", {}).get("info", [])
+        for item in info_list:
+            token = item.get("bearer_token")
+            if token:
+                return str(token)
+    except Exception:  # noqa: BLE001
+        pass
+    return None
+
+
+def _is_session_expired(response: httpx.Response) -> bool:
+    """Return True if the response body indicates SonicOS session expiry."""
+    try:
+        body = response.json()
+        info_list = body.get("status", {}).get("info", [])
+        for item in info_list:
+            if item.get("code") == _SESSION_EXPIRED_CODE:
+                return True
+    except Exception:  # noqa: BLE001
+        pass
+    return False
+
+
+# ---------------------------------------------------------------------------
+# AuthManager
+# ---------------------------------------------------------------------------
+
+
+class AuthManager:
+    """Manages SonicOS session authentication.
+
+    SonicOS 7.x requires HTTP Digest auth with qop=auth-int (body integrity).
+    httpx does not support auth-int, so we implement the handshake manually:
+      1. POST /auth without credentials → 401 with Digest challenge
+      2. Compute Authorization header with auth-int
+      3. POST /auth again with the computed header → 200 + JWT bearer_token in body
+    Subsequent requests use Authorization: Bearer <token>.
+    """
+
+    def __init__(self, base_url: str, username: str, password: str) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._username = username
+        self._password = password
+        self._bearer_token: str | None = None
+        self._lock = asyncio.Lock()
+        self._authenticated = False
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._authenticated and self._bearer_token is not None
+
+    async def authenticate(self, client: httpx.AsyncClient) -> None:
+        """Perform Digest auth-int handshake against POST /auth."""
+        auth_url = f"{self._base_url}/auth"
+        body = b"{}"
+        headers = {"Content-Type": "application/json", "Accept": "application/json"}
+
+        logger.debug("Authenticating to %s (step 1 — get challenge)", auth_url)
+
+        # Step 1: unauthenticated request to get the Digest challenge
+        challenge_response = await client.post(auth_url, headers=headers, content=body)
+
+        if challenge_response.status_code != 401:
+            raise AuthenticationError(
+                status_code=challenge_response.status_code,
+                message=f"Expected 401 Digest challenge, got {challenge_response.status_code}",
+                response_body=self._safe_json(challenge_response),
+            )
+
+        challenge = _pick_challenge(challenge_response)
+        if not challenge:
+            raise AuthenticationError(
+                status_code=401,
+                message="Server returned 401 but no usable Digest auth-int challenge",
+                response_body=self._safe_json(challenge_response),
+            )
+
+        logger.debug(
+            "Got Digest challenge: algorithm=%s realm=%s",
+            challenge.get("algorithm"),
+            challenge.get("realm"),
+        )
+
+        # Step 2: authenticated request with computed Digest header
+        auth_header = _build_digest_auth_header(
+            method="POST",
+            url=auth_url,
+            body=body,
+            username=self._username,
+            password=self._password,
+            challenge=challenge,
+        )
+        authed_headers = {**headers, "Authorization": auth_header}
+
+        logger.debug("Authenticating to %s (step 2 — send credentials)", auth_url)
+        response = await client.post(auth_url, headers=authed_headers, content=body)
+
+        if response.status_code == 401:
+            raise AuthenticationError(
+                status_code=401,
+                message="Authentication failed: invalid username or password",
+                response_body=self._safe_json(response),
+            )
+
+        if not response.is_success:
+            raise AuthenticationError(
+                status_code=response.status_code,
+                message=f"Authentication failed with status {response.status_code}",
+                response_body=self._safe_json(response),
+            )
+
+        # SonicOS 7.x returns a JWT bearer_token in the response body (not a cookie)
+        token = _extract_bearer_token(response)
+        if not token:
+            raise AuthenticationError(
+                status_code=response.status_code,
+                message="Authentication succeeded but no bearer_token in response body",
+                response_body=self._safe_json(response),
+            )
+
+        self._bearer_token = token
+        self._authenticated = True
+        logger.debug("Authenticated; bearer token acquired")
+
+    async def ensure_authenticated(self, client: httpx.AsyncClient) -> None:
+        """Ensure a valid session exists, re-authenticating if necessary."""
+        if self.is_authenticated:
+            return
+        async with self._lock:
+            if not self.is_authenticated:
+                await self.authenticate(client)
+
+    async def reauthenticate(self, client: httpx.AsyncClient) -> None:
+        """Force re-authentication, discarding the existing token."""
+        async with self._lock:
+            self._authenticated = False
+            self._bearer_token = None
+            await self.authenticate(client)
+
+    async def logout(self, client: httpx.AsyncClient) -> None:
+        """Destroy the current session via DELETE /auth."""
+        if not self.is_authenticated:
+            return
+        auth_url = f"{self._base_url}/auth"
+        try:
+            await client.delete(
+                auth_url,
+                headers={**self._auth_headers(), "Accept": "application/json"},
+            )
+            logger.debug("Logged out successfully")
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("Logout request failed (ignoring): %s", exc)
+        finally:
+            self._bearer_token = None
+            self._authenticated = False
+
+    def _auth_headers(self) -> dict[str, str]:
+        if self._bearer_token:
+            return {"Authorization": f"Bearer {self._bearer_token}"}
+        return {}
+
+    def check_response_for_session_expiry(self, response: httpx.Response) -> bool:
+        if response.status_code == 401 and _is_session_expired(response):
+            return True
+        if response.is_success and _is_session_expired(response):
+            return True
+        return False
+
+    def raise_if_session_expired(self, response: httpx.Response) -> None:
+        if self.check_response_for_session_expiry(response):
+            raise SessionExpiredError(
+                status_code=response.status_code,
+                message="SonicOS session expired; re-authentication required",
+                response_body=self._safe_json(response),
+            )
+
+    @staticmethod
+    def _safe_json(response: httpx.Response) -> dict:  # type: ignore[type-arg]
+        try:
+            return response.json()  # type: ignore[no-any-return]
+        except Exception:  # noqa: BLE001
+            return {}