Add: Support for the openvasd HTTP API

docs/Makefile

@@ -11,7 +11,10 @@ BUILDDIR      = build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help Makefile livehtml
+
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/api/http.md

@@ -0,0 +1,16 @@
+(http)=
+
+# HTTP APIs
+
+```{eval-rst}
+.. automodule:: gvm.protocols.http
+```
+
+The following modules are provided:
+
+```{eval-rst}
+.. toctree::
+    :maxdepth: 1
+
+    openvasdv1
+```

docs/api/openvasdv1.md

@@ -0,0 +1,18 @@
+(openvasdv1)=
+
+# openvasd v1
+
+```{eval-rst}
+.. automodule:: gvm.protocols.http.openvasd
+    :members:
+```
+
+```{toctree}
+:hidden:
+
+openvasdv1/health
+openvasdv1/metadata
+openvasdv1/notus
+openvasdv1/scans
+openvasdv1/vts
+```

docs/api/openvasdv1/health.md

@@ -0,0 +1,6 @@
+# Health API
+
+```{eval-rst}
+.. automodule:: gvm.protocols.http.openvasd._health
+   :members:
+```

docs/api/openvasdv1/metadata.md

@@ -0,0 +1,6 @@
+# Metadata API
+
+```{eval-rst}
+.. automodule:: gvm.protocols.http.openvasd._metadata
+   :members:
+```

docs/api/openvasdv1/notus.md

@@ -0,0 +1,6 @@
+# Notus API
+
+```{eval-rst}
+.. automodule:: gvm.protocols.http.openvasd._notus
+   :members:
+```

docs/api/openvasdv1/scans.md

@@ -0,0 +1,6 @@
+# Scans API
+
+```{eval-rst}
+.. automodule:: gvm.protocols.http.openvasd._scans
+   :members:
+```

docs/api/openvasdv1/vts.md

@@ -0,0 +1,6 @@
+# VTs API
+
+```{eval-rst}
+.. automodule:: gvm.protocols.http.openvasd._vts
+   :members:
+```

docs/api/protocols.md

@@ -11,6 +11,7 @@
 
 gmp
 ospv1
+http
 ```
 
 ## Dynamic

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.
+"""

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"]

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

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,
+    )

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