From 7616199294a5e15b27ef92f695562e3b1c4edc53 Mon Sep 17 00:00:00 2001 From: encyk Date: Mon, 30 Oct 2023 16:05:45 +0100 Subject: [PATCH 1/6] docs: translating current creators section --- creators/formatting/index.md | 41 +++++++++++ creators/index.md | 34 ++++++++++ creators/overview/index.md | 128 +++++++++++++++++++++++++++++++++++ creators/specs/index.md | 3 + en/challenge/formatting.md | 6 +- en/challenge/index.md | 2 +- index.md | 4 ++ 7 files changed, 214 insertions(+), 4 deletions(-) create mode 100644 creators/formatting/index.md create mode 100644 creators/index.md create mode 100644 creators/overview/index.md create mode 100644 creators/specs/index.md diff --git a/creators/formatting/index.md b/creators/formatting/index.md new file mode 100644 index 0000000..fc4633f --- /dev/null +++ b/creators/formatting/index.md @@ -0,0 +1,41 @@ +# Formátování popisu + +Různá pole ve [specifikaci úlohy]() umožňují využívat Markdown k formátování textu. Markdown je doporučené využívat zvláště v dlouhých textech a popisech, kde značně zvyšuje čitelnost. + + +Kromě Markdownu HAXAGON umožňuje v textech úlohy využívat další speciální funkce, jako Zástupce IP adresy nebo Asciinema přehrávač. + +## Zástupce IP adresy + +Pro vložení IP adresy běžící instance do popisu úlohy je možné použít zástupnou sekvenci ``. Ta bude po spuštění úlohy nahrazena její IP adresou, a to podle zvoleného typu připojení – veřejná IP / VPN. +Když úloha neběží, zástupce se zobrazuje jako text `[ip]`. + +## Asciinema přehrávač + +Jelikož většina našich úloh využívá terminál, může být potřeba studenty naučit a ukázat jim, jak některé příkazy používat. K tomuto účelu je možné využít Asciinema video přehrávač se záznamem terminálu. +Díky [`asciinema-ce`](https://github.com/haxagoncz/asciinema-ce) je možné použít v Markdownu vlastní HTML element ``. + +```html + +``` +Hodnota atributu `src` je id záznamu nahraného na https://asciinema.org/. Je také možné specifikovat další možnosti atributem `options` ve formátu textu s JSONem. Seznam možností je k nalezení v [oficiální dokumentaci](https://asciinema.org/docs/embedding) [anglicky]. + +## Podmíněné renderování + +Spolu se zástupcem `` může být potřeba zobrazit nějaký text až když je úloha spuštěná a má vygenerovanou IP adresu. V tu chvíli přichází na řadu podmíněné zobrazování textu: vše ve vlastním html tagu ` ` který má platnou podmínku bude zobrazenou pouze, pokud se hodnota podmínky rovná `true`. + +Aktuálně je v podmínkách možné používat pouze testování, zda má úloha IP adresu. + +```html +Toto je normální text. + + Toto se zobrazí jen když má úloha přidělenou IP adresu. + + + Toto se zobrazuje, když úloha ještě nemá IP adresu (není spuštěná). + **Před připojením na úlohu je nutné, aby byla spuštěná.** + + + Je možné použít i testování na hodnotu true pro zobrazování textu jen u spuštěné úlohy. + +``` \ No newline at end of file diff --git a/creators/index.md b/creators/index.md new file mode 100644 index 0000000..e9ede1a --- /dev/null +++ b/creators/index.md @@ -0,0 +1,34 @@ +--- + +layout: home + +hero: + name: Tvůrci + tagline: |- + Tvorba úloh + - Formátování textů + - Návrhy struktury úloh + +features: + - icon: 🔰 + link: ./overview/ + title: Přehled + details: Rozložení popisu úlohy + - icon: ⚙ + link: ./specs/ + title: Specifikace + details: Podrobné detaily k psaní úloh + - icon: ✍️ + link: ./formatting/ + title: Formátování + details: Vychytávky, které lze použít při psaní popisu + +--- + +
+
+

+ +Zde pravděpodobně ještě dojde ke změnám v rozložení stránek. + +

\ No newline at end of file diff --git a/creators/overview/index.md b/creators/overview/index.md new file mode 100644 index 0000000..1651303 --- /dev/null +++ b/creators/overview/index.md @@ -0,0 +1,128 @@ +# Specifikace úlohy + +Specifikace úlohy definuje informace o úloze: nadpis, popisek a vlajky. Je používán formát `YAML` pro svou jednoduchou čitelnost kýmkoli, i pro neznalé přesného formátu. + +## Příklad + +```yaml +title: 'Testovací úloha' + +# Krátký popisek se jednoduché shrnutí, čeho se úloha týká. +# Zobrazuje se v přehledech a dalších místech, +# kde stačí vědět pouze zhruba o čem úloha je. +shortDescription: 'This is a description, that should be kept short' + +# Teorie je vysvětlení tématu úlohy. +# Může obsahovat příběh, nápovědy a další metody jak udělat úlohu jednodušší, +# když studenti neznají teorii předem z hodin. +# Protože Teorie bývá často dlouhá, je v samostatném souboru, +# na který tento řádek odkazuje. +theory: './THEORY.md' + +# Krátký popis k úloze, který se ukazuje nad zadáním vlajek. +# Zde je možné uvést příběh pro řešení úlohy, nebo jen poskytnout základní informace, +# co bude po řešitelích požadováno. +description: './DESCRIPTION.md' + +# Příručka se částečně podobá Teorii, ale není viditelná pro studenty. +# Díky tomu většinou obsahuje krok za krokem návod k řešení úlohy, +# nebo poznámky pro učitele k vysvětlování látky. +handbook: './HANDBOOK.md' + +# Toto je seznam všech služeb, které jsou dostupné z venku úlohy. +# Služby jsou dostupné na IP adrese úlohy, +# což může být buďto veřejná IP adresa, nebo adresa ve VPN subnetu. +access: + - type: "ssh" + port: 22 + username: student + password: heslo1234 + text: | + Dodatečné informace ke způsobu připojení s možností použití markdownu + + - type: "http" + port: 80 + username: student + password: heslo1234 + text: | + Dodatečné informace ke způsobu připojení s možností použití markdownu + + - type: "vnc" + port: 5900 + username: admin + password: password + text: | + Dodatečné informace ke způsobu připojení s možností použití markdownu + + - type: "rdp" + port: 3389 + username: admin + password: password + text: | + Dodatečné informace ke způsobu připojení s možností použití markdownu + + - type: "tcp" + protocol: "minecraft" + port: 12345 + username: admin + password: password + text: | + Dodatečné informace ke způsobu připojení s možností použití markdownu + + - type: "udp" + protocol: "minecraft" + port: 12345 + username: admin + password: password + text: | + Dodatečné informace ke způsobu připojení s možností použití markdownu + + - type: "other" + text: | + Dodatečné informace ke způsobu připojení s možností použití markdownu + +# Toto je seznam všech vlajek – statických, dynamických, automatických i jiných +flags: + # Typ 2 je statická textová vlajka + - type: 2 + identifier: 'bobs-id' + answer: '1003' + maximumTries: 3 + + name: 'Jaké id má uživatel `bob`?' + + # Popis vlajky je inline markdown, který může obsahovat zástupné znaky. + # (O těch více na další stránce.) + # Je používán jako plný popis vlajky, často zmiňuje další teorii nebo informace. + description: | + V systému souborů na linuxu se v adresáři `etc` nachází soubor `passwd`. + Jsou v něm uloženy informace o uživatelích – jejich id, id primárních skupin, + domovský adresář, uživatelské jméno a shell. + + Může vypadat nějak takto: + ``` + root:x:0:0::/root:/bin/zsh + bin:x:1:1::/:/usr/bin/nologin + daemon:x:2:2::/:/usr/bin/nologin + mail:x:8:12::/var/spool/mail:/usr/bin/nologin + ftp:x:14:11::/srv/ftp:/usr/bin/nologin + http:x:33:33::/srv/http:/usr/bin/nologin + nobody:x:65534:65534:Nobody:/:/usr/bin/nologin + ``` + + Přečtěte soubor `/etc/passwd` a zjistěte id uživatele `bob`. + + # Krátký popis vlajky je shrnutí Popisu, kterým studenti mohou rychle projet + shortDescription: 'Zjistěte přečtením souboru `/etc/passwd` jaké id má uživatel `bob`.' + - type: 1 + maximumTries: 2 + identifier: 'flag.txt' + # Místo statické odpovědi se hodnota odpovědi dynamicky generuje + # uvnitř instance úlohy + placeholder: 'root-flag' + + name: 'Získejte vlajku z `/flag.txt`' + + # Dlouhý popis může být vynechán + shortDescription: 'V souboru `/flag.txt` se nachází vlajka. Přečtěte ho pro její získání.' +``` \ No newline at end of file diff --git a/creators/specs/index.md b/creators/specs/index.md new file mode 100644 index 0000000..4646769 --- /dev/null +++ b/creators/specs/index.md @@ -0,0 +1,3 @@ +::: info +Coming soon:tm: +::: \ No newline at end of file diff --git a/en/challenge/formatting.md b/en/challenge/formatting.md index 7c12a23..039729e 100644 --- a/en/challenge/formatting.md +++ b/en/challenge/formatting.md @@ -10,14 +10,14 @@ and how to use them. ## The \ placeholder The IP placeholder is very simple, every `` in the description, gets -replaced with the challenge IP once it is started, if it isn't running, the ip +replaced with the challenge IP once it is started. If the challenge isn't running, the ip block will get replaced for `[ip]` text. ## Asciinema player Since most of our challenges need you to use the terminal, it might be necessary to teach people how to use some commands. With asciinema, you can add a video player-like terminal! Thanks to [`asciinema-ce`](https://github.com/haxagoncz/asciinema-ce) you can just insert an `` element into the markup and everything else will be handled for you. -```md +```html ``` @@ -28,7 +28,7 @@ You can also define extra options with the `options` attribute. (A string with j With the \ placeholder, you might be wondering how to show your custom message when the challenge isn't running or doesn't have IP yet. That's where conditional rendering comes in, anything you put inside \ element that has a valid condition will only be shown if the condition is true. Currently you can only use that for challenge's IP. -```md +```html This is normal text This is only visible if the challenge has IP. () diff --git a/en/challenge/index.md b/en/challenge/index.md index 4dbdbbe..0745c2f 100644 --- a/en/challenge/index.md +++ b/en/challenge/index.md @@ -1,5 +1,5 @@ # Challenge specification -The challenge specification defines the information about the challenge, it's +The challenge specification defines the information about the challenge, its title, description, and even flags. The YAML format is used for challenges, as it is simply readable by anyone, even if you don't understand the format's specification. diff --git a/index.md b/index.md index f8e221f..efc4acc 100644 --- a/index.md +++ b/index.md @@ -22,5 +22,9 @@ features: link: admins/ title: Školní administrátoři details: Správa systému + - icon: 🛠 + link: creators/ + title: Tvůrci úloh + details: Formát úloh a tvorba popisu --- \ No newline at end of file From f9f5afde5289b20bce01656eaa71f9fed765a008 Mon Sep 17 00:00:00 2001 From: encyk Date: Mon, 30 Oct 2023 22:51:43 +0100 Subject: [PATCH 2/6] docs: creators: challenge and flags syntax --- creators/specs/index.md | 178 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 176 insertions(+), 2 deletions(-) diff --git a/creators/specs/index.md b/creators/specs/index.md index 4646769..231b735 100644 --- a/creators/specs/index.md +++ b/creators/specs/index.md @@ -1,3 +1,177 @@ + # Technická specifikace požadavků na úlohu spustitelnou v platformě Haxagon + + ## Základní principy fungování platformy + + Systém Haxagon zprostředkovává soutěžícím přístup k soutěžním úlohám. Automatizovaně tyto úlohy spouští a vytváří vzdálené připojení pro soutěžící. Aby byla úloha nasaditelná v systému, je nutné, aby splňovala určité technické specifikace. + + ## Technická specifikace úloh + + ### Virtualizace infrastruktury + V systému Haxagon mohou být úlohy spouštěny pomocí dvou druhů virtualizace: + - ***Vagrant*** + [Vagrant](https://www.vagrantup.com/) je nástroj pro správu virtuálních strojů, které umožňuje vytvořit, spravovat a automatizovat viruální prostředí. Je nutné použít livcrt provider pro spouštění úloh v systému Haxagon. + - ***Docker*** + [Docker-compose](https://docs.docker.com/compose/) je nástroj pro spouštění a sprácu aplikací pomocí [Docker](https://docs.docker.com/)u. Umožňuje spouštět více kontejnerů jako jeden celek a čídit je pomocí jednoho konfiguračního souboru. + +### Struktura repozitáře s úlohou +Formát plohy je velice jednoduchý - stačí systému poskytnout následující soubory v gitovém repozitáři: +- `challenge.yaml` - Soubor ve formátu YAML, který definuje základní parametry úlohy. +- potřebné zadání pro virtualizačního providera, který vytvoří infrastrukturu pro každou instanci úlohy (podle druhu virtualizace): + - `Vagrantfile` + - `docker-compose.yaml` +- `THEORY.md` - Markdown soubor s teoretickou částí úlohy, kde jsou řešiteli předávány teoretické znalosti bez vazby na obsah úlohy. +- `HANDBOOK.md` - Markdown soubor obsahující obsah, který slouží jako příručka pro učitele. +- `DESCRIPTION.md` - Krátký popis k zadání úlohy. + +Tyto soubory jsou detailněji rozebrány v následujících sekcích. + +# `challenge.yaml` + +| název parametru | popis parametru | povinný? | +|------------------|-----------------|----------| +| title | Pojmenování úlohy | ANO | +| shortDescription | Krátký popisek shrnující obsah úlohy | ANO | +| theory | Relativní cesta k Markdown souboru s teorií k úloze | NE | +| description | Relativní cesta k Markdown souboru s popisem úlohy k vlajkám | NE | +| handbook | Relativní cesta k Markdown souboru s příručkou pro učitele | NE | +| access | Pole objektů definující možnosti připojení k úloze. Více o přístupu dále. | NE | +| flags | Pole objektů definující vlajky, které budou součástí úlohy. Více o vlajkách dále. | ANO | + +## `access` + ::: info -Coming soon:tm: -::: \ No newline at end of file +TBD +::: + +## `flags` +Vlajky se dělí do celkem 5 typů. + +Všechny typy vlajek mají společné tyto parametry: + +| název parametru | popis parametru | příklad | +|-----------------|-----------------|---------| +| name | Pojmenování vlajky | Oprávnění souboru `file-1` +| description | Bližší info o úkolu. Podporuje Markdown formátování. | Změň oprávnění souboru `file-1` na 742. +| points | Bodové ohodnocení vlajky | 20 +| identifier | Unikátní (v rámci této úlohy) identifikátor vlajky | `file-perms-check1` +| type | Číslo označující druh vlajky | "4" + +## Dynamická vlajka + +Každá instance úlohy má unikátně vygenerované vlajky tak, aby se zamezilo podvádění. Jejich unikátnost je zaručena vygenerováním náhodného řetězce, kterým jsou nahrazeny všechny výskyty **placeholder**u ve všech souborech v repozitáři scénáře. Aby nedošlo k nechtěné záměně, jsou všechna místa určená k nahrazení ohraničena znaky `#@{{'{{'}}` a `}}@#`. Právě **placeholder** slouží autorovi úlohy k označení a odlišení jednotlivých míst. + +Při zpuštění se tedy z `#@{{'{{'}}vlajka1}}@#` stane např. `haxagon{897316929176464ebc9ad085f31e7284}` a v jiné instanci úlohy s úplně stejným scénářem zase `haxagon{99bd2e29f6b569bb880f601815cd77ef}`. + +::: warning POZOR +K nahrazení řetězců dochází až v runtime instance. To znamená, že nahrazení probíhá těsně před tím, než systém zavolá `docker compose up`. + +Je potřeba rozdělit `build` fázi kontejnerů a jejich `runtime` fázi. Například tento kód v souboru Dockerfile některého z kontejnerů úlohy (`RUN echo #@{{'{{'}}vlajka1}}@# > /tmp/test`) nesplní očekávání, protože příkaz `RUN` v Dockerfile je spouštěn při sestavování (`build`) obrazů kontejnerů. + +Pro zpřístupnění dynamické vlajky v `runtime` fázi kontejneru je potřeba vytvořit složku, v ní vytvořit soubor s **placeholder**em a tu složkou připojit (`mount`) pomocí `volumes` definice v docker compose. +::: + +Specifika pro vlajky tohoto typu: + +| název parametru | popis parametru | příklad | +|-----------------|-----------------|---------| +| type | 1, označuje tento typ vlajky | 1 | +| placeholder | Zástupný řetězec znaků sloužící pro označení místa, do kterého se vloží unikátní vlajka | flag2 | +| maximumTries | Maximální možný počet pokusů pro odpověď | 3 | + + +## Statická vlajka + +Tento druh vlajky mám pro všechny uživatele a ve všech instancích stejnou hodnotu. + +Specifika pro vlajky tohoto typu: + +| název parametru | popis parametru | příklad | +|-----------------|-----------------|---------| +| type | 2, označuje tento typ vlajky | 2 | +| answer | Odpověď na úkol | flag{{'{'}}1234} | +| maximumTries | Maximální možný počet pokusů pro odpověď | 3 | + + +## Vlajka s možností výběru odpovědi + +Specifika pro vlajky tohoto typu: + +| název parametru | popis parametru | příklad | +|-----------------|-----------------|---------| +| type | 3, označuje tento typ vlajky | 3 | +| maximumTries | Maximální možný počet pokusů pro odpověď | 3 | +| options | Pole objektů možných odpovědí | viz níže | + +Objekty odpovědí mají tuto strukturu: +```yaml +- value: "chybná odpověď" + correct: false # nebo true pro správnou odpověď +``` + + +## Automaticky vyhodnocující se vlajka + +Pomocí `docker compose exec` se v definovaném **interval**u spouští definovaný příkaz **command** a podle návratové hodnoty **exitCode** procesu se určí, zda byla vlajka splněna. Možnost **container** určuje, ve kterém z možných kontejnerů se proces spustí. + +| název parametru | popis parametru | příklad | +|-----------------|-----------------|---------| +| type | 4, označuje tento typ vlajky | 4 | +| command | Příkaz, který se spustí pro ověření splění úkolu | `bash -c '[ "$(cat /tmp/test.txt)" == "ahoj" ]'` | +| container | Cílový kontejner, ve kterém se příkaz bude spouštět | server | +| shell | Shell, ve kterém je příkaz spouštěn | sh | +| user | Uživatel, pod kterým se příkaz spouští | root | +| interval | Interval, ve kterém dochází ke spuštění příkazu | 2000 | +| exitCode | Návratový kód **command**u, který bude považován za úspěch pro splnění vlajky | 0 | + +## Ukázkový soubor `challenge.yaml` + +```yaml +title: Ukázková úloha + +# relativní cesta k souboru obsahující teorii k látce v úloze +theory: './THEORY.md' + +# relativní cesta k souboru obsahující popis k řešení vlajek +description: ./DESCRIPTION.md + +# relativní cesta k souboru obsahující učitelskou příručku k úloze +handbook: ./HANDBOOK.md + +# vlajky, ktere jsou s ulohou spojeny +flags: + - name: Obsah souboru /tmp/file1 + description: + points: 10 + type: "1" + identifier: "file-content-1" + placeholder: flag1 + maximumTries: 3 + - name: Heslo uživatele adam + description: Najdi způsob, jak získat heslo uživatele `adam` v plaintextu. + points: 20 + type: "2" + identifier: "password-dump1" + answer: flag{adamisbest} + maximumTries: 2 + - name: Vyber správnou odpověď + description: + points: 30 + type: "3" + identifier: "choice-flag1" + maximumTries: 2 + options: + - value: správná odpověd + correct: true + - value: chybná odpověd + correct: false + - name: /tmp/test.txt + description: Do souboru /tmp/test.txt zapiš text "ahoj". + points: 30 + type: "4" + identifier: "file-content-check1" + command: "`bash -c '[ "$(cat /tmp/test.txt)" == "ahoj" ]'`" + interval: 1000 + container: "server" + exitCode: 0 +``` + From 074d0da822f7462ef2d7b5aed08a7a38fd8de55d Mon Sep 17 00:00:00 2001 From: encyk Date: Mon, 30 Oct 2023 23:18:49 +0100 Subject: [PATCH 3/6] docs: creators: rewrote haxagoncz/challenge-guide --- creators/specs/index.md | 115 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) diff --git a/creators/specs/index.md b/creators/specs/index.md index 231b735..620267c 100644 --- a/creators/specs/index.md +++ b/creators/specs/index.md @@ -41,6 +41,7 @@ Tyto soubory jsou detailněji rozebrány v následujících sekcích. ::: info TBD + ::: ## `flags` @@ -175,3 +176,117 @@ flags: exitCode: 0 ``` +--- +
+ +# `docker-compose.yaml` + +Tímto souborem jsme schopni definovat, jaká infrastruktura se pro úlohu spustí. Dokumentace formátu je dostupná na [https://docs.docker.com/compose/](https://docs.docker.com/compose/). + +## Limity +V souboru docker-compose není možné +- Eskalovat práva kontejneru + - Vytvářet privilegované kontejnery + - Přidávat kontejnerům systémové schopnosti (SYStem capabilities) +- Mountovat adresáře a soubory (vše potřebné by mělo být do kontejneru přidáno v build fázi) + +## Signalizace úspěšného nastartování scénáře + +Je nutné systém informovat o tom, že je scénář spuštěný a vše je připaveno. Tuto informaci je možné systému sdělit tím, že do `stdout` entrypointu/commandu libovolného commandu definovaného v docker-compose souboru vypíšete řetězec `SCENARIO_IS_READY`. + +## Ukázkový docker-compose.yml +```yaml +version: "3" + +services: + webserver: + image: nonbusybox + container_name: webserver + command: sh -c '/setup.sh && echo SCENARIO_IS_READY && sleep infinity' + ports: + - "80:80" +``` + +--- +
+ +# `Vagrantfile` + +Vagrantfile je konfigurační soubor pro [Vagrant](https://www.vagrantup.com/), který se používá k nastavení virtuálního prostředí pro vaši úlohu. Tento soubor by měl být umístěn ve stejné složce jako `challenge.yaml`. + +## Obsah Vagrantfile + +Ve `Vagrantfile` může být nastaveno např.: +- Image operačního systému, který se má použít pro virtuální stroj (např. **Ubuntu**, nebo **CentOS**) +- Konfigurace sítě pro virtuální stroj +- Provisioning +- Omezení prostředků (RAM, CPU, růzené IO atp.) + +## Příklad `Vagrantfile` +```ruby +# -*- mode: ruby -*- +# vi: set ft=ruby : + +Vagrant.configure("2") do |config| + + # Nastavení libvirt provider + config.vm.provider :libvirt do |libvirt| + libvirt.driver = "kvm" + end + + # Nastavení obrazu operačního systému pro virtuální stroj + config.vm.box = "ubuntu/focal64" + + # Konfigurace privátní sítě pro virtuální stroj + config.vm.network "private_network", ip: "192.168.33.10" + + # Nastavení RAM a CPU pro virtuální stroj + config.vm.provider "libvirt" do |vb| + vb.memory = "512" + vb.cpus = 1 + end + + # Konfigurace shell provisioningu + config.vm.provision "shell" do |s| + s.inline = <<-SHELL + apt-get update + apt-get install -y apache2 + echo SCENARIO_IS_READY + SHELL + s.env = { + "VARIABLE_NAME" => "value" + } + end +end +``` + +# `THEORY.md` +Zde jsou předávány teoretické znalosti bez vazby na obsah úlohy. +::: info +TBD + +::: +# `DESCRIPTION.md` + +# `HANDBOOK.md` +::: info +TBD + +::: + +# Další konvence pro tvorbu zadání +## Technické informace a kód +Části textu obsahující nejakou technickou informaci, např.: +- definici subnetu - `192.168.40.0/24` +- příkazy - `find --name file` +- parametr - `--sevice-scan` +a podobné zaobalíme do code highlight bloku pomocí znaku \` + +Pokud vkládáme delší kód (např. snippet v bashi, nebo jiném programovacím jazyce), zaobalíme ho do víceřádkového code bloku se zvýrazňováním syntaxe: +\`\`\`jazyk +// kód +\`\`\` +Jméno programovacího jazyka se vloží za první tři zpětné apostrofy, místo slova `jazyk`. + + + From b2643a22c9e882de5866ee96a8bcd246bc063910 Mon Sep 17 00:00:00 2001 From: encyk Date: Tue, 7 Nov 2023 20:01:22 +0100 Subject: [PATCH 4/6] docs: remove mentions of Vagrant and small fixes --- creators/index.md | 8 ---- creators/specs/index.md | 90 +++++++++++++++++++++++------------------ index.md | 8 ++-- 3 files changed, 54 insertions(+), 52 deletions(-) diff --git a/creators/index.md b/creators/index.md index e9ede1a..f67afe3 100644 --- a/creators/index.md +++ b/creators/index.md @@ -24,11 +24,3 @@ features: details: Vychytávky, které lze použít při psaní popisu --- - -
-
-

- -Zde pravděpodobně ještě dojde ke změnám v rozložení stránek. - -

\ No newline at end of file diff --git a/creators/specs/index.md b/creators/specs/index.md index 620267c..2460ec1 100644 --- a/creators/specs/index.md +++ b/creators/specs/index.md @@ -7,18 +7,22 @@ ## Technická specifikace úloh ### Virtualizace infrastruktury + +V systému Haxagon jsou úlohy spouštěny virtualizací v **Dockeru**. +[Docker-compose](https://docs.docker.com/compose/) je nástroj pro spouštění a správu aplikací pomocí [Docker](https://docs.docker.com/)u. Umožňuje spouštět více kontejnerů jako jeden celek a řídit je pomocí jednoho konfiguračního souboru. ### Struktura repozitáře s úlohou -Formát plohy je velice jednoduchý - stačí systému poskytnout následující soubory v gitovém repozitáři: +Formát úlohy je velice jednoduchý – stačí systému poskytnout následující soubory v gitovém repozitáři: - `challenge.yaml` - Soubor ve formátu YAML, který definuje základní parametry úlohy. -- potřebné zadání pro virtualizačního providera, který vytvoří infrastrukturu pro každou instanci úlohy (podle druhu virtualizace): + +- `docker-compose.yaml` / `docker-compose.yml` - Instrukce pro sestavení kontejneru(ů) úlohy, viz [Docker dokumentace](https://docs.docker.com/compose/). - `THEORY.md` - Markdown soubor s teoretickou částí úlohy, kde jsou řešiteli předávány teoretické znalosti bez vazby na obsah úlohy. - `HANDBOOK.md` - Markdown soubor obsahující obsah, který slouží jako příručka pro učitele. - `DESCRIPTION.md` - Krátký popis k zadání úlohy. @@ -32,9 +36,9 @@ Tyto soubory jsou detailněji rozebrány v následujících sekcích. | title | Pojmenování úlohy | ANO | | shortDescription | Krátký popisek shrnující obsah úlohy | ANO | | theory | Relativní cesta k Markdown souboru s teorií k úloze | NE | -| description | Relativní cesta k Markdown souboru s popisem úlohy k vlajkám | NE | +| description | Relativní cesta k Markdown souboru s popisem k vlajkám | NE | | handbook | Relativní cesta k Markdown souboru s příručkou pro učitele | NE | -| access | Pole objektů definující možnosti připojení k úloze. Více o přístupu dále. | NE | +| access | Pole objektů definující možnosti připojení k úloze. Více o přístupu dále. | ANO | | flags | Pole objektů definující vlajky, které budou součástí úlohy. Více o vlajkách dále. | ANO | ## `access` @@ -51,13 +55,13 @@ Všechny typy vlajek mají společné tyto parametry: | název parametru | popis parametru | příklad | |-----------------|-----------------|---------| -| name | Pojmenování vlajky | Oprávnění souboru `file-1` -| description | Bližší info o úkolu. Podporuje Markdown formátování. | Změň oprávnění souboru `file-1` na 742. -| points | Bodové ohodnocení vlajky | 20 -| identifier | Unikátní (v rámci této úlohy) identifikátor vlajky | `file-perms-check1` -| type | Číslo označující druh vlajky | "4" +| name | Pojmenování vlajky | Oprávnění souboru `file-1` +| description | Bližší informace o úkolu. Podporuje Markdown formátování. | Změň oprávnění souboru `file-1` na 742. +| points | Bodové ohodnocení vlajky | 20 +| identifier | Unikátní (v rámci této úlohy) identifikátor vlajky | `file-perms-check1` +| type | Číslo označující druh vlajky
Je nutné uvést `type` jako `string` v uvozovkách! | "4" -## Dynamická vlajka +### Dynamická vlajka Každá instance úlohy má unikátně vygenerované vlajky tak, aby se zamezilo podvádění. Jejich unikátnost je zaručena vygenerováním náhodného řetězce, kterým jsou nahrazeny všechny výskyty **placeholder**u ve všech souborech v repozitáři scénáře. Aby nedošlo k nechtěné záměně, jsou všechna místa určená k nahrazení ohraničena znaky `#@{{'{{'}}` a `}}@#`. Právě **placeholder** slouží autorovi úlohy k označení a odlišení jednotlivých míst. @@ -75,12 +79,12 @@ Specifika pro vlajky tohoto typu: | název parametru | popis parametru | příklad | |-----------------|-----------------|---------| -| type | 1, označuje tento typ vlajky | 1 | +| type | "1", označuje tento typ vlajky | "1" | | placeholder | Zástupný řetězec znaků sloužící pro označení místa, do kterého se vloží unikátní vlajka | flag2 | | maximumTries | Maximální možný počet pokusů pro odpověď | 3 | -## Statická vlajka +### Statická vlajka Tento druh vlajky mám pro všechny uživatele a ve všech instancích stejnou hodnotu. @@ -88,18 +92,18 @@ Specifika pro vlajky tohoto typu: | název parametru | popis parametru | příklad | |-----------------|-----------------|---------| -| type | 2, označuje tento typ vlajky | 2 | +| type | "2", označuje tento typ vlajky | "2" | | answer | Odpověď na úkol | flag{{'{'}}1234} | | maximumTries | Maximální možný počet pokusů pro odpověď | 3 | -## Vlajka s možností výběru odpovědi +### Vlajka s možností výběru odpovědi Specifika pro vlajky tohoto typu: | název parametru | popis parametru | příklad | |-----------------|-----------------|---------| -| type | 3, označuje tento typ vlajky | 3 | +| type | "3", označuje tento typ vlajky | "3" | | maximumTries | Maximální možný počet pokusů pro odpověď | 3 | | options | Pole objektů možných odpovědí | viz níže | @@ -110,20 +114,24 @@ Objekty odpovědí mají tuto strukturu: ``` -## Automaticky vyhodnocující se vlajka +### Automaticky vyhodnocující se vlajka Pomocí `docker compose exec` se v definovaném **interval**u spouští definovaný příkaz **command** a podle návratové hodnoty **exitCode** procesu se určí, zda byla vlajka splněna. Možnost **container** určuje, ve kterém z možných kontejnerů se proces spustí. | název parametru | popis parametru | příklad | |-----------------|-----------------|---------| -| type | 4, označuje tento typ vlajky | 4 | -| command | Příkaz, který se spustí pro ověření splění úkolu | `bash -c '[ "$(cat /tmp/test.txt)" == "ahoj" ]'` | +| type | "4", označuje tento typ vlajky | "4" | +| command | Příkaz, který se spustí pro ověření splnění úkolu | `bash -c '[ "$(cat /tmp/test.txt)" == "ahoj" ]'` | | container | Cílový kontejner, ve kterém se příkaz bude spouštět | server | | shell | Shell, ve kterém je příkaz spouštěn | sh | | user | Uživatel, pod kterým se příkaz spouští | root | | interval | Interval, ve kterém dochází ke spuštění příkazu | 2000 | | exitCode | Návratový kód **command**u, který bude považován za úspěch pro splnění vlajky | 0 | +Parametr `interval` je měřen v milisekundách. + +Pokud bude jako hodnota `interval`u uvedena 0, `command` nebude prováděn automaticky, ale v zadání úlohy se objeví tlačítko, kterým si ho řešitelé mohou spustit manuálně. Toto je vhodné pro náročné příkazy, jejichž vyhodnocení trvá dlouho nebo vyžaduje hodně prostředků. + ## Ukázkový soubor `challenge.yaml` ```yaml @@ -161,9 +169,9 @@ flags: identifier: "choice-flag1" maximumTries: 2 options: - - value: správná odpověd + - value: správná odpověď correct: true - - value: chybná odpověd + - value: chybná odpověď correct: false - name: /tmp/test.txt description: Do souboru /tmp/test.txt zapiš text "ahoj". @@ -187,12 +195,12 @@ Tímto souborem jsme schopni definovat, jaká infrastruktura se pro úlohu spust V souboru docker-compose není možné - Eskalovat práva kontejneru - Vytvářet privilegované kontejnery - - Přidávat kontejnerům systémové schopnosti (SYStem capabilities) + - Přidávat kontejnerům systémové schopnosti (system capabilities) - Mountovat adresáře a soubory (vše potřebné by mělo být do kontejneru přidáno v build fázi) ## Signalizace úspěšného nastartování scénáře -Je nutné systém informovat o tom, že je scénář spuštěný a vše je připaveno. Tuto informaci je možné systému sdělit tím, že do `stdout` entrypointu/commandu libovolného commandu definovaného v docker-compose souboru vypíšete řetězec `SCENARIO_IS_READY`. +Je nutné systém informovat o tom, že je scénář spuštěný a vše je připraveno. Tuto informaci je možné systému sdělit tím, že do `stdout` entrypointu/commandu libovolného commandu definovaného v docker-compose souboru vypíšete řetězec `SCENARIO_IS_READY`. ## Ukázkový docker-compose.yml ```yaml @@ -210,7 +218,7 @@ services: ---
-# `Vagrantfile` + + + # `THEORY.md` Zde jsou předávány teoretické znalosti bez vazby na obsah úlohy. -::: info -TBD - -::: + +Je *důrazně* doporučeno používat správné Markdown formátování pro zvýšení přehlednosti. + # `DESCRIPTION.md` +Úvod k řešení vlajek. Často zde bývá zopakování příběhu úlohy (pokud nějaký je), nebo poznámka o speciálních nestandardních nástrojích, které je možné při řešení využít. + # `HANDBOOK.md` -::: info -TBD - -::: +Do Příručky patří návod k vyřešení celé úlohy, je viditelná pouze pro učitele. + +Také je možné uvést poznámky pro učitele, jak dobře vysvětlit danou látku či na co poukázat. + +
# Další konvence pro tvorbu zadání ## Technické informace a kód -Části textu obsahující nejakou technickou informaci, např.: +Části textu obsahující nějakou technickou informaci, např.: - definici subnetu - `192.168.40.0/24` - příkazy - `find --name file` - parametr - `--sevice-scan` @@ -286,7 +298,5 @@ Pokud vkládáme delší kód (např. snippet v bashi, nebo jiném programovací \`\`\`jazyk // kód \`\`\` -Jméno programovacího jazyka se vloží za první tři zpětné apostrofy, místo slova `jazyk`. - - - +Jméno programovacího jazyka se vloží za první tři zpětné apostrofy, místo slova `jazyk`. +Kompletní seznam podporovaných jazyků na zvýraznění syntaxe je [zde](https://highlightjs.readthedocs.io/en/latest/supported-languages.html). diff --git a/index.md b/index.md index efc4acc..5806b04 100644 --- a/index.md +++ b/index.md @@ -18,10 +18,10 @@ features: link: teachers/ title: Učitelé details: Zadávání a vyhodnocování úloh - - icon: 🛡️ - link: admins/ - title: Školní administrátoři - details: Správa systému + # - icon: 🛡️ + # link: admins/ + # title: Školní administrátoři + # details: Správa systému - icon: 🛠 link: creators/ title: Tvůrci úloh From 5896b5c3f913f7da88113bd2453f6dbd110853f1 Mon Sep 17 00:00:00 2001 From: encyk Date: Tue, 7 Nov 2023 20:07:51 +0100 Subject: [PATCH 5/6] docs: creators: add info about challenge access --- creators/specs/index.md | 38 ++++++++++++++++++++++++++++++++++---- 1 file changed, 34 insertions(+), 4 deletions(-) diff --git a/creators/specs/index.md b/creators/specs/index.md index 2460ec1..8071854 100644 --- a/creators/specs/index.md +++ b/creators/specs/index.md @@ -43,10 +43,28 @@ Tyto soubory jsou detailněji rozebrány v následujících sekcích. ## `access` -::: info -TBD - -::: +Základní formát objektů přístupu je tento: +| název parametru | popis parametru | příklad | +|-----------------|-----------------|---------| +| type | Typ připojení, viz dále. | "ssh" | +| port | Port, na který se mají řešitelé připojit. | 22 | +| username | Uživatelské jméno použité pro připojení. | student | +| password | Heslo použité v páru s uživatelským jménem. | heslo1234 | +| text | Nepovinný text s dodatečnými informacemi. | "Formátovaný \*text\*" | + +V parametru `type` je možné použít jednu z těchto hodnot: +- ssh +- http +- vnc +- rdp +- tcp +- udp +- other + +U typu připojení `other` není povinné uvádět parametry `port`, `username` a `password`, většinou je ale naopak velmi využíván parametr `text` k vysvětlení nestandardního připojení. + +Parametr `text` umožňuje využití Markdownu k formátování. Fungování víceřádkových textů v YAML je hezky vysvětleno na stránce [YAML-multiline.info](https://yaml-multiline.info/). + ## `flags` Vlajky se dělí do celkem 5 typů. @@ -146,6 +164,18 @@ description: ./DESCRIPTION.md # relativní cesta k souboru obsahující učitelskou příručku k úloze handbook: ./HANDBOOK.md +# informace o možnostech připojení na úlohu +access: + - type: "ssh" + port: 22 + username: student + password: heslo1234 + + - type: "http" + port: 80 + username: student + password: heslo1234 + # vlajky, ktere jsou s ulohou spojeny flags: - name: Obsah souboru /tmp/file1 From 2b535588abf0e5b8792e126b827aac53622bc50c Mon Sep 17 00:00:00 2001 From: 3ncy <53367954+3ncy@users.noreply.github.com> Date: Sat, 11 Nov 2023 01:11:13 +0100 Subject: [PATCH 6/6] docs: fix missing link --- creators/formatting/index.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/creators/formatting/index.md b/creators/formatting/index.md index fc4633f..3b093f2 100644 --- a/creators/formatting/index.md +++ b/creators/formatting/index.md @@ -1,7 +1,6 @@ # Formátování popisu -Různá pole ve [specifikaci úlohy]() umožňují využívat Markdown k formátování textu. Markdown je doporučené využívat zvláště v dlouhých textech a popisech, kde značně zvyšuje čitelnost. - +Různá pole ve [specifikaci úlohy](../overview/index.md) umožňují využívat Markdown k formátování textu. Markdown je doporučené využívat zvláště v dlouhých textech a popisech, kde značně zvyšuje čitelnost. Kromě Markdownu HAXAGON umožňuje v textech úlohy využívat další speciální funkce, jako Zástupce IP adresy nebo Asciinema přehrávač. @@ -38,4 +37,4 @@ Toto je normální text. Je možné použít i testování na hodnotu true pro zobrazování textu jen u spuštěné úlohy. -``` \ No newline at end of file +```