openvas-sdk

High-level Python SDK for Greenbone OpenVAS / GVM — trigger scans, monitor status, stop/resume, and retrieve vulnerability results over the Greenbone Management Protocol (GMP).

Built on top of the official python-gvm library with typed models and ergonomic resource managers.

Community-maintained SDK. This project is independently maintained and is not affiliated with, endorsed by, or sponsored by any third-party organization, project, or its contributors.

Features

• Connect via TLS, SSH, or local Unix socket
• Network & web scans with profile-based config resolution
• Authenticated network scans with SSH, SMB, ESXi, and SNMP credentials
• Task control — start, stop (pause), resume, wait for completion
• Reports & results — list findings, download exports, filter by severity
• Typed API — dataclass models for targets, tasks, reports, and results
• PyPI ready — modern pyproject.toml with hatchling

Installation

pip install openvas-sdk

Development install:

pip install -e ".[dev]"

Quick start

from openvas_sdk import ConnectionConfig, OpenVASClient, ScanType

config = ConnectionConfig.tls(
    hostname="192.168.1.10",
    username="admin",
    password="secret",
)

with OpenVASClient(config) as client:
    scan = client.scans.create(
        name="Weekly network scan",
        hosts=["10.0.0.0/24"],
        scan_type=ScanType.NETWORK,
        start=True,
    )

    final = client.scans.wait(scan.task_id, poll_interval=15)
    print(final.status, final.progress)

    if final.report_id:
        report = client.reports.get(final.report_id)
        print(report.high_count, report.medium_count, report.low_count)

Connection types

TLS (remote GVM, port 9390)

config = ConnectionConfig.tls(
    hostname="gvm.example.com",
    username="admin",
    password="secret",
    port=9390,
)

SSH (tunnel to gvmd Unix socket)

config = ConnectionConfig.ssh(
    hostname="gvm.example.com",
    username="admin",
    password="secret",
    ssh_username="gvmuser",
    ssh_password="sshsecret",
)

Unix socket (local GCE / appliance)

config = ConnectionConfig.unix_socket(
    username="admin",
    password="secret",
    socket_path="/run/gvmd/gvmd.sock",
)

Scan types

Type	Description
ScanType.NETWORK	Standard network vulnerability scan
ScanType.WEB	Web application checks (via NVT families)
ScanType.FULL	Deep / ultimate profiles
ScanType.DISCOVERY	Host and service discovery
ScanType.HOST	Host discovery only

Use ScanProfile to pick a named config (e.g. ScanProfile.FULL_AND_FAST) or pass config_id directly.

Task lifecycle

with OpenVASClient(config) as client:
    task = client.tasks.create(
        name="Manual scan",
        config_id="<config-uuid>",
        target_id="<target-uuid>",
    )

    report_id = client.tasks.start(task.id)
    client.tasks.stop(task.id)      # pause / interrupt (resumable)
    client.tasks.resume(task.id)    # continue
    status = client.tasks.get(task.id)

GMP does not expose a dedicated pause command; stop interrupts the scan without deleting the task.

Authenticated network scans

Authenticated scans log into target hosts to run deeper checks (installed packages, patch levels, local configs). Pass a TargetAuth bundle when creating a scan; the SDK creates GVM credentials and attaches them to the target.

SSH only

from openvas_sdk import TargetAuth

auth = TargetAuth.ssh("scanner", "secret", port=22)

scan = client.scans.create_authenticated(
    name="Linux authenticated scan",
    hosts=["192.168.1.100"],
    auth=auth,
    start=True,
)

SSH key

private_key = open("id_rsa").read()
auth = TargetAuth.ssh_key("scanner", private_key, passphrase="optional")

SMB / Windows

auth = TargetAuth.smb(r"DOMAIN\scanner", "secret")

Mixed environment (Linux + Windows)

auth = TargetAuth(
    ssh_username="root",
    ssh_password="linux-secret",
    smb_username=r"DOMAIN\scanner",
    smb_password="windows-secret",
)

SNMP

auth = TargetAuth.snmp_v2c("public")
# or SNMPv3:
auth = TargetAuth.snmp_v3("snmpuser", "authpass", privacy_password="privpass")

Convenience method

scan = client.scans.create_authenticated(
    name="Authenticated audit",
    hosts=["10.0.0.50"],
    auth=TargetAuth.ssh("admin", "secret"),
    start=True,
)
final = client.scans.wait(scan.task_id)

When auth is provided without an explicit profile, the SDK defaults to Full and deep for broader authenticated coverage.

You can also manage credentials directly via client.credentials.create_username_password(...) and pass credential IDs to client.targets.create(...).

One-shot scan

scan = client.scans.run(
    name="Full audit",
    hosts=["192.168.1.1"],
    scan_type=ScanType.FULL,
    timeout=7200,
)

Results & exports

findings = client.results.list(report_id=scan.report_id, min_severity=7.0)
for item in findings:
    print(item.threat, item.name, item.host, item.cve)

formats = client.reports.list_formats()
pdf = next(f for f in formats if f.name == "PDF")
data = client.reports.download(scan.report_id, pdf.id)

Requirements

• Python 3.10+
• A running Greenbone Vulnerability Manager (gvmd) instance
• GMP access enabled (TLS, SSH, or local socket)

Publishing

pip install build twine
python -m build
twine upload dist/*

Trademarks

Trademarks. Any product names, logos, or brands mentioned are the property of their respective owners. Their use is solely for identification and interoperability purposes and does not imply any affiliation, sponsorship, or endorsement.

Disclaimer

Disclaimer. This software is provided "as is", without any warranties, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, or non-infringement. The authors and copyright holders are not liable for any claims, damages, or other liabilities arising from the use of this software.

License

MIT — see LICENSE.