python-gvm 26.2.0__tar.gz → 26.3.0__tar.gz

{python_gvm-26.2.0 → python_gvm-26.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: python-gvm
-Version: 26.2.0
+Version: 26.3.0
 Summary: Library to communicate with remote servers over GMP or OSP
 License: GPL-3.0-or-later
 Author: Greenbone AG
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: httpx[http2] (>=0.28.1,<0.29.0)
 Requires-Dist: lxml (>=4.5.0)
 Requires-Dist: paramiko (>=2.7.1)
 Project-URL: Documentation, https://greenbone.github.io/python-gvm/

{python_gvm-26.2.0 → python_gvm-26.3.0}/gvm/__version__.py

@@ -2,4 +2,4 @@
 
 # THIS IS AN AUTOGENERATED FILE. DO NOT TOUCH!
 
-__version__ = "26.2.0"
+__version__ = "26.3.0"

{python_gvm-26.2.0 → python_gvm-26.3.0}/gvm/protocols/gmp/__init__.py

@@ -9,13 +9,14 @@ In most circumstances you will want to use the :class:`GMP` class which
 dynamically selects the supported GMP protocol of the remote manager daemon.
 
 If you need to use a specific GMP version, you can use the :class:`GMPv224`,
-:class:`GMPv225`, :class:`GMPv226` or :class:`GMPv227` classes.
+:class:`GMPv225`, :class:`GMPv226`, :class:`GMPv227` or :class:`GMPv228` classes.
 
 * :class:`GMP` - Dynamically select supported GMP protocol of the remote manager daemon.
 * :class:`GMPv224` - GMP version 22.4
 * :class:`GMPv225` - GMP version 22.5
 * :class:`GMPv226` - GMP version 22.6
 * :class:`GMPv227` - GMP version 22.7
+* :class:`GMPv228` - GMP version 22.8
 """
 
 from ._gmp import GMP
@@ -23,6 +24,7 @@ from ._gmp224 import GMPv224
 from ._gmp225 import GMPv225
 from ._gmp226 import GMPv226
 from ._gmp227 import GMPv227
+from ._gmp228 import GMPv228
 
 Gmp = GMP  # for backwards compatibility
 
@@ -33,4 +35,5 @@ __all__ = (
     "GMPv225",
     "GMPv226",
     "GMPv227",
+    "GMPv228",
 )

{python_gvm-26.2.0 → python_gvm-26.3.0}/gvm/protocols/gmp/_gmp.py

@@ -16,10 +16,13 @@ from ._gmp224 import GMPv224
 from ._gmp225 import GMPv225
 from ._gmp226 import GMPv226
 from ._gmp227 import GMPv227
+from ._gmp228 import GMPv228
 from .requests import Version
 
-SUPPORTED_GMP_VERSIONS = Union[GMPv224[T], GMPv225[T], GMPv226[T], GMPv227[T]]
-_SUPPORTED_GMP_VERSION_STRINGS = ["22.4", "22.5", "22.6", "22.7"]
+SUPPORTED_GMP_VERSIONS = Union[
+    GMPv224[T], GMPv225[T], GMPv226[T], GMPv227[T], GMPv228[T]
+]
+_SUPPORTED_GMP_VERSION_STRINGS = ["22.4", "22.5", "22.6", "22.7", "22.8"]
 
 
 class GMP(GvmProtocol[T]):
@@ -38,7 +41,8 @@ class GMP(GvmProtocol[T]):
                 # gvm.protocols.gmp.GMPv224,
                 # gvm.protocols.gmp.GMPv225,
                 # gvm.protocols.gmp.GMPv226,
-                # or gvm.protocols.gmp.GMPv227
+                # gvm.protocols.gmp.GMPv227,
+                # or gvm.protocols.gmp.GMPv228
                 # depending on the supported GMP version of the remote manager daemon
                 resp = gmp.get_tasks()
     """
@@ -91,9 +95,13 @@ class GMP(GvmProtocol[T]):
             gmp_class = GMPv224
         elif major_version == 22 and minor_version == 5:
             gmp_class = GMPv225
-        elif major_version == 22 and minor_version >= 6:
+        elif major_version == 22 and minor_version == 6:
             gmp_class = GMPv226
-            if minor_version > 6:
+        elif major_version == 22 and minor_version == 7:
+            gmp_class = GMPv227
+        elif major_version == 22 and minor_version >= 8:
+            gmp_class = GMPv228
+            if minor_version > 8:
                 warnings.warn(
                     "Remote manager daemon uses a newer GMP version than "
                     f"supported by python-gvm {__version__}. Please update to "

python_gvm-26.3.0/gvm/protocols/gmp/_gmp228.py

@@ -0,0 +1,76 @@
+#  SPDX-FileCopyrightText: 2025 Greenbone AG
+#
+#  SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Optional
+
+from gvm.protocols.gmp.requests import EntityID
+
+from .._protocol import T
+from ._gmp227 import GMPv227
+from .requests.v228 import AgentInstallers
+
+
+class GMPv228(GMPv227[T]):
+    """
+    A class implementing the Greenbone Management Protocol (GMP) version 22.8
+
+    Example:
+
+        .. code-block:: python
+
+            from gvm.protocols.gmp import GMPv228 as GMP
+
+            with GMP(connection) as gmp:
+                resp = gmp.get_tasks()
+    """
+
+    @staticmethod
+    def get_protocol_version() -> tuple[int, int]:
+        return (22, 8)
+
+    def get_agent_installers(
+        self,
+        *,
+        filter_string: Optional[str] = None,
+        filter_id: Optional[EntityID] = None,
+        trash: Optional[bool] = None,
+        details: Optional[bool] = None,
+    ) -> T:
+        """Request a list of agent installers
+
+        Args:
+            filter_string: Filter term to use for the query
+            filter_id: UUID of an existing filter to use for the query
+            trash: Whether to get the trashcan agent installers instead
+            details: Whether to include extra details like tasks using this
+                scanner
+        """
+        return self._send_request_and_transform_response(
+            AgentInstallers.get_agent_installers(
+                filter_string=filter_string,
+                filter_id=filter_id,
+                trash=trash,
+                details=details,
+            )
+        )
+
+    def get_agent_installer(self, agent_installer_id: EntityID) -> T:
+        """Request a single agent installer
+
+        Args:
+            agent_installer_id: UUID of an existing agent installer
+        """
+        return self._send_request_and_transform_response(
+            AgentInstallers.get_agent_installer(agent_installer_id)
+        )
+
+    def get_agent_installer_file(self, agent_installer_id: EntityID) -> T:
+        """Request a single agent installer file
+
+        Args:
+            agent_installer_id: UUID of an existing agent installer
+        """
+        return self._send_request_and_transform_response(
+            AgentInstallers.get_agent_installer_file(agent_installer_id)
+        )

python_gvm-26.3.0/gvm/protocols/gmp/requests/v228/__init__.py

@@ -0,0 +1,150 @@
+#  SPDX-FileCopyrightText: 2025 Greenbone AG
+#
+#  SPDX-License-Identifier: GPL-3.0-or-later
+
+from gvm.protocols.gmp.requests.v228._agent_installers import AgentInstallers
+
+from .._entity_id import EntityID
+from .._version import Version
+from ..v227 import (
+    Aggregates,
+    AggregateStatistic,
+    AlertCondition,
+    AlertEvent,
+    AlertMethod,
+    Alerts,
+    AliveTest,
+    AuditReports,
+    Audits,
+    Authentication,
+    CertBundAdvisories,
+    Cpes,
+    CredentialFormat,
+    Credentials,
+    CredentialType,
+    Cves,
+    DfnCertAdvisories,
+    EntityType,
+    Feed,
+    FeedType,
+    Filters,
+    FilterType,
+    Groups,
+    Help,
+    HelpFormat,
+    Hosts,
+    HostsOrdering,
+    InfoType,
+    Notes,
+    Nvts,
+    OperatingSystems,
+    Overrides,
+    Permissions,
+    PermissionSubjectType,
+    Policies,
+    PortLists,
+    PortRangeType,
+    ReportConfigParameter,
+    ReportConfigs,
+    ReportFormats,
+    ReportFormatType,
+    Reports,
+    ResourceNames,
+    ResourceType,
+    Results,
+    Roles,
+    ScanConfigs,
+    Scanners,
+    ScannerType,
+    Schedules,
+    SecInfo,
+    Severity,
+    SnmpAuthAlgorithm,
+    SnmpPrivacyAlgorithm,
+    SortOrder,
+    SystemReports,
+    Tags,
+    Targets,
+    Tasks,
+    Tickets,
+    TicketStatus,
+    TLSCertificates,
+    TrashCan,
+    UserAuthType,
+    Users,
+    UserSettings,
+    Vulnerabilities,
+)
+
+__all__ = (
+    "AgentInstallers",
+    "Aggregates",
+    "AggregateStatistic",
+    "Alerts",
+    "AlertCondition",
+    "AlertEvent",
+    "AlertMethod",
+    "AliveTest",
+    "AuditReports",
+    "Audits",
+    "Authentication",
+    "CertBundAdvisories",
+    "Cpes",
+    "Credentials",
+    "CredentialFormat",
+    "CredentialType",
+    "Cves",
+    "DfnCertAdvisories",
+    "EntityID",
+    "EntityType",
+    "Feed",
+    "FeedType",
+    "Filters",
+    "FilterType",
+    "Groups",
+    "Help",
+    "HelpFormat",
+    "Hosts",
+    "HostsOrdering",
+    "InfoType",
+    "Notes",
+    "Nvts",
+    "OperatingSystems",
+    "Overrides",
+    "Permissions",
+    "PermissionSubjectType",
+    "Policies",
+    "PortLists",
+    "PortRangeType",
+    "ReportConfigs",
+    "ReportConfigParameter",
+    "ReportFormatType",
+    "ReportFormats",
+    "Reports",
+    "ResourceNames",
+    "ResourceType",
+    "Results",
+    "Roles",
+    "ScanConfigs",
+    "Scanners",
+    "ScannerType",
+    "Schedules",
+    "SecInfo",
+    "Severity",
+    "SortOrder",
+    "SnmpAuthAlgorithm",
+    "SnmpPrivacyAlgorithm",
+    "SystemReports",
+    "Tags",
+    "Targets",
+    "Tasks",
+    "Tickets",
+    "TicketStatus",
+    "TLSCertificates",
+    "TrashCan",
+    "UserAuthType",
+    "UserSettings",
+    "Users",
+    "Version",
+    "Vulnerabilities",
+)

python_gvm-26.3.0/gvm/protocols/gmp/requests/v228/_agent_installers.py

@@ -0,0 +1,83 @@
+#  SPDX-FileCopyrightText: 2025 Greenbone AG
+#
+#  SPDX-License-Identifier: GPL-3.0-or-later
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Optional
+
+from gvm.errors import RequiredArgument
+from gvm.protocols.core import Request
+from gvm.protocols.gmp.requests._entity_id import EntityID
+from gvm.utils import to_bool
+from gvm.xml import XmlCommand
+
+
+class AgentInstallers:
+
+    @staticmethod
+    def get_agent_installers(
+        *,
+        filter_string: Optional[str] = None,
+        filter_id: Optional[EntityID] = None,
+        trash: Optional[bool] = None,
+        details: Optional[bool] = None,
+    ) -> Request:
+        """Request a list of agent installers
+
+        Args:
+            filter_string: Filter term to use for the query
+            filter_id: UUID of an existing filter to use for the query
+            trash: Whether to get the trashcan agent installers instead
+            details: Whether to include extra details like tasks using this
+                scanner
+        """
+        cmd = XmlCommand("get_agent_installers")
+        cmd.add_filter(filter_string, filter_id)
+
+        if trash is not None:
+            cmd.set_attribute("trash", to_bool(trash))
+
+        if details is not None:
+            cmd.set_attribute("details", to_bool(details))
+
+        return cmd
+
+    @classmethod
+    def get_agent_installer(cls, agent_installer_id: EntityID) -> Request:
+        """Request a single agent installer
+
+        Args:
+            agent_installer_id: UUID of an existing agent installer
+        """
+        if not agent_installer_id:
+            raise RequiredArgument(
+                function=cls.get_agent_installer.__name__,
+                argument="agent_installer_id",
+            )
+
+        cmd = XmlCommand("get_agent_installers")
+        cmd.set_attribute("agent_installer_id", str(agent_installer_id))
+
+        # for single entity always request all details
+        cmd.set_attribute("details", "1")
+
+        return cmd
+
+    @classmethod
+    def get_agent_installer_file(cls, agent_installer_id: EntityID) -> Request:
+        """Request a single agent installer
+
+        Args:
+            agent_installer_id: UUID of an existing agent installer
+        """
+        if not agent_installer_id:
+            raise RequiredArgument(
+                function=cls.get_agent_installer.__name__,
+                argument="agent_installer_id",
+            )
+
+        cmd = XmlCommand("get_agent_installer_file")
+        cmd.set_attribute("agent_installer_id", str(agent_installer_id))
+
+        return cmd

python_gvm-26.3.0/gvm/protocols/http/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2025 Greenbone AG
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+Package for supported Greenbone HTTP APIs.
+
+Currently only `openvasd version 1 <https://greenbone.github.io/scanner-api/#/>`_ is supported.
+"""

python_gvm-26.3.0/gvm/protocols/http/openvasd/__init__.py

@@ -0,0 +1,18 @@
+# SPDX-FileCopyrightText: 2025 Greenbone AG
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+High-level API interface for interacting with openvasd HTTP services via
+logical modules (health, metadata, scans, etc.).
+
+Usage:
+
+.. code-block:: python
+
+    from gvm.protocols.http.openvasd import OpenvasdHttpAPIv1
+"""
+
+from ._openvasd1 import OpenvasdHttpAPIv1
+
+__all__ = ["OpenvasdHttpAPIv1"]

python_gvm-26.3.0/gvm/protocols/http/openvasd/_api.py

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: 2025 Greenbone AG
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+
+import httpx
+
+
+class OpenvasdAPI:
+    def __init__(
+        self, client: httpx.Client, *, suppress_exceptions: bool = False
+    ):
+        """
+        Initialize the OpenvasdAPI entry point.
+
+        Args:
+            client: An initialized `httpx.Client` configured for communicating
+                    with the openvasd server.
+            suppress_exceptions: If True, suppress exceptions and return structured error responses.
+                Default is False, which means exceptions will be raised.
+        """
+        self._client = client
+        self._suppress_exceptions = suppress_exceptions

python_gvm-26.3.0/gvm/protocols/http/openvasd/_client.py

@@ -0,0 +1,80 @@
+# SPDX-FileCopyrightText: 2025 Greenbone AG
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+http client for initializing a connection to the openvasd HTTP API using optional mTLS authentication.
+"""
+
+import ssl
+from os import PathLike
+from typing import Optional, Tuple, Union
+
+from httpx import Client
+
+StrOrPathLike = Union[str, PathLike[str]]
+
+
+def create_openvasd_http_client(
+    host_name: str,
+    *,
+    api_key: Optional[str] = None,
+    server_ca_path: Optional[StrOrPathLike] = None,
+    client_cert_paths: Optional[
+        Union[StrOrPathLike, Tuple[StrOrPathLike, StrOrPathLike]]
+    ] = None,
+    port: int = 3000,
+) -> Client:
+    """
+    Create a `httpx.Client` configured for mTLS-secured or API KEY access
+    to an openvasd HTTP API instance.
+
+    Args:
+        host_name: Hostname or IP of the OpenVASD server (e.g., "localhost").
+        api_key: Optional API key used for authentication via HTTP headers.
+        server_ca_path: Path to the server's CA certificate (for verifying the server).
+        client_cert_paths: Path to the client certificate (str) or a tuple of
+                            (cert_path, key_path) for mTLS authentication.
+        port: The port to connect to (default: 3000).
+
+    Behavior:
+        - If both `server_ca_path` and `client_cert_paths` are set, an mTLS connection
+            is established using an SSLContext.
+        - If not, `verify` is set to False (insecure), and HTTP is used instead of HTTPS.
+            HTTP connection needs api_key for authorization.
+    """
+    headers = {}
+
+    context: Optional[ssl.SSLContext] = None
+
+    # Prepare mTLS SSL context if needed
+    if client_cert_paths and server_ca_path:
+        context = ssl.create_default_context(
+            ssl.Purpose.SERVER_AUTH, cafile=server_ca_path
+        )
+        if isinstance(client_cert_paths, tuple):
+            context.load_cert_chain(
+                certfile=client_cert_paths[0], keyfile=client_cert_paths[1]
+            )
+        else:
+            context.load_cert_chain(certfile=client_cert_paths)
+
+        context.check_hostname = False
+        context.verify_mode = ssl.CERT_REQUIRED
+
+    # Set verify based on context presence
+    verify: Union[bool, ssl.SSLContext] = context if context else False
+
+    if api_key:
+        headers["X-API-KEY"] = api_key
+
+    protocol = "https" if context else "http"
+    base_url = f"{protocol}://{host_name}:{port}"
+
+    return Client(
+        base_url=base_url,
+        headers=headers,
+        verify=verify,
+        http2=True,
+        timeout=10.0,
+    )

python_gvm-26.3.0/gvm/protocols/http/openvasd/_health.py

@@ -0,0 +1,87 @@
+# SPDX-FileCopyrightText: 2025 Greenbone AG
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+API wrapper for accessing the /health endpoints of the openvasd HTTP API.
+"""
+
+import httpx
+
+from ._api import OpenvasdAPI
+
+
+class HealthAPI(OpenvasdAPI):
+    """
+    Provides access to the openvasd /health endpoints, which expose the
+    operational state of the scanner.
+
+    All methods return the HTTP status code of the response and raise an exception
+    if the server returns an error response (4xx or 5xx).
+    """
+
+    def get_alive(self) -> int:
+        """
+        Check if the scanner process is alive.
+
+        Returns:
+            HTTP status code (e.g., 200 if alive).
+
+        Raises:
+            httpx.HTTPStatusError: If the server response indicates failure and
+                exceptions are not suppressed.
+
+        See: GET /health/alive in the openvasd API documentation.
+        """
+        try:
+            response = self._client.get("/health/alive")
+            response.raise_for_status()
+            return response.status_code
+        except httpx.HTTPStatusError as e:
+            if self._suppress_exceptions:
+                return e.response.status_code
+            raise
+
+    def get_ready(self) -> int:
+        """
+        Check if the scanner is ready to accept requests (e.g., feed loaded).
+
+        Returns:
+            HTTP status code (e.g., 200 if ready).
+
+        Raises:
+            httpx.HTTPStatusError: If the server response indicates failure and
+                exceptions are not suppressed.
+
+        See: GET /health/ready in the openvasd API documentation.
+        """
+        try:
+            response = self._client.get("/health/ready")
+            response.raise_for_status()
+            return response.status_code
+        except httpx.HTTPStatusError as e:
+            if self._suppress_exceptions:
+                return e.response.status_code
+            raise
+
+    def get_started(self) -> int:
+        """
+        Check if the scanner has fully started.
+
+        Returns:
+            HTTP status code (e.g., 200 if started).
+
+        Raises:
+            httpx.HTTPStatusError: If the server response indicates failure and
+                exceptions are not suppressed.
+
+        See: GET /health/started in the openvasd API documentation.
+        """
+        try:
+            response = self._client.get("/health/started")
+            response.raise_for_status()
+            return response.status_code
+        except httpx.HTTPStatusError as e:
+            if self._suppress_exceptions:
+                return e.response.status_code
+            raise