mcp-shodan

Instructions

Implementation Reference

• src/index.ts:485-557 (handler)

  The main execution handler for the 'cve_lookup' tool. Parses input arguments using CVELookupArgsSchema, queries the CVEDB API via queryCVEDB helper, formats the CVE response with severity calculations and structured output, handles errors, and returns formatted JSON content.
  case "cve_lookup": { const parsedCveArgs = CVELookupArgsSchema.safeParse(args); if (!parsedCveArgs.success) { throw new Error("Invalid CVE format. Please use format: CVE-YYYY-NNNNN (e.g., CVE-2021-44228)"); } const cveId = parsedCveArgs.data.cve.toUpperCase(); logToFile(`Looking up CVE: ${cveId}`); try { const result = await queryCVEDB(cveId); // Helper function to format CVSS score severity const getCvssSeverity = (score: number) => { if (score >= 9.0) return "Critical"; if (score >= 7.0) return "High"; if (score >= 4.0) return "Medium"; if (score >= 0.1) return "Low"; return "None"; }; // Format the response in a user-friendly way const formattedResult = { "Basic Information": { "CVE ID": result.cve_id, "Published": new Date(result.published_time).toLocaleString(), "Summary": result.summary }, "Severity Scores": { "CVSS v3": result.cvss_v3 ? { "Score": result.cvss_v3, "Severity": getCvssSeverity(result.cvss_v3) } : "Not available", "CVSS v2": result.cvss_v2 ? { "Score": result.cvss_v2, "Severity": getCvssSeverity(result.cvss_v2) } : "Not available", "EPSS": result.epss ? { "Score": `${(result.epss * 100).toFixed(2)}%`, "Ranking": `Top ${(result.ranking_epss * 100).toFixed(2)}%` } : "Not available" }, "Impact Assessment": { "Known Exploited Vulnerability": result.kev ? "Yes" : "No", "Proposed Action": result.propose_action || "No specific action proposed", "Ransomware Campaign": result.ransomware_campaign || "No known ransomware campaigns" }, "Affected Products": result.cpes?.length > 0 ? result.cpes : ["No specific products listed"], "Additional Information": { "References": result.references?.length > 0 ? result.references : ["No references provided"] } }; 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:159-163 (schema)

  Zod schema definition for input validation of the cve_lookup tool, enforcing CVE ID format.
  const CVELookupArgsSchema = z.object({ cve: z.string() .regex(/^CVE-\d{4}-\d{4,}$/i, "Must be a valid CVE ID format (e.g., CVE-2021-44228)") .describe("The CVE identifier to query (format: CVE-YYYY-NNNNN)."), });
• src/index.ts:326-330 (registration)

  Tool registration in the ListToolsRequest handler, defining name, description, and input schema for cve_lookup.
  { name: "cve_lookup", description: "Query detailed vulnerability information from Shodan's CVEDB. Returns comprehensive CVE details including CVSS scores (v2/v3), EPSS probability and ranking, KEV status, proposed mitigations, ransomware associations, and affected products (CPEs).", inputSchema: zodToJsonSchema(CVELookupArgsSchema), },
• src/index.ts:213-228 (helper)

  Helper function that performs the actual API call to Shodan's CVEDB for a specific CVE ID, handles specific HTTP errors, and returns the raw response data used by the handler.
  // Helper Function for CVE lookups using CVEDB async function queryCVEDB(cveId: string) { try { logToFile(`Querying CVEDB for: ${cveId}`); const response = await axios.get(`${CVEDB_API_URL}/cve/${cveId}`); return response.data; } catch (error: any) { if (error.response?.status === 422) { throw new Error(`Invalid CVE ID format: ${cveId}`); } if (error.response?.status === 404) { throw new Error(`CVE not found: ${cveId}`); } throw new Error(`CVEDB API error: ${error.message}`); } }