# Scans API

API wrapper for interacting with the /scans endpoints of the openvasd HTTP API.

class Credential

  Represents a full credential configuration for a specific service.

  service

    Name of the service (e.g., “ssh”, “snmp”).

    Type:

      str

  port

    Port number associated with the service.

    Type:

      int

  up

    Optional username/password credentials.

    Type:

      gvm.protocols.http.openvasd._scans.CredentialUP | None

  krb5

    Optional Kerberos credentials.

    Type:

      gvm.protocols.http.openvasd._scans.CredentialKRB5 | None

  usk

    Optional user/SSH key credentials.

    Type:

      gvm.protocols.http.openvasd._scans.CredentialUSK | None

  snmp

    Optional SNMP credentials.

    Type:

      gvm.protocols.http.openvasd._scans.CredentialSNMP | None

  __init__(service, port, up=None, krb5=None, usk=None, snmp=None)

class CredentialKRB5

  Represents Kerberos credentials.

  username

    Kerberos username.

    Type:

      str

  password

    Kerberos password.

    Type:

      str

  realm

    Kerberos realm.

    Type:

      str

  kdc

    Key Distribution Center hostname.

    Type:

      str

  __init__(username, password, realm, kdc)

class CredentialSNMP

  Represents SNMP credentials.

  username

    SNMP username.

    Type:

      str

  password

    SNMP authentication password.

    Type:

      str

  community

    SNMP community string.

    Type:

      str

  auth_algorithm

    Authentication algorithm (e.g., “md5”).

    Type:

      str

  privacy_password

    Privacy password for SNMPv3.

    Type:

      str

  privacy_algorithm

    Privacy algorithm (e.g., “aes”).

    Type:

      str

  __init__(username, password, community, auth_algorithm, privacy_password, privacy_algorithm)

class CredentialUP

  Represents username/password credentials for a service.

  username

    The login username.

    Type:

      str

  password

    The login password.

    Type:

      str

  privilege_username

    Optional privilege escalation username.

    Type:

      str | None

  privilege_password

    Optional privilege escalation password.

    Type:

      str | None

  __init__(username, password, privilege_username=None, privilege_password=None)

class CredentialUSK

  Represents credentials using a user/SSH key combination.

  username

    SSH username.

    Type:

      str

  password

    Password for SSH key (if encrypted).

    Type:

      str

  private

    Private key content or reference.

    Type:

      str

  privilege_username

    Optional privilege escalation username.

    Type:

      str | None

  privilege_password

    Optional privilege escalation password.

    Type:

      str | None

  __init__(username, password, private, privilege_username=None, privilege_password=None)

class Port

  Represents a port configuration for scanning.

  protocol

    The protocol to use (“tcp” or “udp”).

    Type:

      str

  range

    A list of port ranges to scan.

    Type:

      list[gvm.protocols.http.openvasd._scans.PortRange]

  __init__(protocol, range)

class PortRange

  Represents a range of ports.

  start

    The starting port number.

    Type:

      int

  end

    The ending port number.

    Type:

      int

  __init__(start, end)

class ScanAction

  Enumeration of valid scan actions supported by the openvasd API.

  This enum defines the allowed actions that can be performed on a scan. Using an enum helps ensure type safety and prevents invalid action strings from being passed to the API.

  Values:

    START: Initiates the scan execution. STOP: Terminates an ongoing scan.

  __new__(value)

class ScanPreference

  Represents a scan-level preference or configuration option.

  id

    Preference ID or name (e.g., “max_checks”, “scan_speed”).

    Type:

      str

  value

    The value assigned to the preference.

    Type:

      str

  __init__(id, value)

class ScansAPI

  Provides access to scan-related operations in the openvasd HTTP API.

  Includes methods for creating, starting, stopping, and retrieving scan details and results.

  create(target, vt_selection, *, scan_preferences=None)

    Create a new scan with the specified target configuration and VT selection.

    Parameters:

      - target (Target) – A Target dataclass instance describing the scan target(s), including hosts, ports, credentials, and alive test settings.

      - vt_selection (list[VTSelection]) – A list of VTSelection instances specifying which vulnerability tests (VTs) to include in the scan.

      - scan_preferences (list[ScanPreference] | None) – Optional list of ScanPreference instances to customize scan behavior (e.g., number of threads, timeout values).

    Returns:

      The full HTTP response returned by the POST /scans request.

    Raises:

      httpx.HTTPStatusError – If the server responds with an error status and the exception is not suppressed.

    Return type:

      Response

    See: POST /scans in the openvasd API documentation.

  delete(scan_id)

    Delete a scan by its ID.

    Parameters:

      scan_id (str | UUID) – The scan identifier.

    Returns:

      The HTTP status code returned by the server on success, or the error status code returned by the server on failure.

    Raises:

      httpx.HTTPStatusError – If the server responds with an error status and the exception is not suppressed.

    Return type:

      int

    See: DELETE /scans/{id} in the openvasd API documentation.

  get(scan_id)

    Retrieve metadata of a single scan by ID.

    Parameters:

      scan_id (str | UUID) – The scan identifier.

    Returns:

      The full HTTP response of the GET /scans/{id} request.

    Raises:

      httpx.HTTPStatusError – If the request fails and exceptions are not suppressed.

    Return type:

      Response

    See: GET /scans/{id} in the openvasd API documentation.

  get_all()

    Retrieve the list of all available scans.

    Returns:

      The full HTTP response of the GET /scans request.

    Raises:

      httpx.HTTPStatusError – If the request fails and exceptions are not suppressed.

    Return type:

      Response

    See: GET /scans in the openvasd API documentation.

  get_preferences()

    Retrieve all available scan preferences from the scanner.

    Returns:

      The full HTTP response of the GET /scans/preferences request.

    Raises:

      httpx.HTTPStatusError – If the server responds with an error status and the exception is not suppressed.

    Return type:

      Response

    See: GET /scans/preferences in the openvasd API documentation.

  get_result(scan_id, result_id)

    Retrieve a specific scan result.

    Parameters:

      - scan_id (str | UUID) – The scan identifier.

      - result_id (str | UUID) – The specific result ID to fetch.

    Returns:

      The full HTTP response of the GET /scans/{id}/results/{rid} request.

    Raises:

      httpx.HTTPStatusError – If the request fails and exceptions are not suppressed.

    Return type:

      Response

    See: GET /scans/{id}/results/{rid} in the openvasd API documentation.

  get_results(scan_id, *, range_start=None, range_end=None)

    Retrieve a range of results for a given scan.

    Parameters:

      - scan_id (str | UUID) – The scan identifier.

      - range_start (int | None) – Optional start index for paginated results.

      - range_end (int | None) – Optional end index for paginated results.

    Returns:

      The full HTTP response of the GET /scans/{id}/results request.

    Raises:

      - InvalidArgumentType – If provided range values are not integers.

      - httpx.HTTPStatusError – If the request fails and exceptions are not suppressed.

    Return type:

      Response

    See: GET /scans/{id}/results in the openvasd API documentation.

  get_status(scan_id)

    Retrieve the status of a scan.

    Parameters:

      scan_id (str | UUID) – The scan identifier.

    Returns:

      The full HTTP response of the GET /scans/{id}/status request.

    Raises:

      httpx.HTTPStatusError – If the request fails and exceptions are not suppressed.

    Return type:

      Response

    See: GET /scans/{id}/status in the openvasd API documentation.

  start(scan_id)

    Start the scan identified by the given scan ID.

    Parameters:

      scan_id (str | UUID) – The unique identifier of the scan.

    Returns:

      HTTP status code (e.g., 200) if successful, or error code (e.g., 404, 500) if the request fails, and safe is False.

    Raises:

      httpx.HTTPStatusError – If the request fails and exceptions are not suppressed.

    Return type:

      int

    See: POST /scans/{id} with action=start in the openvasd API documentation.

  stop(scan_id)

    Stop the scan identified by the given scan ID.

    Parameters:

      scan_id (str | UUID) – The unique identifier of the scan.

    Returns:

      HTTP status code (e.g., 200) if successful, or error code (e.g., 404, 500) if the request fails, and safe is False.

    Raises:

      httpx.HTTPStatusError – If the request fails and exceptions are not suppressed.

    Return type:

      int

    See: POST /scans/{id} with action=stop in the openvasd API documentation.

class Target

  Represents the scan target configuration.

  hosts

    List of target IPs or hostnames.

    Type:

      list[str]

  excluded_hosts

    List of IPs or hostnames to exclude.

    Type:

      list[str]

  ports

    List of port configurations.

    Type:

      list[gvm.protocols.http.openvasd._scans.Port]

  credentials

    List of credentials to use during scanning.

    Type:

      list[gvm.protocols.http.openvasd._scans.Credential]

  alive_test_ports

    Port ranges used to test if hosts are alive.

    Type:

      list[gvm.protocols.http.openvasd._scans.Port]

  alive_test_methods

    Methods used to check if hosts are alive (e.g., “icmp”).

    Type:

      list[str]

  reverse_lookup_unify

    Whether to unify reverse lookup results.

    Type:

      bool

  reverse_lookup_only

    Whether to rely solely on reverse DNS lookups.

    Type:

      bool

  __init__(hosts, excluded_hosts=<factory>, ports=<factory>, credentials=<factory>, alive_test_ports=<factory>, alive_test_methods=<factory>, reverse_lookup_unify=False, reverse_lookup_only=False)

class VTParameter

  Represents a parameter for a specific vulnerability test.

  id

    Identifier of the VT parameter.

    Type:

      int

  value

    Value to assign to the parameter.

    Type:

      str

  __init__(id, value)

class VTSelection

  Represents a selected vulnerability test (VT) and its parameters.

  oid

    The OID (Object Identifier) of the VT.

    Type:

      str

  parameters

    A list of parameters to customize VT behavior.

    Type:

      list[gvm.protocols.http.openvasd._scans.VTParameter]

  __init__(oid, parameters=<factory>)