Add: Add new HTTP API structure and introduce modular sub-APIs

Author: ozgen

gvm/protocols/http/openvasd/__init__.py

@@ -3,7 +3,11 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 """
-Package for sending openvasd and handling the responses of HTTP API requests.
+Package for sending requests to openvasd and handling HTTP API responses.
 
-* :class:`OpenvasdHttpApiV1` - openvasd version 1
+Modules:
+- :class:`OpenvasdHttpApiV1` – Main class for communicating with OpenVASD API v1.
+
+Usage:
+    from gvm.protocols.http.openvasd import OpenvasdHttpApiV1
 """

gvm/protocols/http/openvasd/_client.py

@@ -0,0 +1,81 @@
+# SPDX-FileCopyrightText: 2025 Greenbone AG
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+Client wrapper for initializing a connection to the openvasd HTTP API using optional mTLS authentication.
+"""
+
+import ssl
+from typing import Optional, Tuple, Union
+
+from httpx import Client
+
+
+class OpenvasdClient:
+    """
+    The client wrapper around `httpx.Client` configured for mTLS-secured access or API KEY
+    to an openvasd HTTP API instance.
+    """
+
+    def __init__(
+        self,
+        host_name: str,
+        *,
+        api_key: Optional[str] = None,
+        server_ca_path: Optional[str] = None,
+        client_cert_paths: Optional[Union[str, Tuple[str, str]]] = None,
+        port: int = 3000,
+    ):
+        """
+        Initialize the OpenVASD HTTP client with optional mTLS and API key.
+
+        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}"
+
+        self.client = Client(
+            base_url=base_url,
+            headers=headers,
+            verify=verify,
+            http2=True,
+            timeout=10.0,
+        )

gvm/protocols/http/openvasd/health.py

@@ -0,0 +1,101 @@
+# 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
+
+
+class HealthAPI:
+    """
+    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 __init__(self, client: httpx.Client):
+        """
+        Create a new HealthAPI instance.
+
+        Args:
+            client: An initialized `httpx.Client` configured for communicating
+                    with the openvasd server.
+        """
+        self._client = client
+
+    def get_alive(self, safe: bool = False) -> int:
+        """
+        Check if the scanner process is alive.
+
+        Args:
+            safe: If True, suppress exceptions and return structured error responses.
+
+        Returns:
+            HTTP status code (e.g., 200 if alive).
+
+        Raises:
+            httpx.HTTPStatusError: If the server response indicates failure and safe is False.
+
+        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 safe:
+                return e.response.status_code
+            raise
+
+    def get_ready(self, safe: bool = False) -> int:
+        """
+        Check if the scanner is ready to accept requests (e.g., feed loaded).
+
+        Args:
+            safe: If True, suppress exceptions and return structured error responses.
+
+        Returns:
+            HTTP status code (e.g., 200 if ready).
+
+        Raises:
+            httpx.HTTPStatusError: If the server response indicates failure and safe is False.
+
+        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 safe:
+                return e.response.status_code
+            raise
+
+    def get_started(self, safe: bool = False) -> int:
+        """
+        Check if the scanner has fully started.
+
+        Args:
+            safe: If True, suppress exceptions and return structured error responses.
+
+        Returns:
+            HTTP status code (e.g., 200 if started).
+
+        Raises:
+            httpx.HTTPStatusError: If the server response indicates failure and safe is False.
+
+        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 safe:
+                return e.response.status_code
+            raise

gvm/protocols/http/openvasd/metadata.py

@@ -0,0 +1,105 @@
+# SPDX-FileCopyrightText: 2025 Greenbone AG
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+API wrapper for retrieving metadata from the openvasd HTTP API using HEAD requests.
+"""
+
+import httpx
+
+
+class MetadataAPI:
+    """
+    Provides access to metadata endpoints exposed by the openvasd server
+    using lightweight HTTP HEAD requests.
+
+    These endpoints return useful information in HTTP headers such as:
+    - API version
+    - Feed version
+    - Authentication type
+
+    If the scanner is protected and the request is unauthorized, a 401 response
+    is handled gracefully.
+    """
+
+    def __init__(self, client: httpx.Client):
+        """
+        Initialize a MetadataAPI instance.
+
+        Args:
+            client: An `httpx.Client` configured to communicate with the openvasd server.
+        """
+        self._client = client
+
+    def get(self, safe: bool = False) -> dict:
+        """
+        Perform a HEAD request to `/` to retrieve top-level API metadata.
+
+        Args:
+            safe: If True, suppress exceptions and return structured error responses.
+
+        Returns:
+            A dictionary containing:
+
+              - "api-version"
+              - "feed-version"
+              - "authentication"
+
+            Or if safe=True and error occurs:
+
+              - {"error": str, "status_code": int}
+
+        Raises:
+            httpx.HTTPStatusError: For non-401 HTTP errors if safe=False.
+
+        See: HEAD / in the openvasd API documentation.
+        """
+        try:
+            response = self._client.head("/")
+            response.raise_for_status()
+            return {
+                "api-version": response.headers.get("api-version"),
+                "feed-version": response.headers.get("feed-version"),
+                "authentication": response.headers.get("authentication"),
+            }
+        except httpx.HTTPStatusError as e:
+            if safe:
+                return {"error": str(e), "status_code": e.response.status_code}
+            raise
+
+    def get_scans(self, safe: bool = False) -> dict:
+        """
+         Perform a HEAD request to `/scans` to retrieve scan endpoint metadata.
+
+         Args:
+             safe: If True, suppress exceptions and return structured error responses.
+
+        Returns:
+             A dictionary containing:
+
+               - "api-version"
+               - "feed-version"
+               - "authentication"
+
+             Or if safe=True and error occurs:
+
+               - {"error": str, "status_code": int}
+
+         Raises:
+             httpx.HTTPStatusError: For non-401 HTTP errors if safe=False.
+
+         See: HEAD /scans in the openvasd API documentation.
+        """
+        try:
+            response = self._client.head("/scans")
+            response.raise_for_status()
+            return {
+                "api-version": response.headers.get("api-version"),
+                "feed-version": response.headers.get("feed-version"),
+                "authentication": response.headers.get("authentication"),
+            }
+        except httpx.HTTPStatusError as e:
+            if safe:
+                return {"error": str(e), "status_code": e.response.status_code}
+            raise

gvm/protocols/http/openvasd/notus.py

@@ -0,0 +1,79 @@
+# SPDX-FileCopyrightText: 2025 Greenbone AG
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+API wrapper for interacting with the Notus component of the openvasd HTTP API.
+"""
+
+import urllib.parse
+from typing import List
+
+import httpx
+
+
+class NotusAPI:
+    """
+    Provides access to the Notus-related endpoints of the openvasd HTTP API.
+
+    This includes retrieving supported operating systems and triggering
+    package-based vulnerability scans for a specific OS.
+    """
+
+    def __init__(self, client: httpx.Client):
+        """
+        Initialize a NotusAPI instance.
+
+        Args:
+            client: An `httpx.Client` configured to communicate with the openvasd server.
+        """
+        self._client = client
+
+    def get_os_list(self, safe: bool = False) -> httpx.Response:
+        """
+        Retrieve the list of supported operating systems from the Notus service.
+
+        Args:
+            safe: If True, return error info on failure instead of raising.
+
+        Returns:
+            The full `httpx.Response` on success.
+
+        See: GET /notus in the openvasd API documentation.
+        """
+        try:
+            response = self._client.get("/notus")
+            response.raise_for_status()
+            return response
+        except httpx.HTTPStatusError as e:
+            if safe:
+                return e.response
+            raise
+
+    def run_scan(
+        self, os: str, package_list: List[str], safe: bool = False
+    ) -> httpx.Response:
+        """
+        Trigger a Notus scan for a given OS and list of packages.
+
+        Args:
+            os: Operating system name (e.g., "debian", "alpine").
+            package_list: List of package names to evaluate for vulnerabilities.
+            safe: If True, return error info on failure instead of raising.
+
+        Returns:
+            The full `httpx.Response` on success.
+
+        See: POST /notus/{os} in the openvasd API documentation.
+        """
+        quoted_os = urllib.parse.quote(os)
+        try:
+            response = self._client.post(
+                f"/notus/{quoted_os}", json=package_list
+            )
+            response.raise_for_status()
+            return response
+        except httpx.HTTPStatusError as e:
+            if safe:
+                return e.response
+            raise