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)

Related MCP server: Intigriti MCP Server

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:

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

Scan Operations

Scan Configuration

Vulnerability Management

Scheduling & Automation

Blackout Windows

Reporting

Search

Infrastructure

File Management

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

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

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>"

2. Configure the scan to use it:

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

Vulnerability Statuses

Severity Levels

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);
  }
);

3. Import and register in src/index.ts

Error Handling

The server handles common API errors gracefully:

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