InsightAppSec MCP Server

InsightAppSec MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to the Rapid7 InsightAppSec API for application security scanning, vulnerability management, and reporting.

Overview

This MCP server enables AI assistants like Claude to interact with Rapid7 InsightAppSec, allowing you to:

• Manage applications and their security configurations
• Launch and monitor security scans
• Query and triage vulnerabilities
• Generate security reports
• Automate scan scheduling
• Search across all InsightAppSec resources
• Configure authentication (OAuth, form-based, macros, traffic files)
• Manage token replacement (CSRF, session tokens, dynamic parameters)

Prerequisites

• Node.js 18.0.0 or higher
• A Rapid7 InsightAppSec account with API access
• An API key from the Rapid7 Insight Platform

Installation

From Source

# Clone the repository
git clone https://github.com/yourusername/insightappsec-mcp.git
cd insightappsec-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Create a .env file based on the provided template:

cp .env.example .env

Edit the .env file with your credentials:

INSIGHTAPPSEC_API_KEY=your-api-key-here
INSIGHTAPPSEC_REGION=us

Supported Regions: | Region | Code | |--------|------| | United States | us | | Europe | eu | | Asia-Pacific | ap | | Canada | ca | | Australia | au |

Usage with Claude Desktop

Add the following to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "insightappsec": {
      "command": "node",
      "args": ["C:/path/to/insightappsec-mcp/build/index.js"],
      "env": {
        "INSIGHTAPPSEC_API_KEY": "your-api-key-here",
        "INSIGHTAPPSEC_REGION": "us"
      }
    }
  }
}

Restart Claude Desktop to load the MCP server.

Available Tools

Application Management

| Tool | Description | |------|-------------| | list_apps | List all applications with pagination and sorting | | get_app | Get detailed information about a specific application | | create_app | Create a new application | | update_app | Update application name or description | | delete_app | Delete an application and all associated data | | manage_app_tags | Add or remove tags from an application |

Scan Operations

| Tool | Description | |------|-------------| | list_scans | List scans with pagination and filtering | | get_scan | Get detailed information about a specific scan | | submit_scan | Submit a new scan based on a scan configuration | | delete_scan | Delete a failed scan | | control_scan | Pause, resume, stop, or cancel a running scan | | get_scan_execution_details | Get real-time execution metrics for a scan | | get_scan_engine_events | Get engine event logs for a scan |

Scan Configuration

| Tool | Description | |------|-------------| | list_scan_configs | List all scan configurations | | get_scan_config | Get details of a specific scan configuration | | create_scan_config | Create a new scan configuration | | update_scan_config | Update scan configuration settings | | delete_scan_config | Delete a scan configuration |

Vulnerability Management

| Tool | Description | |------|-------------| | list_vulnerabilities | List vulnerabilities with pagination and sorting | | get_vulnerability | Get detailed information about a vulnerability | | update_vulnerability | Update vulnerability status or severity | | get_vulnerability_discoveries | Get discovery history for a vulnerability | | list_vulnerability_comments | List all comments on a vulnerability | | add_vulnerability_comment | Add a comment to a vulnerability |

Scheduling & Automation

| Tool | Description | |------|-------------| | list_schedules | List all scan schedules | | get_schedule | Get details of a specific schedule | | create_schedule | Create a recurring scan schedule | | update_schedule | Update schedule frequency or timing | | delete_schedule | Delete a scan schedule |

Blackout Windows

| Tool | Description | |------|-------------| | list_blackouts | List all blackout windows | | get_blackout | Get details of a specific blackout window | | create_blackout | Create a blackout window to prevent scans | | update_blackout | Update blackout window settings | | delete_blackout | Delete a blackout window |

Reporting

| Tool | Description | |------|-------------| | list_reports | List all generated reports | | generate_report | Generate a new vulnerability report | | get_report_status | Check the status of a report generation |

Search

| Tool | Description | |------|-------------| | search | Universal search across all InsightAppSec resources using DSL query syntax |

Infrastructure

| Tool | Description | |------|-------------| | list_engines | List all registered scan engines | | get_engine | Get details of a specific scan engine | | list_engine_groups | List all engine groups | | get_engine_group | Get details of a specific engine group |

File Management

| Tool | Description | |------|-------------| | list_files | List all files for an application (macros, traffic, selenium, etc.) | | get_file | Get file metadata by ID | | create_file | Create file metadata entry | | upload_file_content | Upload binary file content (base64-encoded) | | delete_file | Delete a file | | download_file | Download file content as base64 |

Supported File Types:

• MACRO - Recorded authentication sequences (.rec)
• RECORDED_TRAFFIC - HTTP traffic captures (.har, .trec, .saz)
• SELENIUM - Browser automation scripts (.html, .side)
• CERTIFICATE - SSL certificates (.pfx)
• SWAGGER - API specifications (.json, .yaml)
• WSDL - Web service definitions (.wsdl)
• GRAPHQL - GraphQL schemas (.graphqls)

Authentication & Token Management

| Tool | Description | |------|-------------| | get_scan_config_options | Get full scan config options including auth settings | | configure_form_auth | Configure form-based authentication (username/password) | | configure_oauth | Configure OAuth 2.0 authentication | | configure_token_replacement | Configure global token extraction/injection rules | | configure_session_handling | Configure session detection, cookies, relogin triggers | | configure_csrf_handling | Configure automatic CSRF token detection and injection | | configure_macro_auth | Link a macro file to scan config for authentication | | configure_traffic_auth | Link a traffic file to scan config for authentication |

Example Conversations

List Applications

"Show me all my applications in InsightAppSec"

The assistant will use list_apps to retrieve and display your applications.

Start a Security Scan

"Start a scan using the 'Production Web App' scan configuration"

The assistant will:

1. Use list_scan_configs to find the configuration
2. Use submit_scan to start the scan
3. Report the scan ID and status

Check Vulnerability Status

"Show me all high severity vulnerabilities"

The assistant will use search with a DSL query: `` type: VULNERABILITY query: vulnerability.severity='HIGH' ``

Monitor a Running Scan

"What's the status of scan abc-123?"

The assistant will use get_scan and get_scan_execution_details to show:

• Current scan status
• Progress percentage
• Requests completed
• Vulnerabilities found so far

Triage Vulnerabilities

"Mark vulnerability xyz-789 as a false positive and add a comment explaining why"

The assistant will:

1. Use update_vulnerability to set status to FALSE_POSITIVE
2. Use add_vulnerability_comment to add the explanation

Schedule Recurring Scans

"Set up a weekly scan for the production app every Monday at 2 AM"

The assistant will use create_schedule with:

• Frequency: WEEKLY
• Start time: Next Monday at 2:00 AM UTC

Configure OAuth Authentication

"Set up OAuth client credentials authentication for the API scan"

The assistant will use configure_oauth with:

• Grant type: CLIENT_CREDENTIALS
• Token URL, client ID, client secret

Set Up Token Replacement for CSRF

"Configure the scan to automatically handle CSRF tokens"

The assistant will use configure_csrf_handling with:

• auto_detect: true
• Optional regex patterns for token names

Upload Authentication Macro

"Upload my recorded login macro for the scan"

The assistant will:

1. Use create_file to create metadata (type: MACRO)
2. Use upload_file_content with base64-encoded macro content
3. Use configure_macro_auth to link it to the scan config

Search Query Syntax

The search tool supports a powerful DSL for querying resources:

Operators

| Operator | Description | Example | |----------|-------------|---------| | = | Equals | vulnerability.severity='HIGH' | | != | Not equals | scan.status!='COMPLETE' | | >, <, >=, <= | Comparison | vulnerability.cvss>7.0 | | CONTAINS | Substring match | app.name CONTAINS 'prod' | | IN | Value in list | vulnerability.status IN ['UNREVIEWED', 'VERIFIED'] | | AND, OR | Logical operators | severity='HIGH' AND status='UNREVIEWED' |

Searchable Resource Types

• VULNERABILITY
• SCAN
• SCAN_CONFIG
• APP
• SCHEDULE
• BLACKOUT
• MODULE
• ATTACK_TEMPLATE
• ENGINE
• ENGINE_GROUP

Example Queries

# Find critical vulnerabilities in production apps
type: VULNERABILITY
query: vulnerability.severity='HIGH' AND app.name CONTAINS 'prod'

# Find running scans
type: SCAN
query: scan.status='RUNNING'

# Find scan configs without recent scans
type: SCAN_CONFIG
query: scan_config.last_scan_date < '2024-01-01'

Authentication Configuration

The MCP server supports comprehensive authentication configuration for scanning authenticated applications.

OAuth 2.0 Authentication

Configure OAuth for API-based authentication:

configure_oauth:
  scan_config_id: "uuid"
  grant_type: "CLIENT_CREDENTIALS"
  token_url: "https://auth.example.com/oauth/token"
  client_id: "your-client-id"
  client_secret: "your-client-secret"
  scope: "read write"

Supported grant types:

• CLIENT_CREDENTIALS - Server-to-server authentication
• AUTHORIZATION_CODE - User-delegated access
• RESOURCE_OWNER_PASSWORD - Direct username/password
• IMPLICIT - Browser-based apps

Form-Based Authentication

Configure traditional login form authentication:

configure_form_auth:
  scan_config_id: "uuid"
  username_field: "email"
  password_field: "password"
  username: "test@example.com"
  password: "testpassword"
  logged_in_regex: "Welcome|Dashboard"
  logout_link_regex: "logout|sign.out"

Token Replacement

Extract tokens from responses and inject them into subsequent requests:

configure_token_replacement:
  scan_config_id: "uuid"
  extraction_location: "RESPONSE_BODY"
  extraction_pattern: "csrf_token\":\"([^\"]+)\""
  injection_location: "REQUEST_HEADER"
  injection_parameter: "X-CSRF-Token"

Supported locations:

• REQUEST_URL, REQUEST_HEADER, REQUEST_BODY, REQUEST_COOKIE
• RESPONSE_HEADER, RESPONSE_BODY

CSRF Token Handling

Enable automatic CSRF token detection and injection:

configure_csrf_handling:
  scan_config_id: "uuid"
  auto_detect: true
  token_name_regex: "csrf|_token|authenticity"

Session Management

Configure session detection and automatic re-authentication:

configure_session_handling:
  scan_config_id: "uuid"
  session_cookie_regex: "JSESSIONID|PHPSESSID"
  session_loss_regex: "session expired|please login"
  relogin_on_session_loss: true
  lock_cookies: true

Macro-Based Authentication

Use recorded macros for complex authentication flows:

1. Upload the macro file:

create_file:
  app_id: "uuid"
  name: "login-macro.rec"
  type: "MACRO"

upload_file_content:
  app_id: "uuid"
  file_id: "uuid"
  content_base64: "<base64-encoded-macro>"

1. Configure the scan to use it:

configure_macro_auth:
  scan_config_id: "uuid"
  macro_file_id: "uuid"
  replay_speed: 1.0

Vulnerability Statuses

| Status | Description | |--------|-------------| | UNREVIEWED | New vulnerability, not yet triaged | | FALSE_POSITIVE | Determined to be a false positive | | VERIFIED | Confirmed as a real vulnerability | | IGNORED | Acknowledged but accepted risk | | REMEDIATED | Fixed in the application | | DUPLICATE | Duplicate of another finding |

Severity Levels

| Severity | Description | |----------|-------------| | SAFE | No security impact | | INFORMATIONAL | Information disclosure | | LOW | Minor security concern | | MEDIUM | Moderate security risk | | HIGH | Serious security vulnerability |

Development

Project Structure

insightappsec-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── config.ts             # Configuration management
│   ├── client/
│   │   └── api-client.ts     # HTTP client for InsightAppSec API
│   ├── schemas/
│   │   └── common.ts         # Shared Zod schemas
│   ├── tools/
│   │   ├── apps.ts           # Application management tools
│   │   ├── scans.ts          # Scan operation tools
│   │   ├── scan-configs.ts   # Scan configuration tools
│   │   ├── vulnerabilities.ts # Vulnerability management tools
│   │   ├── schedules.ts      # Schedule management tools
│   │   ├── blackouts.ts      # Blackout window tools
│   │   ├── engines.ts        # Engine management tools
│   │   ├── reports.ts        # Reporting tools
│   │   ├── search.ts         # Search tool
│   │   ├── files.ts          # File management tools
│   │   └── auth.ts           # Authentication configuration tools
│   └── utils/
│       └── response-formatter.ts  # MCP response formatting
├── build/                    # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── .env.example

Scripts

# Build the project
npm run build

# Run in development mode
npm run dev

# Type checking
npm run typecheck

# Run tests
npm test

Adding New Tools

1. Create or modify a tool file in src/tools/
2. Use the server.tool() method to register the tool:

server.tool(
  "tool_name",
  "Tool description",
  {
    param1: z.string().describe("Parameter description"),
    param2: z.number().optional().describe("Optional parameter"),
  },
  async ({ param1, param2 }) => {
    const result = await client.get<unknown>("/endpoint");

    if (result.error) {
      return formatErrorResponse(result.error);
    }

    return formatResponse(result.data);
  }
);

1. Import and register in src/index.ts

Error Handling

The server handles common API errors gracefully:

| Status Code | Meaning | |-------------|---------| | 400 | Bad request - check parameters | | 401 | Authentication failed - check API key | | 403 | Access forbidden - insufficient permissions | | 404 | Resource not found | | 409 | Resource conflict | | 422 | Validation error - check request body | | 429 | Rate limited - wait and retry | | 5xx | Server error - retry later |

Error responses include:

• Status code
• Error message
• Correlation ID (for Rapid7 support)
• Detailed error information when available

API Reference

This MCP server wraps the Rapid7 InsightAppSec API v1.

For detailed API documentation, see:

• InsightAppSec API Docs
• Getting Started Guide
• API Use Cases

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Support

• For InsightAppSec API issues, contact Rapid7 Support
• For MCP server issues, open a GitHub issue