Shifter

Self-service agentic cyber range platform. Users provision isolated attack environments to run purple, red, and blue team scenarios with telemetry from targets, including XDR/XSIAM integrations.

Summary

• Summary
• CyberScript
• Getting Started
• Prerequisites
• Installing
• Usage
• Support
• Deployment
• Running the tests
• Built With
• Contributing
• Versioning
• Ethics
• Safety
• Maintainers
• Acknowledgments

CyberScript

Shifter is powered by CyberScript — a language for defining cyber ranges. Write what you want in CyberScript, then Shifter builds it.

instances:
  - name: Domain Controller
    role: dc
    os_type: windows
    domain_controller: true
    xdr_agent: false

  - name: Workstation 1
    role: victim
    os_type: windows
    xdr_agent: true
    join_domain: true

subnets:
  - name: dc_network
    instances: [Domain Controller]
    connected_to: [workstation_network]

You describe attack scenarios, network topology, and victim configurations without dealing with cloud primitives or infrastructure complexity.

See cortex_byot.yaml for a complete example.

Getting Started

These instructions get a copy of the project up and running on your local machine. See Deployment for notes on deploying to a live cloud account.

Prerequisites

• Python 3.12 with uv
• Node 20+ and npm
• Terraform 1.7+, kubectl, helm 3.15+
• pre-commit

Installing

Each package root manages its own dependencies (uv per pyproject.toml, npm per package.json):

# Per-package Python envs
cd shifter/shifter_platform && uv sync
cd ../installation && uv sync
cd ../cyberscript && uv sync
# ...repeat for any package root you'll touch

# Per-package MCP servers
cd mcp/ops && npm ci
# ...repeat for each mcp/* root

# Install pre-commit hooks once per clone
pre-commit install

Full setup with database, secrets, and bootstrap flow: shifter/shifter_platform/documentation/docs/technical/dev/setup.md.

Usage

Local dev runs the Django platform service against a local Postgres + Redis; provisioner, MCP servers, and the GCP/AWS terraform paths are documented under shifter/shifter_platform/documentation/docs/.

Support

Please read SUPPORT.md for details on how to get support for this project.

Deployment

Production deploys flow through .github/workflows/deploy.yml (a single entry point that dispatches per-cloud child workflows). Deployment-specific identifiers (DNS names, alarm emails, GCP project IDs, allow-list domains, SSH keys, etc.) are supplied via gitignored local.auto.tfvars files for local runs and via GitHub repository secrets/variables for CI. The complete required surface is documented in docs/dev/deploy-secrets.md.

Running the tests

Tests run per-package. Common invocations:

cd shifter/shifter_platform && uv run pytest
cd scripts/bootstrap && uv run pytest
cd scripts/gcp && uv run pytest
cd shifter/engine/provisioner && uv run pytest
cd mcp/<name> && npm test

The aggregate gate every PR must pass:

pre-commit run --all-files
python3 scripts/adr_guard/adr_guard.py --all --level ci

Built With

• Django — platform service (portal, CMS, Mission Control)
• Terraform — AWS and GCP infrastructure
• Kustomize + Helm — Kubernetes workload deployment on GKE
• Apache Guacamole — clientless remote access into provisioned range hosts
• Packer — golden VM image build

Contributing

We value your contributions! Please read CONTRIBUTING.md for details on how to contribute, and the process for submitting pull requests.

Versioning

We use SemVer for versioning and conventional commits for commit and pull request titles. Release notes are collated from towncrier fragments under changelog.d/ — see changelog.d/README.md.

Safety

• Human oversight required for all scenarios.

Maintainers

• Brad Edwards — Brad-Edwards-SecOps, Brad-Edwards

Citation

If you use Shifter in academic work or publications, please cite it:

@software{shifter,
  author       = {Edwards, Brad},
  title        = {Shifter: Self-Service Agentic Cyber Range Platform},
  year         = {2026},
  organization = {Palo Alto Networks},
  license      = {MIT},
  url          = {https://github.com/PaloAltoNetworks/shifter}
}