netsight-sdk 1.0.0__tar.gz

netsight_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NetSight contributors
+
+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.

netsight_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: netsight-sdk
+Version: 1.0.0
+Summary: Read-only multi-vendor network device query SDK (core library)
+Author: NetSight contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/magicboxlab-ai/netsight-sdk
+Project-URL: Repository, https://github.com/magicboxlab-ai/netsight-sdk
+Project-URL: Changelog, https://github.com/magicboxlab-ai/netsight-sdk/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/magicboxlab-ai/netsight-sdk/issues
+Project-URL: Documentation, https://github.com/magicboxlab-ai/netsight-sdk/blob/main/docs/guides/user-guide.md
+Keywords: network,automation,sdk,palo-alto,panos,read-only,multi-vendor
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: xmltodict>=0.13.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: jmespath>=1.0.1
+Requires-Dist: pip-audit>=2.7.0
+Requires-Dist: packaging>=23.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: httpx>=0.24.0; extra == "dev"
+Requires-Dist: mypy>=1.5; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=4.0; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: types-tabulate; extra == "dev"
+Requires-Dist: types-jmespath; extra == "dev"
+Requires-Dist: watchdog>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# NetSight
+
+**NetSight** is a read-only, multi-vendor network device query SDK written in Python 3.14. It connects to devices over vendor-native APIs (currently PAN-OS XML; more vendors planned), enforces a deny-all command allowlist, and returns structured data parsed from declarative YAML parser specs.
+
+## For users
+
+See the [**User Guide**](docs/guides/user-guide.md) for installation, configuration, and day-to-day SDK usage — connecting to a device, running an operation, handling results, writing a template workflow.
+
+```python
+from netsight import NetSight
+
+ns = NetSight(config="config/devices.yaml")
+device = ns.device("fw-01")
+info = device.show_system_info()
+routes = device.show_routing_table()
+```
+
+### Installing the core SDK
+
+```sh
+# Minimal SDK install — just the device-query core
+pip install netsight-sdk
+
+# With the dev MCP server (for Claude Code contributors)
+pip install 'netsight-sdk[dev]'
+```
+
+Or, to track the development branch directly:
+
+```sh
+pip install git+https://github.com/magicboxlab-ai/netsight-sdk.git
+```
+
+### First-time setup
+
+After installing the core SDK, run `netsight init` to create your device
+configuration file:
+
+```sh
+# Create ~/.config/netsight/devices.yaml with a template
+netsight init
+
+# Edit the file to add your devices, then verify
+netsight doctor
+```
+
+The config file search order is: `$NETSIGHT_CONFIG_DIR` → `./config/`
+(cwd, for project-local dev workflows) → `$XDG_CONFIG_HOME/netsight/`
+→ `~/.config/netsight/`.
+
+### Installing vendor packs
+
+The core SDK is vendor-agnostic. Vendor support ships as separate pack packages installed alongside the core. Use the `netsight pack` CLI to discover and install packs:
+
+```sh
+# List packs available in the bundled catalog
+netsight pack list --available
+
+# Install a pack
+netsight pack install paloalto-firewall-xml
+
+# Verify everything loaded correctly
+netsight doctor
+```
+
+Packs can also be installed directly from their source repositories:
+
+```sh
+pip install git+https://github.com/magicboxlab-ai/netsight-packs-paloalto.git#subdirectory=packs/paloalto-firewall-xml
+```
+
+After installation, the pack is auto-discovered at startup via the `netsight.packs` entry-point group — no config change required.
+
+See [**User Guide → Vendor packs**](docs/guides/user-guide.md#vendor-packs) for the full install and configuration flow.
+
+## For contributors
+
+NetSight ships a purpose-built MCP server (`netsight-dev`) that exposes the codebase to Claude Code as structured resources and validation tools. The bootstrap flow for a new clone is documented end-to-end in the developer guide:
+
+See [**Developer Guide → Getting Started for Development**](docs/guides/developer-guide.md#getting-started-for-development).
+
+**TL;DR:**
+
+```sh
+git clone <repo-url> netsight
+cd netsight
+python3.14 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+netsight init --local # creates ./config/devices.yaml from the template
+netsight doctor       # verifies the dev env end-to-end
+claude                # approve the netsight-dev MCP server when prompted
+```
+
+The rest of the developer guide covers adding vendor packs, writing parser specs, custom types and transforms, registry wiring, self-documentation conventions, testing, and the release workflow.
+
+## Project layout at a glance
+
+- `netsight/` — SDK source (pack registry, parsers, config management, security module, dev MCP server).
+- `UNITTEST/` — pytest test suite (not `tests/`).
+- `TOOLS/` — shell utilities (`full_test_cycle.sh`, `security_check.sh`).
+- `docs/guides/` — user guide and developer guide.

netsight_sdk-1.0.0/README.md

@@ -0,0 +1,102 @@
+# NetSight
+
+**NetSight** is a read-only, multi-vendor network device query SDK written in Python 3.14. It connects to devices over vendor-native APIs (currently PAN-OS XML; more vendors planned), enforces a deny-all command allowlist, and returns structured data parsed from declarative YAML parser specs.
+
+## For users
+
+See the [**User Guide**](docs/guides/user-guide.md) for installation, configuration, and day-to-day SDK usage — connecting to a device, running an operation, handling results, writing a template workflow.
+
+```python
+from netsight import NetSight
+
+ns = NetSight(config="config/devices.yaml")
+device = ns.device("fw-01")
+info = device.show_system_info()
+routes = device.show_routing_table()
+```
+
+### Installing the core SDK
+
+```sh
+# Minimal SDK install — just the device-query core
+pip install netsight-sdk
+
+# With the dev MCP server (for Claude Code contributors)
+pip install 'netsight-sdk[dev]'
+```
+
+Or, to track the development branch directly:
+
+```sh
+pip install git+https://github.com/magicboxlab-ai/netsight-sdk.git
+```
+
+### First-time setup
+
+After installing the core SDK, run `netsight init` to create your device
+configuration file:
+
+```sh
+# Create ~/.config/netsight/devices.yaml with a template
+netsight init
+
+# Edit the file to add your devices, then verify
+netsight doctor
+```
+
+The config file search order is: `$NETSIGHT_CONFIG_DIR` → `./config/`
+(cwd, for project-local dev workflows) → `$XDG_CONFIG_HOME/netsight/`
+→ `~/.config/netsight/`.
+
+### Installing vendor packs
+
+The core SDK is vendor-agnostic. Vendor support ships as separate pack packages installed alongside the core. Use the `netsight pack` CLI to discover and install packs:
+
+```sh
+# List packs available in the bundled catalog
+netsight pack list --available
+
+# Install a pack
+netsight pack install paloalto-firewall-xml
+
+# Verify everything loaded correctly
+netsight doctor
+```
+
+Packs can also be installed directly from their source repositories:
+
+```sh
+pip install git+https://github.com/magicboxlab-ai/netsight-packs-paloalto.git#subdirectory=packs/paloalto-firewall-xml
+```
+
+After installation, the pack is auto-discovered at startup via the `netsight.packs` entry-point group — no config change required.
+
+See [**User Guide → Vendor packs**](docs/guides/user-guide.md#vendor-packs) for the full install and configuration flow.
+
+## For contributors
+
+NetSight ships a purpose-built MCP server (`netsight-dev`) that exposes the codebase to Claude Code as structured resources and validation tools. The bootstrap flow for a new clone is documented end-to-end in the developer guide:
+
+See [**Developer Guide → Getting Started for Development**](docs/guides/developer-guide.md#getting-started-for-development).
+
+**TL;DR:**
+
+```sh
+git clone <repo-url> netsight
+cd netsight
+python3.14 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+netsight init --local # creates ./config/devices.yaml from the template
+netsight doctor       # verifies the dev env end-to-end
+claude                # approve the netsight-dev MCP server when prompted
+```
+
+The rest of the developer guide covers adding vendor packs, writing parser specs, custom types and transforms, registry wiring, self-documentation conventions, testing, and the release workflow.
+
+## Project layout at a glance
+
+- `netsight/` — SDK source (pack registry, parsers, config management, security module, dev MCP server).
+- `UNITTEST/` — pytest test suite (not `tests/`).
+- `TOOLS/` — shell utilities (`full_test_cycle.sh`, `security_check.sh`).
+- `docs/guides/` — user guide and developer guide.

netsight_sdk-1.0.0/netsight/__init__.py

@@ -0,0 +1,75 @@
+"""NetSight — Read-only multi-vendor network device query SDK.
+
+The importable Python package is ``netsight`` (unchanged). The PyPI
+distribution that ships this package is ``netsight-sdk``. Other
+distributions — ``netsight-ops`` (runtime service platform) and
+vendor packs such as ``netsight-pack-paloalto-firewall-xml`` —
+depend on this core via standard pip dependencies.
+
+The ``__version__`` string below is read from the installed
+distribution metadata at import time, so it always matches what
+``pip show netsight-sdk`` reports. A source-tree import without an
+install (e.g. during bootstrap of a fresh checkout) falls back to
+the compile-time default declared in ``pyproject.toml``.
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__: str = _pkg_version("netsight-sdk")
+except PackageNotFoundError:  # pragma: no cover — source tree without install
+    __version__ = "1.0.0"
+
+from netsight.config import DeviceConfig
+from netsight.data.models import DiffResult, QueryResult, Snapshot
+from netsight.exceptions import (
+    AuthenticationError,
+    CommandDeniedError,
+    ConfigValidationError,
+    DeviceConnectionError,
+    NetSightError,
+    PluginNotFoundError,
+    RateLimitError,
+    ResponseSizeError,
+)
+from netsight.sdk.client import NetSight
+
+
+def bootstrap() -> None:
+    """Discover and register every installed NetSight pack.
+
+    Idempotent public entry point for pack discovery. Call this from any
+    embedding that does not go through :class:`~netsight.sdk.local.LocalBackend`,
+    the dev MCP server, or the ``netsight`` CLI — typically a custom
+    script that imports :class:`NetSight` and wants installed packs to be
+    usable before the first device query.
+
+    The underlying :meth:`netsight.packs.registry.PackRegistry.ensure_loaded`
+    uses double-checked locking and the ``_loaded`` flag to guarantee that
+    entry-point discovery runs exactly once per process, so calling
+    ``bootstrap()`` multiple times (from multiple entry points) is cheap
+    and safe. Per-pack registration errors are absorbed and surfaced via
+    :meth:`PackRegistry.load_errors` rather than raised.
+    """
+    from netsight.packs import pack_registry
+
+    pack_registry.ensure_loaded()
+
+
+__all__ = [
+    "__version__",
+    "NetSight",
+    "DeviceConfig",
+    "QueryResult",
+    "Snapshot",
+    "DiffResult",
+    "AuthenticationError",
+    "CommandDeniedError",
+    "ConfigValidationError",
+    "DeviceConnectionError",
+    "NetSightError",
+    "PluginNotFoundError",
+    "RateLimitError",
+    "ResponseSizeError",
+    "bootstrap",
+]

netsight_sdk-1.0.0/netsight/auth.py

@@ -0,0 +1,226 @@
+"""Authentication strategy and token-caching manager for NetSight.
+
+Design
+------
+``AuthStrategy`` is an ABC that vendor-specific adapters implement — they
+handle the actual network call to obtain or revoke a session token.
+
+``AuthManager`` owns a per-host token cache and enforces TTL-based expiry.
+It deliberately never exposes raw token values in ``repr`` or log output.
+
+Usage example::
+
+    class MyStrategy(AuthStrategy):
+        def acquire_token(self, host, username, password):
+            ...  # POST /login, return token string
+        def revoke_token(self, host, token):
+            ...  # POST /logout
+
+    manager = AuthManager(MyStrategy(), token_ttl_seconds=1800)
+    token = manager.get_token("192.168.1.1", "admin", "hunter2")
+    manager.close()
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from abc import ABC, abstractmethod
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Abstract strategy
+# ---------------------------------------------------------------------------
+
+
+class AuthStrategy(ABC):
+    """Contract that every authentication back-end must satisfy."""
+
+    @abstractmethod
+    def acquire_token(self, host: str, username: str, password: str) -> str:
+        """Obtain a new session token from *host*.
+
+        Parameters
+        ----------
+        host:
+            Hostname or IP address of the target device.
+        username:
+            Account name to authenticate with.
+        password:
+            Credential.  Implementations must not log this value.
+
+        Returns
+        -------
+        str
+            An opaque token string suitable for subsequent API calls.
+
+        Raises
+        ------
+        netsight.exceptions.AuthenticationError
+            If the device rejects the credentials.
+        Any network/transport exception the caller may choose to handle.
+        """
+
+    @abstractmethod
+    def revoke_token(self, host: str, token: str) -> None:
+        """Invalidate *token* on *host*.
+
+        Implementations should be best-effort; ``AuthManager`` handles
+        failures by logging a warning rather than propagating exceptions.
+
+        Parameters
+        ----------
+        host:
+            Same host that issued the token.
+        token:
+            The token to invalidate.
+        """
+
+
+# ---------------------------------------------------------------------------
+# Internal cached-token container
+# ---------------------------------------------------------------------------
+
+
+class _CachedToken:
+    """Lightweight container for a token and its acquisition timestamp.
+
+    Uses ``__slots__`` to minimise per-instance memory overhead — there may
+    be hundreds of these alive at once in a large environment.
+    """
+
+    __slots__ = ("token", "acquired_at")
+
+    def __init__(self, token: str) -> None:
+        self.token: str = token
+        self.acquired_at: float = time.monotonic()
+
+    def is_expired(self, ttl: float) -> bool:
+        """Return ``True`` if the token is older than *ttl* seconds."""
+        return (time.monotonic() - self.acquired_at) >= ttl
+
+
+# ---------------------------------------------------------------------------
+# AuthManager
+# ---------------------------------------------------------------------------
+
+
+class AuthManager:
+    """Caching authentication manager.
+
+    Maintains one valid token per host; transparently reacquires when the
+    TTL expires or after an explicit ``invalidate`` call.
+
+    Parameters
+    ----------
+    strategy:
+        The ``AuthStrategy`` instance used to acquire/revoke tokens.
+    token_ttl_seconds:
+        How long (in seconds) a cached token is considered valid before a
+        new one is acquired.  Defaults to 3600 (one hour).
+    """
+
+    def __init__(
+        self, strategy: AuthStrategy, token_ttl_seconds: float = 3600
+    ) -> None:
+        self._strategy = strategy
+        self._token_ttl: float = token_ttl_seconds
+        # Maps host -> _CachedToken
+        self._cache: dict[str, _CachedToken] = {}
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get_token(self, host: str, username: str, password: str) -> str:
+        """Return a valid token for *host*, acquiring one if necessary.
+
+        The token is taken from the in-memory cache when it exists and has
+        not exceeded the TTL.  Otherwise a new token is acquired from the
+        strategy.
+
+        Parameters
+        ----------
+        host:
+            Target device hostname or IP.
+        username:
+            Credential — passed through to the strategy unchanged.
+        password:
+            Credential — never logged.
+
+        Returns
+        -------
+        str
+            A non-empty token string.
+        """
+        cached = self._cache.get(host)
+        if cached is not None and not cached.is_expired(self._token_ttl):
+            logger.debug("Using cached token for host=%s", host)
+            return cached.token
+
+        logger.info("Acquiring new token for host=%s", host)
+        token = self._strategy.acquire_token(host, username, password)
+        self._cache[host] = _CachedToken(token)
+        return token
+
+    def invalidate(self, host: str) -> None:
+        """Remove the cached token for *host* and attempt to revoke it.
+
+        If the strategy raises during revocation the exception is caught
+        and a ``WARNING`` is emitted; the cache entry is removed regardless.
+
+        Parameters
+        ----------
+        host:
+            The host whose token should be invalidated.
+        """
+        cached = self._cache.pop(host, None)
+        if cached is None:
+            return
+
+        try:
+            self._strategy.revoke_token(host, cached.token)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(
+                "Failed to revoke token for host=%s: %s", host, exc
+            )
+
+    def has_token(self, host: str) -> bool:
+        """Return ``True`` if a non-expired token is cached for *host*.
+
+        Parameters
+        ----------
+        host:
+            The host to query.
+        """
+        cached = self._cache.get(host)
+        if cached is None:
+            return False
+        return not cached.is_expired(self._token_ttl)
+
+    def close(self) -> None:
+        """Revoke all cached tokens and clear the cache.
+
+        Revocation failures are logged at ``WARNING`` and do not prevent the
+        remaining tokens from being processed.
+        """
+        # Snapshot keys so we can safely mutate the dict during iteration
+        hosts = list(self._cache.keys())
+        for host in hosts:
+            self.invalidate(host)
+
+    # ------------------------------------------------------------------
+    # Dunder helpers
+    # ------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        """Return a safe representation that never includes token values."""
+        hosts = list(self._cache.keys())
+        strategy_name = type(self._strategy).__name__
+        return (
+            f"AuthManager(strategy={strategy_name}, "
+            f"hosts={hosts!r}, "
+            f"ttl={self._token_ttl}s)"
+        )