qualys-mcp 0.3.0 → 0.4.0

package/README.md

@@ -10,14 +10,11 @@ Read-only MCP server for the Qualys VMDR API. Exposes host assets, vulnerability
 | `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_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:
 

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),');
@@ -78,30 +79,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 +118,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 +136,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;
 }
@@ -463,25 +391,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 +423,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 +464,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualys-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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",