Repository avatar
AI Tools
v1.0.1
active

cybersim-pro

io.github.kayembahamid/cybersim-pro

Cybersecurity training, simulation, and incident response MCP server

RepositoryWebsite

Documentation

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

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

OCI
docker.io/hamcodes/cybersim-pro-mcp:v1.0.1
Install Command
docker pull docker.io/hamcodes/cybersim-pro-mcp:v1.0.1:undefined
Runtime: docker

Related Servers

ai.aliengiraffe/spotdb

Ephemeral data sandbox for AI workflows with guardrails and security

ai.klavis/strata

MCP server for progressive tool usage at any scale (see https://klavis.ai)

ai.mcpanalytics/analytics

MCP Analytics, searchable tools and reports with interactive HTML visualization