From d58f703bb5d6573fae4a69d413e303605bbbb4e7 Mon Sep 17 00:00:00 2001 From: t0kubetsu Date: Tue, 12 May 2026 10:46:17 +0200 Subject: [PATCH] docs: replace generic template README with spec-specific content Rewrites the README to describe this repository specifically: what files it contains, a summary of the 80 API endpoints grouped by route, how to browse the spec via Swagger UI, how to use it for Kong bootstrap, and how to regenerate the spec from the backend-api app. --- README.md | 88 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 57 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 98670ef..fbddd8a 100644 --- a/README.md +++ b/README.md @@ -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://:/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://:/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).