InsightAppSec 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: "[email protected]"
  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

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

3. 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