# 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](https://insight.rapid7.com/platform#/apiKeyManagement)

## Installation

### From Source

```bash
# 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:

```bash
cp .env.example .env
```

Edit the `.env` file with your credentials:

```env
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`

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

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

```bash
# 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:

```typescript
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](https://help.rapid7.com/insightappsec/en-us/api/v1/docs.html).

For detailed API documentation, see:
- [InsightAppSec API Docs](https://help.rapid7.com/insightappsec/en-us/api/v1/docs.html)
- [Getting Started Guide](https://docs.rapid7.com/insightappsec/api-get-started/)
- [API Use Cases](https://docs.rapid7.com/insightappsec/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](https://www.rapid7.com/support/)
- For MCP server issues, open a GitHub issue