cpe_lookup
Search Shodan's CVEDB for Common Platform Enumeration entries by product name to identify software and hardware versions and configurations. Supports pagination and count-only results.
Instructions
Search for Common Platform Enumeration (CPE) entries by product name in Shodan's CVEDB. Supports pagination and can return either full CPE details or just the total count. Useful for identifying specific versions and configurations of software and hardware.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| product | Yes | The name of the product to search for CPEs. | |
| count | No | If true, returns only the count of matching CPEs. | |
| skip | No | Number of CPEs to skip (for pagination). | |
| limit | No | Maximum number of CPEs to return (max 1000). |
Implementation Reference
- src/index.ts:594-637 (handler)Main handler for cpe_lookup tool: validates input using CpeLookupArgsSchema, queries CVEDB via queryCPEDB helper, formats results (count or list with pagination), and returns as MCP text content or error.
case "cpe_lookup": { const parsedCpeArgs = CpeLookupArgsSchema.safeParse(args); if (!parsedCpeArgs.success) { throw new Error("Invalid cpe_lookup arguments"); } try { const result = await queryCPEDB({ product: parsedCpeArgs.data.product, count: parsedCpeArgs.data.count, skip: parsedCpeArgs.data.skip, limit: parsedCpeArgs.data.limit }); // Format the response based on whether it's a count request or full CPE list const formattedResult = parsedCpeArgs.data.count ? { total_cpes: result.total } : { cpes: result.cpes, skip: parsedCpeArgs.data.skip, limit: parsedCpeArgs.data.limit, total_returned: result.cpes.length }; return { content: [ { type: "text", text: JSON.stringify(formattedResult, null, 2), }, ], }; } catch (error: any) { return { content: [ { type: "text", text: error.message, }, ], isError: true, }; } } - src/index.ts:173-178 (schema)Zod schema defining input arguments for cpe_lookup: product name (required), optional count flag, skip and limit for pagination.
const CpeLookupArgsSchema = z.object({ product: z.string().describe("The name of the product to search for CPEs."), count: z.boolean().optional().default(false).describe("If true, returns only the count of matching CPEs."), skip: z.number().optional().default(0).describe("Number of CPEs to skip (for pagination)."), limit: z.number().optional().default(1000).describe("Maximum number of CPEs to return (max 1000)."), }); - src/index.ts:336-340 (registration)Tool registration in ListToolsRequestHandler: defines name 'cpe_lookup', detailed description, and converts Zod schema to JSON schema for MCP protocol.
{ name: "cpe_lookup", description: "Search for Common Platform Enumeration (CPE) entries by product name in Shodan's CVEDB. Supports pagination and can return either full CPE details or just the total count. Useful for identifying specific versions and configurations of software and hardware.", inputSchema: zodToJsonSchema(CpeLookupArgsSchema), }, - src/index.ts:231-247 (helper)Helper function to query Shodan CVEDB API endpoint /cpes with product and pagination params, logs query, handles 422 validation errors specifically.
async function queryCPEDB(params: { product: string; count?: boolean; skip?: number; limit?: number; }) { try { logToFile(`Querying CVEDB for CPEs with params: ${JSON.stringify(params)}`); const response = await axios.get(`${CVEDB_API_URL}/cpes`, { params }); return response.data; } catch (error: any) { if (error.response?.status === 422) { throw new Error(`Invalid parameters: ${error.response.data?.detail || error.message}`); } throw new Error(`CVEDB API error: ${error.message}`); } }