qualys-mcp 0.3.0 → 0.5.1

package/README.md

@@ -9,15 +9,12 @@ 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_list_hosts` | Scanned host assets (ID, IP, DNS, OS, last scan dates, optional tags; tag 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_list_scans` | Scan history and status |
-| `qualys_list_reports` | Generated reports |
-| `qualys_fetch_report` | Download a finished CSV/XML report inline |
-| `qualys_list_asset_groups` | Asset groups (typically clients/sites) and their IP ranges |
-| `qualys_api_call` | Raw GET/POST to any other Qualys endpoint (read-only actions only) |
+| `qualys_api_call` | Raw GET/POST to any other Qualys endpoint — disabled unless `QUALYS_ENABLE_RAW_API=true` |
+
+The tool set is deliberately lean, focused on vulnerability reporting across a tag-segmented client base. The raw API tool covers anything else (scans, reports, asset groups, schedules) but is off by default so shared deployments stay strictly read-only.
 
 ## Quick start (Claude Desktop / Cowork)
 
@@ -53,6 +50,7 @@ Three required environment variables:
 | `QUALYS_PASSWORD` | Qualys API user password |
 | `QUALYS_BASE_URL` | Your platform's API server (see below) |
 | `QUALYS_GATEWAY_URL` | Optional — the gateway host used by `qualys_asset_inventory` (CSAM/GAV API). Derived automatically from `QUALYS_BASE_URL` (e.g. `https://gateway.qg1.apps.qualys.co.uk` for UK1); only set this if your platform's gateway differs. |
+| `QUALYS_ENABLE_RAW_API` | Optional — set to `true` to expose `qualys_api_call` for arbitrary Qualys API endpoints. Leave unset for team deployments. |
 
 The API server depends on which Qualys platform your subscription lives on — check your Qualys login URL:
 
@@ -95,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

@@ -6,6 +6,7 @@ import { QualysClient, simplify, stripEmpty } from './qualys-client.js';
 const username = process.env.QUALYS_USERNAME || '';
 const password = process.env.QUALYS_PASSWORD || '';
 const baseUrl = process.env.QUALYS_BASE_URL || '';
+const rawApiEnabled = process.env.QUALYS_ENABLE_RAW_API === 'true';
 if (!username || !password || !baseUrl) {
     console.error('Missing required environment variables: QUALYS_USERNAME, QUALYS_PASSWORD, QUALYS_BASE_URL.');
     console.error('QUALYS_BASE_URL is your platform API server, e.g. https://qualysapi.qg1.apps.qualys.co.uk (UK1),');
@@ -27,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.' },
@@ -78,30 +91,6 @@ const tools = [
             properties: {},
         },
     },
-    {
-        name: 'qualys_list_hosts',
-        description: 'List scanned host assets in Qualys VMDR with their ID, IP, DNS name, OS and last scan dates. Use this to find host IDs before pulling their vulnerability detections. Filter by IPs, asset group or scan recency.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                ids: { type: 'string', description: 'Comma-separated host IDs or ranges, e.g. "123,150-200"' },
-                ips: { type: 'string', description: 'Comma-separated IPs or ranges, e.g. "10.0.0.1,10.0.1.0-10.0.1.255"' },
-                ag_ids: { type: 'string', description: 'Comma-separated asset group IDs (see qualys_list_asset_groups)' },
-                ag_titles: { type: 'string', description: 'Comma-separated asset group titles' },
-                details: {
-                    type: 'string',
-                    description: 'Level of detail: "Basic" (default), "Basic/AGs", "All", "All/AGs", or "None" (IDs only)',
-                },
-                os_pattern: { type: 'string', description: 'PCRE regex to match against host operating system, e.g. "Windows Server 2012"' },
-                no_vm_scan_since: { type: 'string', description: 'Only hosts NOT scanned since this date (YYYY-MM-DD) — useful to find stale/unscanned assets' },
-                vm_scan_since: { type: 'string', description: 'Only hosts scanned since this date (YYYY-MM-DD)' },
-                show_tags: { type: 'boolean', description: 'Include asset tags for each host. Default false.' },
-                tags: { type: 'string', description: 'Comma-separated asset tag names to scope to (clients are segmented by tags)' },
-                tag_include_selector: { type: 'string', description: '"any" (default) or "all" — whether hosts must have any or all of the tags' },
-                ...truncationProperties,
-            },
-        },
-    },
     {
         name: 'qualys_host_detections',
         description: 'List vulnerability detections per host — the core VMDR data. Returns each host with its detected vulnerabilities (QID, severity, status, first/last found, results evidence). Filter by host, QID, severity or detection status. Look up QID titles and fixes with qualys_knowledgebase. Output can be large: keep truncation_limit modest and filter where possible.',
@@ -141,57 +130,6 @@ const tools = [
             },
         },
     },
-    {
-        name: 'qualys_list_scans',
-        description: 'List vulnerability scans in Qualys VMDR with their reference, title, launch date, status and target. Useful for checking scan history and whether scheduled scans are completing.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                scan_ref: { type: 'string', description: 'Specific scan reference, e.g. "scan/1234567890.12345"' },
-                state: { type: 'string', description: 'Comma-separated states: "Running", "Paused", "Canceled", "Finished", "Error", "Queued", "Loading"' },
-                type: { type: 'string', description: 'Scan type: "On-Demand", "Scheduled" or "API"' },
-                target: { type: 'string', description: 'Filter by scan target IPs' },
-                launched_after_datetime: { type: 'string', description: 'Only scans launched after this datetime (YYYY-MM-DD or ISO 8601)' },
-                launched_before_datetime: { type: 'string', description: 'Only scans launched before this datetime' },
-            },
-        },
-    },
-    {
-        name: 'qualys_list_reports',
-        description: 'List generated reports in Qualys with their ID, title, type, output format, status and expiry. Use qualys_fetch_report to download a finished report.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                id: { type: 'number', description: 'Specific report ID' },
-                state: { type: 'string', description: 'Report state, e.g. "Finished", "Running", "Errors"' },
-                user_login: { type: 'string', description: 'Filter by the user who launched the report' },
-            },
-        },
-    },
-    {
-        name: 'qualys_fetch_report',
-        description: 'Download a finished Qualys report by ID. Only sensible for text-based formats (CSV, XML) — the content is returned inline, truncated to max_chars. Check qualys_list_reports first for the report status and format.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                id: { type: 'number', description: 'Report ID (must be in Finished state)' },
-                max_chars: { type: 'number', description: 'Maximum characters of report content to return (default 100000)' },
-            },
-            required: ['id'],
-        },
-    },
-    {
-        name: 'qualys_list_asset_groups',
-        description: 'List asset groups in Qualys with their ID, title and IP ranges. Asset groups typically map to clients or sites — use their IDs to scope qualys_list_hosts and qualys_host_detections.',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                ids: { type: 'string', description: 'Comma-separated asset group IDs' },
-                show_attributes: { type: 'string', description: 'Comma-separated attributes to show, e.g. "ALL" or "ID,TITLE,IP_SET". Default "ID,TITLE".' },
-                ...truncationProperties,
-            },
-        },
-    },
     {
         name: 'qualys_api_call',
         description: 'Make a raw call to any Qualys API endpoint not covered by the other tools, e.g. /api/2.0/fo/report/template/scan/?action=list, /api/2.0/fo/schedule/scan/?action=list, or Asset Management endpoints under /qps/rest/2.0/. Only use list/read actions — do not launch scans or modify data. Params are sent as query string (GET) or form body (POST; some endpoints require POST).',
@@ -210,7 +148,9 @@ const tools = [
         },
     },
 ];
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: rawApiEnabled ? tools : tools.filter((t) => t.name !== 'qualys_api_call'),
+}));
 function toIso(ms) {
     return typeof ms === 'number' ? new Date(ms).toISOString() : undefined;
 }
@@ -449,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,
@@ -463,25 +406,6 @@ async function handleTool(name, args) {
                 assets: fullDetails ? assets.map((a) => stripEmpty(a)) : assets.map(compactAsset),
             }, null, 2);
         }
-        case 'qualys_list_hosts': {
-            const result = await client.request('/api/2.0/fo/asset/host/', {
-                action: 'list',
-                echo_request: 0,
-                ids: args.ids,
-                ips: args.ips,
-                ag_ids: args.ag_ids,
-                ag_titles: args.ag_titles,
-                details: args.details ?? 'Basic',
-                os_pattern: args.os_pattern,
-                no_vm_scan_since: args.no_vm_scan_since,
-                vm_scan_since: args.vm_scan_since,
-                show_tags: args.show_tags ? 1 : undefined,
-                ...tagParams(args),
-                truncation_limit: args.truncation_limit ?? 100,
-                id_min: args.id_min,
-            });
-            return JSON.stringify(simplify(result.parsed), null, 2);
-        }
         case 'qualys_host_detections': {
             const result = await client.request('/api/2.0/fo/asset/host/vm/detection/', {
                 action: 'list',
@@ -514,53 +438,10 @@ async function handleTool(name, args) {
             });
             return JSON.stringify(simplify(result.parsed), null, 2);
         }
-        case 'qualys_list_scans': {
-            const result = await client.request('/api/2.0/fo/scan/', {
-                action: 'list',
-                echo_request: 0,
-                scan_ref: args.scan_ref,
-                state: args.state,
-                type: args.type,
-                target: args.target,
-                launched_after_datetime: args.launched_after_datetime,
-                launched_before_datetime: args.launched_before_datetime,
-            });
-            return JSON.stringify(simplify(result.parsed), null, 2);
-        }
-        case 'qualys_list_reports': {
-            const result = await client.request('/api/2.0/fo/report/', {
-                action: 'list',
-                echo_request: 0,
-                id: args.id,
-                state: args.state,
-                user_login: args.user_login,
-            });
-            return JSON.stringify(simplify(result.parsed), null, 2);
-        }
-        case 'qualys_fetch_report': {
-            const result = await client.request('/api/2.0/fo/report/', {
-                action: 'fetch',
-                id: args.id,
-            });
-            const maxChars = args.max_chars ?? 100_000;
-            const content = result.text ?? JSON.stringify(simplify(result.parsed), null, 2);
-            if (content.length > maxChars) {
-                return content.slice(0, maxChars) + `\n\n[Truncated: ${content.length} total characters, showing first ${maxChars}]`;
-            }
-            return content;
-        }
-        case 'qualys_list_asset_groups': {
-            const result = await client.request('/api/2.0/fo/asset/group/', {
-                action: 'list',
-                echo_request: 0,
-                ids: args.ids,
-                show_attributes: args.show_attributes ?? 'ID,TITLE',
-                truncation_limit: args.truncation_limit ?? 200,
-                id_min: args.id_min,
-            });
-            return JSON.stringify(simplify(result.parsed), null, 2);
-        }
         case 'qualys_api_call': {
+            if (!rawApiEnabled) {
+                throw new Error('The raw API tool is disabled. Set QUALYS_ENABLE_RAW_API=true to enable it.');
+            }
             const path = args.path;
             if (!path.startsWith('/'))
                 throw new Error('path must start with /');
@@ -598,7 +479,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error(`Qualys MCP server running (${baseUrl})`);
+    console.error(`Qualys MCP server running (${baseUrl}, raw API ${rawApiEnabled ? 'enabled' : 'disabled'})`);
 }
 main().catch((error) => {
     console.error('Fatal error:', error);

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.3.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",