qualys-cli-mcp 0.1.0

MCP server that wraps qualys-cli — gives any LLM access to the Qualys Cloud Platform

qualys-cli-mcp

MCP server that gives any LLM access to the Qualys Cloud Security Platform via qualys-cli.

Architecture

LLM (Claude, GPT, Llama, etc.)
    │  MCP protocol (stdio or SSE)
    ▼
qualys-cli-mcp (this server — 2 tools)
    │  subprocess
    ▼
qualys-cli (auth, retry, pagination, 273 API endpoints)
    │  HTTPS
    ▼
Qualys Cloud Platform

The MCP server is a thin pass-through. It executes qualys-cli commands as subprocesses and returns parsed JSON. All authentication, retry logic, pagination, and error handling is done by qualys-cli.

Install

pip install qualys-cli-mcp

This automatically pulls qualys-cli as a dependency.

Or install from source:

pip install git+https://stash.intranet.qualys.com/scm/aet/qualys-cli-mcp.git

Configure Credentials

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

qualys-cli configure

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

Usage with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

No credentials in the config — they're pulled from the OS keyring at runtime.

Usage with VS Code / Cursor

Add to your MCP settings:

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

Tools

The server exposes 2 tools:

qualys_cli(command)

Execute any qualys-cli command and get JSON back.

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("pm job list --format json")
qualys_cli("was finding list --severity 5 --format json")

qualys_cli_help()

Get the full command reference — all modules, resources, actions, common patterns, and gotchas.

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 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 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 whitelist
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 Controls

Command Injection Prevention

All commands are validated before execution:

• Shell metacharacters (;, |, `, $, {}, etc.) are blocked
• Only known qualys-cli modules are accepted
• Commands executed via explicit argv list — never through a shell

Credential Security

• Credentials stored in OS keyring only — never in env vars, config files, or MCP client config
• Error messages scrubbed before returning to LLM (passwords, tokens, Bearer values redacted)
• ANSI escape codes stripped from all error output

Module Whitelist

Restrict which Qualys modules are accessible:

export QUALYS_MCP_ALLOWED_MODULES="vm,csam,ca"

Read-Only Mode

Block all write/destructive operations:

export QUALYS_MCP_DENY_WRITE=1

Blocked actions: launch, create, delete, cancel, update, import, activate, deactivate, uninstall, purge, enable, disable, etc.

Response Truncation

Responses exceeding 800KB are automatically truncated to stay under the MCP 1MB transport limit. Key fields (QID, TITLE, SEVERITY, CVE_LIST) are always preserved. Verbose fields (SOLUTION, DIAGNOSIS, CONSEQUENCE) are stripped first.

Resilience

• Automatic retry on transient failures (rate limit, timeout, server errors) with exponential backoff
• Configurable command timeout (default 120s) with process kill on expiry
• 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 audit log with tamper detection
• OS keyring credential storage
• Secret redaction in all logs
• Correlation IDs on every request
• Body size guards (250MB cap)
• Idempotent-only retries (POST/PUT/PATCH never auto-retry)

License

MIT