CyberSim Pro MCP Server

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

Table of Contents

• Feature Highlights
• Quick Start
  • Run with Node.js
  • Run with Docker
  • HTTP Bridge (REST API)
• MCP Client Integration
  • Claude Desktop
  • Cline VS Code Extension
• Tool Reference & Walkthroughs
  • 1. create_scenario
  • 2. simulate_attack
  • 3. analyze_network
  • 4. investigate_incident
  • 5. forensics_analysis
  • 6. generate_report
  • 7. stop_simulation
  • 8. replay_telemetry
  • 9. list_metrics
  • 10. export_controls
  • 11. sync_risk_register
  • 12. generate_validation_report
• Advanced Capabilities
  • Adaptive Adversary Profiles & Plugins
  • Command-Chain Drill-Down
  • Detection Engineering Packs
  • Executive & Governance Suite
  • Audit Logging & Kill Switch
  • Role-Based Access & Approvals
  • Risk & Compliance Sync
• Operational Playbooks
• Contributing & Community Sharing
• Support Resources
• License

Feature Highlights

• Adaptive adversary scenarios tied to real-world APT/FIN actor playbooks, sector-aware CVEs, and plugin-provided intel.
• Command-chain drill-down: pseudo CLI steps (guardrailed) for every attack phase to map outputs to analyst tooling.
• Detection engineering bundles: Sigma, Splunk, and KQL artefacts, MITRE ATT&CK heatmaps, gap analysis, and SOAR integration hooks.
• Incident response suite: deep investigations, forensic artefacts, purple-team scorecards, facilitation kits, executive dashboards, maturity roadmaps, and procurement briefs.
• Operational guardrails: append-only audit logs, approval-gated RBAC, stop_simulation kill switch, role-based prompt templates, and formal policy & ethics guide.
• Telemetry replay & metrics: overlay real PCAP/EDR/SIEM events on simulations, auto-capture readiness metrics, and expose historical trends.
• Risk & control automation: export compensating controls, sync with GRC platforms, and produce auditor-ready validation digests.

Quick Start

Run with Node.js

# Clone the repository (or copy into your workspace)
cd cybersim-pro-mcp

# Install dependencies
npm install

# Build TypeScript sources
npm run build

# Start the MCP server over stdio
node build/index.js

Run with Docker

# Build the image (from the repo root)
docker build -t cybersim-pro-mcp .

# Launch in stdio mode (for Claude, Cline, etc.)
docker run --rm -i cybersim-pro-mcp

HTTP Bridge (REST API)

Expose tools to REST clients or GPT Actions.

npm run serve:http  # defaults to http://localhost:8787

Secure with environment variables:

• CYBERSIM_API_KEY – require Authorization: Bearer <key> header
• CYBERSIM_IP_ALLOW – comma-separated list (127.0.0.1,::1,local,203.0.113.10)
• CYBERSIM_APPROVAL_TOKEN – shared secret required for restricted tools (simulate_attack, stop_simulation, replay_telemetry)
• CYBERSIM_RBAC_CONFIG – optional path to a JSON role policy (see Role-Based Access & Approvals)
• Metrics, control feeds, and audit digests are persisted to ./metrics/, ./controls/, and ./logs/ respectively.

Tamper-Proof Audit Seals

• Enable hash-chained logging by setting CYBERSIM_AUDIT_HMAC_KEY (optionally supply CYBERSIM_AUDIT_CHAIN_ID for multi-tenant tracking).
• Use CYBERSIM_AUDIT_SEAL_KEY (or reuse the HMAC key) to sign exported seals; set _ENCODING=base64 when providing base64 secrets.
• Generate an immutable seal + regulator bundle at any time:
  Terminal

  Copy

  npm run audit:seal -- --log ./logs/audit.log --format json.gz
  

• Outputs are written to ./logs/seals/ (JSON seal plus optional compressed bundle) and include chainHash, chainVerified, signature metadata, and the last approval token event.
• 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).
• Summarise governance progress for Legal/Risk with npm run compliance:report (see docs/COMPLIANCE_ROADMAP.md).

Sample health & scenario creation:

curl -s http://localhost:8787/health

curl -s -X POST http://localhost:8787/tool/create_scenario \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "ransomware",
        "difficulty": "advanced",
        "environment": "corporate",
        "sector": "finance",
        "adversary_profile": "fin7",
        "focus_cves": ["CVE-2024-21410"],
        "operator": {"id": "alice", "role": "controller"},
        "approval_token": "${CYBERSIM_APPROVAL_TOKEN}"
      }' | jq

MCP Client Integration

Claude Desktop

macOS path: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "cybersim-pro": {
      "command": "node",
      "args": ["/absolute/path/to/cybersim-pro-mcp/build/index.js"]
    }
  }
}

For Docker-backed execution:

{
  "mcpServers": {
    "cybersim-pro-docker": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "cybersim-pro-mcp"]
    }
  }
}

Cline VS Code Extension

Open Command Palette → “Cline: Open MCP Settings” and add:

{
  "mcpServers": {
    "cybersim-pro": {
      "command": "node",
      "args": ["/absolute/path/to/cybersim-pro-mcp/build/index.js"]
    }
  }
}

Wrapper scripts in ./scripts/ support runtime switching via CYBERSIM_RUNTIME.

Tool Reference & Walkthroughs

Each tool can be invoked through MCP clients or directly via the HTTP bridge. Examples below use jq for clarity.

1. create_scenario

Generate a tailored scenario with adaptive adversary content.

HTTP Request

curl -s -X POST http://localhost:8787/tool/create_scenario \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "apt",
        "difficulty": "expert",
        "environment": "cloud",
        "sector": "government",
        "adversary_profile": "apt29",
        "focus_cves": ["CVE-2023-23397"]
      }' | jq '.id, .description, .threatIntel'

What you get

• Scenario ID (e.g., SCN-...)
• Sector-aligned objectives and timelines
• Adversary profile with CVEs, detection opportunities, plugin insight list

Use the returned scenarioId to reference the scenario in follow-up drills, reports, or evidence.

2. simulate_attack

Simulate a multi-phase attack and inspect the command-chain drill-down.

HTTP Request

curl -s -X POST http://localhost:8787/tool/simulate_attack \
  -H 'Content-Type: application/json' \
  -d '{
        "attack_type": "ransomware",
        "target": "FILESERVER-001",
        "intensity": "high"
      }' | jq '{simulationId, commandChain: .commandChain[0:5], phases: [.phases[0].artifacts[0]]}'

Highlights

• commandChain array details redacted pseudo commands, safeguards, and MITRE references for each phase.
• phases include techniques, detection methods, and evidence artefacts.
• simulationId feeds into stop_simulation or reporting workflows.

3. analyze_network

Analyse network segments and receive detection artefacts plus coverage insights.

HTTP Request

curl -s -X POST http://localhost:8787/tool/analyze_network \
  -H 'Content-Type: application/json' \
  -d '{
        "network_segment": "DMZ",
        "duration": 30,
        "focus": ["anomalies", "threats", "vulnerabilities"]
      }' | jq '{
        statistics: .statistics.bandwidthUtilization,
        sigma: .detectionArtifacts.sigma[0],
        splunk: .detectionArtifacts.splunk[0].query,
        heatmap: .mitreHeatmap[0:3],
        integration: .integrationHooks
      }'

Output

• Auto-generated Sigma/Splunk/KQL detections with descriptions & tags
• MITRE ATT&CK + D3FEND heatmap coverage with gap analysis
• Integration hooks for Splunk ES, Sentinel, and Cortex XSOAR
• Recommendations aligned with anomalies/vulnerabilities/threats

4. investigate_incident

Run a timeline-driven investigation with evidence, root cause, containment, and remediation details.

HTTP Request

curl -s -X POST http://localhost:8787/tool/investigate_incident \
  -H 'Content-Type: application/json' \
  -d '{
        "incident_id": "INC-2024-001",
        "scope": "deep_dive"
      }' | jq '{severity, timeline: .timeline.events[0:3], rootCause, containmentActions[0]}'

Deliverables

• Attack path reconstruction with dwell time
• Findings and supporting evidence (with chain-of-custody records)
• Containment actions, remediation steps, and lessons learned

5. forensics_analysis

Produce digital forensic artefacts for memory, disk, network, logs, or registry sources.