npm - @burtthecoder/mcp-shodan - Versions diffs - 1.0.7 → 1.0.9 - Mend

@burtthecoder/mcp-shodan 1.0.7 → 1.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/LICENSE CHANGED Viewed

@@ -1,21 +1,21 @@
-MIT License
-Copyright (c) 2024 Burt
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+Copyright (c) 2024 Burt
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -1,176 +1,197 @@
-# Shodan MCP Server
-A Model Context Protocol (MCP) server for querying the [Shodan API](https://shodan.io) and [Shodan CVEDB](https://cvedb.shodan.io). This server provides tools for IP lookups, device searches, DNS lookups, vulnerability queries, CPE lookups, and more. It is designed to integrate seamlessly with MCP-compatible applications like [Claude Desktop](https://claude.ai).
-## Features
-- **IP Lookup**: Retrieve detailed information about an IP address
-- **Search**: Search for devices on Shodan matching specific queries
-- **Ports**: Get a list of ports that Shodan is scanning
-- **Vulnerabilities**: Fetch detailed information about CVEs using Shodan's CVEDB
-- **CPE Lookup**: Search for Common Platform Enumeration (CPE) entries by product name
-- **DNS Lookup**: Resolve hostnames to IP addresses
-## Tools
-### 1. IP Lookup Tool
-- Name: `ip_lookup`
-- Description: Retrieve detailed information about an IP address
-- Parameters:
-  * `ip` (required): IP address to lookup
-### 2. Search Tool
-- Name: `search`
-- Description: Search for devices on Shodan
-- Parameters:
-  * `query` (required): Shodan search query
-  * `max_results` (optional, default: 10): Number of results to return
-### 3. Vulnerabilities Tool
-- Name: `vulnerabilities`
-- Description: Fetch detailed information about CVEs using Shodan's CVEDB
-- Parameters:
-  * `cve` (required): CVE identifier in format CVE-YYYY-NNNNN (e.g., CVE-2021-44228)
-- Returns:
-  * CVE details including:
-    - CVSS v2 and v3 scores
-    - EPSS score and ranking
-    - KEV status
-    - Proposed action
-    - Ransomware campaign information
-    - Affected products (CPEs)
-    - References
-### 4. CPE Lookup Tool
-- Name: `cpe_lookup`
-- Description: Search for Common Platform Enumeration (CPE) entries by product name
-- Parameters:
-  * `product` (required): Name of the product to search for
-  * `count` (optional, default: false): If true, returns only the count of matching CPEs
-  * `skip` (optional, default: 0): Number of CPEs to skip (for pagination)
-  * `limit` (optional, default: 1000): Maximum number of CPEs to return
-- Returns:
-  * When count is true: Total number of matching CPEs
-  * When count is false: List of CPEs with pagination details
-### 5. DNS Lookup Tool
-- Name: `dns_lookup`
-- Description: Resolve hostnames to IP addresses
-- Parameters:
-  * `hostnames` (required): Array of hostnames to resolve
-## Requirements
-- Node.js (v18 or later)
-- A valid [Shodan API Key](https://account.shodan.io/)
-## Setup Guide
-### 1. Installation
-```bash
-git clone <repository_url>
-cd mcp-shodan
-npm install
-```
-### 2. Configuration
-Create a `.env` file in the root directory:
-```
-SHODAN_API_KEY=your_shodan_api_key
-```
-### 3. Build and Run
-```bash
-npm run build
-npm start
-```
-### 4. Configure Claude Desktop
-There are two ways to configure the Shodan MCP server in Claude Desktop:
-#### Option 1: Direct Node Execution (Local Development)
-```json
-{
-  "mcpServers": {
-    "shodan-mcp": {
-      "command": "node",
-      "args": ["path/to/mcp-shodan/build/index.js"],
-      "env": {
-        "SHODAN_API_KEY": "your_shodan_api_key",
-        "DEBUG": "*"
-      }
-    }
-  }
-}
-```
-#### Option 2: NPX Installation (Recommended for Users)
-```json
-{
-  "mcpServers": {
-    "shodan-mcp": {
-      "command": "npm",
-      "args": ["exec", "@burtthecoder/mcp-shodan"],
-      "env": {
-        "SHODAN_API_KEY": "your_shodan_api_key",
-        "DEBUG": "*"
-      }
-    }
-  }
-}
-```
-The npm exec method automatically downloads and runs the latest version of the package from npm.
-Configuration file location:
-Windows: %APPDATA%\Claude\claude_desktop_config.json
-macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
-## Usage
-1. Start the MCP server:
-```bash
-npm start
-```
-2. Launch Claude Desktop and ensure the Shodan MCP server is detected
-3. Use any of the available tools through the Claude interface
-## Development
-To run in development mode with hot reloading:
-```bash
-npm run dev
-```
-## Error Handling
-The server includes comprehensive error handling for:
-- Invalid API keys
-- Rate limiting
-- Network errors
-- Invalid input parameters
-- Invalid CVE formats
-- Invalid CPE lookup parameters
-## Version History
-- v1.0.6: Added CVEDB integration for enhanced CVE lookups and CPE search functionality
-- v1.0.0: Initial release with core functionality
-## Contributing
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-## License
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+# Shodan MCP Server
+A Model Context Protocol (MCP) server for querying the [Shodan API](https://shodan.io) and [Shodan CVEDB](https://cvedb.shodan.io). This server provides tools for IP lookups, device searches, DNS lookups, vulnerability queries, CPE lookups, and more. It is designed to integrate seamlessly with MCP-compatible applications like [Claude Desktop](https://claude.ai).
+## Quick Start (Recommended)
+1. Install the server globally via npm:
+```bash
+npm install -g @burtthecoder/mcp-shodan
+```
+2. Add to your Claude Desktop configuration file:
+```json
+{
+  "mcpServers": {
+    "shodan": {
+      "command": "mcp-shodan",
+      "env": {
+        "SHODAN_API_KEY": "your-shodan-api-key"
+      }
+    }
+  }
+}
+```
+Configuration file location:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+3. Restart Claude Desktop
+## Alternative Setup (From Source)
+If you prefer to run from source or need to modify the code:
+1. Clone and build:
+```bash
+git clone https://github.com/BurtTheCoder/mcp-shodan.git
+cd mcp-shodan
+npm install
+npm run build
+```
+2. Add to your Claude Desktop configuration:
+```json
+{
+  "mcpServers": {
+    "shodan": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-shodan/build/index.js"],
+      "env": {
+        "SHODAN_API_KEY": "your-shodan-api-key"
+      }
+    }
+  }
+}
+```
+## Features
+- **IP Lookup**: Retrieve detailed information about an IP address
+- **Search**: Search for devices on Shodan matching specific queries
+- **Ports**: Get a list of ports that Shodan is scanning
+- **CVE Lookup**: Fetch detailed information about specific CVEs using Shodan's CVEDB
+- **CPE Lookup**: Search for Common Platform Enumeration (CPE) entries by product name
+- **CVEs by Product**: Search for all CVEs affecting a specific product or CPE
+- **DNS Lookup**: Resolve hostnames to IP addresses
+## Tools
+### 1. IP Lookup Tool
+- Name: `ip_lookup`
+- Description: Retrieve detailed information about an IP address
+- Parameters:
+  * `ip` (required): IP address to lookup
+### 2. Search Tool
+- Name: `search`
+- Description: Search for devices on Shodan
+- Parameters:
+  * `query` (required): Shodan search query
+  * `max_results` (optional, default: 10): Number of results to return
+### 3. CVE Lookup Tool
+- Name: `cve_lookup`
+- Description: Fetch detailed information about CVEs using Shodan's CVEDB
+- Parameters:
+  * `cve` (required): CVE identifier in format CVE-YYYY-NNNNN (e.g., CVE-2021-44228)
+- Returns:
+  * CVE details including:
+    - CVSS v2 and v3 scores
+    - EPSS score and ranking
+    - KEV status
+    - Proposed action
+    - Ransomware campaign information
+    - Affected products (CPEs)
+    - References
+### 4. CPE Lookup Tool
+- Name: `cpe_lookup`
+- Description: Search for Common Platform Enumeration (CPE) entries by product name
+- Parameters:
+  * `product` (required): Name of the product to search for
+  * `count` (optional, default: false): If true, returns only the count of matching CPEs
+  * `skip` (optional, default: 0): Number of CPEs to skip (for pagination)
+  * `limit` (optional, default: 1000): Maximum number of CPEs to return
+- Returns:
+  * When count is true: Total number of matching CPEs
+  * When count is false: List of CPEs with pagination details
+### 5. CVEs by Product Tool
+- Name: `cves_by_product`
+- Description: Search for CVEs affecting a specific product or CPE
+- Parameters:
+  * `cpe23` (optional): CPE 2.3 identifier (format: cpe:2.3:part:vendor:product:version)
+  * `product` (optional): Name of the product to search for CVEs
+  * `count` (optional, default: false): If true, returns only the count of matching CVEs
+  * `is_kev` (optional, default: false): If true, returns only CVEs with KEV flag set
+  * `sort_by_epss` (optional, default: false): If true, sorts CVEs by EPSS score
+  * `skip` (optional, default: 0): Number of CVEs to skip (for pagination)
+  * `limit` (optional, default: 1000): Maximum number of CVEs to return
+  * `start_date` (optional): Start date for filtering CVEs (format: YYYY-MM-DDTHH:MM:SS)
+  * `end_date` (optional): End date for filtering CVEs (format: YYYY-MM-DDTHH:MM:SS)
+- Notes:
+  * Must provide either cpe23 or product, but not both
+  * Date filtering uses published time of CVEs
+- Returns:
+  * When count is true: Total number of matching CVEs
+  * When count is false: List of CVEs with pagination details and query parameters
+### 6. DNS Lookup Tool
+- Name: `dns_lookup`
+- Description: Resolve hostnames to IP addresses
+- Parameters:
+  * `hostnames` (required): Array of hostnames to resolve
+## Requirements
+- Node.js (v18 or later)
+- A valid [Shodan API Key](https://account.shodan.io/)
+## Troubleshooting
+### API Key Issues
+If you see API key related errors:
+1. Verify your API key:
+   - Should be a valid Shodan API key
+   - No extra spaces or quotes around the key
+   - Must be from your Shodan account settings
+2. After any configuration changes:
+   - Save the config file
+   - Restart Claude Desktop
+### Module Loading Issues
+If you see module loading errors:
+1. For global installation: Use the simple configuration shown in Quick Start
+2. For source installation: Ensure you're using Node.js v18 or later
+## Development
+To run in development mode with hot reloading:
+```bash
+npm run dev
+```
+## Error Handling
+The server includes comprehensive error handling for:
+- Invalid API keys
+- Rate limiting
+- Network errors
+- Invalid input parameters
+- Invalid CVE formats
+- Invalid CPE lookup parameters
+- Invalid date formats
+- Mutually exclusive parameter validation
+## Version History
+- v1.0.7: Added CVEs by Product search functionality and renamed vulnerabilities tool to cve_lookup
+- v1.0.6: Added CVEDB integration for enhanced CVE lookups and CPE search functionality
+- v1.0.0: Initial release with core functionality
+## Contributing
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+## License
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/build/index.js CHANGED Viewed

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, InitializeRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
@@ -41,7 +40,7 @@ const SearchArgsSchema = z.object({
         .default(10)
         .describe("Maximum results to return."),
 });
-const VulnerabilitiesArgsSchema = z.object({
+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)."),
@@ -55,6 +54,17 @@ const CpeLookupArgsSchema = z.object({
     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)."),
 });
+const CVEsByProductArgsSchema = z.object({
+    cpe23: z.string().optional().describe("The CPE version 2.3 identifier (format: cpe:2.3:part:vendor:product:version)."),
+    product: z.string().optional().describe("The name of the product to search for CVEs."),
+    count: z.boolean().optional().default(false).describe("If true, returns only the count of matching CVEs."),
+    is_kev: z.boolean().optional().default(false).describe("If true, returns only CVEs with the KEV flag set."),
+    sort_by_epss: z.boolean().optional().default(false).describe("If true, sorts CVEs by EPSS score in descending order."),
+    skip: z.number().optional().default(0).describe("Number of CVEs to skip (for pagination)."),
+    limit: z.number().optional().default(1000).describe("Maximum number of CVEs to return (max 1000)."),
+    start_date: z.string().optional().describe("Start date for filtering CVEs (format: YYYY-MM-DDTHH:MM:SS)."),
+    end_date: z.string().optional().describe("End date for filtering CVEs (format: YYYY-MM-DDTHH:MM:SS).")
+}).refine(data => !(data.cpe23 && data.product), { message: "Cannot specify both cpe23 and product. Use only one." }).refine(data => data.cpe23 || data.product, { message: "Must specify either cpe23 or product." });
 // Helper Function to Query Shodan API
 async function queryShodan(endpoint, params) {
     try {
@@ -101,6 +111,20 @@ async function queryCPEDB(params) {
         throw new Error(`CVEDB API error: ${error.message}`);
     }
 }
+// Helper Function for CVEs by product/CPE lookups using CVEDB
+async function queryCVEsByProduct(params) {
+    try {
+        logToFile(`Querying CVEDB for CVEs with params: ${JSON.stringify(params)}`);
+        const response = await axios.get(`${CVEDB_API_URL}/cves`, { params });
+        return response.data;
+    }
+    catch (error) {
+        if (error.response?.status === 422) {
+            throw new Error(`Invalid parameters: ${error.response.data?.detail || error.message}`);
+        }
+        throw new Error(`CVEDB API error: ${error.message}`);
+    }
+}
 // Server Setup
 const server = new Server({
     name: "shodan-mcp",
@@ -126,7 +150,7 @@ server.setRequestHandler(InitializeRequestSchema, async (request) => {
             name: "shodan-mcp",
             version: "1.0.0",
         },
-        instructions: "This server provides tools for querying Shodan, including IP lookups, searches, vulnerabilities, and CPE lookups.",
+        instructions: "This server provides tools for querying Shodan, including IP lookups, searches, CVE lookups, CPE lookups, and CVE searches by product/CPE.",
     };
 });
 // Register Tools
@@ -143,9 +167,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             inputSchema: zodToJsonSchema(SearchArgsSchema),
         },
         {
-            name: "vulnerabilities",
+            name: "cve_lookup",
             description: "Retrieve vulnerability information for a CVE. Use format: CVE-YYYY-NNNNN (e.g., CVE-2021-44228)",
-            inputSchema: zodToJsonSchema(VulnerabilitiesArgsSchema),
+            inputSchema: zodToJsonSchema(CVELookupArgsSchema),
         },
         {
             name: "dns_lookup",
@@ -157,6 +181,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             description: "Search for Common Platform Enumeration (CPE) entries by product name.",
             inputSchema: zodToJsonSchema(CpeLookupArgsSchema),
         },
+        {
+            name: "cves_by_product",
+            description: "Search for CVEs affecting a specific product or CPE. Provide either product name or CPE 2.3 identifier.",
+            inputSchema: zodToJsonSchema(CVEsByProductArgsSchema),
+        },
     ];
     logToFile("Registered tools.");
     return { tools };
@@ -200,12 +229,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
-            case "vulnerabilities": {
-                const parsedVulnArgs = VulnerabilitiesArgsSchema.safeParse(args);
-                if (!parsedVulnArgs.success) {
+            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 = parsedVulnArgs.data.cve.toUpperCase();
+                const cveId = parsedCveArgs.data.cve.toUpperCase();
                 logToFile(`Looking up CVE: ${cveId}`);
                 try {
                     const result = await queryCVEDB(cveId);
@@ -308,6 +337,61 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     };
                 }
             }
+            case "cves_by_product": {
+                const parsedArgs = CVEsByProductArgsSchema.safeParse(args);
+                if (!parsedArgs.success) {
+                    throw new Error("Invalid arguments. Must provide either cpe23 or product name, but not both.");
+                }
+                try {
+                    const result = await queryCVEsByProduct({
+                        cpe23: parsedArgs.data.cpe23,
+                        product: parsedArgs.data.product,
+                        count: parsedArgs.data.count,
+                        is_kev: parsedArgs.data.is_kev,
+                        sort_by_epss: parsedArgs.data.sort_by_epss,
+                        skip: parsedArgs.data.skip,
+                        limit: parsedArgs.data.limit,
+                        start_date: parsedArgs.data.start_date,
+                        end_date: parsedArgs.data.end_date
+                    });
+                    // Format the response based on whether it's a count request or full CVE list
+                    const formattedResult = parsedArgs.data.count
+                        ? { total_cves: result.total }
+                        : {
+                            cves: result.cves,
+                            skip: parsedArgs.data.skip,
+                            limit: parsedArgs.data.limit,
+                            total_returned: result.cves.length,
+                            query_params: {
+                                cpe23: parsedArgs.data.cpe23,
+                                product: parsedArgs.data.product,
+                                is_kev: parsedArgs.data.is_kev,
+                                sort_by_epss: parsedArgs.data.sort_by_epss,
+                                start_date: parsedArgs.data.start_date,
+                                end_date: parsedArgs.data.end_date
+                            }
+                        };
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify(formattedResult, null, 2),
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: error.message,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@burtthecoder/mcp-shodan",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "A Model Context Protocol server for Shodan API queries.",
   "main": "./build/index.js",
   "bin": {