Metadata-Version: 2.4
Name: qualys-cli-mcp
Version: 0.1.0
Summary: MCP server that wraps qualys-cli — gives any LLM access to the Qualys Cloud Platform
Project-URL: Homepage, https://github.com/qualys/qualys-cli-mcp
Project-URL: Documentation, https://github.com/qualys/qualys-cli-mcp#readme
Project-URL: Issues, https://github.com/qualys/qualys-cli-mcp/issues
Project-URL: Changelog, https://github.com/qualys/qualys-cli-mcp/blob/main/CHANGELOG.md
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

MCP server that gives any LLM access to the Qualys Cloud Security Platform via [qualys-cli](https://stash.intranet.qualys.com/projects/AET/repos/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

```bash
pip install qualys-cli-mcp
```

This automatically pulls `qualys-cli` as a dependency.

Or install from source:

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

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

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

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

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

### Read-Only Mode

Block all write/destructive operations:

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