Skip to content

docs: replace generic template README with spec-specific content #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
t0kubetsu wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: replace generic template README with spec-specific content #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 57 additions & 31 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,79 @@
# Table of Contents
# range42-api-definitions

- [Project Overview](#Project-Overview)
- [Repository Content](#Repository-Content)
- [Contributing](#Contributing)
- [License](#License)
OpenAPI specification for the CR42 backend API (`CR42 - API`, version `v0.1`).

---

# Project Overview
## Contents

**RANGE42** is a modular cyber range platform designed for real-world readiness.
We build, deploy, and document offensive, defensive, and hybrid cyber training environments using reproducible, infrastructure-as-code methodologies.
| File | Description |
|------|-------------|
| `openapi.json` | Machine-readable OpenAPI 3.x specification (used by Kong and tooling) |
| `openapi.json.pretty` | Human-readable formatted copy of the same spec |

## What we build
---

## API Summary

**80 endpoints**, all under the `/v0/admin/` prefix.

| Route group | Endpoints | Description |
|-------------|-----------|-------------|
| `/v0/admin/proxmox/vms/` | 25 | VM lifecycle: create, clone, delete, start, stop, pause, resume, bulk operations, config queries |
| `/v0/admin/proxmox/vms/.../snapshot/` | 10 | Per-VM snapshot management: list, create, delete, revert |
| `/v0/admin/run/bundles/` | 30 | Run named bundles: Ubuntu package installs, user setup, Proxmox VM provisioning (admin / vuln / student roles) |
| `/v0/admin/run/scenarios/` | 1 | Run a named scenario by name |
| `/v0/admin/proxmox/firewall/` | 12 | Firewall rules and aliases at VM, node, and datacenter scope |
| `/v0/admin/proxmox/network/` | 6 | Network interface management on VMs and nodes |
| `/v0/admin/proxmox/storage/` | 4 | Storage listing, ISO listing, template listing, ISO download |
| `/v0/admin/debug/` | 2 | Health check (`ping`) and functional test (`func_test`) |

---

## How to Use

- Proxmox-based cyber ranges with dynamic catalog
- Ansible roles for automated deployments (Wazuh, Kong, Docker, etc.)
- Private APIs for range orchestration and telemetry
- Developer and testing toolkits and JSON transformers for automation pipelines
- ...
### Browse via Swagger UI

## Repository Overview
When the `range42-backend-api` service is running locally, the interactive Swagger UI is available at:

- **RANGE42 deployer UI** : A web interface to visually design infrastructure schemas and trigger deployments.
- **RANGE42 deployer backend API** : Orchestrates deployments by executing playbooks and bundles from the catalog.
- **RANGE42 catalog** : A collection of Ansible roles and Docker/Docker Compose stacks, forming deployable bundles.
- **RANGE42 playbooks** : Centralized playbooks that can be invoked by the backend or CLI.
- **RANGE42 proxmox role** : An Ansible role for controlling Proxmox nodes via the Proxmox API.
- **RANGE42 devkit** : Helper scripts for testing, debugging, and development workflows.
- **RANGE42 kong API gateway** : A network service in front of the backend API, handling authentication, ACLs, and access control policies.
- **RANGE42 swagger API spec** : OpenAPI/Swagger JSON definition of the backend API.
```
http://<backend-host>:<port>/docs
```

### Putting it all together
The raw OpenAPI JSON is served at:

These repositories provide a modular and extensible platform to design, manage and deploy infrastructures automatically either from the UI (coming soon) or from the CLI through the playbooks repository.
```
http://<backend-host>:<port>/openapi.json
```

### Kong gateway bootstrap

Kong reads `openapi.json` to auto-configure its routes and upstream services. Point Kong's deck/sync configuration at this file to keep the gateway in sync with the current spec.

---

# Repository Content
## Regenerating the Spec

The spec is generated directly from the running `range42-backend-api` application. From the root of that repo:

```bash
PYTHONPATH=. python -c "
import json
from app.main import create_app
print(json.dumps(create_app().openapi(), indent=2))
" > openapi.json
```

This repository contains the OpenAPISwagger JSON specification for the backend API used by the deployer UI and behind the kong API gateway : handling authentication, ACLs, and access control policies.
Then copy the result here and update `openapi.json.pretty` with the formatted version.

---

## Contributing

This is a collaborative initiative, developed for applied security training, community integration, and internal capability building.
We use centralized community health files in Range42 community health.
This is a collaborative initiative developed for applied security training, community integration, and internal capability building.
We use centralized community health files in the [Range42 community health](https://github.com/range42/.github) repository.

## License

- GPL-3.0 license

GPL-3.0 — see [LICENSE](LICENSE).