qualys-mcp 0.1.0 → 0.2.0

package/README.md

@@ -6,7 +6,8 @@ Read-only MCP server for the Qualys VMDR API. Exposes host assets, vulnerability
 
 | Tool | Purpose |
 |---|---|
-| `qualys_list_hosts` | Scanned host assets (ID, IP, DNS, OS, last scan dates) |
+| `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_knowledgebase` | QID details: title, CVEs, threat, impact, solution |
 | `qualys_list_scans` | Scan history and status |
@@ -48,6 +49,7 @@ Three required environment variables:
 | `QUALYS_USERNAME` | Qualys API user login |
 | `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. |
 
 The API server depends on which Qualys platform your subscription lives on — check your Qualys login URL:
 
@@ -78,6 +80,8 @@ npm run build          # compile to dist/
 
 ## 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`.
+- 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.
 - 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.

package/dist/index.js

@@ -2,7 +2,7 @@
 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';
+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 || '';
@@ -12,7 +12,7 @@ if (!username || !password || !baseUrl) {
     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 client = new QualysClient({ username, password, baseUrl, gatewayUrl: process.env.QUALYS_GATEWAY_URL });
 const server = new Server({ name: 'qualys-mcp', version: '0.1.0' }, { capabilities: { tools: {} } });
 const truncationProperties = {
     truncation_limit: {
@@ -25,6 +25,19 @@ 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").',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                filter: { type: 'string', description: 'QQL filter, e.g. tags.name:"Superfast IT" or lastLoggedOnUser:"jsmith". Omit to return all assets.' },
+                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.' },
+            },
+        },
+    },
     {
         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.',
@@ -42,6 +55,7 @@ const tools = [
                 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.' },
                 ...truncationProperties,
             },
         },
@@ -152,8 +166,53 @@ const tools = [
     },
 ];
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+function toIso(ms) {
+    return typeof ms === 'number' ? new Date(ms).toISOString() : undefined;
+}
+function compactAsset(a) {
+    return stripEmpty({
+        assetId: a.assetId,
+        assetName: a.assetName,
+        address: a.address,
+        dnsName: a.dnsName,
+        operatingSystem: a.operatingSystem?.fullName ?? a.operatingSystem?.osName,
+        criticality: a.criticality?.score,
+        riskScore: a.riskScore,
+        lastLoggedOnUser: a.lastLoggedOnUser,
+        tags: a.tagList?.tag?.map((t) => t.tagName),
+        agent: a.agent
+            ? {
+                status: a.agent.status,
+                version: a.agent.version,
+                lastCheckedIn: toIso(a.agent.lastCheckedIn) ?? a.agent.lastCheckedIn,
+                lastActivity: toIso(a.agent.lastActivity) ?? a.agent.lastActivity,
+            }
+            : undefined,
+        lastVMScan: toIso(a.sensor?.lastVMScan) ?? a.sensor?.lastVMScan,
+        lastComplianceScan: toIso(a.sensor?.lastComplianceScan) ?? a.sensor?.lastComplianceScan,
+        sources: a.inventory?.source ?? a.assetType,
+        lastModifiedDate: a.lastModifiedDate,
+    });
+}
+const INVENTORY_FIELDS = 'assetId,assetName,address,dnsName,operatingSystem,criticality,riskScore,lastLoggedOnUser,tag,agent,sensor,inventory,assetType,lastModifiedDate';
 async function handleTool(name, args) {
     switch (name) {
+        case 'qualys_asset_inventory': {
+            const fullDetails = args.full_details === true;
+            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,
+            }));
+            const assets = result?.assetListData?.asset ?? [];
+            return JSON.stringify({
+                count: result?.count,
+                hasMore: result?.hasMore,
+                lastSeenAssetId: result?.lastSeenAssetId,
+                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',
@@ -166,6 +225,7 @@ async function handleTool(name, args) {
                 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,
                 truncation_limit: args.truncation_limit ?? 100,
                 id_min: args.id_min,
             });

package/dist/qualys-client.js

@@ -26,12 +26,27 @@ const parser = new XMLParser({
     trimValues: true,
     isArray: (name) => ARRAY_TAGS.has(name),
 });
+export function deriveGatewayUrl(baseUrl) {
+    const url = new URL(baseUrl);
+    if (url.hostname.includes('.apps.')) {
+        return 'https://' + url.hostname.replace(/^qualysapi\./, 'gateway.');
+    }
+    return 'https://' + url.hostname.replace(/^qualysapi\./, 'gateway.qg1.apps.');
+}
 export class QualysClient {
+    username;
+    password;
     authHeader;
     baseUrl;
+    gatewayUrl;
+    token = null;
+    tokenExpiresAt = 0;
     constructor(config) {
+        this.username = config.username;
+        this.password = config.password;
         this.authHeader = 'Basic ' + Buffer.from(`${config.username}:${config.password}`).toString('base64');
         this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        this.gatewayUrl = (config.gatewayUrl || deriveGatewayUrl(this.baseUrl)).replace(/\/+$/, '');
     }
     async request(path, params = {}, method = 'GET') {
         const url = new URL(this.baseUrl + (path.startsWith('/') ? path : '/' + path));
@@ -75,6 +90,55 @@ export class QualysClient {
             return { text, contentType };
         }
     }
+    async getToken(forceRefresh = false) {
+        if (!forceRefresh && this.token && Date.now() < this.tokenExpiresAt) {
+            return this.token;
+        }
+        const response = await fetch(this.gatewayUrl + '/auth', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({ username: this.username, password: this.password, token: 'true' }),
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            throw new Error(`Qualys gateway auth failed (${response.status}) at ${this.gatewayUrl}/auth: ${text.slice(0, 500)}. ` +
+                'If your platform gateway differs, set QUALYS_GATEWAY_URL.');
+        }
+        this.token = text.trim();
+        this.tokenExpiresAt = Date.now() + 3.5 * 60 * 60 * 1000;
+        return this.token;
+    }
+    async gatewayRequest(path, query = {}, 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 !== '') {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        for (let attempt = 0;; attempt++) {
+            const token = await this.getToken(attempt > 0);
+            const response = await fetch(url, {
+                method,
+                headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+            });
+            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;
+            }
+            const text = await response.text();
+            if (!response.ok) {
+                throw new Error(`Qualys gateway API error ${response.status} for ${method} ${url.pathname}: ${text.slice(0, 2000)}`);
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return text;
+            }
+        }
+    }
 }
 export function simplify(parsed) {
     if (!parsed || typeof parsed !== 'object')
@@ -90,3 +154,19 @@ export function simplify(parsed) {
     }
     return obj;
 }
+export function stripEmpty(value) {
+    if (Array.isArray(value)) {
+        const arr = value.map(stripEmpty).filter((v) => v !== undefined);
+        return arr.length > 0 ? arr : undefined;
+    }
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            const stripped = stripEmpty(v);
+            if (stripped !== undefined)
+                out[k] = stripped;
+        }
+        return Object.keys(out).length > 0 ? out : undefined;
+    }
+    return value === null || value === undefined ? undefined : value;
+}

package/package.json

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