Metadata-Version: 2.4
Name: qualys-cli-mcp
Version: 0.1.1
Summary: Model Context Protocol (MCP) server giving any LLM secure, audited access to the Qualys Cloud Platform (VM, PM, WAS, TotalCloud, Container Security, CSAM, and more).
Project-URL: Homepage, https://www.qualys.com
Author: qualys-cli-mcp contributors
License-Expression: MIT
License-File: LICENSE
Keywords: llm,mcp,model-context-protocol,qualys,security,vulnerability-management
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.0
Requires-Dist: qualys-cli>=0.1.1
Description-Content-Type: text/markdown

# qualys-cli-mcp

[![PyPI](https://img.shields.io/pypi/v/qualys-cli-mcp.svg)](https://pypi.org/project/qualys-cli-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/qualys-cli-mcp.svg)](https://pypi.org/project/qualys-cli-mcp/)
[![License](https://img.shields.io/pypi/l/qualys-cli-mcp.svg)](https://pypi.org/project/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

```bash
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.

```bash
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`:

```json
{
  "mcpServers": {
    "qualys": {
      "command": "qualys-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:

```bash
export QUALYS_MCP_ALLOWED_MODULES="vm,csam,ca"
```

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

```bash
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
