mcp-shodan

Instructions

Implementation Reference

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

  Handler for 'cve_lookup' tool: validates input, queries CVEDB API via helper, formats CVE response with severity, EPSS, KEV status, and returns structured JSON.
  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 input schema for cve_lookup tool requiring a valid CVE ID string.
  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:327-330 (registration)

  Registration of 'cve_lookup' tool in listTools handler, with name, description, and input schema.
  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:214-228 (helper)

  Helper function to query Shodan CVEDB API for CVE details, handles 422/404 errors specifically.
  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}`); } }
• src/index.ts:87-102 (helper)

  TypeScript interface defining the structure of CVE response from CVEDB API.
  interface CveResponse { cve_id: string; summary: string; cvss: number; cvss_version: number; cvss_v2: number; cvss_v3: number; epss: number; ranking_epss: number; kev: boolean; propose_action: string; ransomware_campaign: string; references: string[]; published_time: string; cpes: string[]; }