qualys-cli-mcp 0.1.0__py3-none-any.whl

qualys_cli_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,219 @@
+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

qualys_cli_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+qualys_mcp/__init__.py,sha256=jHDLhC0M6NrrtEMfV9UaUxrBr8CibJnU4yA9aYYdjwE,78
+qualys_mcp/__main__.py,sha256=cd4U3rpWb0QpoErwLWN-KaQPrquhPCPPleff7bIhQPE,78
+qualys_mcp/auth.py,sha256=scgnrxE22wybv3RtEjiXa88rD7qB55s0XNx7Fu29Tx8,3573
+qualys_mcp/server.py,sha256=UlIBP6syqv0mWVLCuf0GYvK_AzIK8qhpxwUawgI_3vw,42719
+qualys_mcp/tenant.py,sha256=MHlK_4jW3HvaIyi_I0bWKubfwEvTjkR4Eop_EKLIvOQ,2292
+qualys_mcp/tools.py,sha256=PG41pze1JhY4F_DrroNzr3nCvwiAcyT2o54IgvupPy4,8005
+qualys_cli_mcp-0.1.0.dist-info/METADATA,sha256=GjiW6Z0mtK2emhut94VdI0bu8_efkXkeglFPsjaGQmw,7215
+qualys_cli_mcp-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+qualys_cli_mcp-0.1.0.dist-info/entry_points.txt,sha256=_VuZDuFoPSK9XFCZ8yVVrop4Fbr7f-2DK4bSeZQnWsY,54
+qualys_cli_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=AZcPTOxR2q5jykiRf6MuuzZQy-yMO-wKTJYtSNN4HmQ,1084
+qualys_cli_mcp-0.1.0.dist-info/RECORD,,

qualys_cli_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

qualys_cli_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+qualys-mcp = qualys_mcp.server:main

qualys_cli_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qualys-cli-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qualys_mcp/__init__.py

@@ -0,0 +1 @@
+"""qualys-mcp — MCP server that wraps qualys-cli as a pass-through tool."""

qualys_mcp/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as: python -m qualys_mcp"""
+from .server import main
+
+main()

qualys_mcp/auth.py

@@ -0,0 +1,110 @@
+# qualys_mcp/auth.py
+"""Authentication providers for multi-tenant qualys-mcp.
+
+Two modes:
+  1. API keys (StaticTokenVerifier) - simple, good for server-to-server
+  2. OAuth 2.1 (JWTVerifier) - validates JWT Bearer tokens from an external IdP
+
+Both use FastMCP's built-in auth infrastructure. Inside tool functions,
+call `get_access_token()` to get the authenticated client's identity.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+log = logging.getLogger("qualys-mcp")
+
+
+def create_api_key_verifier(
+    keys: dict[str, dict[str, Any]],
+) -> Any:
+    """Create a StaticTokenVerifier for API key authentication.
+
+    Note: StaticTokenVerifier stores keys in plain text in memory. The security
+    boundary is the config file itself (which should be file-permission restricted).
+    For deployments requiring hashed key storage, replace with a custom TokenVerifier.
+
+    Args:
+        keys: mapping of API key string to {"client_id": str, "scopes": list[str]}
+
+    Returns:
+        A FastMCP StaticTokenVerifier that validates Bearer tokens against the key set.
+    """
+    from fastmcp.server.auth.providers.jwt import StaticTokenVerifier
+
+    token_map: dict[str, dict[str, Any]] = {}
+    for key_value, meta in keys.items():
+        token_map[key_value] = {
+            "client_id": meta["client_id"],
+            "scopes": meta.get("scopes", []),
+        }
+
+    verifier = StaticTokenVerifier(tokens=token_map)
+    log.info("API key auth: %d keys configured", len(token_map))
+    return verifier
+
+
+def create_oauth_provider(
+    issuer_url: str,
+    audience: str,
+    algorithm: str | None = None,
+) -> Any:
+    """Create a JWTVerifier for OAuth 2.1 token validation.
+
+    Validates Bearer tokens (JWTs) issued by the configured authorization server.
+    Uses JWKS discovery from the issuer's .well-known endpoint.
+
+    Args:
+        issuer_url: OAuth issuer URL (e.g. "https://auth.cisco.com")
+        audience: Expected audience claim in tokens
+        algorithm: Allowed signing algorithm (default: "RS256")
+
+    Returns:
+        A FastMCP JWTVerifier that validates JWTs against the issuer's JWKS.
+    """
+    from fastmcp.server.auth.providers.jwt import JWTVerifier
+
+    verifier = JWTVerifier(
+        jwks_uri=f"{issuer_url.rstrip('/')}/.well-known/jwks.json",
+        issuer=issuer_url,
+        audience=audience,
+        algorithm=algorithm or "RS256",
+    )
+    log.info("OAuth auth: issuer=%s audience=%s", issuer_url, audience)
+    return verifier
+
+
+def load_api_keys_from_tenant_config(config_path: str) -> dict[str, dict[str, Any]]:
+    """Load API keys from the tenant config file.
+
+    Reads [api_keys] section:
+        [api_keys.<name>]
+        key = "bearer-token-value"
+        client_id = "tenant-client-id"
+        scopes = ["qualys:read"]
+    """
+    import tomllib
+    from pathlib import Path
+
+    path = Path(config_path)
+    if not path.is_file():
+        return {}
+
+    with open(path, "rb") as f:
+        data = tomllib.load(f)
+
+    keys: dict[str, dict[str, Any]] = {}
+    for name, cfg in data.get("api_keys", {}).items():
+        for required in ("key", "client_id"):
+            if required not in cfg:
+                raise ValueError(f"api_keys.{name} missing required field {required!r}")
+        key_value = cfg["key"]
+        if key_value in keys:
+            log.warning("duplicate API key in config (api_keys.%s overwrites previous)", name)
+        keys[key_value] = {
+            "client_id": cfg["client_id"],
+            "scopes": cfg.get("scopes", ["qualys:read"]),
+        }
+    return keys