Démarrage rapide : lancer un lab avec l'API Scenario

Ce guide décrit l'API Scenario de bout en bout pour lancer un lab à partir d'un scénario, suivre son exécution et récupérer un accès distant — en cURL et en Python. Il reproduit ce que fait le CLI mantis (mantis_api_client/mantis_api_client/scenario_api.py).

Avant de commencer, obtenez un jeton d'accès et l'identifiant de votre espace de travail — voir le guide d'authentification.

export BASE="https://app.mantis-platform.io/api/scenario/lab"
export TOKEN="<votre jeton d'accès>"
export WORKSPACE_ID="<votre workspace id>"

Étape 1 — Parcourir le catalogue

Listez les scénarios auxquels vous avez accès et choisissez-en un par son name.

cURL

curl "$BASE/scenario/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID"

Python

import requests

BASE = "https://app.mantis-platform.io/api/scenario/lab"
TOKEN = "<votre jeton d'accès>"
WORKSPACE_ID = "<votre workspace id>"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "X-Workspace-Id": WORKSPACE_ID}

scenarios = requests.get(f"{BASE}/scenario/", headers=HEADERS)
scenarios.raise_for_status()
for s in scenarios.json()["scenario_list"]:
    print(s["name"])

Étape 2 — Lancer le lab

POST /scenario/run_lab crée et démarre le lab en un appel (utilisez /scenario/create_lab pour le démarrer plus tard). Le corps encapsule un lab_config ; la réponse est l'identifiant du lab.

cURL

curl -X POST "$BASE/scenario/run_lab?workspace_id=$WORKSPACE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
        "lab_config": {
          "content_type": "KILLCHAIN",
          "content_name": "<nom-de-scenario-etape-1>",
          "scenario_profile": "default",
          "max_duration": 3600
        }
      }'

Python

lab_config = {
    "content_type": "KILLCHAIN",              # KILLCHAIN | ATTACK | TOPOLOGY | BASEBOX | BAS | DFIR
    "content_name": "<nom-de-scenario-etape-1>",
    "scenario_profile": "default",
    "max_duration": 3600,                      # en secondes ; 0 = pas de délai maximum
}
resp = requests.post(
    f"{BASE}/scenario/run_lab",
    params={"workspace_id": WORKSPACE_ID},
    json={"lab_config": lab_config},
    headers=HEADERS,
)
resp.raise_for_status()
lab_id = resp.json()
print("Lab lancé :", lab_id)

Étape 3 — Suivre l'exécution

Interrogez GET /runner/{lab_id} jusqu'à l'état RUNNING (ou un état terminal).

cURL

curl "$BASE/runner/$LAB_ID" -H "Authorization: Bearer $TOKEN"

Python

import time

while True:
    r = requests.get(f"{BASE}/runner/{lab_id}", headers=HEADERS)
    r.raise_for_status()
    status = r.json().get("status")
    print("statut :", status)
    if status in ("RUNNING", "ERROR", "STOPPED"):
        break
    time.sleep(10)

Étape 4 — Obtenir l'accès distant

Une fois le lab en cours d'exécution, récupérez les informations de connexion aux machines déployées.

cURL

curl "$BASE/runner/$LAB_ID/remote_access" -H "Authorization: Bearer $TOKEN"

Python

access = requests.get(f"{BASE}/runner/{lab_id}/remote_access", headers=HEADERS)
access.raise_for_status()
print(access.json())

Étape 5 — Arrêter et nettoyer

# Arrêter l'exécution
curl "$BASE/runner/$LAB_ID/stop" -H "Authorization: Bearer $TOKEN"
# Supprimer le lab
curl -X DELETE "$BASE/runner/$LAB_ID" -H "Authorization: Bearer $TOKEN"

Script complet

import time
import requests

BASE = "https://app.mantis-platform.io/api/scenario/lab"
TOKEN = "<votre jeton d'accès>"
WORKSPACE_ID = "<votre workspace id>"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "X-Workspace-Id": WORKSPACE_ID}


def launch_scenario(name: str, profile: str = "default") -> str:
    lab_config = {
        "content_type": "KILLCHAIN",
        "content_name": name,
        "scenario_profile": profile,
        "max_duration": 3600,
    }
    resp = requests.post(
        f"{BASE}/scenario/run_lab",
        params={"workspace_id": WORKSPACE_ID},
        json={"lab_config": lab_config},
        headers=HEADERS,
    )
    resp.raise_for_status()
    return resp.json()


def wait_running(lab_id: str) -> str:
    while True:
        status = requests.get(f"{BASE}/runner/{lab_id}", headers=HEADERS).json()["status"]
        if status in ("RUNNING", "ERROR", "STOPPED"):
            return status
        time.sleep(10)


if __name__ == "__main__":
    scenarios = requests.get(f"{BASE}/scenario/", headers=HEADERS).json()["scenario_list"]
    name = scenarios[0]["name"]
    lab_id = launch_scenario(name)
    print("Lancé", lab_id, "->", wait_running(lab_id))
    print(requests.get(f"{BASE}/runner/{lab_id}/remote_access", headers=HEADERS).json())

Pour aller plus loin

• Référence complète des endpoints : l'API Scenario (chaque endpoint fournit des exemples cURL + Python).
• Guide d'authentification pour la gestion des jetons.