qualys-mcp 0.4.0 → 0.5.1

package/README.md

@@ -9,7 +9,7 @@ Read-only MCP server for the Qualys VMDR API. Exposes host assets, vulnerability
 | `qualys_vuln_overview` | Estate-wide counts by tag: every client's open vulnerabilities by severity in one call, with optional CVSS threshold |
 | `qualys_vuln_summary` | Aggregated vulnerability counts by severity, per client tag and per machine — the dashboard/reporting tool |
 | `qualys_list_tags` | Asset tags and tag hierarchies (how clients are segmented) |
-| `qualys_asset_inventory` | Full CSAM/Global AssetView inventory: all assets with criticality, tags, last logged-on user, agent check-in, sources (QQL filterable) |
+| `qualys_asset_inventory` | Full CSAM/Global AssetView inventory: all assets with criticality, tags, last logged-on user, agent check-in, sources (filterable by tag, OS, etc.) |
 | `qualys_host_detections` | Vulnerabilities detected per host (QID, severity, status, optional evidence; tag filterable) — the drill-down tool |
 | `qualys_knowledgebase` | QID details: title, CVEs, threat, impact, solution |
 | `qualys_api_call` | Raw GET/POST to any other Qualys endpoint — disabled unless `QUALYS_ENABLE_RAW_API=true` |
@@ -93,7 +93,7 @@ Qualys severity (1–5) is not CVSS. If your remediation policy is CVSS-based
 
 ## Notes
 
-- `qualys_asset_inventory` uses the CSAM/Global AssetView gateway API (JWT auth, JSON) and answers "show me all machines" — including agent-tracked assets, criticality scores and tags. Filter with QQL, e.g. `tags.name:"Client A"`, `operatingSystem.category1:"Windows"`, `criticality.score>=3`. Paginate with `hasMore`/`lastSeenAssetId`.
+- `qualys_asset_inventory` uses the CSAM/Global AssetView gateway API (JWT auth, JSON) and answers "show me all machines" — including agent-tracked assets, criticality scores and tags. Filter with structured criteria sent in the request body, e.g. `filters: [{"field": "tags.name", "value": "Client A"}]` — this endpoint does not accept QQL strings. Criteria are ANDed; if a field isn't filterable the API error lists every valid field. Paginate with `hasMore`/`lastSeenAssetId`. Note the gateway API has a much stricter rate quota than the VM API — filter rather than sweep repeatedly.
 - For per-machine critical vulnerability counts, combine it with `qualys_host_detections` using `severities="5"` (or `"4,5"`).
 - The Qualys VM API v2 returns XML; this server converts it to JSON.
 - Rate/concurrency limits (HTTP 409/429) are retried automatically using the `X-RateLimit-ToWait-Sec` header, up to 3 times.

package/dist/index.js

@@ -28,11 +28,23 @@ const truncationProperties = {
 const tools = [
     {
         name: 'qualys_asset_inventory',
-        description: 'Full asset inventory from Qualys CSAM/Global AssetView — the same data as the Asset Management UI: every asset (agent-tracked and scanned) with name, IP, OS, asset criticality score, TruRisk score, tags, last logged-on user, agent last check-in and last scan dates. This is the primary tool for "show me all machines/assets". Filter with Qualys QQL, e.g. tags.name:"Client A", operatingSystem.category1:"Windows", or criticality.score>=3. Returns a compact summary per asset by default; set full_details=true for complete raw records (large — software, ports, volumes). For counts of critical vulnerabilities per machine, combine with qualys_host_detections (severities="5").',
+        description: 'Full asset inventory from Qualys CSAM/Global AssetView — the same data as the Asset Management UI: every asset (agent-tracked and scanned) with name, IP, OS, asset criticality score, TruRisk score, tags, last logged-on user, agent last check-in and last scan dates. This is the primary tool for "show me all machines/assets". Filter with structured criteria (ANDed), e.g. [{"field": "tags.name", "value": "Client A"}] or [{"field": "operatingSystem.category1", "value": "Windows"}]. Returns a compact summary per asset by default; set full_details=true for complete raw records (large — software, ports, volumes). For counts of critical vulnerabilities per machine, combine with qualys_host_detections (severities="5").',
         inputSchema: {
             type: 'object',
             properties: {
-                filter: { type: 'string', description: 'QQL filter, e.g. tags.name:"Superfast IT" or lastLoggedOnUser:"jsmith". Omit to return all assets.' },
+                filters: {
+                    type: 'array',
+                    description: 'Filter criteria, ANDed together. Verified fields: tags.name, operatingSystem.category1 ("Windows"/"Linux"), operatingSystem.category2 ("Server"/"Desktop"). If a field is not filterable, the API error helpfully lists every valid field name — read it and retry. Note: QQL strings are NOT supported by this endpoint.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            field: { type: 'string', description: 'Field name, e.g. "tags.name"' },
+                            operator: { type: 'string', description: 'Default "EQUALS"' },
+                            value: { type: 'string', description: 'Value to match, e.g. "Gordon Moody"' },
+                        },
+                        required: ['field', 'value'],
+                    },
+                },
                 page_size: { type: 'number', description: 'Assets per page (default 100, max 300)' },
                 last_seen_asset_id: { type: 'number', description: 'Pagination cursor: pass the lastSeenAssetId from the previous response to get the next page (response also has hasMore=1/0)' },
                 full_details: { type: 'boolean', description: 'Return complete raw asset records instead of the compact summary. Default false.' },
@@ -377,12 +389,15 @@ async function handleTool(name, args) {
         }
         case 'qualys_asset_inventory': {
             const fullDetails = args.full_details === true;
+            const filters = args.filters;
+            const body = filters?.length
+                ? { filters: filters.map((f) => ({ field: f.field, operator: f.operator ?? 'EQUALS', value: f.value })) }
+                : undefined;
             const result = (await client.gatewayRequest('/rest/2.0/search/am/asset', {
-                filter: args.filter,
                 pageSize: Math.min(args.page_size ?? 100, 300),
                 lastSeenAssetId: args.last_seen_asset_id,
                 includeFields: fullDetails ? undefined : INVENTORY_FIELDS,
-            }));
+            }, body));
             const assets = result?.assetListData?.asset ?? [];
             return JSON.stringify({
                 count: result?.count,

package/dist/qualys-client.js

@@ -108,7 +108,7 @@ export class QualysClient {
         this.tokenExpiresAt = Date.now() + 3.5 * 60 * 60 * 1000;
         return this.token;
     }
-    async gatewayRequest(path, query = {}, method = 'POST') {
+    async gatewayRequest(path, query = {}, body, method = 'POST') {
         const url = new URL(this.gatewayUrl + (path.startsWith('/') ? path : '/' + path));
         for (const [key, value] of Object.entries(query)) {
             if (value !== undefined && value !== null && value !== '') {
@@ -117,15 +117,27 @@ export class QualysClient {
         }
         for (let attempt = 0;; attempt++) {
             const token = await this.getToken(attempt > 0);
+            const headers = { Authorization: `Bearer ${token}`, Accept: 'application/json' };
+            if (body !== undefined)
+                headers['Content-Type'] = 'application/json';
             const response = await fetch(url, {
                 method,
-                headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+                headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
             });
             if (response.status === 401 && attempt < 1)
                 continue;
-            if (response.status === 429 && attempt < MAX_RETRIES) {
-                await new Promise((resolve) => setTimeout(resolve, 10_000 * (attempt + 1)));
-                continue;
+            if (response.status === 429) {
+                const toWait = Number(response.headers.get('x-ratelimit-towait-sec')) || 0;
+                if (attempt < MAX_RETRIES && toWait <= 120) {
+                    await new Promise((resolve) => setTimeout(resolve, (toWait || 10 * (attempt + 1)) * 1000));
+                    continue;
+                }
+                const rl = (name) => response.headers.get(name) ?? 'n/a';
+                throw new Error(`Qualys gateway API rate limit reached for ${url.pathname} as user "${this.username}" ` +
+                    `(X-RateLimit-Limit: ${rl('x-ratelimit-limit')}, X-RateLimit-Remaining: ${rl('x-ratelimit-remaining')}, ` +
+                    `X-RateLimit-ToWait-Sec: ${rl('x-ratelimit-towait-sec')}${toWait ? `, ~${Math.ceil(toWait / 3600)} hour(s)` : ''}). ` +
+                    'The VM API tools (qualys_vuln_overview/vuln_summary/host_detections/knowledgebase/list_tags) use a separate limit and still work.');
             }
             const text = await response.text();
             if (!response.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualys-mcp",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "MCP server for the Qualys VMDR API (read-only) — hosts, vulnerability detections, KnowledgeBase, scans, reports and asset groups",
   "main": "dist/index.js",
   "type": "module",