qualys-cli.

A unified command-line interface for the Qualys Cloud Platform — VM, PC, WAS, TotalCloud, Cloud Agent, Container Security, CSAM, Patch, ETM, and more.

28Modules

228Commands

v0.1.3Version

3.12+Python

MITLicense

1 Install

pipx install qualys-cli

2 Configure

qualys-cli configure

3 Run

qualys-cli vm host list

4 Pipe to JSON

qualys-cli mode agentic

Global flags & output modes

Two persistent output modes govern the default rendering: interactive (rich tables, colours, animated cyber-themed spinner — the default) and agentic (clean JSON, no decoration — best for scripts, CI, and AI agents).

Flag / command	What it does
`qualys-cli mode`	Show current output mode for the active profile
`qualys-cli mode agentic`	Switch to agentic (JSON) output persistently
`qualys-cli mode interactive`	Switch back to rich-table output
`--format json\|jsonl\|yaml\|table\|csv\|tsv\|markdown`	One-shot per-command output override. Note: `csv`, `tsv`, and `markdown` auto-uncap (no 25-row truncation) since they're typically piped to spreadsheets / tickets.
`--limit 0`	Remove the default 25-row table cap (table format only — exports already uncap automatically)
`--output-file results.json`	Dump full data to a file (JSON / YAML / CSV / NDJSON by extension)
`--where field=value` · `field!=v` · `field~regex` · `field>=N` · `field>N` · `field<=N` · `field<N`	Post-filter rows after extraction. Numeric coercion when both sides parse as numbers; field names match case-insensitively (e.g. `severity` matches `SEVERITY`).
`--columns name,id,status`	Override default table columns
`--sort field[:asc\|:desc]` · `--sort-by FIELD [--sort-desc]`	Sort rows in memory (case-insensitive field match). `--sort` is the terse form; `--sort-by` + `--sort-desc` is the verbose pair.
`--jq '.path[].name'`	jq-lite expression on the parsed payload (dotted keys, `[]` flatten, `[N]` index)
`--dry-run` / `--explain`	Print the resolved HTTP request and exit (no network I/O)
`-v` / `-vv`	Log requests and response sizes; secrets and Authorization headers redacted
`--profile NAME`	Select a named credential profile
`--version` / `-V`	Print version and exit
`QUALYS_OUTPUT_MODE=agentic`	Per-shell override for output mode
`QUALYS_PROFILE=NAME`	Per-shell profile override
`QUALYS_URL` / `QUALYS_GATEWAY_URL`	Override platform / gateway URLs (otherwise auto-detected)
`QUALYS_USERNAME` / `QUALYS_PASSWORD`	Per-shell credential override (no keyring write)
`QUALYS_AUDIT_LOG=off`	Disable audit logging for the current shell
`QUALYS_AUDIT_FSYNC=1`	fsync() each audit line (SIEM-grade durability)
`QUALYS_AUDIT_HMAC=0`	Disable tamper-evident HMAC chaining
`QUALYS_TIMEOUT` / `QUALYS_CONNECT_TIMEOUT`	Per-call timeouts (seconds)
`QUALYS_MAX_RETRIES`	Retry attempts (default 4)
`QUALYS_BACKOFF_BASE` / `QUALYS_BACKOFF_CAP`	Tune full-jitter backoff window
`QUALYS_BODY_LIMIT_BYTES`	Refuse responses larger than N bytes (default 250 MB)
`QUALYS_NO_FLAIR=1`	Disable the cyber-themed cycling spinner
`QUALYS_CACHE=off` / `QUALYS_CACHE_TTL`	Control the ETag-aware response cache

Security & resiliency

Every call is wrapped in retry-with-jitter, audit logging with correlation IDs, and a typed exception hierarchy with deterministic exit codes. Secrets never reach disk, logs, or stderr.

Credential storage

Passwords stored in the OS keyring (macOS Keychain / Linux Secret Service / Windows Credential Manager). Config file is 0600.

Secret redaction

Argv, query strings, request bodies, and verbose logs are scrubbed before any persistence. JWT tokens are summarised as a stable jwt:<sha256-prefix> fingerprint.

Audit log (JSONL, HMAC-chained)

Default ~/.config/qualys-cli/audit.log. One JSON object per lifecycle event and HTTP call, each cryptographically chained to the previous via HMAC-SHA-256. qualys-cli verify-audit detects tampering. Size-rotates at 10 MB.

Correlation IDs

Each invocation gets one X-Correlation-ID; each attempt gets an X-Request-ID. Both are sent on the wire and stamped into every audit and error record.

Retry & backoff

Full-jitter exponential backoff on 408, 425, 429, 500, 502, 503, 504, and transport errors. Honours Retry-After on 429/503. JWT auto-refreshes on 401 without consuming the retry budget.

Typed errors

Auth, NotFound, RateLimit, Timeout, Network, Server, Configuration — each with a distinct exit code (3, 4, 5, 6, 6, 7, 2) and a closed-set type in the JSON error payload.

Tunables

Override timeouts and retry behaviour via env: QUALYS_TIMEOUT, QUALYS_CONNECT_TIMEOUT, QUALYS_MAX_RETRIES, QUALYS_BACKOFF_BASE, QUALYS_BACKOFF_CAP, QUALYS_MAX_CONNECTIONS, QUALYS_MAX_KEEPALIVE.

Defensive defaults

Destructive operations require --yes. No telemetry. No update checks. The only outbound traffic is to the configured Qualys platform URL.

Idempotent retries

Only GET / HEAD / DELETE retry by default; POST / PUT / PATCH require explicit opt-in to avoid silent double-submits (vm scan launch never fires twice). Read-shaped /search/ POSTs are auto-detected.

Scope-restricted profiles

allowed_modules in a profile pins it to a subset of API surfaces (e.g. analyst account → vm only). Out-of-scope commands are refused before any HTTP call.

PII redaction

redact_fields in a profile scrubs response payloads before rendering — name, email, ssn, etc. Mirrors the existing argv / body redaction so PII never reaches stdout, logs, or files.

Body-size guard

Refuses to load > 250 MB into memory unless --output-file streams to disk. Prevents OOM on legacy report exports.

Connection-error taxonomy

DNS / TLS / refused / reset / timeout each map to a distinct error class with its own hint, so a misconfigured proxy doesn't masquerade as a credential problem.

Concurrency safety

Per-profile JWT-exchange lock so parallel pagination workers don't clobber each other's tokens. Audit-log writes re-resolve the file handle inside the lock so rotation is safe under high call volume.

Cache hygiene

The local ETag cache only stores 200 OK responses with non-empty bodies. 304 Not Modified serves the previously-cached body without overwriting it; 4xx / 5xx never poison the cache.

Read-only preflight

qualys-cli doctor exchanges a fresh JWT to verify credentials but discards it — running doctor on a cron does NOT mutate config.toml or invalidate other workers' cached tokens.

Bind-anywhere safety

qualys-cli serve refuses non-loopback hosts unless the operator explicitly passes --allow-public-network. The server has no auth on the wire, so this prevents an accidental --host 0.0.0.0 from exposing the CLI to the LAN.

Saved-query safety

Query names are restricted to [A-Za-z0-9_-]+ with a defence-in-depth check that the resolved path stays inside the queries directory. TOML serialisation goes through json.dumps so descriptions / args containing quotes, backslashes, newlines, or Unicode round-trip safely.

MCP & integrations — wire qualys-cli into Claude / Cursor / agents

qualys-cli mcp runs a Model Context Protocol stdio server. Every CLI command is published as an MCP tool whose JSON Schema is generated from its option signature, so Claude Desktop, Cursor, and any MCP-aware agent can drive the full Qualys API surface natively.

No console output by design

MCP servers speak JSON-RPC on stdin / stdout; any extra output would corrupt the protocol. So when you run qualys-cli mcp in a terminal it just sits silently waiting for a client to write a request to stdin. To verify it's alive, paste this and press Enter:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}

You should see a single JSON line back. Ctrl-C to exit.

1 · Find the Claude Desktop config file

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

2 · Use the absolute path to qualys-cli

Claude Desktop launches MCP servers without a shell, so qualys-cli on PATH won't be found. Resolve the absolute path:

which qualys-cli
# e.g. /Users/you/.local/bin/qualys-cli  (pipx install)
#      /Users/you/repo/.venv/bin/qualys-cli  (uv venv)

3 · Add to `claude_desktop_config.json`

{
  "mcpServers": {
    "qualys-cli": {
      "command": "/absolute/path/to/qualys-cli",
      "args": ["mcp"],
      "env": {
        "QUALYS_PROFILE": "default",
        "QUALYS_AUDIT_LOG": "/Users/you/.config/qualys-cli/audit.log"
      }
    }
  }
}

If you already have other MCP servers, add the "qualys-cli": {…} entry alongside them inside the existing mcpServers object — don't create a second block.

4 · Fully relaunch Claude Desktop

Cmd-Q (not just close the window) then reopen. Servers are only re-scanned on a full relaunch. In a new chat, click the 🔌 tools icon at the bottom-right of the input box — you should see qualys-cli with ~227 tools listed using underscore-separated names (vm_host_list, csam_asset_list, pm_job_list, csam_vuln_list-easm, …). Anthropic's tool-name validator requires ^[a-zA-Z0-9_-]{1,64}$, so the MCP server uses _ as the path separator (not .); CLI verbs with hyphens such as rotate-jwt are preserved intact.

5 · Troubleshoot via the Claude Desktop logs

tail -f ~/Library/Logs/Claude/mcp*.log

Log / error says	Fix
`spawn qualys-cli ENOENT`	Use the absolute path to the binary (step 2).
`Error: No username for profile 'default'`	Run `qualys-cli configure` once in a terminal so creds land in the keyring, then relaunch Claude.
`JSONDecodeError` on first frame	Something on `stdout` is corrupting the protocol. Make sure no `print()` lurks in a startup hook.
`EPIPE` on shutdown	Harmless — expected when Claude tears the server down.
`tools.N.FrontendRemoteMcpToolDefinition.name: String should match pattern '^[a-zA-Z0-9_-]{1,64}$'`	Upgrade `qualys-cli` — older builds emitted tool names with dots (`vm.host.list`); current builds use underscores (`vm_host_list`) which match Anthropic's validator.
Validator complains about `id` being null / missing, plus `unrecognized_keys: ["error"]` on responses	Upgrade `qualys-cli` — older builds responded to JSON-RPC notifications (e.g. `notifications/initialized`) with a method-not-found `error` frame and `id: null`, which Anthropic's strict validator rejects. Current builds drop notifications silently and only respond to actual requests.

Test before wiring Claude Desktop — use the official MCP inspector

Browse the tool catalogue, fire tools/list and tools/call interactively, and see every JSON-RPC frame on the wire — far easier than tailing logs:

npx @modelcontextprotocol/inspector qualys-cli mcp

Audit trail of MCP-driven calls

The MCP server runs each tool by shelling out to a fresh qualys-cli process in agentic mode, so every Claude-driven invocation lands in the audit log with its own correlation ID — exactly as if a human had typed the command:

tail -f ~/.config/qualys-cli/audit.log | jq .

Cursor & other MCP clients

Cursor's ~/.cursor/mcp.json uses the same shape as Claude Desktop's config — drop in the identical "qualys-cli" entry. Any MCP-aware client (Continue.dev, Cline, Zed AI, custom agents via the @modelcontextprotocol/sdk packages) can drive it too — the JSON-RPC interface is standard.

Alternative — local HTTP bridge

Prefer REST over MCP? qualys-cli serve boots a localhost HTTP server on 127.0.0.1:8765 with three endpoints: GET / (health), GET /tools (catalogue), POST /run (invoke a command). Useful for low-code tools, Postman collections, and dashboards.

No commands match your search

Try a shorter term, or press Esc to clear.

Vulnerability Management

Hosts, scans, knowledgebase, option profiles, reports, schedules, scanner appliances

Basic auth · XML17 commands

On this pagescan4 host2 kb1 option-profile3 report4 scan-schedule2 appliance1

scan4

vm › scan › list

qualys-cli vm scan list

List VM scans.

qualys-cli.

1 Install

2 Configure

3 Run

4 Pipe to JSON

Global flags & output modes

Security & resiliency

MCP & integrations — wire qualys-cli into Claude / Cursor / agents

No console output by design

1 · Find the Claude Desktop config file

2 · Use the absolute path to qualys-cli

3 · Add to claude_desktop_config.json

4 · Fully relaunch Claude Desktop

5 · Troubleshoot via the Claude Desktop logs

Test before wiring Claude Desktop — use the official MCP inspector

Audit trail of MCP-driven calls

Cursor & other MCP clients

Alternative — local HTTP bridge

No commands match your search

scan4

host2

kb1

option-profile3

report4

scan-schedule2

appliance1

scan2

scan-schedule2

policy2

posture1

option-profile1

webapp7

scan9

finding9

auth-record4

option-profile5

schedule7

report8

catalog4

dns5

import2

connector1

evaluation1

report3

rule5

exception2

iac2

cdr1

agent7

scan1

act-key4

config3

image5

container4

registry3

sensor2

report4

asset4

easm9

vuln3

domain2

report2

component2

business2

connector1

org2

job8

mitigation3

patch3

report4

asset1

report7

ip2

network2

domain2

group2

record1

vault2

neo4j2

nginx2

3 · Add to `claude_desktop_config.json`