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:

  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.

HTTP Request

curl -s -X POST http://localhost:8787/tool/forensics_analysis \
  -H 'Content-Type: application/json' \
  -d '{
        "artifact_type": "disk",
        "system_id": "WORKSTATION-001",
        "analysis_depth": "comprehensive"
      }' | jq '{artifactSummary: .findings[0], chainOfCustody: .chainOfCustody[0]}'

Expect curated findings, hash validation, custody records, and preservation guidance.

---

6. generate_report

Generate executive, incident, vulnerability, or compliance reports with optional facilitation mode.

HTTP Request

curl -s -X POST http://localhost:8787/tool/generate_report \
  -H 'Content-Type: application/json' \
  -d '{
        "report_type": "executive",
        "incident_ids": ["INC-2024-001", "INC-2024-002"],
        "include_recommendations": true,
        "mode": "facilitation"
      }' | jq '{
        executiveSummary,
        scorecard: .scorecard.metrics,
        facilitationKit: .facilitationKit.agenda,
        dashboard: .executiveDashboard.heatmap,
        roadmap: .maturityRoadmap.milestones,
        procurement: .procurementBrief.faqs
      }'

Key sections:

• Executive summary & risk posture
• Purple-team scorecard metrics and lessons
• Facilitation kit (kickoff prompt, teleprompter notes, agenda)
• Executive dashboard (risk, downtime, financial exposure)
• Maturity roadmap (NIST CSF, CMMC, ISO 27001 alignment)
• Procurement brief (FAQs, legal considerations, risk controls)

---

7. stop_simulation

Kill a single simulation or all active runs with audit logging.

# Stop a specific simulation ID
target="SIM-1759281782112"
curl -s -X POST http://localhost:8787/tool/stop_simulation \
  -H 'Content-Type: application/json' \
  -d "{\"simulation_id\": \"$target\", \"reason\": \"Executive requested early termination\", \"operator\": {\"id\": \"alice\", \"role\": \"controller\"}, \"approval_token\": \"${CYBERSIM_APPROVAL_TOKEN}\"}"

# Stop everything (returns list of terminated runs)
curl -s -X POST http://localhost:8787/tool/stop_simulation \
  -H 'Content-Type: application/json' \
  -d '{"operator":{"id":"alice","role":"controller"},"approval_token":"'"${CYBERSIM_APPROVAL_TOKEN}"'"}'

The audit logger records the termination reason, counts, and timestamps for compliance evidence.

---

8. replay_telemetry

Overlay raw telemetry (PCAP/EDR/SIEM exports) against a live simulation to validate coverage.

HTTP Request

curl -s -X POST http://localhost:8787/tool/replay_telemetry \
  -H 'Content-Type: application/json' \
  -d '{
        "simulation_id": "SIM-1759281782112",
        "telemetry": [
          {"timestamp":"2024-05-01T10:00:00Z","indicator":"powershell.exe","description":"Beacon to rare domain","techniqueId":"t1059.001"}
        ],
        "operator": {"id": "alice", "role": "controller"},
        "approval_token": "'"${CYBERSIM_APPROVAL_TOKEN}"'"
      }' | jq '{matchedTechniques, detectionGaps, observations}'

Matched techniques confirm detections fired; detectionGaps highlight phases lacking telemetry coverage. Recommended controls are appended automatically to the compensating-control feed.

---

9. list_metrics

Summarise readiness metrics across all exercises.

curl -s -X POST http://localhost:8787/tool/list_metrics -H 'Content-Type: application/json' -d '{}' | jq

Outputs include total exercises, reports generated, and average detection/containment times alongside the latest trend entries.

---

10. export_controls

Export the consolidated compensating-control feed (detections, automations, gap closures).

curl -s -X POST http://localhost:8787/tool/export_controls -H 'Content-Type: application/json' -d '{}' | jq '.[0:5]'

Each entry includes category, source, priority, and payload ready for SIEM/SOAR ingestion.

---

11. sync_risk_register

Generate REST payloads for governance platforms such as ServiceNow GRC, Archer, or OneTrust.

curl -s -X POST http://localhost:8787/tool/sync_risk_register \
  -H 'Content-Type: application/json' \
  -d '{
        "system": "servicenow",
        "incident_id": "INC-2024-001",
        "priority": "Critical",
        "owner": "risk.governance@example.com"
      }' | jq

The response provides the endpoint, HTTP method, payload, and checklist for operators to update the risk register.

---

12. generate_validation_report

Produce an auditor-facing summary with hashed proof of recent CyberSim activity.

curl -s -X POST http://localhost:8787/tool/generate_validation_report -H 'Content-Type: application/json' -d '{}' | jq

The digest contains the SHA-256 hash, total entries, and redacted samples suitable for regulator briefings.

---

Advanced Capabilities

Adaptive Adversary Profiles & Plugins

• Profiles (e.g., APT29, FIN7) embed motivations, campaigns, preferred tactics, CVEs, and countermeasures.
• PluginRegistry (src/utils/pluginRegistry.ts) lets you register sector or vendor-specific intel providers. Each plugin can inject CVEs, notes, and detection enhancements.
• Scenario outputs surface threatIntel.pluginInsights referencing contributing providers.

Command-Chain Drill-Down

Simulations include commandChain entries describing pseudo commands, safeguards, and technique references. Use these to:

• Map red-team actions to your tooling (e.g., WMI logs, PowerShell policy)
• Provide narrations during live tabletop facilitation
• Export to internal red-team wikis without exposing live payloads

Detection Engineering Packs

Network analysis responses include:

• Sigma rules (YAML-string), Splunk searches, Sentinel KQL queries
• Playbooks for triage/containment
• MITRE ATT&CK + D3FEND mappings and coverage heatmaps
• Integration hooks for Splunk ES saved searches, Sentinel analytics rules, and Cortex XSOAR playbooks

Executive & Governance Suite

generate_report outputs provide everything needed for leadership alignment:

• Executive dashboard, downtime estimates, financial impact
• Purple-team metrics & lessons learned
• Facilitation kit for hybrid workshops
• Maturity roadmap with quarterly milestones and framework alignment
• Procurement brief with FAQ, legal, and risk-control summaries

Audit Logging & Kill Switch

• 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).
• Entries capture timestamp, tool, sanitized arguments, metadata, and error messages; validation exposes chainVerified, lastChainHash, and signature provenance.
• npm run audit:seal produces a signed seal and regulator bundle under logs/seals/, ready for object-lock storage or shareable attestations.
• npm run compliance:report surfaces control maturity, framework mappings, and roadmap freshness for monthly stakeholder updates.
• The stop_simulation tool halts activity immediately and records the termination reason for traceability.
• generate_validation_report produces hashed digests and anomaly flags that auditors can cross-check against sealed exports.

Identity Roadmap

• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• After upgrading, run npm run migrate:provenance to backfill legacy metrics/control logs with the new provenance fields before exporting historical evidence.

Role-Based Access & Approvals

• High-impact tools (simulate_attack, stop_simulation, replay_telemetry) respect role policies defined via CYBERSIM_RBAC_CONFIG.
• Restricted tools require a shared approval token (CYBERSIM_APPROVAL_TOKEN), enabling dual-control or change-ticket workflows.
• Operator metadata is captured in the audit log, supporting segregation-of-duties reviews.
• Default policy grants analysts access to low-risk tooling while controllers/CISOs can execute adversary simulations.

Risk & Compliance Sync

• sync_risk_register generates ready-to-post payloads for ServiceNow GRC, Archer, OneTrust, or custom systems.
• export_controls provides the compensating-control feed derived from detection packs, telemetry gaps, and automation hooks.
• Telemetry replay and network analysis automatically feed the control register so lessons learned become enforceable controls.

---

Operational Playbooks

• Learning Path – follow beginner → intermediate → advanced exercises (see Learning Path section below) to ramp analysts.
• Role-Based Prompt Templates – prebuilt red/blue/purple/executive prompts in docs/ROLE_BASED_PROMPTS.md.
• Policy & Ethics Guide – acceptable use, regulatory alignment, and safety checklist in docs/POLICY_AND_ETHICS.md.
• Benchmark Library – curated scenarios per industry with KPIs in docs/BENCHMARK_LIBRARY.md.
• Community Sharing Program – contribute sanitized scenarios/detections using the workflow in docs/COMMUNITY_PROGRAM.md.

Learning Path (Recap)

• Beginner: phishing or simple malware, focus on indicators and detection basics.
• Intermediate: ransomware/APT scenarios, run investigations and network analysis.
• Advanced: full kill-chain drills, deep forensics, executive reporting, automation via HTTP bridge.

---

Contributing & Community Sharing

1. Fork the repository and branch from main (or community/main when contributing to shared content).
2. Add code or documentation, ensuring TypeScript builds succeed (npm run build).
3. For community packs, follow sanitisation and metadata guidelines in docs/COMMUNITY_PROGRAM.md.
4. Submit a pull request; audit logs and documentation updates are encouraged alongside new features.

---

Support Resources

• Role-based prompts: docs/ROLE_BASED_PROMPTS.md
• Policy & ethics: docs/POLICY_AND_ETHICS.md
• Plugin guide: docs/PLUGIN_ARCHITECTURE.md
• Benchmark scenarios: docs/BENCHMARK_LIBRARY.md
• Community sharing workflow: docs/COMMUNITY_PROGRAM.md

For assistance:

1. Review the documentation above.
2. Inspect source code comments and example responses.
3. Reproduce minimal scenarios (create_scenario → simulate_attack) to isolate issues.
4. File issues or discussions on the GitHub repository.

---

License

Released under the MIT License. Use, modify, and adapt CyberSim Pro MCP Server for authorised defensive purposes.