{
  "markdown": "# CyberSim Pro MCP Server\n\nCyberSim Pro is a professional-grade Model Context Protocol (MCP) server purpose-built for cybersecurity training, purple-team collaboration, and executive readiness. It equips AI assistants and automation pipelines with structured tools to generate scenarios, simulate adversaries, analyse telemetry, investigate incidents, perform forensics, and publish board-ready reports—all while recording an immutable audit trail.\n\n---\n\n## Table of Contents\n- [Feature Highlights](#feature-highlights)\n- [Quick Start](#quick-start)\n  - [Run with Node.js](#run-with-nodejs)\n  - [Run with Docker](#run-with-docker)\n  - [HTTP Bridge (REST API)](#http-bridge-rest-api)\n- [MCP Client Integration](#mcp-client-integration)\n  - [Claude Desktop](#claude-desktop)\n  - [Cline VS Code Extension](#cline-vscode-extension)\n- [Tool Reference & Walkthroughs](#tool-reference--walkthroughs)\n  - [1. `create_scenario`](#1-create_scenario)\n  - [2. `simulate_attack`](#2-simulate_attack)\n  - [3. `analyze_network`](#3-analyze_network)\n  - [4. `investigate_incident`](#4-investigate_incident)\n  - [5. `forensics_analysis`](#5-forensics_analysis)\n  - [6. `generate_report`](#6-generate_report)\n  - [7. `stop_simulation`](#7-stop_simulation)\n  - [8. `replay_telemetry`](#8-replay_telemetry)\n  - [9. `list_metrics`](#9-list_metrics)\n  - [10. `export_controls`](#10-export_controls)\n  - [11. `sync_risk_register`](#11-sync_risk_register)\n  - [12. `generate_validation_report`](#12-generate_validation_report)\n- [Advanced Capabilities](#advanced-capabilities)\n  - [Adaptive Adversary Profiles & Plugins](#adaptive-adversary-profiles--plugins)\n  - [Command-Chain Drill-Down](#command-chain-drill-down)\n  - [Detection Engineering Packs](#detection-engineering-packs)\n  - [Executive & Governance Suite](#executive--governance-suite)\n  - [Audit Logging & Kill Switch](#audit-logging--kill-switch)\n  - [Role-Based Access & Approvals](#role-based-access--approvals)\n  - [Risk & Compliance Sync](#risk--compliance-sync)\n- [Operational Playbooks](#operational-playbooks)\n- [Contributing & Community Sharing](#contributing--community-sharing)\n- [Support Resources](#support-resources)\n- [License](#license)\n\n---\n\n## Feature Highlights\n- **Adaptive adversary scenarios** tied to real-world APT/FIN actor playbooks, sector-aware CVEs, and plugin-provided intel.\n- **Command-chain drill-down**: pseudo CLI steps (guardrailed) for every attack phase to map outputs to analyst tooling.\n- **Detection engineering bundles**: Sigma, Splunk, and KQL artefacts, MITRE ATT&CK heatmaps, gap analysis, and SOAR integration hooks.\n- **Incident response suite**: deep investigations, forensic artefacts, purple-team scorecards, facilitation kits, executive dashboards, maturity roadmaps, and procurement briefs.\n- **Operational guardrails**: append-only audit logs, approval-gated RBAC, `stop_simulation` kill switch, role-based prompt templates, and formal policy & ethics guide.\n- **Telemetry replay & metrics**: overlay real PCAP/EDR/SIEM events on simulations, auto-capture readiness metrics, and expose historical trends.\n- **Risk & control automation**: export compensating controls, sync with GRC platforms, and produce auditor-ready validation digests.\n\n---\n\n## Quick Start\n\n### Run with Node.js\n```bash\n# Clone the repository (or copy into your workspace)\ncd cybersim-pro-mcp\n\n# Install dependencies\nnpm install\n\n# Build TypeScript sources\nnpm run build\n\n# Start the MCP server over stdio\nnode build/index.js\n```\n\n### Run with Docker\n```bash\n# Build the image (from the repo root)\ndocker build -t cybersim-pro-mcp .\n\n# Launch in stdio mode (for Claude, Cline, etc.)\ndocker run --rm -i cybersim-pro-mcp\n```\n\n### HTTP Bridge (REST API)\nExpose tools to REST clients or GPT Actions.\n```bash\nnpm run serve:http  # defaults to http://localhost:8787\n```\nSecure with environment variables:\n- `CYBERSIM_API_KEY` – require `Authorization: Bearer <key>` header\n- `CYBERSIM_IP_ALLOW` – comma-separated list (`127.0.0.1,::1,local,203.0.113.10`)\n- `CYBERSIM_APPROVAL_TOKEN` – shared secret required for restricted tools (`simulate_attack`, `stop_simulation`, `replay_telemetry`)\n- `CYBERSIM_RBAC_CONFIG` – optional path to a JSON role policy (see [Role-Based Access & Approvals](#role-based-access--approvals))\n- Metrics, control feeds, and audit digests are persisted to `./metrics/`, `./controls/`, and `./logs/` respectively.\n\n### Tamper-Proof Audit Seals\n- Enable hash-chained logging by setting `CYBERSIM_AUDIT_HMAC_KEY` (optionally supply `CYBERSIM_AUDIT_CHAIN_ID` for multi-tenant tracking).\n- Use `CYBERSIM_AUDIT_SEAL_KEY` (or reuse the HMAC key) to sign exported seals; set `_ENCODING=base64` when providing base64 secrets.\n- Generate an immutable seal + regulator bundle at any time:\n  ```bash\n  npm run audit:seal -- --log ./logs/audit.log --format json.gz\n  ```\n- Outputs are written to `./logs/seals/` (JSON seal plus optional compressed bundle) and include `chainHash`, `chainVerified`, signature metadata, and the last approval token event.\n- Schedule `npm run audit:seal` via CI/cron to push weekly bundles into your immutable evidence locker (see `.github/workflows/audit-seal.yml` for a GitHub Actions example).\n- Summarise governance progress for Legal/Risk with `npm run compliance:report` (see `docs/COMPLIANCE_ROADMAP.md`).\n\nSample health & scenario creation:\n```bash\ncurl -s http://localhost:8787/health\n\ncurl -s -X POST http://localhost:8787/tool/create_scenario \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n        \"type\": \"ransomware\",\n        \"difficulty\": \"advanced\",\n        \"environment\": \"corporate\",\n        \"sector\": \"finance\",\n        \"adversary_profile\": \"fin7\",\n        \"focus_cves\": [\"CVE-2024-21410\"],\n        \"operator\": {\"id\": \"alice\", \"role\": \"controller\"},\n        \"approval_token\": \"${CYBERSIM_APPROVAL_TOKEN}\"\n      }' | jq\n```\n\n---\n\n## MCP Client Integration\n\n### Claude Desktop\nmacOS path: `~/Library/Application Support/Claude/claude_desktop_config.json`\n```json\n{\n  \"mcpServers\": {\n    \"cybersim-pro\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/cybersim-pro-mcp/build/index.js\"]\n    }\n  }\n}\n```\nFor Docker-backed execution:\n```json\n{\n  \"mcpServers\": {\n    \"cybersim-pro-docker\": {\n      \"command\": \"docker\",\n      \"args\": [\"run\", \"--rm\", \"-i\", \"cybersim-pro-mcp\"]\n    }\n  }\n}\n```\n\n### Cline VS Code Extension\nOpen **Command Palette → “Cline: Open MCP Settings”** and add:\n```json\n{\n  \"mcpServers\": {\n    \"cybersim-pro\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/cybersim-pro-mcp/build/index.js\"]\n    }\n  }\n}\n```\nWrapper scripts in `./scripts/` support runtime switching via `CYBERSIM_RUNTIME`.\n\n---\n\n## Tool Reference & Walkthroughs\nEach tool can be invoked through MCP clients or directly via the HTTP bridge. Examples below use `jq` for clarity.\n\n### 1. `create_scenario`\nGenerate a tailored scenario with adaptive adversary content.\n\n**HTTP Request**\n```bash\ncurl -s -X POST http://localhost:8787/tool/create_scenario \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n        \"type\": \"apt\",\n        \"difficulty\": \"expert\",\n        \"environment\": \"cloud\",\n        \"sector\": \"government\",\n        \"adversary_profile\": \"apt29\",\n        \"focus_cves\": [\"CVE-2023-23397\"]\n      }' | jq '.id, .description, .threatIntel'\n```\n\n**What you get**\n- Scenario ID (e.g., `SCN-...`)\n- Sector-aligned objectives and timelines\n- Adversary profile with CVEs, detection opportunities, plugin insight list\n\nUse the returned `scenarioId` to reference the scenario in follow-up drills, reports, or evidence.\n\n---\n\n### 2. `simulate_attack`\nSimulate a multi-phase attack and inspect the command-chain drill-down.\n\n**HTTP Request**\n```bash\ncurl -s -X POST http://localhost:8787/tool/simulate_attack \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n        \"attack_type\": \"ransomware\",\n        \"target\": \"FILESERVER-001\",\n        \"intensity\": \"high\"\n      }' | jq '{simulationId, commandChain: .commandChain[0:5], phases: [.phases[0].artifacts[0]]}'\n```\n\n**Highlights**\n- `commandChain` array details redacted pseudo commands, safeguards, and MITRE references for each phase.\n- `phases` include techniques, detection methods, and evidence artefacts.\n- `simulationId` feeds into `stop_simulation` or reporting workflows.\n\n---\n\n### 3. `analyze_network`\nAnalyse network segments and receive detection artefacts plus coverage insights.\n\n**HTTP Request**\n```bash\ncurl -s -X POST http://localhost:8787/tool/analyze_network \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n        \"network_segment\": \"DMZ\",\n        \"duration\": 30,\n        \"focus\": [\"anomalies\", \"threats\", \"vulnerabilities\"]\n      }' | jq '{\n        statistics: .statistics.bandwidthUtilization,\n        sigma: .detectionArtifacts.sigma[0],\n        splunk: .detectionArtifacts.splunk[0].query,\n        heatmap: .mitreHeatmap[0:3],\n        integration: .integrationHooks\n      }'\n```\n\n**Output**\n- Auto-generated Sigma/Splunk/KQL detections with descriptions & tags\n- MITRE ATT&CK + D3FEND heatmap coverage with gap analysis\n- Integration hooks for Splunk ES, Sentinel, and Cortex XSOAR\n- Recommendations aligned with anomalies/vulnerabilities/threats\n\n---\n\n### 4. `investigate_incident`\nRun a timeline-driven investigation with evidence, root cause, containment, and remediation details.\n\n**HTTP Request**\n```bash\ncurl -s -X POST http://localhost:8787/tool/investigate_incident \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n        \"incident_id\": \"INC-2024-001\",\n        \"scope\": \"deep_dive\"\n      }' | jq '{severity, timeline: .timeline.events[0:3], rootCause, containmentActions[0]}'\n```\n\n**Deliverables**\n- Attack path reconstruction with dwell time\n- Findings and supporting evidence (with chain-of-custody records)\n- Containment actions, remediation steps, and lessons learned\n\n---\n\n### 5. `forensics_analysis`\nProduce digital forensic artefacts for memory, disk, network, logs, or registry sources.\n\n**HTTP Request**\n```bash\ncurl -s -X POST http://localhost:8787/tool/forensics_analysis \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n        \"artifact_type\": \"disk\",\n        \"system_id\": \"WORKSTATION-001\",\n        \"analysis_depth\": \"comprehensive\"\n      }' | jq '{artifactSummary: .findings[0], chainOfCustody: .chainOfCustody[0]}'\n```\n\nExpect curated findings, hash validation, custody records, and preservation guidance.\n\n---\n\n### 6. `generate_report`\nGenerate executive, incident, vulnerability, or compliance reports with optional facilitation mode.\n\n**HTTP Request**\n```bash\ncurl -s -X POST http://localhost:8787/tool/generate_report \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n        \"report_type\": \"executive\",\n        \"incident_ids\": [\"INC-2024-001\", \"INC-2024-002\"],\n        \"include_recommendations\": true,\n        \"mode\": \"facilitation\"\n      }' | jq '{\n        executiveSummary,\n        scorecard: .scorecard.metrics,\n        facilitationKit: .facilitationKit.agenda,\n        dashboard: .executiveDashboard.heatmap,\n        roadmap: .maturityRoadmap.milestones,\n        procurement: .procurementBrief.faqs\n      }'\n```\n\nKey sections:\n- Executive summary & risk posture\n- Purple-team scorecard metrics and lessons\n- Facilitation kit (kickoff prompt, teleprompter notes, agenda)\n- Executive dashboard (risk, downtime, financial exposure)\n- Maturity roadmap (NIST CSF, CMMC, ISO 27001 alignment)\n- Procurement brief (FAQs, legal considerations, risk controls)\n\n---\n\n### 7. `stop_simulation`\nKill a single simulation or all active runs with audit logging.\n\n```bash\n# Stop a specific simulation ID\ntarget=\"SIM-1759281782112\"\ncurl -s -X POST http://localhost:8787/tool/stop_simulation \\\n  -H 'Content-Type: application/json' \\\n  -d \"{\\\"simulation_id\\\": \\\"$target\\\", \\\"reason\\\": \\\"Executive requested early termination\\\", \\\"operator\\\": {\\\"id\\\": \\\"alice\\\", \\\"role\\\": \\\"controller\\\"}, \\\"approval_token\\\": \\\"${CYBERSIM_APPROVAL_TOKEN}\\\"}\"\n\n# Stop everything (returns list of terminated runs)\ncurl -s -X POST http://localhost:8787/tool/stop_simulation \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"operator\":{\"id\":\"alice\",\"role\":\"controller\"},\"approval_token\":\"'\"${CYBERSIM_APPROVAL_TOKEN}\"'\"}'\n```\n\nThe audit logger records the termination reason, counts, and timestamps for compliance evidence.\n\n---\n\n### 8. `replay_telemetry`\nOverlay raw telemetry (PCAP/EDR/SIEM exports) against a live simulation to validate coverage.\n\n**HTTP Request**\n```bash\ncurl -s -X POST http://localhost:8787/tool/replay_telemetry \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n        \"simulation_id\": \"SIM-1759281782112\",\n        \"telemetry\": [\n          {\"timestamp\":\"2024-05-01T10:00:00Z\",\"indicator\":\"powershell.exe\",\"description\":\"Beacon to rare domain\",\"techniqueId\":\"t1059.001\"}\n        ],\n        \"operator\": {\"id\": \"alice\", \"role\": \"controller\"},\n        \"approval_token\": \"'\"${CYBERSIM_APPROVAL_TOKEN}\"'\"\n      }' | jq '{matchedTechniques, detectionGaps, observations}'\n```\n\nMatched techniques confirm detections fired; `detectionGaps` highlight phases lacking telemetry coverage. Recommended controls are appended automatically to the compensating-control feed.\n\n---\n\n### 9. `list_metrics`\nSummarise readiness metrics across all exercises.\n\n```bash\ncurl -s -X POST http://localhost:8787/tool/list_metrics -H 'Content-Type: application/json' -d '{}' | jq\n```\n\nOutputs include total exercises, reports generated, and average detection/containment times alongside the latest trend entries.\n\n---\n\n### 10. `export_controls`\nExport the consolidated compensating-control feed (detections, automations, gap closures).\n\n```bash\ncurl -s -X POST http://localhost:8787/tool/export_controls -H 'Content-Type: application/json' -d '{}' | jq '.[0:5]'\n```\n\nEach entry includes category, source, priority, and payload ready for SIEM/SOAR ingestion.\n\n---\n\n### 11. `sync_risk_register`\nGenerate REST payloads for governance platforms such as ServiceNow GRC, Archer, or OneTrust.\n\n```bash\ncurl -s -X POST http://localhost:8787/tool/sync_risk_register \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n        \"system\": \"servicenow\",\n        \"incident_id\": \"INC-2024-001\",\n        \"priority\": \"Critical\",\n        \"owner\": \"risk.governance@example.com\"\n      }' | jq\n```\n\nThe response provides the endpoint, HTTP method, payload, and checklist for operators to update the risk register.\n\n---\n\n### 12. `generate_validation_report`\nProduce an auditor-facing summary with hashed proof of recent CyberSim activity.\n\n```bash\ncurl -s -X POST http://localhost:8787/tool/generate_validation_report -H 'Content-Type: application/json' -d '{}' | jq\n```\n\nThe digest contains the SHA-256 hash, total entries, and redacted samples suitable for regulator briefings.\n\n---\n\n## Advanced Capabilities\n\n### Adaptive Adversary Profiles & Plugins\n- Profiles (e.g., APT29, FIN7) embed motivations, campaigns, preferred tactics, CVEs, and countermeasures.\n- `PluginRegistry` (`src/utils/pluginRegistry.ts`) lets you register sector or vendor-specific intel providers. Each plugin can inject CVEs, notes, and detection enhancements.\n- Scenario outputs surface `threatIntel.pluginInsights` referencing contributing providers.\n\n### Command-Chain Drill-Down\nSimulations include `commandChain` entries describing pseudo commands, safeguards, and technique references. Use these to:\n- Map red-team actions to your tooling (e.g., WMI logs, PowerShell policy)\n- Provide narrations during live tabletop facilitation\n- Export to internal red-team wikis without exposing live payloads\n\n### Detection Engineering Packs\nNetwork analysis responses include:\n- Sigma rules (YAML-string), Splunk searches, Sentinel KQL queries\n- Playbooks for triage/containment\n- MITRE ATT&CK + D3FEND mappings and coverage heatmaps\n- Integration hooks for Splunk ES saved searches, Sentinel analytics rules, and Cortex XSOAR playbooks\n\n### Executive & Governance Suite\n`generate_report` outputs provide everything needed for leadership alignment:\n- Executive dashboard, downtime estimates, financial impact\n- Purple-team metrics & lessons learned\n- Facilitation kit for hybrid workshops\n- Maturity roadmap with quarterly milestones and framework alignment\n- Procurement brief with FAQ, legal, and risk-control summaries\n\n### Audit Logging & Kill Switch\n- Every tool invocation is appended to `logs/audit.log` (configurable via `CYBERSIM_AUDIT_LOG_DIR`) and chained with SHA-256 hashes plus optional HMAC signatures (`CYBERSIM_AUDIT_HMAC_KEY`, `CYBERSIM_AUDIT_CHAIN_ID`).\n- Entries capture timestamp, tool, sanitized arguments, metadata, and error messages; validation exposes `chainVerified`, `lastChainHash`, and signature provenance.\n- `npm run audit:seal` produces a signed seal and regulator bundle under `logs/seals/`, ready for object-lock storage or shareable attestations.\n- `npm run compliance:report` surfaces control maturity, framework mappings, and roadmap freshness for monthly stakeholder updates.\n- The `stop_simulation` tool halts activity immediately and records the termination reason for traceability.\n- `generate_validation_report` produces hashed digests and anomaly flags that auditors can cross-check against sealed exports.\n\n**Identity Roadmap**\n- Enterprise SSO/SCIM integration is tracked in `docs/SSO_SCIM_DESIGN.md`; prepare `server.json` with an `identity` block and customise `config/role-mappings.example.json` when enabling the gateway.\n- OIDC callbacks: `POST /api/auth/oidc/callback` (JSON body with `id_token`); SAML assertions: `POST /api/sso/assert` (form-encoded `SAMLResponse` supported). Fetch SAML metadata via `GET /api/sso/metadata`.\n- SCIM v2 endpoints (`/api/scim/v2/Users`, `/api/scim/v2/Groups`) require `identity.scim.bearerToken` or `CYBERSIM_SCIM_TOKEN`; weekly audit seal workflow captures provisioning evidence.\n- Provide IdP MFA context to bypass restricted-tool MFA holds via `identity.sso.oidc.mfaSatisfiedAmrValues` / `mfaSatisfiedAcrValues` (defaults recognise common AMR/ACR values); sessions persist until `sessionTtlMinutes` expires or `X-Cybersim-Session` token is rotated.\n- Resolved IdP sessions now flow into every simulator/manager pipeline; returned JSON payloads include a `provenance` block so scenarios, simulations, investigations, forensics, metrics, and control feeds all reference the initiating identity or operator.\n- MCP stdio clients inherit the same provenance envelope when `operator` metadata is supplied, allowing downstream tools to align artefacts with human or automated actors even without an active IdP session.\n- After upgrading, run `npm run migrate:provenance` to backfill legacy metrics/control logs with the new provenance fields before exporting historical evidence.\n\n### Role-Based Access & Approvals\n- High-impact tools (`simulate_attack`, `stop_simulation`, `replay_telemetry`) respect role policies defined via `CYBERSIM_RBAC_CONFIG`.\n- Restricted tools require a shared approval token (`CYBERSIM_APPROVAL_TOKEN`), enabling dual-control or change-ticket workflows.\n- Operator metadata is captured in the audit log, supporting segregation-of-duties reviews.\n- Default policy grants analysts access to low-risk tooling while controllers/CISOs can execute adversary simulations.\n\n### Risk & Compliance Sync\n- `sync_risk_register` generates ready-to-post payloads for ServiceNow GRC, Archer, OneTrust, or custom systems.\n- `export_controls` provides the compensating-control feed derived from detection packs, telemetry gaps, and automation hooks.\n- Telemetry replay and network analysis automatically feed the control register so lessons learned become enforceable controls.\n\n---\n\n## Operational Playbooks\n- **Learning Path** – follow beginner → intermediate → advanced exercises (see *Learning Path* section below) to ramp analysts.\n- **Role-Based Prompt Templates** – prebuilt red/blue/purple/executive prompts in `docs/ROLE_BASED_PROMPTS.md`.\n- **Policy & Ethics Guide** – acceptable use, regulatory alignment, and safety checklist in `docs/POLICY_AND_ETHICS.md`.\n- **Benchmark Library** – curated scenarios per industry with KPIs in `docs/BENCHMARK_LIBRARY.md`.\n- **Community Sharing Program** – contribute sanitized scenarios/detections using the workflow in `docs/COMMUNITY_PROGRAM.md`.\n\n### Learning Path (Recap)\n- **Beginner**: phishing or simple malware, focus on indicators and detection basics.\n- **Intermediate**: ransomware/APT scenarios, run investigations and network analysis.\n- **Advanced**: full kill-chain drills, deep forensics, executive reporting, automation via HTTP bridge.\n\n---\n\n## Contributing & Community Sharing\n1. Fork the repository and branch from `main` (or `community/main` when contributing to shared content).\n2. Add code or documentation, ensuring TypeScript builds succeed (`npm run build`).\n3. For community packs, follow sanitisation and metadata guidelines in `docs/COMMUNITY_PROGRAM.md`.\n4. Submit a pull request; audit logs and documentation updates are encouraged alongside new features.\n\n---\n\n## Support Resources\n- Role-based prompts: `docs/ROLE_BASED_PROMPTS.md`\n- Policy & ethics: `docs/POLICY_AND_ETHICS.md`\n- Plugin guide: `docs/PLUGIN_ARCHITECTURE.md`\n- Benchmark scenarios: `docs/BENCHMARK_LIBRARY.md`\n- Community sharing workflow: `docs/COMMUNITY_PROGRAM.md`\n\nFor assistance:\n1. Review the documentation above.\n2. Inspect source code comments and example responses.\n3. Reproduce minimal scenarios (`create_scenario` → `simulate_attack`) to isolate issues.\n4. File issues or discussions on the GitHub repository.\n\n---\n\n## License\nReleased under the [MIT License](LICENSE). Use, modify, and adapt CyberSim Pro MCP Server for authorised defensive purposes.\n",
  "bytes": 21535,
  "sha": "bcbbf0b05a9084abd9738a32b682a94ef895e8a149ab09413f15b233ab92ec14",
  "repo_slug": "kayembahamid/cybersim-pro",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kayembahamid_cybersim_pro_87d789e0/readme"
}