OpenVAS MCP Server

Official MCP server for Greenbone Vulnerability Management, communicates with GVM

GitHub
4

Tài liệu

Greenbone Logo

OpenVAS MCP Server

A Model Context Protocol server for Greenbone Vulnerability Management (GVM/OpenVAS), written in Rust. It exposes the complete rust-gvm-api REST contract as typed MCP tools, forwards each caller's gvmd identity to the gateway, and lets an AI assistant manage targets, tasks, scan configurations, reports and compliance audits through a single binary.

Table of Contents

Requirements

  • A running rust-gvm-api REST gateway (contract 0.5.0) in front of gvmd; verified end to end against gvmd 26.43.0 / GMP 22.8
  • Rust 1.90 or later, to build from source
  • Docker, for the container image and the live end-to-end tests

No GVM installation is required to build or test the server: the test suite runs against a mock gateway, and the server itself never speaks GMP.

Installation

Docker, streamable HTTP on http://localhost:8000/mcp. Images are published under immutable release tags only (no latest); take vX.Y.Z from the releases:

docker run --rm \
  -e GVM_GATEWAY_URL=http://gateway:8080 \
  -e GVM_USERNAME=admin \
  -e GVM_PASSWORD=secret \
  -p 127.0.0.1:8000:8000 \
  ghcr.io/greenbone-hive/openvas-mcp:vX.Y.Z

Binary over stdio, from a release or cargo build --release, registered with the MCP client:

{
  "mcpServers": {
    "openvas": {
      "command": "/path/to/gvm-mcp",
      "env": {
        "GVM_GATEWAY_URL": "http://localhost:8080",
        "GVM_USERNAME": "admin",
        "GVM_PASSWORD": "secret"
      }
    }
  }
}

Start with the openvas_test_connection tool: it checks gateway liveness and readiness, the gvmd version and the forwarded identity. Release archives, checksums, the compose example and client registration for both transports are covered in docs/installation.md.

Configuration

Every setting is an environment variable and a CLI flag of the same meaning (gvm-mcp --help). GVM_PASSWORD_FILE points at a mounted secret and wins over GVM_PASSWORD.

RequiredVariableDefaultDescription
noGVM_GATEWAY_URLhttp://127.0.0.1:8080Origin of the rust-gvm-api gateway, without /api/v1
no*GVM_USERNAMEgvmd username of the fallback identity (stdio, and HTTP callers that send no Authorization)
no*GVM_PASSWORDgvmd password of the fallback identity; also read from GVM_PASSWORD_FILE
noMCP_TRANSPORTstdiostdio or streamable-http
noMCP_BIND_ADDR127.0.0.1:8000Listen address of the streamable-HTTP transport
noMCP_ALLOWED_HOSTSlocalhost,127.0.0.1,::1Host headers accepted by the HTTP transport (DNS-rebinding guard); * disables the check
noMCP_REQUIRE_CALLER_AUTHfalseReject HTTP tool calls without an Authorization header instead of serving them with the fallback identity
noGVM_TOOLSETSdefaultToolsets to expose: default, all or a comma-separated list
noGVM_READ_ONLYfalseExpose only non-mutating tools
noGVM_HTTP_TIMEOUT30Gateway HTTP timeout in seconds
noGVM_LOG_LEVELinfoLog level when RUST_LOG is unset: error, warn, info, debug, trace

* required for stdio clients; HTTP callers may instead authenticate as themselves.

Authentication

The server holds no session and invents no authentication of its own. The Authorization value of each gateway call is resolved per request: the inbound MCP request's Authorization header when present (so every streamable-HTTP caller authenticates as themselves with Basic gvmd credentials or a gateway session token), otherwise a Basic header built from GVM_USERNAME / GVM_PASSWORD. Without either, the gateway answers 401 and the tool reports it.

The one exception is asynchronous report exports: the gateway cancels an export job when the session that created it ends, so openvas_export_report opens a job-bound gateway session with the caller's credentials and closes it after the download, on cancel or when the job reaches a terminal state.

For HTTP deployments, MCP_REQUIRE_CALLER_AUTH=true keeps the fallback identity for stdio only, MCP_ALLOWED_HOSTS guards against DNS rebinding, and TLS belongs on a reverse proxy in front of the server. The gateway client never follows redirects, rejects credentials embedded in the gateway URL, redacts secrets from debug output and caps downloaded artifacts at 3 MB. Details in docs/authentication.md.

Toolsets

194 tools in 25 toolsets. default is every toolset except identity, which is always opt-in; GVM_READ_ONLY removes every mutating tool from the listing.

gvm-mcp --list-toolsets                     # the 25 toolsets
gvm-mcp --toolsets targets,tasks,reports    # scoped surface
gvm-mcp --toolsets default,identity         # include user administration
gvm-mcp --read-only                         # reads only
SelectionTools
default171
default, read-only89
default,identity194
default,identity, read-only99

List tools return summarized rows with pagination; get tools return the gateway's full JSON. The toolset reference, the definition of a mutating tool and the availability notes are in docs/toolsets.md; scan, audit, export and deletion flows are in docs/usage.md.

Development

cargo build --release   # target/release/gvm-mcp
cargo test              # unit and mock-gateway tests, no GVM needed
cargo fmt --all && cargo clippy --all-targets --all-features -- -D warnings
python3 scripts/gateway_sync_check.py --spec ../rust-gvm-api/spec/rest-api --write-doc

The tool surface mirrors the gateway's spec/rest-api: 195 of the contract's 199 operations map to exactly one tool each, and the drift check above fails on any missing, stale or broken mapping. CI runs the same gate plus the drift check against the gateway's main branch. A live end-to-end suite, gated behind #[ignore], exercises every endpoint against a real gateway and gvmd; see docs/development.md.

Documentation

Maintainer

This project is maintained by Greenbone AG

License

Copyright (C) 2026 Greenbone AG

Licensed under the GNU Affero General Public License v3.0 or later.