Opprette din første øvelse

For dette eksempelet vil vi lage en faktisk øvelse som definerer VM-er og nettverksbrytere som er nødvendige for en deltaker. Det vil bestå av en server-VM som vil bli gitt til deltakeren, en poenggivende VM som vil spore deltakerens fremgang og en nettverksbryter som vil koble de to. Samt funksjoner som installerer de nødvendige komponentene og betingelser som sjekker om deltakeren har fullført sine oppgaver.

Nå som vi har en pakke, kan vi lage en øvelse som bruker den. For å gjøre det, må vi logge inn på Ranger-nettstedet og logge inn.

Etter å ha opprettet vår nye øvelse, kan vi begynne å jobbe med SDL (Scenario Description Language)-filen. SDL-filen er skrevet i YAML-formatet som beskriver øvelsen. Detaljert informasjon om SDL-filen finner du i SDL Referanseguide

YAML-syntaksen

En veldig rask oversikt over den grunnleggende YAML-syntaksen som brukes i SDL:

# En nøkkel-verdi par
key: value

# En liste - YAML bruker innrykk for å definere struktur
key:
  - value
  - value2

# Et kart
key:
  key2: value
  key3: value2
  key4:
    - value3
    - value4

Skrive SDL

Vi kan skrive vår SDL på Ranger-nettstedet i Dashboard-fanen. Det gir også en enkel syntakssjekker for å hjelpe oss med å skrive SDL.

Vi kan starte med å gi vår SDL et navn:

name: 'My First Exercise'

Med unntak av penn og papir øvelser, trenger sannsynligvis alle øvelser en VM. For dette eksempelet vil vi bruke to VM-pakker, en ferdiglaget pakke kalt debian-12-gui-docker som et basisbilde for vår WordPress-server og debian11-network-manager for vår poenggivende maskin og en switch for å koble de to. I SDL tilhører alle VM-er og brytere under nodes-blokken. Følgende referanseguide kan vi definere vår VM med sine obligatoriske felt:

Noder (Nodes)

nodes:
  wordpress-server:
    type: vm
    source: debian-12-gui-docker
    resources:
      cpu: 2
      ram: 4 GiB

  scoring-machine:
    type: vm
    source: debian11-network-manager
    resources:
      cpu: 2
      ram: 4 GiB

  switch:
    type: switch

For å installere tilleggspakker som Funksjoner eller Betingelser må vi også gi den roles slik at vi har tilgang til VM-ene kontoer og senere koble en deltaker entity til selve VM-en. Roller refererer til kontonavnene definert i pakken. For dette eksempelet vil vi bruke root-kontoen.

nodes:
  wordpress-server:
    type: vm
    source: debian-12-gui-docker
    resources:
      cpu: 1
      ram: 2 GiB
    roles:
      admin: root

Infrastruktur (Infrastructure)

Infrastruktur lar oss spesifisere antall noder eller nettverksbrytere vi ønsker å opprette, samt deres sammenkoblinger og avhengigheter.

For vårt eksempel distribuerer vi en VM per node og kobler dem til vår bryter:

infrastructure:
  switch: 1

  wordpress-server:
    count: 1
    links:
      - switch

  scoring-machine:
    count: 1
    links:
      - switch

nodes:
  wordpress-server:
    type: vm
    source: debian-12-gui-docker
    resources:
      cpu: 2
      ram: 4 GiB
    roles:
      admin: root

  scoring-machine:
    type: vm
    source: debian11-network-manager
    resources:
      cpu: 2
      ram: 4 GiB

  switch:
    type: switch

Entiteter (Entities)

Nå som vi har en VM, kan vi koble den til en deltaker enhet. En entity kan være enten en organisasjon, et team eller en person. Å gi dem en rolle er nødvendig for automatiske og manuelle poenggivingsformål. For dette eksempelet vil vi opprette et Blue Team og gi det en deltaker:

entities:
  blue-team:
    role: Blue
    entities:
      participant:
        role: Blue

Vi er nå klare til å oppdatere admin-rollen i vår VM. Formatet for å tildele barneenheter er <parent>.<child>.<grandchild> ... etc. For øyeblikket bruker vi kortform notasjon for vår admin-rolle. For å legge til en enhet, må vi bytte til langform notasjon:

nodes:
  wordpress-server:
    type: vm
    source: debian-12-gui-docker
    resources:
      cpu: 2
      ram: 4 GiB
    roles:
      admin:
        username: root
        entities:
          - blue-team.participant

Vi har nå koblet vår VM til en deltaker. Senere når vi kobler deltaker enheten til en ekte brukers konto, kan de se VM-ens legitimasjon de ble tildelt i deres dashbord.

Funksjoner (Features)

Funksjoner brukes til å kopiere filer til VM-en og kjøre vilkårlige kommandoer etter at den er initialisert. Dette gir oss fleksibilitet og modularitet for å bruke de samme basis VM-pakkene til forskjellige formål. For dette eksempelet vil vi installere en WordPress-server ved å bruke wordpress-4-8-0-docker-pakken fra Deputy Digital Library. For å gjøre det, må vi legge til en features-blokk:

features:
  wordpress:
    type: service
    source: wordpress-4-8-0-docker

I tillegg må vi gi våre VM-er statiske IP-adresser slik at denne spesifikke distribusjonen kan kommunisere med hverandre som designet. For dette eksempelet vil vi bruke debian-ip-setter-pakken fra Deputy Digital Library. Vi må definere to funksjoner, en for hver VM:

features:
  wordpress:
    type: service
    source: wordpress-4-8-0-docker

  static-ip-1:
    type: service
    source: debian-ip-setter
    environment:
      - STATIC_IP=10.1.1.1/24

  static-ip-2:
    type: service
    source: debian-ip-setter
    environment:
      - STATIC_IP=10.1.1.2/24

Nå må vi legge til funksjonen til VM-en og gi den tilgang til en rolle som tjenesten vil bli installert med. For dette eksempelet vil vi bruke admin-rollen.

nodes:
  wordpress-server:
    type: vm
    source: debian-12-gui-docker
    resources:
      cpu: 2
      ram: 4 GiB
    roles:
      admin:
        username: root
        entities:
          - blue-team.participant
    features:
      static-ip-1: admin
      wordpress: admin

  scoring-machine:
    type: vm
    source: debian11-network-manager
    resources:
      cpu: 2
      ram: 4 GiB
    roles:
      admin: root
    features:
      static-ip-2: admin

Betingelser (Conditions)

Betingelser er vilkårlige skript som installeres på og kjøres på deres tildelte VM og periodisk sjekker betingelsen til noe. De installeres alltid etter at alle funksjoner er installert. De returnerer en verdi mellom 0..1 til Ranger og brukes både til poenggivingsformål i Metrikker eller som triggere for Hendelser.

Kort sagt, betingelser brukes til å sjekke om en deltaker har fullført en oppgave.

For vårt eksempel vil vi bruke en betingelse for å sjekke om vår WordPress-server fortsatt bruker sine standard usikre administrator legitimasjon ved å bruke en ferdiglaget pakke kalt wordpress-check-credentials. Å definere dem er likt som å definere funksjoner.

Denne betingelsen krever også at en WP_URL miljøvariabel settes, som peker den mot mål WordPress-nettstedet.

Bruken av en poenggivende maskin kan ikke være nødvendig for alle øvelser da betingelsene kan kjøres direkte på deltakerens VM i stedet. Betingelsesstrømmer vil også gjenopprette hvis deltakere slår av eller starter sine VM-er på nytt. Men siden betingelser bare er skript som kjøres på VM-ene, hvis brukeren har root-tilgang til VM-en, kan de endre eller deaktivere betingelsene.

conditions:
  wordpress-check-credentials:
    source: wordpress-check-credentials
    environment:
      - WP_URL=10.1.1.1:8000

# ...

nodes:
  wordpress-server:
    type: vm
    source: debian-12-gui-docker
    resources:
      cpu: 2
      ram: 4 GiB
    roles:
      admin:
        username: root
        entities:
          - blue-team.participant
    features:
      wordpress: admin
    conditions:
      wordpress-check-credentials: admin

Nå sjekker vi betingelsen til vår WordPress-server. Men for å bruke betingelsen i vårt poenggivingssystem må vi definere de poenggivingsrelaterte blokkene Metrikker, Evalueringer og TLOs (Trenings og læringsmål).

Metrikker (Metrics)

Metrikker brukes til å kvantifisere en spesifikk betingelse. De kan være enten conditional hvor de er koblet til en betingelse eller manual hvor deltakeren manuelt sender inn en verdi eller fil for Ranger-manageren å evaluere.

I vårt eksempel vil vi koble metrikken til vår eksisterende betingelse og gi den en vilkårlig maks poengsum på 100 poeng.

metrics:
  wordpress-credentials-metric:
    type: conditional
    max-score: 100
    condition: wordpress-check-credentials

Evalueringer (Evaluations)

Evalueringer brukes til å vurdere om en metrikk eller gruppe av metrikker har blitt tilstrekkelig fullført ved å sammenligne metrikkenes poengsum med en definert minimum poengsum terskel. min-score terskelen kan være enten en absolutt verdi eller en prosentandel av den kombinerte maksimale poengsummen til sine tildelte metrikker.

For vårt eksempel vil vi bruke kortform versjonen av min-score terskelen og sette den til 100 prosent.

evaluations:
  wordpress-credentials-evaluation:
    min-score: 100
    metrics:
      - wordpress-credentials-metric

Trenings og læringsmål (Traning and Learning Objectives - TLOs)

Trenings og læringsmål (TLOs) brukes til å beskrive læringsmålene for en øvelse. Ved å koble den til vår evaluering, kan vi definere TLO-ene som oppnås ved å fullføre øvelsen.

tlos:
  wordpress-credentials-tlo:
    evaluation: wordpress-credentials-evaluation

For å koble TLO-en til deltakeren, må vi legge den til deltakerens enhet:

tlos:
  wordpress-credentials-tlo:
    evaluation: wordpress-credentials-evaluation

entities:
  blue-team:
    role: Blue
    entities:
      participant:
        role: Blue
        tlos:
          - wordpress-credentials-tlo

Injiserer (Injects)

Injiserer er neste i vår kjede. De definerer en source som er en Injisert type pakke som vil bli distribuert når hendelsen har blitt utløst. Det er likt en funksjon bortsett fra at Injiserer kan distribueres når som helst under øvelsens kjøretid.

injects:
  demo_inject:
    source: flag-generator

La oss også legge til Injiser til vår node slik at vi vet med hvilke roller og til hvilken VM den vil bli distribuert til:

nodes:
  wordpress-server:
    type: vm
    source: debian-12-gui-docker
    resources:
      cpu: 2
      ram: 4 GiB
    roles:
      admin:
        username: root
        entities:
          - blue-team.participant
    features:
      wordpress: admin
    conditions:
      wordpress-check-credentials: admin
    injects:
      demo_inject: admin

Hendelser (Events)

Hendelser brukes til å utløse installasjonen av Injiserer og vise tilleggsinformasjon til deltakeren. Valgfritt kan hendelser også inneholde et source-felt som refererer til en Event-type pakke som inneholder en markdown-fil som vil bli vist til deltakeren når hendelsen utløses i deres hendelsesfane.

I følgende eksempel definerer vi en betinget hendelse som kun vil bli distribuert hvis betingelsen returnerer en 1.0 verdi under hendelsens distribusjonsvindu, som vi vil definere i den kommende scripts-blokken. Det er også mulig å utelate betingelsene helt og ha hendelsen alltid distribuert når distribusjonsvinduet åpnes.

Hver hendelse er unik per distribusjon, noe som betyr:

• Betingelser og injects trenger ikke å være på samme VM.
• Hvis flere VM-er har de samme hendelsens betingelser, må de alle være i en suksess (1.0) betingelse for at hendelsen skal bli distribuert.
• Hvis flere VM-er har de samme hendelsens injects, vil de alle bli distribuert når hendelsen utløses.

events:
  example-event:
    name: Demo Event
    source: demo-event-info
    conditions:
      - wordpress-check-credentials
    injects:
      - demo_inject

For at vår deltaker skal kunne se hendelsen i deres hendelsesfane etter at den har blitt utløst, må vi legge den til entities-blokken. Hendelser definert under enheter arves til alle dens barn. I vårt eksempel, hvis vi skulle definere det under blue-team, ville det bli arvet av participant også.

entities:
  blue-team:
    role: Blue
    entities:
      participant:
        role: Blue
        tlos:
          - wordpress-credentials-tlo
        events:
          - example-event

Skript (Scripts)

Skript definerer tidsvinduet hvor hendelsene knyttet til det kan utløses. Hendelser har i tillegg et tidsfelt som indikerer når hendelsen vil bli kvalifisert til å bli utløst.

scripts:
  demo_script:
    start-time: 0
    end-time: 2h
    speed: 1
    events:
      example-event: 5m

I eksempelet ovenfor har vi satt skriptets starttid til 0 som vil starte det ved begynnelsen av distribusjonen og avslutte etter at 2 timer har gått. Hastighetsfeltet brukes til å øke eller redusere tiden hvor hendelsene kan utløses. Standardverdien er 1, noe som betyr at hendelsene vil bli utløst i samme hastighet som distribusjonstiden. En verdi på 2 vil utløse hendelsene dobbelt så raskt og en verdi på 0.5 vil utløse dem halvparten så raskt.

Hendelsenes tidsfelt brukes til å definere når hendelsen vil bli kvalifisert til å bli utløst under skriptets distribusjonsvindu. I vårt eksempel vil example-event være kvalifisert til å bli utløst etter at 5 minutter har gått siden starten av distribusjonen. Hendelsenes tidsverdi må være lik eller større enn skriptets starttid og mindre eller lik skriptets sluttid.

Fortellinger (Stories)

Fortellinger brukes til å gruppere skript sammen og i tillegg kontrollere hastigheten som skript utløses med. Som med skript, er speed-variabelen en tidsmultiplikator, å sette den til 2 vil få skriptene til å starte og avslutte dobbelt så raskt.

stories:
  demo_story:
    speed: 1
    scripts:
      - demo_script

Setter alt sammen

I dette eksempelet SDL har vi laget en enkel øvelse som distribuerer en WordPress-server og en poenggivende maskin som er koblet over en bryter. Vi har også definert en betingelse som sjekker over nettverket om WordPress-serveren fortsatt bruker sine standard usikre administrator legitimasjon og en metrikk som viser oss resultatet av den sjekken som en poengsum. Vår evaluering setter minimum poengsum terskelen til 100 prosent og vår TLO er koblet til deltaker enheten. Hvis betingelsen passerer, vil hendelsen bli utløst og inject vil bli distribuert og vår deltaker vil kunne se den i Hendelser (Events)-fanen hvis enheten deres er koblet til Ranger-brukeren av manageren.

Til slutt skal SDL-filen vår se omtrent slik ut:

name: 'My First Exercise'

stories:
  demo_story:
    speed: 1
    scripts:
      - demo_script

scripts:
  demo_script:
    start-time: 0
    end-time: 2h
    speed: 1
    events:
      example-event: 5m

events:
  example-event:
    name: Bonus Tasks
    source: demo-event-info
    conditions:
      - wordpress-check-credentials
    injects:
      - demo_inject

injects:
  demo_inject:
    source: flag-generator

conditions:
  wordpress-check-credentials:
    source: wordpress-check-credentials
    environment:
      - WP_URL=10.1.1.1:8000

features:
  wordpress:
    type: service
    source: wordpress-4-8-0-docker
  static-ip-1:
    type: service
    source: debian-ip-setter
    environment:
      - STATIC_IP=10.1.1.1/24
  static-ip-2:
    type: service
    source: debian-ip-setter
    environment:
      - STATIC_IP=10.1.1.2/24

nodes:
  wordpress-server:
    type: vm
    source: debian-12-gui-docker
    resources:
      cpu: 2
      ram: 4 GiB
    roles:
      admin:
        username: root
        entities:
          - blue-team.participant
    features:
      static-ip-1: admin
      wordpress: admin
    injects:
      demo_inject: admin

  scoring-machine:
    type: vm
    source: debian11-network-manager
    resources:
      cpu: 2
      ram: 4 GiB
    roles:
      admin: root
    features:
      static-ip-2: admin
    conditions:
      wordpress-check-credentials: admin

  switch:
    type: switch

infrastructure:
  switch: 1
  wordpress-server:
    count: 1
    links:
      - switch
  scoring-machine:
    count: 1
    links:
      - switch

metrics:
  wordpress-credentials-metric:
    type: conditional
    max-score: 100
    condition: wordpress-check-credentials

evaluations:
  wordpress-credentials-evaluation:
    min-score: 100
    metrics:
      - wordpress-credentials-metric

tlos:
  wordpress-credentials-tlo:
    evaluation: wordpress-credentials-evaluation

entities:
  blue-team:
    role: Blue
    entities:
      participant:
        role: Blue
        tlos:
          - wordpress-credentials-tlo
        events:
          - example-event