io.github.kayembahamid/cybersim-pro

Official

by kayembahamid · TypeScript

Cybersecurity training, simulation, and incident response MCP server

Cybersecurity training, simulation, and incident response environment for learning.

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.

Feature Highlights
Quick Start
MCP Client Integration
- Claude Desktop
- Cline VS Code Extension
Tool Reference & Walkthroughs
Advanced Capabilities
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

bash

# 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

bash

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

bash

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:

bash

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:

bash

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

json

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

For Docker-backed execution:

json

{
  "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:

json

{
  "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

bash

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

bash

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

bash

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

bash

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

bash

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

bash

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.

bash

# 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

bash

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.

bash

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

bash

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.

bash

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.

bash

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.

Fork the repository and branch from main (or community/main when contributing to shared content).
Add code or documentation, ensuring TypeScript builds succeed (npm run build).
For community packs, follow sanitisation and metadata guidelines in docs/COMMUNITY_PROGRAM.md.
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:

Review the documentation above.
Inspect source code comments and example responses.
Reproduce minimal scenarios (create_scenario → simulate_attack) to isolate issues.
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.

Install

Configuration

Arguments

--rm

-i

claude_desktop_config.json

{
  "mcpServers": {
    "cybersim-pro": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "docker.io/hamcodes/cybersim-pro-mcp:v1.0.1"
      ]
    }
  }
}

CyberSim Pro MCP Server

Table of Contents

Feature Highlights

Quick Start

Run with Node.js

Run with Docker

HTTP Bridge (REST API)

Tamper-Proof Audit Seals

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

Learning Path (Recap)

Contributing & Community Sharing

Support Resources

License

Install

Configuration

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`