python-gvm 26.5.0__tar.gz → 26.7.0__tar.gz

{python_gvm-26.5.0 → python_gvm-26.7.0}/PKG-INFO

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: python-gvm
-Version: 26.5.0
+Version: 26.7.0
 Summary: Library to communicate with remote servers over GMP or OSP
 License: GPL-3.0-or-later
+License-File: LICENSE
 Author: Greenbone AG
 Author-email: info@greenbone.net
 Requires-Python: >=3.9.2,<4.0.0
@@ -16,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Dist: httpx[http2] (>=0.28.1,<0.29.0)

{python_gvm-26.5.0 → python_gvm-26.7.0}/gvm/__version__.py

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

{python_gvm-26.5.0 → python_gvm-26.7.0}/gvm/protocols/gmp/_gmpnext.py

@@ -2,7 +2,7 @@
 #
 #  SPDX-License-Identifier: GPL-3.0-or-later
 
-from typing import Mapping, Optional, Sequence
+from typing import Any, Mapping, Optional, Sequence
 
 from gvm.protocols.gmp.requests import EntityID
 
@@ -114,28 +114,23 @@ class GMPNext(GMPv227[T]):
         agent_ids: list[EntityID],
         *,
         authorized: Optional[bool] = None,
-        min_interval: Optional[int] = None,
-        heartbeat_interval: Optional[int] = None,
-        schedule: Optional[str] = None,
+        config: Optional[Mapping[str, Any]] = None,
         comment: Optional[str] = None,
     ) -> T:
-        """Modify multiple agents
+        """
+        Modify multiple agents.
 
         Args:
-            agent_ids: List of agent UUIDs to modify
-            authorized: Whether the agent is authorized
-            min_interval: Minimum scan interval
-            heartbeat_interval: Interval for sending heartbeats
-            schedule: Cron-style schedule for agent
-            comment: Comment for the agents
+            agent_ids: List of agent UUIDs to modify.
+            authorized: Whether the agent is authorized.
+            config: Nested config for Agent Controller.
+            comment: Optional comment for the change.
         """
         return self._send_request_and_transform_response(
             Agents.modify_agents(
                 agent_ids=agent_ids,
                 authorized=authorized,
-                min_interval=min_interval,
-                heartbeat_interval=heartbeat_interval,
-                schedule=schedule,
+                config=config,
                 comment=comment,
             )
         )
@@ -150,6 +145,25 @@ class GMPNext(GMPv227[T]):
             Agents.delete_agents(agent_ids=agent_ids)
         )
 
+    def modify_agent_control_scan_config(
+        self,
+        agent_control_id: EntityID,
+        config: Mapping[str, Any],
+    ) -> T:
+        """
+        Modify agent control scan config.
+
+        Args:
+            agent_control_id: The agent control UUID.
+            config: Nested config for Agent Controller.
+        """
+        return self._send_request_and_transform_response(
+            Agents.modify_agent_control_scan_config(
+                agent_control_id=agent_control_id,
+                config=config,
+            )
+        )
+
     def get_agent_groups(
         self,
         *,
@@ -454,6 +468,49 @@ class GMPNext(GMPv227[T]):
             )
         )
 
+    def create_container_image_task(
+        self,
+        name: str,
+        oci_image_target_id: EntityID,
+        scanner_id: EntityID,
+        *,
+        comment: Optional[str] = None,
+        alterable: Optional[bool] = None,
+        schedule_id: Optional[EntityID] = None,
+        alert_ids: Optional[Sequence[EntityID]] = None,
+        schedule_periods: Optional[int] = None,
+        observers: Optional[Sequence[str]] = None,
+        preferences: Optional[Mapping[str, SupportsStr]] = None,
+    ) -> T:
+        """Create a new scan task using an OCI image target.
+
+        Args:
+            name: Name of the new task.
+            oci_image_target_id: UUID of the OCI image target to be scanned.
+            scanner_id: UUID of scanner to use for scanning the agents.
+            comment: Optional comment for the task.
+            alterable: Whether the task should be alterable.
+            alert_ids: List of UUIDs for alerts to be applied to the task.
+            schedule_id: UUID of a schedule when the task should be run.
+            schedule_periods: Limit to number of scheduled runs, 0 for unlimited.
+            observers: List of usernames or IDs allowed to observe the task.
+            preferences: Scanner preferences as name/value pairs.
+        """
+        return self._send_request_and_transform_response(
+            Tasks.create_container_image_task(
+                name=name,
+                oci_image_target_id=oci_image_target_id,
+                scanner_id=scanner_id,
+                comment=comment,
+                alterable=alterable,
+                schedule_id=schedule_id,
+                alert_ids=alert_ids,
+                schedule_periods=schedule_periods,
+                observers=observers,
+                preferences=preferences,
+            )
+        )
+
     def create_container_task(
         self, name: str, *, comment: Optional[str] = None
     ) -> T:
@@ -586,6 +643,7 @@ class GMPNext(GMPv227[T]):
         target_id: Optional[EntityID] = None,
         scanner_id: Optional[EntityID] = None,
         agent_group_id: Optional[EntityID] = None,
+        oci_image_target_id: Optional[EntityID] = None,
         alterable: Optional[bool] = None,
         hosts_ordering: Optional[HostsOrdering] = None,
         schedule_id: Optional[EntityID] = None,
@@ -604,6 +662,7 @@ class GMPNext(GMPv227[T]):
             target_id: UUID of target to be scanned
             scanner_id: UUID of scanner to use for scanning the target
             agent_group_id: UUID of agent group to use for scanning
+            oci_image_target_id: UUID of the OCI Image target to be scanned.
             comment: The comment on the task.
             alert_ids: List of UUIDs for alerts to be applied to the task
             hosts_ordering: The order hosts are scanned in
@@ -622,6 +681,7 @@ class GMPNext(GMPv227[T]):
                 target_id=target_id,
                 scanner_id=scanner_id,
                 agent_group_id=agent_group_id,
+                oci_image_target_id=oci_image_target_id,
                 alterable=alterable,
                 hosts_ordering=hosts_ordering,
                 schedule_id=schedule_id,

python_gvm-26.7.0/gvm/protocols/gmp/requests/next/_agents.py

@@ -0,0 +1,321 @@
+# SPDX-FileCopyrightText: 2025 Greenbone AG
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Any, Mapping, Optional, Sequence
+
+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 Agents:
+
+    @staticmethod
+    def _add_element(element, name: str, value: Any) -> None:
+        """
+        Helper to add a sub-element with a value if the value is not None.
+
+        Args:
+            element: The XML parent element to which the new element is added.
+            name: Name of the sub-element to create.
+            value: Value to set as the text of the sub-element. If None, the
+                element will not be created.
+        """
+        if value is not None:
+            element.add_element(name, str(value))
+
+    @classmethod
+    def _validate_agent_config(
+        cls, config: Mapping[str, Any], *, caller: str
+    ) -> None:
+        """Ensure all required fields exist, are well-shaped, and non-empty."""
+
+        def valid_map(d: Any, key: str, path: str) -> Mapping[str, Any]:
+            if not isinstance(d, Mapping):
+                raise RequiredArgument(
+                    function=caller, argument=f"config.{path.rstrip('.')}"
+                )
+            v = d.get(key)
+            if not isinstance(v, Mapping):
+                raise RequiredArgument(
+                    function=caller, argument=f"config.{path}{key}"
+                )
+            return v
+
+        def valid_value(d: Mapping[str, Any], key: str, path: str) -> Any:
+            v = d.get(key)
+            if v is None or (isinstance(v, str) and v.strip() == ""):
+                raise RequiredArgument(
+                    function=caller, argument=f"config.{path}{key}"
+                )
+            return v
+
+        # agent_control.retry
+        ac = valid_map(config, "agent_control", "")
+        retry = valid_map(ac, "retry", "agent_control.")
+        valid_value(retry, "attempts", "agent_control.retry.")
+        valid_value(retry, "delay_in_seconds", "agent_control.retry.")
+        valid_value(retry, "max_jitter_in_seconds", "agent_control.retry.")
+
+        # agent_script_executor
+        se = valid_map(config, "agent_script_executor", "")
+        valid_value(se, "bulk_size", "agent_script_executor.")
+        valid_value(se, "bulk_throttle_time_in_ms", "agent_script_executor.")
+        valid_value(se, "indexer_dir_depth", "agent_script_executor.")
+
+        sched = se.get("scheduler_cron_time")
+        if isinstance(sched, Sequence) and not isinstance(sched, (str, bytes)):
+            items = [str(x) for x in sched]
+        else:
+            items = []
+        if not items or any(not str(x).strip() for x in items):
+            raise RequiredArgument(
+                function=caller,
+                argument="config.agent_script_executor.scheduler_cron_time",
+            )
+
+        # heartbeat
+        hb = valid_map(config, "heartbeat", "")
+        valid_value(hb, "interval_in_seconds", "heartbeat.")
+        valid_value(hb, "miss_until_inactive", "heartbeat.")
+
+    @classmethod
+    def _append_agent_config(cls, parent, config: Mapping[str, Any]) -> None:
+        """
+        Append an agent configuration block to the given XML parent element.
+
+        Expected config structure::
+
+            {
+                "agent_control": {
+                    "retry": {
+                        "attempts": 6,
+                        "delay_in_seconds": 60,
+                        "max_jitter_in_seconds": 10
+                    }
+                },
+                "agent_script_executor": {
+                    "bulk_size": 2,
+                    "bulk_throttle_time_in_ms": 300,
+                    "indexer_dir_depth": 100,
+                    "scheduler_cron_time": ["0 */12 * * *"]
+                },
+                "heartbeat": {
+                    "interval_in_seconds": 300,
+                    "miss_until_inactive": 1
+                }
+            }
+
+        Args:
+            parent: The XML parent element to which the `<config>` element
+                should be appended.
+            config: Mapping containing the agent configuration fields to
+                serialize.
+        """
+        xml_config = parent.add_element("config")
+
+        # agent_control.retry
+        ac = config["agent_control"]
+        retry = ac["retry"]
+        xml_ac = xml_config.add_element("agent_control")
+        xml_retry = xml_ac.add_element("retry")
+        cls._add_element(xml_retry, "attempts", retry.get("attempts"))
+        cls._add_element(
+            xml_retry, "delay_in_seconds", retry.get("delay_in_seconds")
+        )
+        cls._add_element(
+            xml_retry,
+            "max_jitter_in_seconds",
+            retry.get("max_jitter_in_seconds"),
+        )
+
+        # agent_script_executor
+        se = config["agent_script_executor"]
+        xml_se = xml_config.add_element("agent_script_executor")
+        cls._add_element(xml_se, "bulk_size", se.get("bulk_size"))
+        cls._add_element(
+            xml_se,
+            "bulk_throttle_time_in_ms",
+            se.get("bulk_throttle_time_in_ms"),
+        )
+        cls._add_element(
+            xml_se, "indexer_dir_depth", se.get("indexer_dir_depth")
+        )
+        sched = se.get("scheduler_cron_time")
+        xml_sched = xml_se.add_element("scheduler_cron_time")
+        for item in sched:
+            xml_sched.add_element("item", str(item))
+
+        # heartbeat
+        hb = config["heartbeat"]
+        xml_hb = xml_config.add_element("heartbeat")
+        cls._add_element(
+            xml_hb, "interval_in_seconds", hb.get("interval_in_seconds")
+        )
+        cls._add_element(
+            xml_hb, "miss_until_inactive", hb.get("miss_until_inactive")
+        )
+
+    @classmethod
+    def get_agents(
+        cls,
+        *,
+        filter_string: Optional[str] = None,
+        filter_id: Optional[EntityID] = None,
+        details: Optional[bool] = None,
+    ) -> Request:
+        """Request a list of agents.
+
+        Args:
+            filter_string: Filter term to use for the query.
+            filter_id: UUID of an existing filter to use for the query.
+            details: Whether to include detailed agent info.
+        """
+        cmd = XmlCommand("get_agents")
+        cmd.add_filter(filter_string, filter_id)
+
+        if details is not None:
+            cmd.set_attribute("details", to_bool(details))
+
+        return cmd
+
+    @classmethod
+    def modify_agents(
+        cls,
+        agent_ids: list[EntityID],
+        *,
+        authorized: Optional[bool] = None,
+        config: Optional[Mapping[str, Any]] = None,
+        comment: Optional[str] = None,
+    ) -> Request:
+        """
+        Modify multiple agents.
+
+        Args:
+            agent_ids: List of agent UUIDs to modify.
+            authorized: Whether the agent is authorized.
+            config: Nested config, e.g.:
+                {
+                  "agent_control": {
+                    "retry": {
+                      "attempts": 6,
+                      "delay_in_seconds": 60,
+                      "max_jitter_in_seconds": 10,
+                    }
+                  },
+                  "agent_script_executor": {
+                      "bulk_size": 2,
+                      "bulk_throttle_time_in_ms": 300,
+                      "indexer_dir_depth": 100,
+                      "scheduler_cron_time": ["0 */12 * * *"],  # str or list[str]
+                  },
+                  "heartbeat": {
+                      "interval_in_seconds": 300,
+                      "miss_until_inactive": 1,
+                  },
+                }
+            comment: Optional comment for the change.
+        """
+        if not agent_ids:
+            raise RequiredArgument(
+                function=cls.modify_agents.__name__, argument="agent_ids"
+            )
+
+        cmd = XmlCommand("modify_agent")
+        xml_agents = cmd.add_element("agents")
+
+        for agent_id in agent_ids:
+            xml_agents.add_element("agent", attrs={"id": agent_id})
+
+        if authorized is not None:
+            cmd.add_element("authorized", to_bool(authorized))
+
+        if config is not None:
+            cls._validate_agent_config(
+                config, caller=cls.modify_agents.__name__
+            )
+            cls._append_agent_config(cmd, config)
+
+        if comment:
+            cmd.add_element("comment", comment)
+
+        return cmd
+
+    @classmethod
+    def delete_agents(cls, agent_ids: list[EntityID]) -> Request:
+        """Delete multiple agents
+
+        Args:
+            agent_ids: List of agent UUIDs to delete
+        """
+        if not agent_ids:
+            raise RequiredArgument(
+                function=cls.delete_agents.__name__, argument="agent_ids"
+            )
+
+        cmd = XmlCommand("delete_agent")
+        xml_agents = cmd.add_element("agents")
+
+        for agent_id in agent_ids:
+            xml_agents.add_element("agent", attrs={"id": agent_id})
+
+        return cmd
+
+    @classmethod
+    def modify_agent_control_scan_config(
+        cls,
+        agent_control_id: EntityID,
+        config: Mapping[str, Any],
+    ) -> Request:
+        """
+        Modify agent control scan config.
+
+        Args:
+            agent_control_id: The agent control UUID.
+            config: Nested config, e.g.:
+                {
+                  "agent_control": {
+                    "retry": {
+                      "attempts": 6,
+                      "delay_in_seconds": 60,
+                      "max_jitter_in_seconds": 10,
+                    }
+                  },
+                  "agent_script_executor": {
+                      "bulk_size": 2,
+                      "bulk_throttle_time_in_ms": 300,
+                      "indexer_dir_depth": 100,
+                      "scheduler_cron_time": ["0 */12 * * *"],  # str or list[str]
+                  },
+                  "heartbeat": {
+                      "interval_in_seconds": 300,
+                      "miss_until_inactive": 1,
+                  },
+                }
+        """
+        if not agent_control_id:
+            raise RequiredArgument(
+                function=cls.modify_agent_control_scan_config.__name__,
+                argument="agent_control_id",
+            )
+        if not config:
+            raise RequiredArgument(
+                function=cls.modify_agent_control_scan_config.__name__,
+                argument="config",
+            )
+
+        cls._validate_agent_config(
+            config, caller=cls.modify_agent_control_scan_config.__name__
+        )
+
+        cmd = XmlCommand(
+            "modify_agent_control_scan_config",
+        )
+        cmd.set_attribute("agent_control_id", str(agent_control_id))
+
+        cls._append_agent_config(cmd, config)
+
+        return cmd

{python_gvm-26.5.0 → python_gvm-26.7.0}/gvm/protocols/gmp/requests/next/_tasks.py

@@ -119,6 +119,96 @@ class Tasks:
 
         return cmd
 
+    @classmethod
+    def create_container_image_task(
+        cls,
+        name: str,
+        oci_image_target_id: EntityID,
+        scanner_id: EntityID,
+        *,
+        comment: Optional[str] = None,
+        alterable: Optional[bool] = None,
+        schedule_id: Optional[EntityID] = None,
+        alert_ids: Optional[Sequence[EntityID]] = None,
+        schedule_periods: Optional[int] = None,
+        observers: Optional[Sequence[str]] = None,
+        preferences: Optional[Mapping[str, SupportsStr]] = None,
+    ) -> Request:
+        """Create a new scan task using an OCI image target.
+
+        Args:
+            name: Name of the new task.
+            oci_image_target_id: UUID of the OCI Image target to be scanned.
+            scanner_id: UUID of scanner to use for scanning the agents.
+            comment: Optional comment for the task.
+            alterable: Whether the task should be alterable.
+            alert_ids: List of UUIDs for alerts to be applied to the task.
+            schedule_id: UUID of a schedule when the task should be run.
+            schedule_periods: Limit to number of scheduled runs, 0 for unlimited.
+            observers: List of usernames or IDs allowed to observe the task.
+            preferences: Scanner preferences as name/value pairs.
+        """
+        if not name:
+            raise RequiredArgument(
+                function=cls.create_container_image_task.__name__,
+                argument="name",
+            )
+
+        if not oci_image_target_id:
+            raise RequiredArgument(
+                function=cls.create_container_image_task.__name__,
+                argument="oci_image_target_id",
+            )
+
+        if not scanner_id:
+            raise RequiredArgument(
+                function=cls.create_container_image_task.__name__,
+                argument="scanner_id",
+            )
+
+        cmd = XmlCommand("create_task")
+        cmd.add_element("name", name)
+        cmd.add_element("usage_type", "scan")
+        cmd.add_element(
+            "oci_image_target", attrs={"id": str(oci_image_target_id)}
+        )
+        cmd.add_element("scanner", attrs={"id": str(scanner_id)})
+
+        if comment:
+            cmd.add_element("comment", comment)
+
+        if alterable is not None:
+            cmd.add_element("alterable", to_bool(alterable))
+
+        if alert_ids:
+            for alert in alert_ids:
+                cmd.add_element("alert", attrs={"id": str(alert)})
+
+        if schedule_id:
+            cmd.add_element("schedule", attrs={"id": str(schedule_id)})
+
+            if schedule_periods is not None:
+                if (
+                    not isinstance(schedule_periods, Integral)
+                    or schedule_periods < 0
+                ):
+                    raise InvalidArgument(
+                        "schedule_periods must be an integer greater or equal than 0"
+                    )
+                cmd.add_element("schedule_periods", str(schedule_periods))
+
+        if observers:
+            cmd.add_element("observers", to_comma_list(observers))
+
+        if preferences is not None:
+            xml_prefs = cmd.add_element("preferences")
+            for pref_name, pref_value in preferences.items():
+                xml_pref = xml_prefs.add_element("preference")
+                xml_pref.add_element("scanner_name", pref_name)
+                xml_pref.add_element("value", str(pref_value))
+
+        return cmd
+
     @classmethod
     def create_container_task(
         cls, name: str, *, comment: Optional[str] = None
@@ -350,6 +440,7 @@ class Tasks:
         target_id: Optional[EntityID] = None,
         scanner_id: Optional[EntityID] = None,
         agent_group_id: Optional[EntityID] = None,
+        oci_image_target_id: Optional[EntityID] = None,
         alterable: Optional[bool] = None,
         hosts_ordering: Optional[HostsOrdering] = None,
         schedule_id: Optional[EntityID] = None,
@@ -368,6 +459,7 @@ class Tasks:
             target_id: UUID of target to be scanned
             scanner_id: UUID of scanner to use for scanning the target
             agent_group_id: UUID of agent group to use for scanning
+            oci_image_target_id: UUID of the OCI Image target to be scanned.
             comment: The comment on the task.
             alert_ids: List of UUIDs for alerts to be applied to the task
             hosts_ordering: The order hosts are scanned in
@@ -383,11 +475,17 @@ class Tasks:
                 function=cls.modify_task.__name__, argument="task_id"
             )
 
-        if target_id and agent_group_id:
+        if (
+            sum(
+                id is not None
+                for id in (target_id, agent_group_id, oci_image_target_id)
+            )
+            > 1
+        ):
             raise InvalidArgument(
                 function=cls.modify_task.__name__,
-                argument="target_id/agent_group_id",
-                message="Only one of target_id or agent_group_id can be modified at a time",
+                argument="target_id/agent_group_id/oci_image_target_id",
+                message="Only one of target_id, agent_group_id or oci_image_target_id can be modified at a time",
             )
 
         cmd = XmlCommand("modify_task")
@@ -408,6 +506,11 @@ class Tasks:
         if agent_group_id:
             cmd.add_element("agent_group", attrs={"id": str(agent_group_id)})
 
+        if oci_image_target_id:
+            cmd.add_element(
+                "oci_image_target", attrs={"id": str(oci_image_target_id)}
+            )
+
         if alterable is not None:
             cmd.add_element("alterable", to_bool(alterable))
 

{python_gvm-26.5.0 → python_gvm-26.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "python-gvm"
-version = "26.5.0"
+version = "26.7.0"
 description = "Library to communicate with remote servers over GMP or OSP"
 license = "GPL-3.0-or-later"
 authors = ["Greenbone AG <info@greenbone.net>"]

{python_gvm-26.5.0 → python_gvm-26.7.0}/tests/protocols/gmpnext/entities/agents/test_delete_agents.py

@@ -10,9 +10,9 @@ class GmpDeleteAgentsTestMixin:
         self.gmp.delete_agents(agent_ids=["agent-123", "agent-456"])
 
         self.connection.send.has_been_called_with(
-            b"<delete_agents>"
+            b"<delete_agent>"
             b'<agents><agent id="agent-123"/><agent id="agent-456"/></agents>'
-            b"</delete_agents>"
+            b"</delete_agent>"
         )
 
     def test_delete_agents_without_ids(self):