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