qualys-cli-mcp 0.2.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (22) hide show
  1. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/CHANGELOG.md +23 -0
  2. qualys_cli_mcp-0.3.0/Dockerfile +70 -0
  3. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/PKG-INFO +7 -3
  4. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/README.md +5 -1
  5. qualys_cli_mcp-0.3.0/config/tenants.example.toml +46 -0
  6. qualys_cli_mcp-0.3.0/deploy/Dockerfile.standalone +21 -0
  7. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/deploy/README.md +15 -0
  8. qualys_cli_mcp-0.3.0/deploy/k8s/qualys-mcp.yaml +129 -0
  9. qualys_cli_mcp-0.3.0/deploy/k8s/secret.example.yaml +41 -0
  10. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/pyproject.toml +5 -14
  11. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/qualys_mcp/server.py +50 -1
  12. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/qualys_mcp/tools.py +60 -0
  13. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/tests/test_server_unit.py +71 -0
  14. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/.gitignore +0 -0
  15. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/LICENSE +0 -0
  16. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/qualys_mcp/__init__.py +0 -0
  17. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/qualys_mcp/__main__.py +0 -0
  18. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/qualys_mcp/auth.py +0 -0
  19. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/qualys_mcp/tenant.py +0 -0
  20. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/tests/test_auth.py +0 -0
  21. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/tests/test_tenant.py +0 -0
  22. {qualys_cli_mcp-0.2.0 → qualys_cli_mcp-0.3.0}/tests/test_tools.py +0 -0
@@ -6,6 +6,29 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.3.0] — 2026-11-03
10
+
11
+ ### Added
12
+ - Curated tools `etm_finding_list`, `etm_asset_list`,
13
+ `cs_k8s_namespace_list`, `cs_k8s_pod_list` (24 tools total).
14
+ - Command reference covers the qualys-cli 0.3.0 resources (pm
15
+ blocking-rule, etm finding/asset, was catalog/option-profile, ca isolation,
16
+ cs k8s-resource/secret-detector/qid-list/tag).
17
+ - The PyPI source distribution now includes the complete deployment kit —
18
+ Dockerfile, Kubernetes reference manifests (deploy/k8s/), tenants example
19
+ config, and deploy/README.md — so customers can build and deploy the
20
+ container image directly from the sdist while the official registry
21
+ image is pending. `pip download qualys-cli-mcp --no-binary :all:` →
22
+ `docker build`.
23
+
24
+ ### Fixed
25
+ - `cs k8s-resource namespace-list|namespace-get|pod-list|pod-get` were
26
+ classified as writes, so read-only deployments and `qualys:read` OAuth
27
+ tokens rejected them.
28
+
29
+ ### Changed
30
+ - Requires `qualys-cli>=0.3.0`.
31
+
9
32
  ## [0.2.0] — 2026-09-21
10
33
 
11
34
  ### Added
@@ -0,0 +1,70 @@
1
+ # qualys-cli-mcp — hardened container for corporate / Kubernetes deployment.
2
+ #
3
+ # Base: Chainguard's Wolfi Python images — maintained to zero known CVEs,
4
+ # glibc-based (manylinux wheels work), and the runtime image is shell-less
5
+ # and package-manager-less, so there is nothing to exploit and nothing to
6
+ # patch. Baseline comparison: python:3.12-slim carried 156 CVEs (44 HIGH)
7
+ # at the time of the switch; this image scans clean.
8
+ #
9
+ # Build: docker build -t qualys-cli-mcp:latest .
10
+ # Run: docker run --rm -p 8080:8080 \
11
+ # -e QUALYS_USERNAME=... -e QUALYS_PASSWORD=... \
12
+ # -v ./tenants.toml:/etc/qualys-mcp/tenants.toml:ro \
13
+ # qualys-cli-mcp:latest
14
+ #
15
+ # The image carries no credentials. Inject them via env (QUALYS_USERNAME /
16
+ # QUALYS_PASSWORD — in Kubernetes, from a Secret) or mount a pre-built
17
+ # ~/.config/qualys-cli profile volume. Multi-tenant deployments mount
18
+ # tenants.toml (see config/tenants.example.toml and deploy/k8s/).
19
+ #
20
+ # Default command serves streamable-http on 0.0.0.0:8080 with API-key auth,
21
+ # reading tenants + API keys from /etc/qualys-mcp/tenants.toml (mount it —
22
+ # in Kubernetes, from a Secret). Override CMD for stdio (sidecar/exec use)
23
+ # or --auth-mode oauth.
24
+
25
+ # ── Build stage (dev image: has pip; same Python as the runtime tag).
26
+ # Fully rootless: the venv lives under the nonroot user's home at the same
27
+ # path in both stages, so no root is needed even at build time. ───────────
28
+ FROM cgr.dev/chainguard/python:latest-dev AS build
29
+
30
+ ENV PYTHONDONTWRITEBYTECODE=1 \
31
+ PYTHONUNBUFFERED=1 \
32
+ PIP_NO_CACHE_DIR=1
33
+
34
+ WORKDIR /app
35
+ COPY pyproject.toml uv.lock README.md LICENSE ./
36
+ COPY qualys_mcp ./qualys_mcp
37
+
38
+ # The server shells out to qualys-cli; it installs as a dependency of this
39
+ # package, so one venv carries both entry points. After installing, strip
40
+ # the installers from the venv — the runtime never needs pip/setuptools,
41
+ # and shipping them only carries their CVE surface.
42
+ RUN python -m venv /home/nonroot/venv \
43
+ && /home/nonroot/venv/bin/pip install --no-cache-dir . \
44
+ && /home/nonroot/venv/bin/pip uninstall -y pip setuptools wheel
45
+
46
+ # ── Runtime stage (shell-less, package-manager-less, nonroot uid 65532) ─────
47
+ FROM cgr.dev/chainguard/python:latest
48
+
49
+ LABEL org.opencontainers.image.title="qualys-cli-mcp" \
50
+ org.opencontainers.image.description="MCP server exposing the Qualys Cloud Platform via qualys-cli" \
51
+ org.opencontainers.image.source="https://github.com/qualys/qualys-cli-mcp" \
52
+ org.opencontainers.image.licenses="MIT"
53
+
54
+ ENV PATH="/home/nonroot/venv/bin:$PATH" \
55
+ PYTHONDONTWRITEBYTECODE=1 \
56
+ PYTHONUNBUFFERED=1 \
57
+ HOME="/home/nonroot" \
58
+ QUALYS_MCP_AUDIT_LOG="/home/nonroot/audit/mcp-audit.jsonl" \
59
+ QUALYS_CLI_PATH="/home/nonroot/venv/bin/qualys-cli"
60
+
61
+ COPY --from=build --chown=65532:65532 /home/nonroot/venv /home/nonroot/venv
62
+
63
+ USER 65532
64
+ WORKDIR /home/nonroot
65
+
66
+ EXPOSE 8080
67
+
68
+ ENTRYPOINT ["/home/nonroot/venv/bin/qualys-cli-mcp"]
69
+ CMD ["--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8080", \
70
+ "--auth-mode", "api-key", "--tenant-config", "/etc/qualys-mcp/tenants.toml"]
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: qualys-cli-mcp
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  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).
5
5
  Project-URL: Homepage, https://www.qualys.com
6
6
  Author-email: Qualys <support@qualys.com>
@@ -26,7 +26,7 @@ Classifier: Topic :: System :: Systems Administration
26
26
  Classifier: Topic :: Utilities
27
27
  Requires-Python: >=3.11
28
28
  Requires-Dist: fastmcp>=2.0
29
- Requires-Dist: qualys-cli>=0.2.0
29
+ Requires-Dist: qualys-cli>=0.3.0
30
30
  Description-Content-Type: text/markdown
31
31
 
32
32
  <a href="https://www.qualys.com/"><img src="https://ik.imagekit.io/qualys/image/logo/qualys.svg" alt="Qualys" height="60"></a>
@@ -111,7 +111,7 @@ identical across clients.
111
111
 
112
112
  ## Tools
113
113
 
114
- The server exposes **18 tools**: 2 generic pass-through tools plus 16 curated,
114
+ The server exposes **24 tools**: 2 generic pass-through tools plus 22 curated,
115
115
  typed tools for the most common operations.
116
116
 
117
117
  ### Generic tools
@@ -141,6 +141,8 @@ these over free-form commands:
141
141
  | `vm_host_list()` | List scanned hosts by IP / range |
142
142
  | `vm_host_detection()` | Detections for specific hosts |
143
143
  | `vm_kb_by_cve()` / `vm_kb_by_qid()` | KnowledgeBase lookups |
144
+ | `vm_detection_stats()` | MTTR / SLA / backlog-age aggregates (supports `kev=True`) |
145
+ | `vm_kev_qids()` | QIDs covering the CISA KEV catalog |
144
146
  | `pc_posture_list()` | Policy Compliance posture |
145
147
  | `pm_job_list()` / `pm_patch_list()` | Patch jobs and catalog |
146
148
  | `was_finding_list()` | Web application findings |
@@ -148,6 +150,8 @@ these over free-form commands:
148
150
  | `cs_image_vulns()` | Container image vulnerabilities |
149
151
  | `csam_riskiest_assets()` / `csam_asset_count()` | Asset risk and inventory |
150
152
  | `ca_agent_list()` | Cloud Agent inventory |
153
+ | `etm_finding_list()` / `etm_asset_list()` | ETM findings and asset inventory (QQL) |
154
+ | `cs_k8s_namespace_list()` / `cs_k8s_pod_list()` | Kubernetes namespaces and pods |
151
155
 
152
156
  ## Supported modules
153
157
 
@@ -80,7 +80,7 @@ identical across clients.
80
80
 
81
81
  ## Tools
82
82
 
83
- The server exposes **18 tools**: 2 generic pass-through tools plus 16 curated,
83
+ The server exposes **24 tools**: 2 generic pass-through tools plus 22 curated,
84
84
  typed tools for the most common operations.
85
85
 
86
86
  ### Generic tools
@@ -110,6 +110,8 @@ these over free-form commands:
110
110
  | `vm_host_list()` | List scanned hosts by IP / range |
111
111
  | `vm_host_detection()` | Detections for specific hosts |
112
112
  | `vm_kb_by_cve()` / `vm_kb_by_qid()` | KnowledgeBase lookups |
113
+ | `vm_detection_stats()` | MTTR / SLA / backlog-age aggregates (supports `kev=True`) |
114
+ | `vm_kev_qids()` | QIDs covering the CISA KEV catalog |
113
115
  | `pc_posture_list()` | Policy Compliance posture |
114
116
  | `pm_job_list()` / `pm_patch_list()` | Patch jobs and catalog |
115
117
  | `was_finding_list()` | Web application findings |
@@ -117,6 +119,8 @@ these over free-form commands:
117
119
  | `cs_image_vulns()` | Container image vulnerabilities |
118
120
  | `csam_riskiest_assets()` / `csam_asset_count()` | Asset risk and inventory |
119
121
  | `ca_agent_list()` | Cloud Agent inventory |
122
+ | `etm_finding_list()` / `etm_asset_list()` | ETM findings and asset inventory (QQL) |
123
+ | `cs_k8s_namespace_list()` / `cs_k8s_pod_list()` | Kubernetes namespaces and pods |
120
124
 
121
125
  ## Supported modules
122
126
 
@@ -0,0 +1,46 @@
1
+ # config/tenants.example.toml
2
+ #
3
+ # Tenant configuration for multi-tenant qualys-cli-mcp deployments.
4
+ # Copy to tenants.toml and edit for your environment.
5
+ #
6
+ # Each tenant maps an OAuth client_id to a qualys-cli credential profile.
7
+ # Profiles are created with: qualys-cli configure --profile <name>
8
+
9
+ [tenants.cisco-luna]
10
+ client_id = "cisco-luna-client-001"
11
+ qualys_profile = "cisco-prod"
12
+ allowed_modules = ["vm", "csam", "ca", "was", "pm"]
13
+ deny_write = true
14
+ description = "Cisco Project Luna - production read-only"
15
+
16
+ [tenants.cisco-dev]
17
+ client_id = "cisco-dev-client-002"
18
+ qualys_profile = "cisco-dev"
19
+ allowed_modules = [] # empty = all modules
20
+ deny_write = false
21
+ description = "Cisco Project Luna - dev/testing"
22
+
23
+ [tenants.internal-analyst]
24
+ client_id = "internal-analyst-key"
25
+ qualys_profile = "default"
26
+ allowed_modules = ["vm", "csam", "etm"]
27
+ deny_write = true
28
+ description = "Internal analyst - read-only VM/CSAM/ETM"
29
+
30
+ # -----------------------------------------------------------------------
31
+ # API Keys (for server-to-server auth without full OAuth)
32
+ # -----------------------------------------------------------------------
33
+ # Each key maps a Bearer token to a tenant client_id.
34
+ # The client_id must match a [tenants.*] entry above.
35
+ #
36
+ # Generate keys with: python -c "import secrets; print(secrets.token_urlsafe(32))"
37
+
38
+ [api_keys.cisco-prod]
39
+ key = "REPLACE-WITH-GENERATED-KEY"
40
+ client_id = "cisco-luna-client-001"
41
+ scopes = ["qualys:read"]
42
+
43
+ [api_keys.cisco-dev]
44
+ key = "REPLACE-WITH-GENERATED-KEY"
45
+ client_id = "cisco-dev-client-002"
46
+ scopes = ["qualys:read", "qualys:write"]
@@ -0,0 +1,21 @@
1
+ FROM cgr.dev/chainguard/python:latest-dev AS build
2
+ ARG VERSION=0.2.0
3
+ ENV PIP_NO_CACHE_DIR=1
4
+ RUN python -m venv /home/nonroot/venv \
5
+ && /home/nonroot/venv/bin/pip install "qualys-cli-mcp==${VERSION}" \
6
+ && /home/nonroot/venv/bin/pip uninstall -y pip setuptools wheel
7
+
8
+ FROM cgr.dev/chainguard/python:latest
9
+ ENV PATH="/home/nonroot/venv/bin:$PATH" \
10
+ PYTHONDONTWRITEBYTECODE=1 \
11
+ PYTHONUNBUFFERED=1 \
12
+ HOME="/home/nonroot" \
13
+ QUALYS_MCP_AUDIT_LOG="/home/nonroot/audit/mcp-audit.jsonl" \
14
+ QUALYS_CLI_PATH="/home/nonroot/venv/bin/qualys-cli"
15
+ COPY --from=build --chown=65532:65532 /home/nonroot/venv /home/nonroot/venv
16
+ USER 65532
17
+ WORKDIR /home/nonroot
18
+ EXPOSE 8080
19
+ ENTRYPOINT ["/home/nonroot/venv/bin/qualys-cli-mcp"]
20
+ CMD ["--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8080", \
21
+ "--auth-mode", "api-key", "--tenant-config", "/etc/qualys-mcp/tenants.toml"]
@@ -1,5 +1,20 @@
1
1
  # Deploying qualys-cli-mcp
2
2
 
3
+ ## Getting the deployment kit (customers)
4
+
5
+ Everything on this page ships inside the PyPI source distribution — no
6
+ container registry or source-control access required:
7
+
8
+ ```bash
9
+ pip download qualys-cli-mcp --no-binary :all: --no-deps
10
+ tar xzf qualys_cli_mcp-*.tar.gz && cd qualys_cli_mcp-*/
11
+ docker build -t qualys-cli-mcp:local .
12
+ ```
13
+
14
+ Push the built image to your own registry and point `deploy/k8s/qualys-mcp.yaml`
15
+ at it. When the official image is published under the qualys org, swap the
16
+ image reference and drop the local build step.
17
+
3
18
  ## Container image
4
19
 
5
20
  `Dockerfile` builds a hardened image on Chainguard's Wolfi Python base:
@@ -0,0 +1,129 @@
1
+ # qualys-cli-mcp on Kubernetes — corporate deployment reference.
2
+ #
3
+ # Apply order:
4
+ # 1. Create the two Secrets (see secret.example.yaml) — never commit real ones.
5
+ # 2. kubectl apply -f qualys-mcp.yaml
6
+ #
7
+ # Clients connect to http://qualys-mcp.<namespace>.svc:8080/mcp with
8
+ # `Authorization: Bearer <api key from tenants.toml>` (MCP streamable-http).
9
+ # Put corporate TLS in front via your Ingress/mesh; the pod itself serves HTTP.
10
+ ---
11
+ apiVersion: apps/v1
12
+ kind: Deployment
13
+ metadata:
14
+ name: qualys-mcp
15
+ labels:
16
+ app: qualys-mcp
17
+ spec:
18
+ replicas: 2 # stateless: caches are per-pod conveniences
19
+ selector:
20
+ matchLabels:
21
+ app: qualys-mcp
22
+ template:
23
+ metadata:
24
+ labels:
25
+ app: qualys-mcp
26
+ spec:
27
+ securityContext:
28
+ runAsNonRoot: true
29
+ runAsUser: 65532 # Chainguard runtime's nonroot uid
30
+ fsGroup: 65532
31
+ seccompProfile:
32
+ type: RuntimeDefault
33
+ containers:
34
+ - name: qualys-mcp
35
+ image: qualys-cli-mcp:latest # pin a digest in production
36
+ imagePullPolicy: IfNotPresent
37
+ ports:
38
+ - name: mcp
39
+ containerPort: 8080
40
+ envFrom:
41
+ - secretRef:
42
+ name: qualys-credentials # QUALYS_USERNAME / QUALYS_PASSWORD (+ QUALYS_URL / QUALYS_GATEWAY_URL if not auto-detected)
43
+ env:
44
+ - name: QUALYS_MCP_DENY_WRITE # defense in depth; per-tenant deny_write still applies
45
+ value: "1"
46
+ volumeMounts:
47
+ - name: tenants
48
+ mountPath: /etc/qualys-mcp
49
+ readOnly: true
50
+ - name: config # qualys-cli JWT token cache + ETag response cache
51
+ mountPath: /home/nonroot/.config
52
+ - name: audit
53
+ mountPath: /home/nonroot/audit
54
+ - name: tmp
55
+ mountPath: /tmp
56
+ securityContext:
57
+ allowPrivilegeEscalation: false
58
+ readOnlyRootFilesystem: true
59
+ capabilities:
60
+ drop: ["ALL"]
61
+ resources:
62
+ requests:
63
+ cpu: 100m
64
+ memory: 256Mi
65
+ limits:
66
+ # Subscription-wide detection pulls buffer pages in memory;
67
+ # 1Gi covers the 1000-host lean pages comfortably.
68
+ memory: 1Gi
69
+ startupProbe:
70
+ tcpSocket:
71
+ port: mcp
72
+ failureThreshold: 12
73
+ periodSeconds: 5
74
+ livenessProbe:
75
+ tcpSocket:
76
+ port: mcp
77
+ periodSeconds: 30
78
+ readinessProbe:
79
+ # /mcp answers 401 to unauthenticated requests once auth is wired;
80
+ # any HTTP response means the server loop is up. TCP keeps the
81
+ # probe auth-agnostic.
82
+ tcpSocket:
83
+ port: mcp
84
+ periodSeconds: 10
85
+ volumes:
86
+ - name: tenants
87
+ secret:
88
+ secretName: qualys-mcp-tenants # key: tenants.toml
89
+ - name: config
90
+ emptyDir: {}
91
+ - name: audit
92
+ emptyDir: {}
93
+ # For durable audit trails, replace with a PVC or ship the JSONL
94
+ # via your log collector (it lands in /home/nonroot/audit/).
95
+ - name: tmp
96
+ emptyDir: {}
97
+ ---
98
+ apiVersion: v1
99
+ kind: Service
100
+ metadata:
101
+ name: qualys-mcp
102
+ labels:
103
+ app: qualys-mcp
104
+ spec:
105
+ selector:
106
+ app: qualys-mcp
107
+ ports:
108
+ - name: mcp
109
+ port: 8080
110
+ targetPort: mcp
111
+ ---
112
+ # Optional but recommended: only the namespaces that host MCP clients
113
+ # (agent platforms, Claude gateways) may reach the server.
114
+ apiVersion: networking.k8s.io/v1
115
+ kind: NetworkPolicy
116
+ metadata:
117
+ name: qualys-mcp
118
+ spec:
119
+ podSelector:
120
+ matchLabels:
121
+ app: qualys-mcp
122
+ policyTypes: ["Ingress"]
123
+ ingress:
124
+ - from:
125
+ - namespaceSelector:
126
+ matchLabels:
127
+ qualys-mcp-client: "true"
128
+ ports:
129
+ - port: 8080
@@ -0,0 +1,41 @@
1
+ # EXAMPLES ONLY — copy, fill, and apply out-of-band (sealed-secrets,
2
+ # external-secrets, SOPS, or `kubectl create secret`). Never commit real values.
3
+ #
4
+ # Single-tenant: credentials via env is simplest — get_profile() gives
5
+ # QUALYS_USERNAME/QUALYS_PASSWORD top priority, no keyring needed in-cluster.
6
+ #
7
+ # Multi-tenant: instead of env creds, mount a full qualys-cli config with one
8
+ # profile per tenant (add a third Secret with config.toml projected to
9
+ # /home/qmcp/.config/qualys-cli/) and set each tenant's qualys_profile.
10
+ ---
11
+ apiVersion: v1
12
+ kind: Secret
13
+ metadata:
14
+ name: qualys-credentials
15
+ type: Opaque
16
+ stringData:
17
+ QUALYS_USERNAME: "REPLACE-ME"
18
+ QUALYS_PASSWORD: "REPLACE-ME"
19
+ # Optional — auto-detected from the username's platform when omitted:
20
+ QUALYS_URL: "https://qualysapi.qg2.apps.qualys.com"
21
+ QUALYS_GATEWAY_URL: "https://gateway.qg2.apps.qualys.com"
22
+ ---
23
+ apiVersion: v1
24
+ kind: Secret
25
+ metadata:
26
+ name: qualys-mcp-tenants
27
+ type: Opaque
28
+ stringData:
29
+ tenants.toml: |
30
+ # See config/tenants.example.toml for the full schema.
31
+ [tenants.corp-agents]
32
+ client_id = "corp-agents-001"
33
+ qualys_profile = "default"
34
+ allowed_modules = ["vm", "csam", "tc", "pc"]
35
+ deny_write = true
36
+ description = "Corporate AI agents - read-only"
37
+
38
+ [api_keys.corp-agents]
39
+ key = "REPLACE-WITH: python -c 'import secrets; print(secrets.token_urlsafe(32))'"
40
+ client_id = "corp-agents-001"
41
+ scopes = ["qualys:read"]
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "qualys-cli-mcp"
7
- version = "0.2.0"
7
+ version = "0.3.0"
8
8
  description = "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)."
9
9
  readme = { file = "README.md", content-type = "text/markdown" }
10
10
  requires-python = ">=3.11"
@@ -57,7 +57,7 @@ classifiers = [
57
57
  ]
58
58
  dependencies = [
59
59
  "fastmcp>=2.0",
60
- "qualys-cli>=0.2.0",
60
+ "qualys-cli>=0.3.0",
61
61
  ]
62
62
 
63
63
  [project.scripts]
@@ -66,17 +66,6 @@ qualys-cli-mcp = "qualys_mcp.server:main"
66
66
  [project.urls]
67
67
  Homepage = "https://www.qualys.com"
68
68
 
69
- [tool.uv.sources]
70
- # Local/intranet development only: resolves `qualys-cli` from the sibling
71
- # checkout instead of PyPI so `uv sync`/`uv lock` work before a matching
72
- # qualys-cli release is published. `[tool.uv.sources]` is a uv-only
73
- # resolution hint — hatchling ignores it when building the sdist/wheel, so
74
- # the published package's dependency metadata is always the plain
75
- # `qualys-cli>=0.2.0` version spec above, never this path. Per
76
- # PUBLISHING.md, do not replace the version spec itself with a `git+`/path
77
- # dependency — PyPI rejects direct-URL dependencies at upload time.
78
- qualys-cli = { path = "../qualys-cli", editable = true }
79
-
80
69
  [dependency-groups]
81
70
  dev = [
82
71
  "pytest>=8",
@@ -97,10 +86,12 @@ include = [
97
86
  "CHANGELOG.md",
98
87
  "LICENSE",
99
88
  "pyproject.toml",
89
+ "Dockerfile",
90
+ "deploy",
91
+ "config/tenants.example.toml",
100
92
  ]
101
93
  exclude = [
102
94
  ".claude",
103
- "config",
104
95
  "docs",
105
96
  "evals",
106
97
  "scripts",
@@ -129,6 +129,19 @@ _READ_ACTIONS = {
129
129
  "list", "get", "count", "fetch", "detection", "runs", "summary",
130
130
  "products", "results", "vulns", "software", "findings", "download",
131
131
  "export", "info", "data", "list-easm", "list-scan",
132
+ # cs k8s-resource compound verbs (qualys-cli Nov 2026 CS expansion:
133
+ # `cs k8s-resource namespace-list|namespace-get|pod-list|pod-get`).
134
+ # Without these, a read-only deployment (QUALYS_MCP_DENY_WRITE=1) or a
135
+ # qualys:read-scoped OAuth token would incorrectly reject these
136
+ # harmless K8s inventory reads as writes.
137
+ "namespace-list", "namespace-get", "pod-list", "pod-get",
138
+ # Read-only actions that were falling through to the default-deny
139
+ # (treated as writes), so DENY_WRITE / qualys:read callers were refused
140
+ # them — including the backing commands of the curated vm_detection_stats
141
+ # (`vm host detection-stats`) and vm_kev_qids (`vm kb kev-qids`) tools.
142
+ "detection-stats", "kev-qids", "qvs", "exists", "exist", "status",
143
+ "retest-status", "columns", "resources", "orgs", "plan",
144
+ "list-by-asset", "sn-export", "download-resource",
132
145
  }
133
146
 
134
147
  # Top-level commands that are themselves a read/diagnostic action (no resource).
@@ -322,6 +335,8 @@ DEDICATED TOOLS (use these first -- they have typed parameters):
322
335
  vm_host_detection(ips, severities) Get detections by IP
323
336
  vm_kb_by_cve(cve) KB lookup by CVE
324
337
  vm_kb_by_qid(qids) KB lookup by QID
338
+ vm_detection_stats(metric, kev, ...) MTTR / SLA / backlog-age stats
339
+ vm_kev_qids() CISA KEV QID set
325
340
  pc_posture_list(policy_id) Compliance posture
326
341
  pm_job_list(limit) Patch jobs
327
342
  pm_patch_list(limit) Patch catalog
@@ -332,6 +347,10 @@ DEDICATED TOOLS (use these first -- they have typed parameters):
332
347
  csam_riskiest_assets(min_risk_score) Top risky assets
333
348
  csam_asset_count() Asset count
334
349
  ca_agent_list(limit) Cloud agents
350
+ etm_finding_list(qql, page_size) ETM findings inventory
351
+ etm_asset_list(qql, page_size) ETM asset inventory
352
+ cs_k8s_namespace_list(query, page_size) K8s namespaces
353
+ cs_k8s_pod_list(query, page_size) K8s pods
335
354
 
336
355
  FOR EVERYTHING ELSE, use qualys_cli(command) with the reference below:
337
356
 
@@ -348,43 +367,73 @@ pc scan list, launch
348
367
  pc policy list, export
349
368
  pc posture list (requires --policy-id)
350
369
  pc option-profile list
370
+ pc control list
371
+ pc exception list
372
+ pc scan-schedule list, delete
351
373
  pm job list, get, create, update, delete, runs, summary
352
374
  pm patch list, count, products <patchId>
353
375
  pm mitigation list, create, delete
354
376
  pm report list, generate, download
355
377
  pm asset list
378
+ pm blocking-rule list, create, delete
356
379
  etm report list, create, get, download, delete
380
+ etm finding list, get, count
381
+ etm asset list, count
357
382
  was webapp list, get, count, create, update, delete
358
383
  was scan list, get, count, launch, cancel, results
359
384
  was finding list, get, count
360
385
  was auth-record list, get, count, delete
361
386
  was schedule list, get, count, create, delete
362
387
  was report list, get, count, create-webapp, create-scan, download, delete
388
+ was catalog list, count, get, update, add-to-subscription, delete
389
+ was option-profile list, count, get, create, update, delete
390
+ was dns list, get, count, create, delete
391
+ was import burp, owasp-zap
363
392
  tc connector list (requires --provider AWS|AZURE|GCP)
364
393
  tc evaluation list (requires --provider)
365
394
  tc rule list, create, enable, disable, delete
366
395
  tc report list, create, download
367
396
  tc cdr findings
397
+ tc exception list, delete
398
+ tc iac list, get
399
+ tc resource list, get
368
400
  ca agent list, count, activate, deactivate, uninstall
369
401
  ca act-key list, get, create, delete
370
402
  ca config list, create, delete
403
+ ca isolation isolate, unisolate (--platform required)
404
+ ca scan launch-ods
371
405
  cs image list, get, vulns, software, delete
372
406
  cs container list, get, vulns, software
373
407
  cs registry list, get, delete
374
408
  cs sensor list, get
375
409
  cs report list, create, download, delete
410
+ cs k8s-resource namespace-list, namespace-get, pod-list, pod-get
411
+ cs secret-detector list, create, bulk-update
412
+ cs qid-list list, get, vulns
413
+ cs tag create, update, delete, assign, remove, exist
414
+ cs k8s-cluster list, get
415
+ cs policy list
376
416
  csam asset count, list, get
377
417
  csam easm list, create, update, delete
378
418
  csam vuln list-easm, list-scan, data
379
419
  csam domain list, count
380
420
  csam report create, download
421
+ csam business import-asset, import-app
422
+ csam component list, list-by-asset
423
+ csam connector sync
424
+ csam org list, count
381
425
  asset ip list, add
382
426
  asset network list, create
383
427
  asset group list, delete
428
+ asset domain list, create
429
+ asset tag list
384
430
  scanauth record list
385
431
  scanauth vault list, create
432
+ scanauth neo4j list, create
433
+ scanauth nginx list, create
386
434
  user list, create
387
435
  sub info, export, import
436
+ sub user-prefs export, import
388
437
  doctor (preflight check -- verify creds work)
389
438
  health (machine-readable health probe)
390
439
  cache (manage local response cache)
@@ -1224,7 +1273,7 @@ def main():
1224
1273
  else:
1225
1274
  log.info("auth: OK")
1226
1275
 
1227
- log.info("18 tools registered (2 generic + 16 curated)")
1276
+ log.info("24 tools registered (2 generic + 22 curated)")
1228
1277
  log.info("transport: %s", args.transport)
1229
1278
  _audit("startup", version=__version__, cli=_CLI, transport=args.transport, auth_mode=args.auth_mode)
1230
1279
 
@@ -355,3 +355,63 @@ def register_tools(mcp, run_qualys_cli):
355
355
  _build_args(["ca", "agent", "list"], {"--limit": str(limit)}),
356
356
  source="ca_agent_list",
357
357
  )
358
+
359
+ # ── New Nov 2026 resources (ETM findings/assets, CS k8s-resource) ──────
360
+
361
+ @mcp.tool()
362
+ async def etm_finding_list(
363
+ qql: str | None = None,
364
+ page_size: int = 20,
365
+ ) -> dict:
366
+ """List findings from the ETM findings inventory.
367
+
368
+ Args:
369
+ qql: Findings QQL query, e.g. "finding.severity:5"
370
+ """
371
+ return await run_qualys_cli(
372
+ _build_args(["etm", "finding", "list"], {"--qql": qql, "--page-size": str(page_size)}),
373
+ source="etm_finding_list",
374
+ )
375
+
376
+ @mcp.tool()
377
+ async def etm_asset_list(
378
+ qql: str | None = None,
379
+ page_size: int = 20,
380
+ ) -> dict:
381
+ """List assets from the ETM asset inventory.
382
+
383
+ Args:
384
+ qql: Asset QQL query, e.g. "asset.criticalityScore:5"
385
+ """
386
+ return await run_qualys_cli(
387
+ _build_args(["etm", "asset", "list"], {"--qql": qql, "--page-size": str(page_size)}),
388
+ source="etm_asset_list",
389
+ )
390
+
391
+ @mcp.tool()
392
+ async def cs_k8s_namespace_list(
393
+ query: str | None = None,
394
+ page_size: int = 50,
395
+ ) -> dict:
396
+ """List Kubernetes namespaces tracked by Container Security."""
397
+ return await run_qualys_cli(
398
+ _build_args(
399
+ ["cs", "k8s-resource", "namespace-list"],
400
+ {"--query": query, "--page-size": str(page_size)},
401
+ ),
402
+ source="cs_k8s_namespace_list",
403
+ )
404
+
405
+ @mcp.tool()
406
+ async def cs_k8s_pod_list(
407
+ query: str | None = None,
408
+ page_size: int = 50,
409
+ ) -> dict:
410
+ """List Kubernetes pods tracked by Container Security."""
411
+ return await run_qualys_cli(
412
+ _build_args(
413
+ ["cs", "k8s-resource", "pod-list"],
414
+ {"--query": query, "--page-size": str(page_size)},
415
+ ),
416
+ source="cs_k8s_pod_list",
417
+ )
@@ -248,6 +248,25 @@ _READ_COMMANDS = [
248
248
  ["cs", "image", "vulns", "5"],
249
249
  ["cs", "image", "software"],
250
250
  ["etm", "report", "download", "--id", "3"],
251
+ # backing commands of curated tools — must work under DENY_WRITE
252
+ ["vm", "host", "detection-stats", "--metric", "mttr"],
253
+ ["vm", "kb", "kev-qids"],
254
+ ["vm", "kb", "qvs", "--cve", "CVE-2024-3400"],
255
+ # qualys-cli 0.3.0 read commands
256
+ ["etm", "finding", "list", "--qql", "finding.severity:5"],
257
+ ["etm", "asset", "count"],
258
+ ["cs", "k8s-resource", "namespace-list"],
259
+ ["cs", "k8s-resource", "pod-get", "abc"],
260
+ ["cs", "qid-list", "vulns", "1"],
261
+ ["cs", "tag", "exist", "prod"],
262
+ ["pm", "blocking-rule", "list"],
263
+ ["was", "catalog", "get", "1"],
264
+ # other read actions that used to fall through to default-deny
265
+ ["was", "scan", "status", "1"],
266
+ ["was", "finding", "retest-status", "1"],
267
+ ["csam", "component", "list-by-asset", "1"],
268
+ ["csam", "easm", "orgs"],
269
+ ["pm", "mitigation", "plan", "--qids", "1"],
251
270
  ["sub", "info"],
252
271
  ["sub", "export"],
253
272
  ["user", "list"],
@@ -286,6 +305,16 @@ _WRITE_COMMANDS = [
286
305
  # flag-interleaving that tries to shift the action out of its slot
287
306
  ["asset", "ip", "--note", "list", "add"],
288
307
  ["asset", "ip", "add", "--note", "list"],
308
+ # qualys-cli 0.3.0 write commands
309
+ ["ca", "isolation", "isolate", "1", "--platform", "windows"],
310
+ ["ca", "isolation", "unisolate", "1", "--platform", "windows"],
311
+ ["pm", "blocking-rule", "create"],
312
+ ["cs", "secret-detector", "bulk-update", "1"],
313
+ ["cs", "tag", "assign"],
314
+ ["was", "catalog", "update", "1", "--status", "x"],
315
+ ["was", "option-profile", "update", "1", "--name", "x"],
316
+ # a newly added read verb must not downgrade a write elsewhere in argv
317
+ ["was", "catalog", "update", "status"],
289
318
  # unknown/novel verbs and modules default to write
290
319
  ["vm", "scan", "frobnicate"],
291
320
  # local mutators / server starters default to write
@@ -519,3 +548,45 @@ def test_transient_exit_codes_still_retried(tmp_path, monkeypatch):
519
548
 
520
549
  async def _instant_sleep(_seconds):
521
550
  return None
551
+
552
+
553
+ def test_command_help_reference_matches_cli():
554
+ """Every module/resource/action in _COMMAND_HELP must exist in qualys-cli.
555
+
556
+ The reference is what the LLM reads to build qualys_cli() commands, so a
557
+ wrong name (e.g. `was profile` instead of `was option-profile`) produces
558
+ commands that fail at runtime.
559
+ """
560
+ import re
561
+
562
+ from qualys_cli.cli import app
563
+ from typer.main import get_command
564
+
565
+ from qualys_mcp.server import _COMMAND_HELP
566
+
567
+ root = get_command(app)
568
+ table = _COMMAND_HELP.split("MODULE RESOURCE ACTIONS", 1)[1]
569
+ table = table.split("\n\n", 1)[0]
570
+ problems = []
571
+ for line in table.splitlines()[2:]:
572
+ m = re.match(r"^(\S+)\s+(\S+)\s+(.*)$", line)
573
+ if not m:
574
+ continue
575
+ mod, res, acts = m.groups()
576
+ group = root.commands.get(mod)
577
+ if group is None:
578
+ problems.append(f"unknown module: {mod}")
579
+ continue
580
+ sub = getattr(group, "commands", {}).get(res.rstrip(","))
581
+ if sub is None:
582
+ if not hasattr(group, "commands") or res.startswith("("):
583
+ continue # top-level command row, e.g. "doctor (preflight ...)"
584
+ problems.append(f"unknown resource: {mod} {res}")
585
+ continue
586
+ if not hasattr(sub, "commands"):
587
+ continue # `<module> <action>` grammar row (user, sub)
588
+ for a in re.sub(r"\(.*?\)", "", acts).split(","):
589
+ a = a.strip().split(" ")[0].strip("<>")
590
+ if a and a not in sub.commands:
591
+ problems.append(f"unknown action: {mod} {res} {a}")
592
+ assert not problems, problems
File without changes