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:
- krb5¶
Optional Kerberos credentials.
- Type:
- usk¶
Optional user/SSH key credentials.
- Type:
- snmp¶
Optional SNMP credentials.
- Type:
- __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:
- __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:
- credentials¶
List of credentials to use during scanning.
- Type:
- alive_test_ports¶
Port ranges used to test if hosts are alive.
- Type:
- 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)¶