qualys-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Superfast IT
+
+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.

package/README.md

@@ -0,0 +1,84 @@
+# Qualys MCP Server
+
+Read-only MCP server for the Qualys VMDR API. Exposes host assets, vulnerability detections, the KnowledgeBase, scans, reports and asset groups to Claude (Claude Desktop / Cowork, Claude Code, or any MCP client).
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `qualys_list_hosts` | Scanned host assets (ID, IP, DNS, OS, last scan dates) |
+| `qualys_host_detections` | Vulnerabilities detected per host (QID, severity, status, evidence) |
+| `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) |
+
+## Quick start (Claude Desktop / Cowork)
+
+Add to `mcpServers` in your `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+"qualys": {
+  "command": "npx",
+  "args": ["-y", "qualys-mcp"],
+  "env": {
+    "QUALYS_USERNAME": "your-api-username",
+    "QUALYS_PASSWORD": "your-api-password",
+    "QUALYS_BASE_URL": "https://qualysapi.qg1.apps.qualys.co.uk"
+  }
+}
+```
+
+For Claude Code:
+
+```bash
+claude mcp add-json qualys --scope user '{"type":"stdio","command":"npx","args":["-y","qualys-mcp"],"env":{"QUALYS_USERNAME":"your-api-username","QUALYS_PASSWORD":"your-api-password","QUALYS_BASE_URL":"https://qualysapi.qg1.apps.qualys.co.uk"}}'
+```
+
+Requires Node.js 18+.
+
+## Configuration
+
+Three required environment variables:
+
+| Variable | Value |
+|---|---|
+| `QUALYS_USERNAME` | Qualys API user login |
+| `QUALYS_PASSWORD` | Qualys API user password |
+| `QUALYS_BASE_URL` | Your platform's API server (see below) |
+
+The API server depends on which Qualys platform your subscription lives on — check your Qualys login URL:
+
+| You log in at | `QUALYS_BASE_URL` |
+|---|---|
+| qualysguard.qg1.apps.qualys.co.uk (UK1) | `https://qualysapi.qg1.apps.qualys.co.uk` |
+| qualysguard.qualys.eu (EU1) | `https://qualysapi.qualys.eu` |
+| qualysguard.qg2.apps.qualys.eu (EU2) | `https://qualysapi.qg2.apps.qualys.eu` |
+| qualysguard.qualys.com (US1) | `https://qualysapi.qualys.com` |
+| qualysguard.qg2.apps.qualys.com (US2) | `https://qualysapi.qg2.apps.qualys.com` |
+| qualysguard.qg3.apps.qualys.com (US3) | `https://qualysapi.qg3.apps.qualys.com` |
+
+Full list: https://www.qualys.com/platform-identification/
+
+Best practice: create a dedicated read-only API user in Qualys (Users → New User, role "Reader" with API access enabled) rather than using your main login. Each team member should use their own API credentials.
+
+## Development
+
+```bash
+git clone <repo>
+cd qualys-mcp
+npm install
+cp .env.example .env   # fill in credentials
+npm run dev            # watch mode
+npm run inspector      # MCP Inspector UI
+npm run build          # compile to dist/
+```
+
+## Notes
+
+- 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.
+- Large result sets are truncated by Qualys; the response then contains a `WARNING` element with the URL for the next page — pass its `id_min` value back to the same tool to continue.
+- `qualys_host_detections` output is verbose. Default truncation is 20 hosts per call; filter by `severities`, `status` or asset group where possible.

package/dist/index.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { QualysClient, simplify } from './qualys-client.js';
+const username = process.env.QUALYS_USERNAME || '';
+const password = process.env.QUALYS_PASSWORD || '';
+const baseUrl = process.env.QUALYS_BASE_URL || '';
+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),');
+    console.error('https://qualysapi.qualys.eu (EU1), https://qualysapi.qg2.apps.qualys.eu (EU2), https://qualysapi.qualys.com (US1).');
+    process.exit(1);
+}
+const client = new QualysClient({ username, password, baseUrl });
+const server = new Server({ name: 'qualys-mcp', version: '0.1.0' }, { capabilities: { tools: {} } });
+const truncationProperties = {
+    truncation_limit: {
+        type: 'number',
+        description: 'Max records per response. When truncated, the response includes a WARNING with the URL for the next page (use its id_min value with this tool to continue).',
+    },
+    id_min: {
+        type: 'number',
+        description: 'Only return records with ID >= this value. Used for paging through truncated results.',
+    },
+};
+const tools = [
+    {
+        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)' },
+                ...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.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ids: { type: 'string', description: 'Comma-separated host IDs or ranges' },
+                ips: { type: 'string', description: 'Comma-separated IPs or ranges' },
+                ag_ids: { type: 'string', description: 'Comma-separated asset group IDs' },
+                ag_titles: { type: 'string', description: 'Comma-separated asset group titles' },
+                qids: { type: 'string', description: 'Comma-separated QIDs (vulnerability IDs) to filter on' },
+                severities: { type: 'string', description: 'Comma-separated severity levels 1-5, e.g. "4,5" for high and critical' },
+                status: {
+                    type: 'string',
+                    description: 'Comma-separated detection statuses: "New", "Active", "Re-Opened", "Fixed". Default excludes Fixed.',
+                },
+                show_igs: { type: 'boolean', description: 'Include information-gathered (IG) detections as well as vulnerabilities. Default false.' },
+                detection_updated_since: { type: 'string', description: 'Only detections updated since this date (YYYY-MM-DD)' },
+                ...truncationProperties,
+            },
+        },
+    },
+    {
+        name: 'qualys_knowledgebase',
+        description: 'Look up vulnerabilities in the Qualys KnowledgeBase by QID: title, severity, CVE IDs, vendor references, threat description, impact, solution/patch information, and exploit/malware correlation. Use details="All" for the full write-up including the fix.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                ids: { type: 'string', description: 'Comma-separated QIDs or ranges, e.g. "91234,105000-105999"' },
+                details: { type: 'string', description: 'Level of detail: "Basic" (default) or "All" (includes threat, impact and solution text)' },
+                last_modified_after: { type: 'string', description: 'Only QIDs modified after this date (YYYY-MM-DD)' },
+                id_min: { type: 'number', description: 'Only QIDs >= this value' },
+                id_max: { type: 'number', description: 'Only QIDs <= this value' },
+            },
+        },
+    },
+    {
+        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).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'API path starting with /, e.g. "/api/2.0/fo/schedule/scan/"' },
+                params: {
+                    type: 'object',
+                    description: 'Parameters as key/value pairs, e.g. {"action": "list", "echo_request": "0"}',
+                    additionalProperties: { type: 'string' },
+                },
+                method: { type: 'string', description: '"GET" (default) or "POST"' },
+            },
+            required: ['path'],
+        },
+    },
+];
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+async function handleTool(name, args) {
+    switch (name) {
+        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,
+                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',
+                echo_request: 0,
+                ids: args.ids,
+                ips: args.ips,
+                ag_ids: args.ag_ids,
+                ag_titles: args.ag_titles,
+                qids: args.qids,
+                severities: args.severities,
+                status: args.status,
+                show_igs: args.show_igs ? 1 : undefined,
+                detection_updated_since: args.detection_updated_since,
+                truncation_limit: args.truncation_limit ?? 20,
+                id_min: args.id_min,
+            });
+            return JSON.stringify(simplify(result.parsed), null, 2);
+        }
+        case 'qualys_knowledgebase': {
+            const result = await client.request('/api/2.0/fo/knowledge_base/vuln/', {
+                action: 'list',
+                echo_request: 0,
+                ids: args.ids,
+                details: args.details ?? 'Basic',
+                last_modified_after: args.last_modified_after,
+                id_min: args.id_min,
+                id_max: args.id_max,
+            });
+            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': {
+            const path = args.path;
+            if (!path.startsWith('/'))
+                throw new Error('path must start with /');
+            const method = args.method?.toUpperCase() === 'POST' ? 'POST' : 'GET';
+            const params = args.params || {};
+            if (!('echo_request' in params) && path.startsWith('/api/'))
+                params.echo_request = '0';
+            const result = await client.request(path, params, method);
+            return result.parsed !== undefined
+                ? JSON.stringify(simplify(result.parsed), null, 2)
+                : (result.text ?? '');
+        }
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        const text = await handleTool(name, args || {});
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`Qualys MCP server running (${baseUrl})`);
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/qualys-client.js

@@ -0,0 +1,92 @@
+import { XMLParser } from 'fast-xml-parser';
+const MAX_RETRIES = 3;
+const ARRAY_TAGS = new Set([
+    'HOST',
+    'DETECTION',
+    'VULN',
+    'SCAN',
+    'REPORT',
+    'ASSET_GROUP',
+    'CVE',
+    'BUGTRAQ',
+    'VENDOR_REFERENCE',
+    'COMPLIANCE',
+    'CORRELATION',
+    'EXPLOIT',
+    'MALWARE',
+    'ASSET_GROUP_TITLE',
+    'TAG',
+    'DNS_DATA',
+    'WARNING',
+    'OPTION_PROFILE',
+]);
+const parser = new XMLParser({
+    ignoreAttributes: true,
+    parseTagValue: false,
+    trimValues: true,
+    isArray: (name) => ARRAY_TAGS.has(name),
+});
+export class QualysClient {
+    authHeader;
+    baseUrl;
+    constructor(config) {
+        this.authHeader = 'Basic ' + Buffer.from(`${config.username}:${config.password}`).toString('base64');
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+    }
+    async request(path, params = {}, method = 'GET') {
+        const url = new URL(this.baseUrl + (path.startsWith('/') ? path : '/' + path));
+        const search = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined && value !== null && value !== '') {
+                search.set(key, String(value));
+            }
+        }
+        const headers = {
+            Authorization: this.authHeader,
+            'X-Requested-With': 'qualys-mcp',
+        };
+        let body;
+        if (method === 'POST') {
+            headers['Content-Type'] = 'application/x-www-form-urlencoded';
+            body = search.toString();
+        }
+        else {
+            url.search = search.toString();
+        }
+        for (let attempt = 0;; attempt++) {
+            const response = await fetch(url, { method, headers, body });
+            if ((response.status === 409 || response.status === 429) && attempt < MAX_RETRIES) {
+                const toWait = Number(response.headers.get('x-ratelimit-towait-sec')) ||
+                    Number(response.headers.get('retry-after')) ||
+                    10 * (attempt + 1);
+                if (toWait <= 120) {
+                    await new Promise((resolve) => setTimeout(resolve, toWait * 1000));
+                    continue;
+                }
+            }
+            const contentType = response.headers.get('content-type') || '';
+            const text = await response.text();
+            if (!response.ok) {
+                throw new Error(`Qualys API error ${response.status} for ${method} ${url.pathname}: ${text.slice(0, 2000)}`);
+            }
+            if (text.trimStart().startsWith('<')) {
+                return { parsed: parser.parse(text), contentType };
+            }
+            return { text, contentType };
+        }
+    }
+}
+export function simplify(parsed) {
+    if (!parsed || typeof parsed !== 'object')
+        return parsed;
+    const obj = parsed;
+    const keys = Object.keys(obj).filter((k) => k !== '?xml');
+    if (keys.length === 1) {
+        const inner = obj[keys[0]];
+        if (inner && typeof inner === 'object' && 'RESPONSE' in inner) {
+            return inner.RESPONSE;
+        }
+        return inner;
+    }
+    return obj;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "qualys-mcp",
+  "version": "0.1.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",
+  "bin": {
+    "qualys-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "qualys",
+    "vmdr",
+    "vulnerability-management",
+    "claude"
+  ],
+  "author": "Superfast IT",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.4",
+    "fast-xml-parser": "^4.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx watch --env-file=.env src/index.ts",
+    "start": "node dist/index.js",
+    "inspector": "npx @modelcontextprotocol/inspector tsx --env-file=.env src/index.ts"
+  }
+}