The Range42 project is an open-source initiative focused on creating realistic, scalable cybersecurity training environments. Our project is composed of multiple sub-projects contributed by cybersecurity professionals, educators, researchers, and enthusiasts who actively use and improve the Range42 platform. The Range42 project fully supports the Contributor Covenant Code of Conduct to foster an inclusive and collaborative environment for learning and advancing cybersecurity education.
The Range42 roadmap is driven by the needs of our user communities including cybersecurity training organizations, educational institutions, corporate security teams, government agencies, and individual practitioners seeking hands-on cybersecurity experience.
Participating in the Range42 project is accessible to everyone, regardless of their experience level. Get familiar with how we use GitHub at Range42 Project, then read on for details on how you can contribute:
The most common way to contribute to the Range42 project is to report bugs, issues, or suggest new features and scenarios.
:todo: Adapt with real-world repos Each project component (Range42 core, scenario-library, infrastructure, assessment-engine, documentation or any other projects within the Range42 organization) has its own issue management system. Don't forget that you can cross-reference issues between sub-projects.
- Use the provided issue template. When reporting an issue on GitHub, please use one of the issue templates. Do not delete or remove parts of it. The issue template is designed to gather essential information about your environment, the scenario being used, and steps to reproduce the issue.
- New issues should include all relevant information. Add comprehensive details including:
- Range42 version and deployment method
- Operating system and virtualization platform
- Scenario/exercise being run
- Expected vs actual behavior
- Screenshots or logs where applicable
- Network configuration details (if relevant)
- Performance metrics (if performance-related)
- Security policy. To disclose a security issue confidentially, please see the Reporting Security Vulnerabilities section.
- Avoid duplicate issues. Search both open and closed issues before creating a new one. If you find a similar issue, comment on the existing one rather than creating a duplicate. This helps us track interest and priority.
- No guarantees on implementation. Creating an issue is a way to submit items for consideration. The Range42 team will prioritize based on project roadmap, community needs, and available resources.
When developers resolve your issue, the GitHub issue will typically be closed from the relevant commit message. We maintain a main stable branch with regular updates and feature branches for development.
If you test a fix and find it doesn't resolve your issue, please comment on the original issue explaining the situation. We'll receive a notification and respond accordingly.
Issues may be closed with specific resolutions like R: invalid, R: duplicate, or R: wontfix. Each label has a description explaining the decision.
:todo: Check what those link to, SECURITY.md ? View our Security Policy.
Given the nature of cybersecurity training environments, we take security reports seriously and have established procedures for responsible disclosure.
Before you get started, read our coding guidelines.
If you want to contribute to the Range42 core project:
- First fork the Range42 core project
- Branch off from
main(main branch is the primary development branch)git checkout main - Create a branch for your contribution
git checkout -b feature/new-scenario-engine - Work on your fix or feature (focus only on that feature, avoid debug code or unrelated changes)
- Commit your changes with meaningful commit messages following our Commit Message Best Practices. Use prefixes like
feat:for new features,fix:for bug fixes,docs:for documentation, orrefactor:for code improvements. - Push and open a pull request via GitHub.
For changes to scenarios, assessments, or infrastructure components, see the Scenario Development CheckList.
Range42 follows Semantic Versioning (SemVer) for all releases. Understanding semantic versioning helps maintain compatibility and communicate changes effectively to our users.
- MAJOR version (e.g., 2.0.0): Incompatible API changes or significant breaking changes that require user action
- MINOR version (e.g., 1.3.0): New features or functionality added in a backward-compatible manner
- PATCH version (e.g., 1.2.5): Backward-compatible bug fixes, security patches, or minor improvements
1.0.0→2.0.0: Breaking change (e.g., scenario format changes requiring migration)1.2.0→1.3.0: New feature (e.g., added new assessment engine capability)1.2.3→1.2.4: Bug fix (e.g., fixed deployment script error)
- Pre-release versions:
1.0.0-alpha,1.0.0-beta.1,1.0.0-rc.2 - Build metadata:
1.0.0+20240115(not considered in version precedence)
When contributing, ensure your changes align with the appropriate version increment. Major changes require broader community discussion and migration guides.
- Small, incremental changes are preferred over large, complex ones
- Include tests for new functionality
- Update documentation when adding new features
- Ensure scenarios are tested in multiple environments
- Follow security best practices for training content
Range42 scenarios are defined in structured formats (JSON/YAML) that describe:
- Network topologies
- Vulnerable services and applications
- Attack vectors and defensive measures
- Learning objectives and assessment criteria
- Resource requirements
- Design phase: Create a scenario specification document outlining learning objectives, target audience, and technical requirements
- Implementation: Develop the scenario configuration files, supporting scripts, and documentation
- Testing: Validate the scenario in isolated environments across different platforms
- Documentation: Create instructor guides, student materials, and technical documentation
- Validation: Run automated tests using our CI/CD pipeline
All scenarios undergo JSON/YAML validation and security scanning before integration.
If you want to contribute realistic attack scenarios:
- Research and design: Base scenarios on real-world attack patterns, TTPs (Tactics, Techniques, and Procedures), and current threat intelligence
- Create scenario files: Develop configuration files following our Scenario Schema
- Develop supporting materials: Include network diagrams, VM configurations, and assessment rubrics
- Educational content: Create learning objectives, prerequisites, and expected outcomes
- Testing: Validate across different skill levels and environments
- Documentation: Provide clear setup instructions and troubleshooting guides
For more information, see "Developing Effective Range42 Scenarios" in our documentation.
Range42 infrastructure automation includes:
- Container orchestration configurations
- Virtual machine templates and provisioning scripts
- Network simulation and configuration
- Monitoring and logging systems
- Auto-scaling and resource management
To contribute:
- Fork the infrastructure repository
- Create or modify Infrastructure as Code (IaC) templates
- Test deployments in multiple cloud environments
- Validate security configurations and network isolation
- Update documentation and deployment guides
- Submit pull request with comprehensive testing results
Range42 uses open standards and APIs for:
- Scenario definition and exchange
- Assessment and scoring
- User management and progress tracking
- Infrastructure provisioning
- Reporting and analytics
We encourage developers to build compatible tools and integrations. See our API documentation and integration guides.
We welcome improvements to our documentation, particularly:
- User guides: Setup, configuration, and usage instructions
- Instructor materials: Teaching guides, assessment rubrics, and best practices
- Developer documentation: API references, architecture guides, and contribution workflows
- Scenario documentation: Learning objectives, technical details, and troubleshooting
See our documentation contribution guidelines.
All Range42 repositories include CI/CD pipelines that:
- Validate code quality and security
- Test scenario deployment and functionality
- Check infrastructure provisioning
- Verify documentation builds
- Run security scans on container images
Contributions to our testing infrastructure are welcome, including:
- Unit and integration tests
- Security testing frameworks
- Performance benchmarking
- Cross-platform compatibility tests
Testing new Range42 releases helps ensure stability and functionality across different environments. Testing should be done in isolated environments, never in production training systems.
Areas that benefit from testing:
- New scenario deployments
- Infrastructure scaling and performance
- User interface changes
- API functionality
- Integration with external tools
If you'd like to test Range42 without a full installation, use our pre-built VM images.
We accept translations through our localization platform: https://crowdin.com/project/cyberrange
Help make Range42 accessible in your language by translating:
- User interface elements
- Documentation and guides
- Scenario descriptions and instructions
- Error messages and help text
Note that only reviewed translations are included in releases.
Most Range42 developers are not native English speakers. We welcome corrections and improvements to our English documentation, user interfaces, and communications.
As a Range42 user, contribute to our UX efforts by:
- Completing the Range42 User Experience Survey
- Providing feedback on scenario difficulty and effectiveness
- Suggesting improvements to the user interface
- Contributing to user personas and user stories
For UX-related questions, contact us at ux@cyberrange-project.org
Help improve our website at https://cyberrange-project.org/. See website-related issues for current improvement opportunities.
The website is built using Jekyll. You can build a local copy to test changes before submitting pull requests.
Join our community:
- Discord: Real-time chat and support
- Forums: Discussion and knowledge sharing
- Monthly meetings: Community calls and project updates
- Conferences: Present your scenarios and research at cybersecurity education events
Contributors are recognized through:
- Public acknowledgment in release notes
- Contributor badges and profiles
- Annual community awards
- Speaking opportunities at conferences
- Co-authorship on academic publications
New contributors should:
- Read this contributing guide and the Code of Conduct
- Join our Discord or forum for introductions
- Review open issues labeled "good first issue"
- Set up a development environment using our setup guide
- Start with small contributions like documentation or bug fixes
- Engage with the community and ask questions
Remember: Every contribution, no matter how small, helps advance cybersecurity education and training. Thank you for your interest in making Range42 better!