qualys-cli-mcp

A Model Context Protocol (MCP) server for the Qualys Cloud Platform. It gives any MCP-capable LLM or agent — Claude, GPT, Llama, and others — secure, audited access to Qualys Vulnerability Management, Patch Management, Web Application Scanning, TotalCloud (CSPM), Container Security, CSAM, and more, through a single hardened tool surface.

The server is a thin, security-focused layer over qualys-cli. The CLI handles authentication, retries, pagination, and JWT refresh; the MCP layer adds command validation, credential redaction, module allow-listing, read-only enforcement, response-size guards, and an append-only audit log.

Architecture

LLM (Claude, GPT, Llama, …)
    │  MCP protocol (stdio or SSE)
    ▼
qualys-cli-mcp (this server)
    │  subprocess (validated argv — never a shell)
    ▼
qualys-cli (auth, retry, pagination, 273 API endpoints)
    │  HTTPS
    ▼
Qualys Cloud Platform

Requirements

• Python 3.11 or newer (macOS, Linux, Windows)
• A configured qualys-cli profile (credentials are stored in the OS keyring)

Installation

pip install qualys-cli-mcp

qualys-cli is installed automatically as a dependency.

Configure credentials

Credentials are stored securely in the OS keyring (macOS Keychain, Linux Secret Service, Windows Credential Manager) — never in environment variables or plain-text config files.

qualys-cli configure

This prompts for your username and password, auto-detects your Qualys platform, and stores everything securely. This is a one-time setup.

Connect your MCP client

The server runs over stdio and needs no credentials in the client config — they are pulled from the OS keyring at runtime.

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "qualys": {
      "command": "qualys-cli-mcp"
    }
  }
}

VS Code / Cursor — add the same entry to your MCP settings. The config is identical across clients.

Tools

The server exposes 18 tools: 2 generic pass-through tools plus 16 curated, typed tools for the most common operations.

Generic tools

qualys_cli(command) — execute any qualys-cli command and receive structured JSON:

qualys_cli("vm scan list --state Running --format json")
qualys_cli("vm host detection --ips 10.0.0.1 --severities 4,5 --format json")
qualys_cli("csam asset list --filter asset.riskScore=GREATER=900 --format json --limit 10")
qualys_cli("was finding list --severity 5 --format json")

qualys_cli_help() — the full command reference: all modules, resources, actions, filter syntax, and common patterns.

Curated tools

Typed, parameter-validated wrappers for frequent tasks — the agent should prefer these over free-form commands:

Tool	Purpose
qualys_status()	Connectivity and authentication check
vm_scan_list()	List vulnerability scans by state
vm_host_list()	List scanned hosts by IP / range
vm_host_detection()	Detections for specific hosts
vm_kb_by_cve() / vm_kb_by_qid()	KnowledgeBase lookups
pc_posture_list()	Policy Compliance posture
pm_job_list() / pm_patch_list()	Patch jobs and catalog
was_finding_list()	Web application findings
tc_connector_list() / tc_cdr_findings()	TotalCloud connectors and CDR
cs_image_vulns()	Container image vulnerabilities
csam_riskiest_assets() / csam_asset_count()	Asset risk and inventory
ca_agent_list()	Cloud Agent inventory

Supported modules

Module	Coverage	Auth
VM (Vulnerability Management)	Scans, hosts, detections, KB, appliances, reports	Basic
PC (Policy Compliance)	Scans, policies, posture	Basic
PM (Patch Management)	Jobs, patches, mitigations, reports	JWT
ETM (Enterprise TruRisk)	Reports, findings	JWT
WAS (Web App Scanning)	Webapps, scans, findings, schedules, reports	Basic
TC (TotalCloud / CSPM)	Connectors, evaluations, rules, CDR	JWT
CA (Cloud Agent)	Agents, activation keys, config profiles	Basic / JWT
CS (Container Security)	Images, containers, registries, sensors	JWT
CSAM (Asset Management)	Assets, EASM, vulnerabilities, domains	JWT
Asset	IPs, networks, groups	Basic
ScanAuth	Auth records, vaults	Basic
User	User management	Basic
Sub	Subscription config	Basic

Configuration

All settings are optional — the server works with zero configuration after qualys-cli configure.

Variable	Default	Description
QUALYS_PROFILE	default	qualys-cli profile name
QUALYS_CLI_PATH	auto-detected	Path to the qualys-cli binary
QUALYS_MCP_TIMEOUT	120	Command timeout (seconds)
QUALYS_MCP_MAX_RESPONSE	800000	Max response bytes before truncation
QUALYS_MCP_MAX_RETRIES	2	Retries on transient failures (rate limit, timeout, 5xx)
QUALYS_MCP_ALLOWED_MODULES	all	Comma-separated module allow-list
QUALYS_MCP_DENY_WRITE	false	1 to block destructive commands
QUALYS_MCP_AUDIT_LOG	~/.config/qualys-cli/mcp-audit.jsonl	Audit log path (off to disable)

Security & governance

Command-injection prevention. Every command is validated before execution: shell metacharacters (;, |, `, $, {}, …) are rejected, only known Qualys modules are accepted, and commands run via an explicit argv list — never through a shell. Managed flags (--profile, --config) and their abbreviations cannot be overridden by the caller.

Credential security. Credentials live in the OS keyring only. Error messages and verbose output are scrubbed before returning to the model — passwords, tokens, Bearer values, and JWTs are redacted, and ANSI escape codes stripped.

Module allow-list. Restrict which Qualys modules are reachable:

export QUALYS_MCP_ALLOWED_MODULES="vm,csam,ca"

Read-only mode. Block all write and destructive operations (launch, create, delete, cancel, update, activate, purge, …):

export QUALYS_MCP_DENY_WRITE=1

Response truncation. Responses exceeding the size cap are truncated to stay under the MCP transport limit. Key fields (QID, TITLE, SEVERITY, CVE_LIST) are preserved; verbose fields (SOLUTION, DIAGNOSIS, CONSEQUENCE) are stripped first.

Resilience. Automatic retry on transient failures (rate limit, timeout, 5xx) with exponential backoff, a configurable command timeout with process kill on expiry, and an append-only audit log of every tool call.

Inherited from qualys-cli. Exponential backoff with jitter on 429/5xx, JWT auto-refresh on 401, HMAC-signed tamper-evident audit log, OS-keyring credential storage, secret redaction in all logs, per-request correlation IDs, body-size guards, and idempotent-only retries (POST/PUT/PATCH never auto-retry).

Multi-tenant & authenticated deployments

For remote or shared deployments, the server supports API-key and OAuth 2.1 (JWT) authentication with per-tenant credential profiles, module allow-lists, write policies, and OAuth scope enforcement (qualys:read, qualys:write, qualys:admin). See the bundled configuration reference for details.

License

MIT