qualys-mcp 0.2.0 → 0.3.0

package/README.md

@@ -6,9 +6,12 @@ Read-only MCP server for the Qualys VMDR API. Exposes host assets, vulnerability
 
 | Tool | Purpose |
 |---|---|
+| `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) |
-| `qualys_host_detections` | Vulnerabilities detected per host (QID, severity, status, evidence) |
+| `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 |
@@ -78,6 +81,18 @@ npm run inspector      # MCP Inspector UI
 npm run build          # compile to dist/
 ```
 
+## Reporting across a client base
+
+Clients segmented by asset tags? The intended flow for "state of vulnerabilities across our clients" is:
+
+1. `qualys_vuln_overview` — one call sweeps the whole estate and returns a client-by-client table: tag, host count, open vulnerabilities by severity. Use `exclude_tags` to drop system tags (e.g. "Cloud Agent") from the grouping.
+2. `qualys_vuln_summary` with `tags: "Client A"` — expand one client into its per-machine breakdown, sorted worst-first. Aggregation happens inside the server, so even thousands of detections come back as a few KB of counts.
+3. `qualys_host_detections` with `tags`/`ids` — drill into the individual findings on a machine, then `qualys_knowledgebase` for the fix.
+
+### CVSS-based thresholds (Cyber Essentials)
+
+Qualys severity (1–5) is not CVSS. If your remediation policy is CVSS-based — e.g. Cyber Essentials' "fix CVSS 7.0+ within 14 days" — pass `cvss_min: 7` to `qualys_vuln_overview` or `qualys_vuln_summary`. The server joins each detection against the KnowledgeBase CVSS v3 base score (v2 where no v3 exists) and counts only vulnerabilities at or above the threshold. QIDs with no CVSS data are excluded and reported in the response's `cvssFilter` block. Scores are cached for the server's lifetime, so repeated dashboard queries are fast.
+
 ## 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`.

package/dist/index.js

@@ -38,6 +38,46 @@ const tools = [
             },
         },
     },
+    {
+        name: 'qualys_vuln_overview',
+        description: 'Estate-wide vulnerability overview grouped by asset tag — one call answers "how many open vulnerabilities does each client have?". Sweeps all detection data server-side, groups counts by each host\'s tags, and returns a table of tag → host count and vulnerability counts by severity. Set cvss_min=7 to count only CVSS 7.0+ vulnerabilities (the Cyber Essentials remediation threshold) — scores are joined from the KnowledgeBase (CVSS v3 base, falling back to v2). Hosts with multiple tags are counted under each tag. Use qualys_vuln_summary to expand one client into its per-machine breakdown.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                cvss_min: { type: 'number', description: 'Only count vulnerabilities with CVSS base score >= this value, e.g. 7 for Cyber Essentials. Omit to count everything.' },
+                tags: { type: 'string', description: 'Optionally restrict the sweep to hosts with these comma-separated tags. Default: whole estate.' },
+                exclude_tags: { type: 'string', description: 'Comma-separated tag names to omit from the grouping (e.g. system tags like "Cloud Agent")' },
+                severities: { type: 'string', description: 'Only count these Qualys severity levels, e.g. "4,5". Usually unnecessary when cvss_min is set.' },
+                status: { type: 'string', description: 'Detection statuses to count. Default "New,Active,Re-Opened" (open vulnerabilities).' },
+                max_hosts: { type: 'number', description: 'Safety cap on hosts to sweep (default 10000)' },
+            },
+        },
+    },
+    {
+        name: 'qualys_vuln_summary',
+        description: 'Aggregated vulnerability counts by severity — the dashboard tool. Give it one or more client tags (or IPs/asset group IDs) and it pulls ALL matching detection data server-side and returns compact counts: totals by severity (1-5, confirmed vs potential) plus a per-machine breakdown sorted worst-first. Use this to report on the state of vulnerabilities per client; use qualys_host_detections to drill into the individual findings on a specific machine afterwards. Call qualys_list_tags first to see available client tags.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tags: { type: 'string', description: 'Comma-separated asset tag names to scope to, e.g. "Client A" — tags are how clients are segmented' },
+                tag_include_selector: { type: 'string', description: '"any" (default) or "all" — whether hosts must have any or all of the tags' },
+                ips: { type: 'string', description: 'Alternatively scope by comma-separated IPs or ranges' },
+                ag_ids: { type: 'string', description: 'Alternatively scope by comma-separated asset group IDs' },
+                cvss_min: { type: 'number', description: 'Only count vulnerabilities with CVSS base score >= this value, e.g. 7 for Cyber Essentials (CVSS v3 base, v2 fallback, joined from the KnowledgeBase)' },
+                severities: { type: 'string', description: 'Only count these Qualys severity levels, e.g. "4,5". Default: all.' },
+                status: { type: 'string', description: 'Detection statuses to count. Default "New,Active,Re-Opened" (open vulnerabilities). Add "Fixed" to include remediated ones.' },
+                max_hosts: { type: 'number', description: 'Safety cap on hosts to aggregate (default 5000)' },
+            },
+        },
+    },
+    {
+        name: 'qualys_list_tags',
+        description: 'List asset tags defined in Qualys, including tag hierarchies (parent tags with their children). Tags are how clients are segmented — use this to discover the client list, then feed tag names into qualys_vuln_summary or qualys_asset_inventory. Returns the first 100 tags.',
+        inputSchema: {
+            type: 'object',
+            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.',
@@ -56,6 +96,8 @@ const tools = [
                 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,
             },
         },
@@ -78,6 +120,9 @@ const tools = [
                 },
                 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)' },
+                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' },
+                include_results: { type: 'boolean', description: 'Include the detection RESULTS evidence text (verbose). Default false.' },
                 ...truncationProperties,
             },
         },
@@ -195,8 +240,213 @@ function compactAsset(a) {
     });
 }
 const INVENTORY_FIELDS = 'assetId,assetName,address,dnsName,operatingSystem,criticality,riskScore,lastLoggedOnUser,tag,agent,sensor,inventory,assetType,lastModifiedDate';
+function tagParams(args) {
+    if (!args.tags)
+        return {};
+    return {
+        use_tags: 1,
+        tag_set_by: 'name',
+        tag_include_selector: args.tag_include_selector ?? 'any',
+        tag_set_include: args.tags,
+    };
+}
+async function sweepDetections(args, showTags, maxHosts) {
+    const hosts = [];
+    let idMin;
+    let truncated = false;
+    while (true) {
+        const result = await client.request('/api/2.0/fo/asset/host/vm/detection/', {
+            action: 'list',
+            echo_request: 0,
+            ...tagParams(args),
+            ips: args.ips,
+            ag_ids: args.ag_ids,
+            severities: args.severities,
+            status: args.status ?? 'New,Active,Re-Opened',
+            show_results: 0,
+            show_igs: 0,
+            show_tags: showTags ? 1 : undefined,
+            truncation_limit: Math.min(1000, maxHosts),
+            id_min: idMin,
+        });
+        const resp = simplify(result.parsed);
+        const pageHosts = resp?.HOST_LIST?.HOST ?? [];
+        for (const h of pageHosts) {
+            const detections = h?.DETECTION_LIST?.DETECTION ?? [];
+            hosts.push({
+                id: String(h.ID),
+                ip: h.IP,
+                dns: h.DNS,
+                os: h.OS,
+                lastScan: h.LAST_SCAN_DATETIME,
+                tags: (h.TAGS?.TAG ?? []).map((t) => String(t.NAME)),
+                detections: detections.map((d) => ({ qid: String(d.QID), sev: String(d.SEVERITY), type: String(d.TYPE) })),
+            });
+        }
+        const warningUrl = resp?.WARNING?.[0]?.URL;
+        const nextIdMin = warningUrl?.match(/id_min=(\d+)/)?.[1];
+        if (!nextIdMin)
+            break;
+        if (hosts.length >= maxHosts) {
+            truncated = true;
+            break;
+        }
+        idMin = Number(nextIdMin);
+    }
+    return { hosts, truncated };
+}
+const cvssCache = new Map();
+async function fetchCvssScores(qids) {
+    const missing = [...new Set(qids)].filter((q) => !cvssCache.has(q));
+    const num = (x) => {
+        const n = parseFloat(String(x ?? ''));
+        return Number.isFinite(n) ? n : undefined;
+    };
+    for (let i = 0; i < missing.length; i += 400) {
+        const chunk = missing.slice(i, i + 400);
+        const result = await client.request('/api/2.0/fo/knowledge_base/vuln/', { action: 'list', echo_request: 0, ids: chunk.join(','), details: 'Basic' }, 'POST');
+        const resp = simplify(result.parsed);
+        const vulns = resp?.VULN_LIST?.VULN ?? [];
+        for (const v of vulns) {
+            cvssCache.set(String(v.QID), { v2: num(v.CVSS?.BASE), v3: num(v.CVSS_V3?.BASE) });
+        }
+        for (const q of chunk)
+            if (!cvssCache.has(q))
+                cvssCache.set(q, {});
+    }
+}
+async function applyCvssFilter(hosts, cvssMin) {
+    await fetchCvssScores(hosts.flatMap((h) => h.detections.map((d) => d.qid)));
+    const unknown = new Set();
+    let excludedUnknown = 0;
+    for (const h of hosts) {
+        h.detections = h.detections.filter((d) => {
+            const score = cvssCache.get(d.qid);
+            const base = score?.v3 ?? score?.v2;
+            if (base === undefined) {
+                unknown.add(d.qid);
+                excludedUnknown += 1;
+                return false;
+            }
+            return base >= cvssMin;
+        });
+    }
+    return {
+        basis: `CVSS v3 base score >= ${cvssMin} (v2 base used where no v3 score exists)`,
+        unknownCvssQids: unknown.size,
+        detectionsExcludedUnknownCvss: excludedUnknown,
+    };
+}
+function countBySeverity(detections, totals) {
+    const counts = { confirmed: {}, potential: {} };
+    for (const d of detections) {
+        const bucket = d.type === 'Potential' ? 'potential' : 'confirmed';
+        counts[bucket][d.sev] = (counts[bucket][d.sev] ?? 0) + 1;
+        if (totals)
+            totals[bucket][d.sev] = (totals[bucket][d.sev] ?? 0) + 1;
+    }
+    return counts;
+}
+const hostWeight = (c, total) => (c.confirmed['5'] ?? 0) * 1e6 + (c.confirmed['4'] ?? 0) * 1e3 + total;
 async function handleTool(name, args) {
     switch (name) {
+        case 'qualys_vuln_summary': {
+            const maxHosts = args.max_hosts ?? 5000;
+            const { hosts, truncated } = await sweepDetections(args, false, maxHosts);
+            const cvssInfo = args.cvss_min !== undefined ? await applyCvssFilter(hosts, args.cvss_min) : undefined;
+            const totals = { confirmed: {}, potential: {} };
+            const rows = hosts.map((h) => {
+                const counts = countBySeverity(h.detections, totals);
+                return {
+                    id: h.id,
+                    ip: h.ip,
+                    dns: h.dns,
+                    os: h.os,
+                    lastScan: h.lastScan,
+                    confirmed: counts.confirmed,
+                    potential: counts.potential,
+                    total: h.detections.length,
+                };
+            });
+            rows.sort((a, b) => hostWeight(b, b.total) - hostWeight(a, a.total));
+            return JSON.stringify(stripEmpty({
+                scope: {
+                    tags: args.tags,
+                    ips: args.ips,
+                    ag_ids: args.ag_ids,
+                    severities: args.severities,
+                    status: args.status ?? 'New,Active,Re-Opened',
+                },
+                cvssFilter: cvssInfo,
+                hostCount: rows.length,
+                totalsBySeverity: totals,
+                truncated: truncated
+                    ? `Stopped at max_hosts=${maxHosts} — counts are incomplete; narrow the scope or raise max_hosts`
+                    : undefined,
+                hosts: rows,
+            }), null, 2);
+        }
+        case 'qualys_vuln_overview': {
+            const maxHosts = args.max_hosts ?? 10000;
+            const { hosts, truncated } = await sweepDetections(args, true, maxHosts);
+            const cvssInfo = args.cvss_min !== undefined ? await applyCvssFilter(hosts, args.cvss_min) : undefined;
+            const excluded = new Set((args.exclude_tags ?? '')
+                .split(',')
+                .map((t) => t.trim())
+                .filter(Boolean));
+            const overall = { confirmed: {}, potential: {} };
+            const byTag = new Map();
+            for (const h of hosts) {
+                countBySeverity(h.detections, overall);
+                const tags = h.tags.filter((t) => !excluded.has(t));
+                for (const tag of tags.length > 0 ? tags : ['(untagged)']) {
+                    let row = byTag.get(tag);
+                    if (!row) {
+                        row = { hosts: 0, counts: { confirmed: {}, potential: {} }, total: 0 };
+                        byTag.set(tag, row);
+                    }
+                    row.hosts += 1;
+                    countBySeverity(h.detections, row.counts);
+                    row.total += h.detections.length;
+                }
+            }
+            const tagRows = [...byTag.entries()]
+                .map(([tag, r]) => ({ tag, hosts: r.hosts, confirmed: r.counts.confirmed, potential: r.counts.potential, total: r.total }))
+                .sort((a, b) => hostWeight(b, b.total) - hostWeight(a, a.total));
+            return JSON.stringify(stripEmpty({
+                scope: {
+                    tags: args.tags,
+                    severities: args.severities,
+                    status: args.status ?? 'New,Active,Re-Opened',
+                    exclude_tags: args.exclude_tags,
+                },
+                cvssFilter: cvssInfo,
+                hostCount: hosts.length,
+                note: 'Hosts carrying multiple tags are counted under each tag, so tag rows can overlap.',
+                truncated: truncated
+                    ? `Stopped at max_hosts=${maxHosts} — counts are incomplete; narrow the scope or raise max_hosts`
+                    : undefined,
+                overallBySeverity: overall,
+                byTag: tagRows,
+            }), null, 2);
+        }
+        case 'qualys_list_tags': {
+            const result = await client.request('/qps/rest/2.0/search/am/tag', {}, 'POST');
+            const resp = simplify(result.parsed);
+            const rawTags = resp?.data?.Tag ?? [];
+            const tags = (Array.isArray(rawTags) ? rawTags : [rawTags]).map((t) => stripEmpty({
+                id: t.id,
+                name: t.name,
+                created: t.created,
+                children: (() => {
+                    const kids = t.children?.list?.TagSimple;
+                    if (!kids)
+                        return undefined;
+                    return (Array.isArray(kids) ? kids : [kids]).map((k) => ({ id: k.id, name: k.name }));
+                })(),
+            }));
+            return JSON.stringify({ count: resp?.count, hasMoreRecords: resp?.hasMoreRecords, tags }, null, 2);
+        }
         case 'qualys_asset_inventory': {
             const fullDetails = args.full_details === true;
             const result = (await client.gatewayRequest('/rest/2.0/search/am/asset', {
@@ -226,6 +476,7 @@ async function handleTool(name, args) {
                 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,
             });
@@ -243,7 +494,9 @@ async function handleTool(name, args) {
                 severities: args.severities,
                 status: args.status,
                 show_igs: args.show_igs ? 1 : undefined,
+                show_results: args.include_results ? undefined : 0,
                 detection_updated_since: args.detection_updated_since,
+                ...tagParams(args),
                 truncation_limit: args.truncation_limit ?? 20,
                 id_min: args.id_min,
             });

package/dist/qualys-client.js

@@ -61,7 +61,7 @@ export class QualysClient {
             'X-Requested-With': 'qualys-mcp',
         };
         let body;
-        if (method === 'POST') {
+        if (method === 'POST' && [...search.keys()].length > 0) {
             headers['Content-Type'] = 'application/x-www-form-urlencoded';
             body = search.toString();
         }

package/package.json

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