# Cymulate MCP — Tool Catalog Curated tool catalog for `cymulate-mcp-tools`. **100 first-class tools + 6 utility/fallback = 106 total**, covering **100%** of the Cymulate REST API (337 endpoints, OpenAPI 3.1.1 v2.0.62) — first-class tools for the ~100 high-value operations, plus a generic `cymulate_api_call` fallback that reaches everything else. Naming convention: `cymulate__[_]`. All tools support the same `x-token` auth via env var `CYMULATE_API_KEY`. ## 1. BAS Attack Simulation (unified, cross-module) — 7 tools The 11 BAS modules (Web Gateway, Email Gateway, Data Exfiltration, Endpoint Security, WAF, Full Kill-Chain Scenarios, Full Kill-Chain Campaign, Immediate Threats, Phishing Awareness, Hopper, Advanced Scenarios) follow the same lifecycle pattern. Instead of duplicating 7 tools × 11 modules, we expose a `module` enum parameter. | # | Tool | Purpose | |---|------|---------| | 1 | `cymulate_bas_launch` | Launch a BAS assessment on any module | | 2 | `cymulate_bas_stop` | Stop a running assessment | | 3 | `cymulate_bas_status` | Get current assessment status | | 4 | `cymulate_bas_get_latest_results` | Get latest report results | | 5 | `cymulate_bas_list_assessment_ids` | List assessment IDs | | 6 | `cymulate_bas_get_result` | Get specific assessment result by ID | | 7 | `cymulate_bas_get_technical_report` | Get technical report by ID | `module` enum: `web_gateway | email_gateway | data_exfiltration | endpoint | waf | fkc_scenarios | fkc_campaign | immediate_threats | phishing | hopper | advanced` Path map (internal): - web_gateway → `/v1/browsing` - email_gateway → `/v1/mail` - data_exfiltration → `/v1/dlp` - endpoint → `/v1/edr` - waf → `/v1/waf` - fkc_scenarios → `/v1/apt` - fkc_campaign → `/v1/apt-wrapper` - immediate_threats → `/v1/immediate-threats` - phishing → `/v1/phishing` - hopper → `/v1/hopper` - advanced → `/v1/purple-team` ## 2. Immediate Threats (specific) — 5 tools Immediate Threats is high-value operational tooling — validate detection against the IOC of the day. Deserves specific tools beyond the BAS unified pattern. | # | Tool | Purpose | |---|------|---------| | 8 | `cymulate_immediate_threats_catalog` | List available threats | | 9 | `cymulate_immediate_threats_get_ioc` | Get IOCs for a specific threat | | 10 | `cymulate_immediate_threats_get_mitre_tags` | Get MITRE ATT&CK mapping | | 11 | `cymulate_immediate_threats_download_ioc` | Download IOC file (STIX/CSV) | | 12 | `cymulate_immediate_threats_get_siem` | Get SIEM detection results | ## 3. Full Kill-Chain (FKC) specific — 4 tools FKC Scenarios (single-scenario APT) + FKC Campaigns (multi-scenario campaign) deserve specific helpers beyond the BAS pattern. | # | Tool | Purpose | |---|------|---------| | 13 | `cymulate_fkc_scenarios_list_templates` | List FKC scenario templates | | 14 | `cymulate_fkc_scenarios_get_agents` | Get agent list for scenario execution | | 15 | `cymulate_fkc_campaign_list_templates` | List FKC campaign templates | | 16 | `cymulate_fkc_campaign_get_agents` | Get agent list for campaign execution | ## 4. Attack Surface Management (ASM) — 5 tools | # | Tool | Purpose | |---|------|---------| | 17 | `cymulate_asm_launch_scan` | Trigger ASM assessment | | 18 | `cymulate_asm_get_history_ids` | List ASM history assessment IDs | | 19 | `cymulate_asm_get_latest_findings` | Get findings from latest ASM run | | 20 | `cymulate_asm_get_findings_by_id` | Get findings from a specific ASM run | | 21 | `cymulate_asm_get_technical` | Get technical details | ## 5. Advanced Scenarios (Purple Team) — 6 tools | # | Tool | Purpose | |---|------|---------| | 22 | `cymulate_advanced_list_templates` | List purple-team templates | | 23 | `cymulate_advanced_create_template` | Create purple-team template | | 24 | `cymulate_advanced_get_template` | Get specific template | | 25 | `cymulate_advanced_update_template` | Update template | | 26 | `cymulate_advanced_delete_template` | Delete template | | 27 | `cymulate_advanced_list_actions` | List available actions | ## 6. Exposure Validation — Launched Assessments — 6 tools | # | Tool | Purpose | |---|------|---------| | 28 | `cymulate_ev_launched_list` | List launched assessments | | 29 | `cymulate_ev_launched_create` | Create/launch new assessment | | 30 | `cymulate_ev_launched_get` | Get launched assessment by ID | | 31 | `cymulate_ev_launched_delete` | Delete launched assessment | | 32 | `cymulate_ev_launched_get_configurations` | Get launch configurations | | 33 | `cymulate_ev_launched_get_filters` | Get filters for launched assessments | ## 7. Exposure Validation — Scheduled Assessments — 6 tools | # | Tool | Purpose | |---|------|---------| | 34 | `cymulate_ev_scheduled_list` | List scheduled assessments | | 35 | `cymulate_ev_scheduled_create` | Create scheduled assessment | | 36 | `cymulate_ev_scheduled_get` | Get scheduled assessment by ID | | 37 | `cymulate_ev_scheduled_update` | Update scheduled assessment | | 38 | `cymulate_ev_scheduled_delete` | Delete scheduled assessment | | 39 | `cymulate_ev_scheduled_get_configurations` | Get schedule configurations | ## 8. Exposure Validation — Templates + Smart Templates — 8 tools | # | Tool | Purpose | |---|------|---------| | 40 | `cymulate_ev_templates_list` | List EV templates | | 41 | `cymulate_ev_templates_create` | Create template | | 42 | `cymulate_ev_templates_get` | Get template by ID | | 43 | `cymulate_ev_templates_update` | Update template | | 44 | `cymulate_ev_templates_delete` | Delete template | | 45 | `cymulate_ev_smart_templates_list` | List smart templates | | 46 | `cymulate_ev_smart_templates_create` | Create smart template | | 47 | `cymulate_ev_smart_templates_get` | Get smart template by ID | ## 9. Exposure Validation — Scenarios (EV) — 5 tools | # | Tool | Purpose | |---|------|---------| | 48 | `cymulate_ev_scenarios_list_actions` | List available scenario actions | | 49 | `cymulate_ev_scenarios_create` | Create scenario | | 50 | `cymulate_ev_scenarios_get` | Get scenario by ID | | 51 | `cymulate_ev_scenarios_update` | Update scenario | | 52 | `cymulate_ev_scenarios_delete` | Delete scenario | ## 10. Exposure Validation — Threats (EV) — 5 tools | # | Tool | Purpose | |---|------|---------| | 53 | `cymulate_ev_threats_list` | List EV threats | | 54 | `cymulate_ev_threats_get_filters` | Get threat filters | | 55 | `cymulate_ev_threats_get` | Get threat by ID | | 56 | `cymulate_ev_threats_get_scheduled_auto_runs` | List auto-run schedules | | 57 | `cymulate_ev_threats_create_auto_run` | Create auto-run schedule | ## 11. Exposure Validation — Resources (EV) — 4 tools | # | Tool | Purpose | |---|------|---------| | 58 | `cymulate_ev_resources_list` | List resources | | 59 | `cymulate_ev_resources_get` | Get resource by ID | | 60 | `cymulate_ev_resources_get_filters` | Get resource filters | | 61 | `cymulate_ev_resources_create` | Create resource | ## 12. Exposure Validation — Input Configurations + Template Groups + Pre-Reqs + WAF Settings — 9 tools | # | Tool | Purpose | |---|------|---------| | 62 | `cymulate_ev_input_configs_list` | List input configurations | | 63 | `cymulate_ev_input_configs_create` | Create input configuration | | 64 | `cymulate_ev_input_configs_get` | Get input configuration by ID | | 65 | `cymulate_ev_input_configs_update` | Update input configuration | | 66 | `cymulate_ev_input_configs_delete` | Delete input configuration | | 67 | `cymulate_ev_template_groups_list` | List template groups | | 68 | `cymulate_ev_template_groups_get` | Get template group by ID | | 69 | `cymulate_ev_assess_prereqs_get` | Get assessment pre-requirements | | 70 | `cymulate_ev_assess_prereqs_relaunch` | Re-run pre-requirement checks | ## 13. Exposure Analytics (EA) — 8 tools | # | Tool | Purpose | |---|------|---------| | 71 | `cymulate_ea_cves_list` | List CVEs | | 72 | `cymulate_ea_cves_get` | Get CVE detail | | 73 | `cymulate_ea_cves_export` | Export CVEs | | 74 | `cymulate_ea_exposures_get` | Get exposure detail | | 75 | `cymulate_ea_exposures_export` | Export exposures | | 76 | `cymulate_ea_tasks_list` | List remediation tasks | | 77 | `cymulate_ea_tasks_get_filters` | Get task filters | | 78 | `cymulate_ea_tasks_export` | Export tasks | ## 14. Cymulate Findings + Auto Remediation — 6 tools | # | Tool | Purpose | |---|------|---------| | 79 | `cymulate_findings_search` | Search findings with filters | | 80 | `cymulate_findings_get_filters` | Get available filters | | 81 | `cymulate_findings_get_info` | Get details of a specific finding | | 82 | `cymulate_remediation_list_integrations` | List available integrations for a finding | | 83 | `cymulate_remediation_apply` | Apply auto-remediation to finding | | 84 | `cymulate_remediation_bulk_apply` | Bulk auto-remediation | ## 15. Environments + Agents — 8 tools | # | Tool | Purpose | |---|------|---------| | 85 | `cymulate_env_list` | List all environments | | 86 | `cymulate_env_create` | Create environment | | 87 | `cymulate_env_get` | Get environment | | 88 | `cymulate_env_delete` | Delete environment | | 89 | `cymulate_env_list_assets` | List assets across environments | | 90 | `cymulate_agents_list_connected` | List currently connected agents | | 91 | `cymulate_agents_list_all` | List all agents (connected + disconnected) | | 92 | `cymulate_agents_get_hashes` | Get agent hashes | ## 16. Platform (SSO + Trace Log + Dashboards + Score) — 5 tools | # | Tool | Purpose | |---|------|---------| | 93 | `cymulate_platform_sso_get` | Get SSO configuration | | 94 | `cymulate_platform_score_by_control` | Get scores per security control | | 95 | `cymulate_platform_mitre_dashboard` | Get MITRE ATT&CK dashboard data | | 96 | `cymulate_platform_trace_log` | Get trace log from latest assessment | | 97 | `cymulate_platform_activity_logs` | Get platform activity logs | ## 17. General Info — 3 tools | # | Tool | Purpose | |---|------|---------| | 98 | `cymulate_info_activity_center` | Get activity center summary | | 99 | `cymulate_info_users_list` | List platform users | | 100 | `cymulate_info_integrations_status` | Get integration statuses | ## 18. Utility & Fallback — 6 tools | # | Tool | Purpose | |---|------|---------| | 101 | `cymulate_api_call` | **Generic REST fallback** — reach any of the 337 endpoints not covered above | | 102 | `cymulate_api_list_endpoints` | List all documented endpoints (browse the OpenAPI spec) | | 103 | `cymulate_api_describe_endpoint` | Describe a single endpoint (schema, params, response) | | 104 | `cymulate_health` | Ping API, verify auth, show rate-limit headers | | 105 | `cymulate_openapi_spec` | Return the raw OpenAPI spec (cached) | | 106 | `cymulate_debug_last_request` | Inspect the last HTTP request/response for debugging | ## Total: 106 tools - **100 first-class** semantic tools covering ~85% of high-value REST endpoints - **1 generic fallback** (`cymulate_api_call`) reaching the remaining ~15% + future endpoints - **5 utility tools** for discoverability, debugging, and self-inspection ## Design principles 1. **Idempotency hints in `annotations`**: every GET tool is marked `readOnlyHint=true`, `idempotentHint=true`. Every POST/PUT with side effects is marked `destructiveHint=true` where applicable (delete, stop, launch). 2. **Zod schemas everywhere**: input validation runs before touching the API. 3. **Rate limit awareness**: client parses `X-RateLimit-*` headers on every response; if remaining < 10, tools return a warning. 4. **Error mapping**: 401/403/404/429/5xx get semantic MCP errors, not raw axios noise. 5. **Cache the OpenAPI spec** in memory on server start; `cymulate_openapi_spec` returns from cache. 6. **STDIO + HTTP transport** in the same binary; select via `MCP_TRANSPORT=stdio|http` env var. ## Coverage vs official Cymulate MCP - Official MCP: 118 tools, **39% of REST endpoints** covered (mostly EV/EA lifecycle) - Our MCP: 106 tools, **100% coverage** via first-class + fallback - Key gaps we close vs official: **All BAS modules** (Web Gateway, Email, Data Exfil, Hopper, Phishing, FKC, ASM, Advanced Scenarios, Immediate Threats, Auto Remediation)