使用说明
InsightAppSec MCP服务器
模型上下文协议（MCP）服务器，为人工智能助手提供对Rapid7 InsightAppSec API的访问，用于应用程序安全扫描、漏洞管理和报告。
概述
此MCP服务器使Claude等AI助手能够与Rapid7 InsightAppSec交互，使您能够：
- 管理应用程序及其安全配置
- 启动并监控安全扫描
- 查询和分类漏洞
- 生成安全报告
- 自动安排扫描时间
- 搜索所有InsightAppSec资源
- 配置身份验证 （OAuth、基于表单、宏、流量文件）
- 管理令牌替换 （CSRF、会话令牌、动态参数）
先决条件
- Node.js 18.0.0或更高版本
- 具有API访问权限的Rapid7 InsightAppSec帐户
- 来自的API密钥 Rapid7洞察平台
安装
来源
# 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
配置
创建 .env 基于所提供模板的文件：
cp .env.example .env
编辑 .env 使用您的凭据文件：
INSIGHTAPPSEC_API_KEY=your-api-key-here
INSIGHTAPPSEC_REGION=us
支持的地区：
| 地区 | 代码 |
|---|---|
| 美国 | us |
| 欧洲 | eu |
| 亚太地区 | ap |
| 加拿大 | ca |
| 澳大利亚 | au |
使用Claude Desktop
将以下内容添加到您的Claude Desktop配置文件中：
窗户： %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"
}
}
}
}
重新启动Claude Desktop以加载MCP服务器。
可用工具
应用程序管理
| 工具 | 说明 |
|---|---|
list_apps |
列出所有具有分页和排序功能的应用程序 |
get_app |
获取特定应用程序的详细信息 |
create_app |
创建新应用程序 |
update_app |
更新应用程序名称或描述 |
delete_app |
删除应用程序和所有相关数据 |
manage_app_tags |
在应用程序中添加或删除标签 |
扫描操作
| 工具 | 说明 |
|---|---|
list_scans |
具有分页和筛选功能的列表扫描 |
get_scan |
获取特定扫描的详细信息 |
submit_scan |
根据扫描配置提交新的扫描 |
delete_scan |
删除失败的扫描 |
control_scan |
暂停、恢复、停止或取消正在运行的扫描 |
get_scan_execution_details |
获取扫描的实时执行指标 |
get_scan_engine_events |
获取扫描的引擎事件日志 |
扫描配置
| 工具 | 说明 |
|---|---|
list_scan_configs |
列出所有扫描配置 |
get_scan_config |
获取特定扫描配置的详细信息 |
create_scan_config |
创建新的扫描配置 |
update_scan_config |
更新扫描配置设置 |
delete_scan_config |
删除扫描配置 |
漏洞管理
| 工具 | 说明 |
|---|---|
list_vulnerabilities |
使用分页和排序列出漏洞 |
get_vulnerability |
获取有关漏洞的详细信息 |
update_vulnerability |
更新漏洞状态或严重性 |
get_vulnerability_discoveries |
获取漏洞的发现历史记录 |
list_vulnerability_comments |
列出对漏洞的所有评论 |
add_vulnerability_comment |
为漏洞添加注释 |
调度和自动化
| 工具 | 说明 |
|---|---|
list_schedules |
列出所有扫描计划 |
get_schedule |
获取特定日程的详细信息 |
create_schedule |
创建定期扫描计划 |
update_schedule |
更新计划频率或时间 |
delete_schedule |
删除扫描计划 |
遮光窗
| 工具 | 说明 |
|---|---|
list_blackouts |
列出所有遮光窗 |
get_blackout |
获取特定遮光窗的详细信息 |
create_blackout |
创建遮光窗口以防止扫描 |
update_blackout |
更新遮光窗设置 |
delete_blackout |
删除遮光窗口 |
报告
| 工具 | 说明 |
|---|---|
list_reports |
列出所有生成的报告 |
generate_report |
生成新的漏洞报告 |
get_report_status |
检查报告生成的状态 |
搜索
| 工具 | 说明 |
|---|---|
search |
使用DSL查询语法在所有InsightAppSec资源中进行通用搜索 |
基础设施
| 工具 | 说明 |
|---|---|
list_engines |
列出所有已注册的扫描引擎 |
get_engine |
获取特定扫描引擎的详细信息 |
list_engine_groups |
列出所有发动机组 |
get_engine_group |
获取特定发动机组的详细信息 |
文件管理
| 工具 | 说明 |
|---|---|
list_files |
列出应用程序的所有文件（宏、流量、selenium等） |
get_file |
按ID获取文件元数据 |
create_file |
创建文件元数据条目 |
upload_file_content |
上传二进制文件内容（base64编码） |
delete_file |
删除文件 |
download_file |
以base64格式下载文件内容 |
支持的文件类型：
MACRO-记录的身份验证序列（.rec）RECORDED_TRAFFIC-HTTP流量捕获（.har、.trec、.saz）SELENIUM-浏览器自动化脚本（.html、.side）CERTIFICATE-SSL证书（.pfx）SWAGGER-API规范（.json、.yaml）WSDL-Web服务定义（.wsdl）GRAPHQL-GraphQL模式（.graphqls）
身份验证和令牌管理
| 工具 | 说明 |
|---|---|
get_scan_config_options |
获取完整的扫描配置选项，包括身份验证设置 |
configure_form_auth |
配置基于表单的身份验证（用户名/密码） |
configure_oauth |
配置OAuth 2.0身份验证 |
configure_token_replacement |
配置全局令牌提取/注入规则 |
configure_session_handling |
配置会话检测、Cookie、重新登录触发器 |
configure_csrf_handling |
配置自动CSRF令牌检测和注入 |
configure_macro_auth |
将宏文件链接到扫描配置以进行身份验证 |
configure_traffic_auth |
将流量文件链接到扫描配置以进行身份验证 |
对话示例
列出应用程序
“在InsightAppSec中显示我的所有应用程序”
助理将使用 list_apps 检索和显示您的应用程序。
启动安全扫描
“使用‘Production Web App’扫描配置启动扫描”
助理将：
- 使用
list_scan_configs查找配置 - 使用
submit_scan开始扫描 - 报告扫描ID和状态
检查漏洞状态
“显示所有高严重性漏洞”
助理将使用 search 使用DSL查询：
type: VULNERABILITY
query: vulnerability.severity='HIGH'
监视正在运行的扫描
“扫描abc-123的状态如何？”
助理将使用 get_scan 和 get_scan_execution_details 显示：
- 当前扫描状态
- 进度百分比
- 请求已完成
- 到目前为止发现的漏洞
分类漏洞
“将漏洞xyz-789标记为误报，并添加注释解释原因”
助理将：
- 使用
update_vulnerability将状态设置为FALSE_POSITIVE - 使用
add_vulnerability_comment添加说明
安排定期扫描
“每周一凌晨2点为生产应用程序设置每周扫描”
助理将使用 create_schedule 与：
- 频率：
WEEKLY - 开始时间：下周一凌晨2:00 UTC
配置OAuth身份验证
“为API扫描设置OAuth客户端凭据身份验证”
助理将使用 configure_oauth 与：
- 资助类型：
CLIENT_CREDENTIALS - 令牌URL、客户端ID、客户端密钥
为CSRF设置令牌替换
“配置扫描以自动处理CSRF令牌”
助理将使用 configure_csrf_handling 与：
auto_detect: true- 令牌名称的可选正则表达式模式
上传身份验证宏
“上传我录制的登录宏进行扫描”
助理将：
- 使用
create_file创建元数据（类型：MACRO） - 使用
upload_file_content具有base64编码的宏内容 - 使用
configure_macro_auth将其链接到扫描配置
搜索查询语法
这 search 该工具支持强大的DSL来查询资源：
运算符
| 操作员 | 描述 | 示例 |
|---|---|---|
= |
等于 | vulnerability.severity='HIGH' |
!= |
不等于 | scan.status!='COMPLETE' |
>, <, >=, <= |
比较 | vulnerability.cvss>7.0 |
CONTAINS |
子字符串匹配 | app.name CONTAINS 'prod' |
IN |
列表中的值 | vulnerability.status IN ['UNREVIEWED', 'VERIFIED'] |
AND, OR |
逻辑运算符 | severity='HIGH' AND status='UNREVIEWED' |
可搜索资源类型
VULNERABILITYSCANSCAN_CONFIGAPPSCHEDULEBLACKOUTMODULEATTACK_TEMPLATEENGINEENGINE_GROUP
查询示例
# 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'
验证配置
MCP服务器支持全面的身份验证配置，用于扫描经过身份验证的应用程序。
OAuth 2.0身份验证
为基于API的身份验证配置OAuth：
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"
支持的资助类型：
CLIENT_CREDENTIALS-服务器到服务器身份验证AUTHORIZATION_CODE-用户授权访问RESOURCE_OWNER_PASSWORD-直接用户名/密码IMPLICIT-基于浏览器的应用程序
基于表单的身份验证
配置传统登录表单身份验证：
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"
令牌替换
从响应中提取令牌并将其注入后续请求中：
configure_token_replacement:
scan_config_id: "uuid"
extraction_location: "RESPONSE_BODY"
extraction_pattern: "csrf_token\":\"([^\"]+)\""
injection_location: "REQUEST_HEADER"
injection_parameter: "X-CSRF-Token"
支持的位置：
REQUEST_URL,REQUEST_HEADER,REQUEST_BODY,REQUEST_COOKIERESPONSE_HEADER,RESPONSE_BODY
CSRF令牌处理
启用自动CSRF令牌检测和注入：
configure_csrf_handling:
scan_config_id: "uuid"
auto_detect: true
token_name_regex: "csrf|_token|authenticity"
会话管理
配置会话检测和自动重新身份验证：
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
基于宏的身份验证
使用录制的宏进行复杂的身份验证流程：
- 上传宏文件：
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>"
- 配置扫描以使用它：
configure_macro_auth:
scan_config_id: "uuid"
macro_file_id: "uuid"
replay_speed: 1.0
漏洞状态
| 状态 | 描述 |
|---|---|
UNREVIEWED |
新漏洞，尚未分类 |
FALSE_POSITIVE |
确定为假阳性 |
VERIFIED |
确认为真正的漏洞 |
IGNORED |
已确认但已接受的风险 |
REMEDIATED |
已在应用程序中修复 |
DUPLICATE |
重复另一项发现 |
严重级别
| 严重性 | 描述 |
|---|---|
SAFE |
无安全影响 |
INFORMATIONAL |
信息披露 |
LOW |
轻微安全问题 |
MEDIUM |
中等安全风险 |
HIGH |
严重安全漏洞 |
发展
项目结构
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
脚本
# Build the project
npm run build
# Run in development mode
npm run dev
# Type checking
npm run typecheck
# Run tests
npm test
添加新工具
- 在中创建或修改工具文件
src/tools/ - 使用
server.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);
}
);
- 导入并注册
src/index.ts
错误处理
服务器正常处理常见的API错误：
| 状态代码 | 含义 |
|---|---|
| 400 | 错误请求-检查参数 |
| 401 | 身份验证失败-检查API密钥 |
| 403 | 禁止访问-权限不足 |
| 404 | 找不到资源 |
| 409 | 资源冲突 |
| 422 | 验证错误-检查请求正文 |
| 429 | 速率受限-等待并重试 |
| 5xx | 服务器错误-稍后重试 |
错误响应包括：
- 状态码
- 错误信息
- 相关ID（用于Rapid7支持）
- 详细的错误信息（如果可用）
api参考
此MCP服务器包装 Rapid7 InsightAppSec API v1.
有关API的详细文档，请参阅：
许可证
麻省理工学院
贡献
欢迎投稿！请随时提交问题和拉取请求。
支持
- 有关InsightAppSec API问题，请联系 Rapid7支持
- 对于MCP服务器问题，打开GitHub问题
