Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/api/gmpnext.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,27 @@

## Enums

```{eval-rst}
.. autoclass:: gvm.protocols.gmp.requests.next.ActiveDirectoryObjectType
:members:
:undoc-members:
:no-index:
```

```{eval-rst}
.. autoclass:: gvm.protocols.gmp.requests.next.ActiveDirectorySearchScope
:members:
:undoc-members:
:no-index:
```

```{eval-rst}
.. autoclass:: gvm.protocols.gmp.requests.next.ActiveDirectoryTlsMode
:members:
:undoc-members:
:no-index:
```

```{eval-rst}
.. autoclass:: gvm.protocols.gmp.requests.next.AlertCondition
:members:
Expand Down
74 changes: 70 additions & 4 deletions gvm/protocols/gmp/_gmpnext.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,10 @@
from .._protocol import T
from ._gmp227 import GMPv227
from .requests.next import (
ActiveDirectory,
ActiveDirectoryObjectType,
ActiveDirectorySearchScope,
ActiveDirectoryTlsMode,
AgentGroups,
AgentInstallerInstructionLanguageType,
AgentInstallerInstructions,
Expand Down Expand Up @@ -367,7 +371,7 @@ def create_active_directory_credential(
bind_dn: str,
base_dn: str,
bind_password: str,
tls_mode: str,
tls_mode: ActiveDirectoryTlsMode | str,
comment: str | None = None,
port: int | None = None,
ca_certificate: str | None = None,
Expand Down Expand Up @@ -411,7 +415,7 @@ def modify_active_directory_credential(
bind_dn: str | None = None,
base_dn: str | None = None,
bind_password: str | None = None,
tls_mode: str | None = None,
tls_mode: ActiveDirectoryTlsMode | str | None = None,
port: int | str | None = None,
ca_certificate: str | None = None,
) -> T:
Expand Down Expand Up @@ -457,7 +461,7 @@ def verify_active_directory_credential(
bind_dn: str | None = None,
bind_password: str | None = None,
base_dn: str | None = None,
tls_mode: str | None = None,
tls_mode: ActiveDirectoryTlsMode | str | None = None,
port: int | None = None,
ca_certificate: str | None = None,
) -> T:
Expand All @@ -472,7 +476,7 @@ def verify_active_directory_credential(
bind_dn: Distinguished name used to bind to the directory.
bind_password: Password used for the bind.
base_dn: Base distinguished name for directory searches.
tls_mode: Either "ldaps" or "starttls".
tls_mode: TLS mode, either "ldaps" or "starttls".
port: Optional server port, from 1 to 65535.
ca_certificate: Optional CA certificate in PEM format.
"""
Expand All @@ -489,6 +493,68 @@ def verify_active_directory_credential(
)
)

def get_active_directory_objects(
self,
credential_id: EntityID,
*,
base_dn: str | None = None,
group_dn: str | None = None,
scope: ActiveDirectorySearchScope | str | None = None,
object_types: Sequence[ActiveDirectoryObjectType | str] | None = None,
max_results: int | None = None,
include_disabled_computers: bool | None = None,
targets: bool | None = None,
tasks: bool | None = None,
details: bool | None = None,
) -> T:
"""Search Active Directory using a saved AD credential.

Requires AD integration to be enabled in gvmd and a saved AD
credential. Options set to None are omitted from the request so that
gvmd applies its defaults.

The response includes per-type counts for the fetched subset and an
objects truncated attribute indicating whether more objects were
available.

Args:
credential_id: UUID of a saved AD credential.
base_dn: Nonempty search base within the credential's base DN.
Defaults to the credential's base DN.
group_dn: Nonempty DN selecting explicit direct group members
within the search base and scope. Must be within the
credential's base DN.
scope: Search scope, either "base", "onelevel", or "subtree".
Defaults to "onelevel", searching immediately below base_dn. Use
"subtree" to search at all directory depths.
object_types: Nonempty selection of "ou", "container", "computer",
or "group". Defaults to "ou", "computer", and "group".
Duplicates are ignored, preserving first-occurrence order.
max_results: Maximum number of objects to fetch after LDAP
filtering, from 1 to 1000. Omit to use the server default.
include_disabled_computers: Include disabled computers. Defaults
to True.
targets: Include matching targets for computers. Defaults to False.
tasks: Include tasks and readable configurations for matching
targets. Requires targets=True. Defaults to False.
details: Include computer OS version and service principal names.
Defaults to False.
"""
return self._send_request_and_transform_response(
ActiveDirectory.get_active_directory_objects(
credential_id=credential_id,
base_dn=base_dn,
group_dn=group_dn,
scope=scope,
object_types=object_types,
max_results=max_results,
include_disabled_computers=include_disabled_computers,
targets=targets,
tasks=tasks,
details=details,
)
)

def create_credential_store_credential(
self,
name: str,
Expand Down
10 changes: 10 additions & 0 deletions gvm/protocols/gmp/requests/next/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@
#
# SPDX-License-Identifier: GPL-3.0-or-later

from gvm.protocols.gmp.requests.next._active_directory import (
ActiveDirectory,
ActiveDirectoryObjectType,
ActiveDirectorySearchScope,
)
from gvm.protocols.gmp.requests.next._agent_groups import AgentGroups
from gvm.protocols.gmp.requests.next._agent_installer_instructions import (
AgentInstallerInstructionLanguageType,
Expand All @@ -11,6 +16,7 @@
from gvm.protocols.gmp.requests.next._audit_report import AuditReport
from gvm.protocols.gmp.requests.next._credential_stores import CredentialStores
from gvm.protocols.gmp.requests.next._credentials import (
ActiveDirectoryTlsMode,
Credentials,
CredentialStoreCredentialType,
CredentialType,
Expand Down Expand Up @@ -130,6 +136,10 @@
)

__all__ = (
"ActiveDirectory",
"ActiveDirectoryObjectType",
"ActiveDirectorySearchScope",
"ActiveDirectoryTlsMode",
"AgentGroups",
"AgentInstallerInstructionLanguageType",
"AgentInstallerInstructions",
Expand Down
176 changes: 176 additions & 0 deletions gvm/protocols/gmp/requests/next/_active_directory.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,176 @@
# SPDX-FileCopyrightText: 2026 Greenbone AG
#
# SPDX-License-Identifier: GPL-3.0-or-later

from collections.abc import Sequence

from gvm._enum import Enum
from gvm.errors import InvalidArgument, RequiredArgument
from gvm.protocols.core import Request
from gvm.utils import to_bool
from gvm.xml import XmlCommand

from .._entity_id import EntityID


class ActiveDirectorySearchScope(Enum):
"""Enum for Active Directory search scopes"""

BASE = "base"
ONELEVEL = "onelevel"
SUBTREE = "subtree"


class ActiveDirectoryObjectType(Enum):
"""Enum for Active Directory object types"""

OU = "ou"
CONTAINER = "container"
COMPUTER = "computer"
GROUP = "group"


class ActiveDirectory:
@classmethod
def get_active_directory_objects(
cls,
credential_id: EntityID,
*,
base_dn: str | None = None,
group_dn: str | None = None,
scope: ActiveDirectorySearchScope | str | None = None,
object_types: Sequence[ActiveDirectoryObjectType | str] | None = None,
max_results: int | None = None,
include_disabled_computers: bool | None = None,
targets: bool | None = None,
tasks: bool | None = None,
details: bool | None = None,
) -> Request:
"""Search Active Directory using a saved AD credential.

Requires AD integration to be enabled in gvmd and a saved AD
credential. Options set to None are omitted from the request so that
gvmd applies its defaults.

Args:
credential_id: UUID of a saved AD credential.
base_dn: Nonempty search base within the credential's base DN.
Defaults to the credential's base DN.
group_dn: Nonempty DN selecting explicit direct group members
within the search base and scope. Must be within the
credential's base DN.
scope: Search scope, either "base", "onelevel", or "subtree".
Defaults to "onelevel", searching immediately below base_dn. Use
"subtree" to search at all directory depths.
object_types: Nonempty selection of "ou", "container", "computer",
or "group". Defaults to "ou", "computer", and "group".
Duplicates are ignored, preserving first-occurrence order.
max_results: Maximum number of objects to fetch after LDAP
filtering, from 1 to 1000. Omit to use the server default.
include_disabled_computers: Include disabled computers. Defaults
to True.
targets: Include matching targets for computers. Defaults to False.
tasks: Include tasks and readable configurations for matching
targets. Requires targets=True. Defaults to False.
details: Include computer OS version and service principal names.
Defaults to False.
"""
if not credential_id:
raise RequiredArgument(
function=cls.get_active_directory_objects.__name__,
argument="credential_id",
)
if base_dn is not None and not base_dn:
raise RequiredArgument(
function=cls.get_active_directory_objects.__name__,
argument="base_dn",
)
if group_dn is not None and not group_dn:
raise RequiredArgument(
function=cls.get_active_directory_objects.__name__,
argument="group_dn",
)
if scope is not None and not scope:
raise RequiredArgument(
function=cls.get_active_directory_objects.__name__,
argument="scope",
)
if scope is not None and not isinstance(
scope, ActiveDirectorySearchScope
):
try:
scope = ActiveDirectorySearchScope(scope)
except InvalidArgument as error:
raise InvalidArgument(
str(error),
function=cls.get_active_directory_objects.__name__,
argument="scope",
) from None
if object_types is not None and (
isinstance(object_types, str)
or not object_types
or any(not object_type for object_type in object_types)
):
raise InvalidArgument(
function=cls.get_active_directory_objects.__name__,
argument="object_types",
)
try:
normalized_object_types = (
list(
dict.fromkeys(
ActiveDirectoryObjectType(t) for t in object_types
)
)
if object_types is not None
else None
)
except InvalidArgument as error:
raise InvalidArgument(
str(error),
function=cls.get_active_directory_objects.__name__,
argument="object_types",
) from None
if max_results is not None and (
isinstance(max_results, bool)
or not isinstance(max_results, int)
or not 1 <= max_results <= 1000
):
raise InvalidArgument(
function=cls.get_active_directory_objects.__name__,
argument="max_results",
)
if tasks and not targets:
raise InvalidArgument(
function=cls.get_active_directory_objects.__name__,
argument="tasks",
)

cmd = XmlCommand("get_active_directory_objects")
cmd.set_attribute("credential_id", str(credential_id))
if scope is not None:
cmd.set_attribute("scope", scope.value)
if max_results is not None:
cmd.set_attribute("max_results", str(max_results))
if include_disabled_computers is not None:
cmd.set_attribute(
"include_disabled_computers",
to_bool(include_disabled_computers),
)
if targets is not None:
cmd.set_attribute("targets", to_bool(targets))
if tasks is not None:
cmd.set_attribute("tasks", to_bool(tasks))
if details is not None:
cmd.set_attribute("details", to_bool(details))

if base_dn is not None:
cmd.add_element("base_dn", base_dn)
if group_dn is not None:
cmd.add_element("group_dn", group_dn)
if normalized_object_types is not None:
types_element = cmd.add_element("object_types")
for object_type in normalized_object_types:
types_element.add_element("object_type", object_type.value)

return cmd
Loading