docs: review 05-2025 (#626)

Author: pandatix

webdocs/_index.md

@@ -3,9 +3,9 @@ title: Chall-Manager
 description: Chall-Manager solves the Challenge Instances on Demand problem through a future-proof generalization. It can deploy anything, anywhere, at any time !
 ---
 
-{{% alert title="Warning" color="warning" %}}
+{{< alert title="Warning" color="warning" >}}
 Currently entering public beta phase, for any issue: ctfer-io@protonmail.com 
-{{% /alert %}}
+{{< /alert >}}
 
 Chall-Manager is a MicroService whose goal is to manage challenges and their instances.
 Each of those instances are self-operated by the source (either team or user) which rebalance the concerns to empowers them.

webdocs/challmaker-guides/create-scenario/index.md

@@ -127,7 +127,10 @@ pulumi up         # preview and deploy
 ## Pack it up !
 
 Now that your scenario is designed and coded accordingly to your artistic direction, you have to prepare it for an OCI registry such that Chall-Manager can process it.
-Make sure to remove all unnecessary files, and pack the directory it is contained within.
+Make sure to remove all unnecessary files, such that the scenario is mimimal.
+
+A scenario is an OCI blob that is delivered through an OCI registry (e.g. [Docker Registry](https://hub.docker.com/_/registry), [Zot](https://github.com/project-zot/zot), [Artifactory](https://github.com/project-zot/zot)). To ease the creation and distribution of a scenario we will use `chall-manager-cli`.
+It will pack the files of a `directory` inside an OCI blob of data with annotation `application/vnd.ctfer-io.file`, and push it in the registry.
 
 ```bash
 cd ..
@@ -138,16 +141,17 @@ oras push \
 	$(find scenario -type f)
 ```
 
+Authentication is optional yet recommended. The same holds for certificate validation that could be turned off with `--insecure`.
+
 And you're done. Yes, it was that easy :)
 
 But it could be even more [using the SDK](/docs/chall-manager/challmaker-guides/software-development-kit) !
 
 {{< alert title="Tips & Tricks" color="primary" >}}
 You don't need to archive all files.
 
-If you don't pre-compiled your [scenario](/docs/chall-manager/glossary#scenario), you need to archive all source files.
-
-If you prebuilt the [scenario](/docs/chall-manager/glossary#scenario), you'll only need to pack the `main` binary and `Pulumi.yaml` file.
+If you prebuild the [scenario](/docs/chall-manager/glossary#scenario), you'll only need to pack the `main` binary and `Pulumi.yaml` files.
+It should make chall-manager run with better in production, and reduce supply chain risks as the binary won't be re-compiled.
 {{< /alert >}}
 
 ## Use an additional configuration
@@ -188,7 +192,7 @@ func main() {
 		// ...
 
 		// 3. Return content as always
-		resp.ConnectionInfo = pulumi.String(string(b)).ToStringOutput()
+		resp.ConnectionInfo = pulumi.Sprintf("Running %s for %s", image, cidr)
 		return nil
 	})
 }

webdocs/challmaker-guides/flag-variation-engine.md

@@ -5,32 +5,33 @@ categories: [How-to Guides]
 tags: [Anticheat]
 ---
 
-Shareflag is considered by some as the worst part of competitions leading to unfair events, while some others consider this a strategy.
-We consider this a problem we could solve.
+Shareflag is widely frowned upon by participants, as it undermines the spirit of fair play and learning.
+It not only skews the scoreboard but also devalues the hard work of those who solve challenges independently. This behavior creates frustration among honest teams and can diminish the overall experience, turning the event into a disheartening one.
+
+Nevertheless, Chall-Manager enables you to **solve shareflag**.
 
 ## Context
 
-In "standard" CTFs as we could most see them, it is impossible to solve this problem: if everyone has the same binary to reverse-engineer, how can you differentiate the flag per each team thus avoid shareflag ?
+In common CTFs, a challenge has a flag that must be found by players in order to claim the points. But it implies that everyone has been provided the same content, e.g. the same binary to reverse-engineer.
+With such approach, how can you differentiate the flag per each team thus detect -if not avoid- shareflag ?
 
-For this, you have to variate the flag for each source. One simple solution is to [use the SDK](#use-the-sdk).
+A perfect solution would be to have a flag for each source. One simple solution is to [use the SDK](#use-the-sdk).
 
 ## Use the SDK
 
-The SDK can variate a given input with human-readable equivalent characters in the ASCII-extended charset, making it handleable for CTF platforms (at least we expect it). If one character is out of those ASCII-character, it will be untouched.
-
-To import this part of the SDK, execute the following.
+The SDK can **variate** a given input with human-readable equivalent characters in the ASCII-extended charset, making it handleable for CTF platforms (or at least we expect so). If one character is out of those ASCII-character, it will remain unchanged.
 
-```bash
-go get github.com/ctfer-io/chall-manager/sdk
-```
-
-Then, in your scenario, you can create a constant that contains the "base flag" (i.e. the unvariated flag).
+In your scenario, you can create a constant that contains the original flag.
 
 ```go
 const flag = "my-supper-flag"
 ```
 
-Finally, you can export the variated flag.
+Then, you can simply pass it to the SDK to variate it. It will use the identity of the instance as the PRNG seed, thus you should avoid passing it to the players.
+
+If you want to use decorator around the flag (e.g. `BREFCTF{}`), don't put it in the `flag` constant else it will be variated.
+
+A complete example follows.
 
 {{< tabpane code=true >}}
 {{< tab header="SDK" lang="go" >}}
@@ -85,5 +86,3 @@ func main() {
 }
 {{< /tab >}}
 {{< /tabpane >}}
-
-If you want to use decorator around the flag (e.g. `BREFCTF{}`), don't put it in the `flag` constant else it will be variated.

webdocs/challmaker-guides/software-development-kit/index.md

@@ -6,7 +6,7 @@ tags: [SDK, Kubernetes]
 ---
 
 When you (a ChallMaker) want to deploy a single container specific for each [source](/docs/chall-manager/glossary#source), you don't want to understand how to deploy it to a specific provider. In fact, your technical expertise does not imply you are a Cloud expert... And it was not to expect !
-Writing a 500-lines long [scenario](/docs/chall-manager/glossary#scenario) fitting the API only to deploy a container is a tedious job you don't want to do more than once: create a deployment, the service, possibly the ingress, have a configuration and secrets to handle...
+Writing a 500-lines long [scenario](/docs/chall-manager/glossary#scenario) fitting the API only to deploy a container in a hardened environment is a tedious job you don't have time for.
 
 For this reason, we built a Software Development Kit to ease your use of chall-manager.
 It contains all the features of the chall-manager without passing you the issues of API compliance.
@@ -15,39 +15,38 @@ Additionnaly, we prepared some common use-cases factory to help you _focus on yo
 - [Kubernetes ExposedMonopod](#kubernetes-exposedmonopod)
 - [Kubernetes ExposedMultipod](#kubernetes-exposedmultipod)
 
-The community is free to create new pre-made recipes, and we welcome contributions to add new official ones. Please open an issue as a Request For Comments, and a Pull Request if possible to propose an implementation.
+The community is **free to create and distribute new (or alternatives) pre-made recipes**, and we welcome contributions to add new official ones. Please open an issue as a Request For Comments, and a Pull Request if possible to propose an implementation.
 
 ## Build scenarios
 
-Fitting the chall-manager scenario API imply fitting inputs and outputs models.
-
-Even if easy, it still requires work, and functionalities or evolutions does not guarantee you easy maintenance: offline compatibility with OCI registry, pre-configured providers, etc.
-
-Indeed, if you are dealing with a chall-manager deployed in a Kubernetes cluster, the `...pulumi.ResourceOption` contains a pre-configured provider such that every Kubernetes resources the scenario will create, they will be deployed in the proper namespace.
+The common API for chall-manager scenario is very simple, defined per inputs and outputs.
+They could be respectively fetched from the stack configuration and exported through stack outputs.
 
 ### Inputs
 
-Those are fetchable from the Pulumi configuration.
-
 | Name | Required | Description |
 |---|:---:|---|
-| `identity` | ✅ | the [identity](/docs/chall-manager/glossary#identity) of the Challenge on Demand request |
+| `identity` | ✅ | The [identity](/docs/chall-manager/glossary#identity) of the Challenge on Demand request. |
 
 ### Outputs
 
-Those should be exported from the Pulumi context.
-
 | Name | Required | Description |
 |---|:---:|---|
-| `connection_info` | ✅ | the connection information, as a string (e.g. `curl http://a4...d6.my-ctf.lan`) |
-| `flag` | ❌ | the identity-specific flag the CTF platform should only validate for the given [source](/docs/chall-manager/glossary#source) |
+| `connection_info` | ✅ | The connection information, as a string (e.g. `curl http://a4...d6.my-ctf.lan`) |
+| `flag` | ❌ | The identity-specific flag the CTF platform should only validate for the given [source](/docs/chall-manager/glossary#source) |
 
 ## Kubernetes ExposedMonopod
 
-When you want to deploy a challenge composed of a single container, on a Kubernetes cluster, you want it to be fast and easy.
+**Fit:** deploy a single container on a Kubernetes cluster.
 
-Then, the Kubernetes `ExposedMonopod` fits your needs ! You can easily configure the container you are looking for and deploy it to production in the next seconds.
-The following shows you how easy it is to write a scenario that creates a Deployment with a single replica of a container, exposes a port through a service, then build the ingress specific to the [identity](/docs/chall-manager/glossary#identity) and finally provide the connection information as a `curl` command.
+The `kubernetes.ExposedMonopod` helps you deploy it as a single Pod in a Deployment, expose it with 1 Service per port and if requested 1 Ingress per port.
+
+{{< imgproc kubernetes-exposedmonopod Fit "800x800" >}}
+The Kubernetes ExposedMonopod architecture for deployed resources.
+{{< /imgproc >}}
+
+The following is an example from the [24h IUT 2023](https://github.com/pandatix/24hiut-2023-cyber) usage of this SDK resource such that it deploys the Docker image `pandatix/license-lvl1:latest`, and expose port `8080` (implicitely using TCP) through an ingress. The result is used to create the connection information i.e. a `curl` example command.
+For more info on configuration, please refer to the [code base](https://github.com/ctfer-io/chall-manager/blob/main/sdk/kubernetes/exposed-monopod.go).
 
 {{< card code=true header="`main.go`" lang="go" >}}
 package main
@@ -87,18 +86,17 @@ func main() {
 To use ingresses, make sure your Kubernetes cluster can deal with them: have an ingress controller (e.g. [Traefik](https://traefik.io/)), and DNS resolution points to the Kubernetes cluster.
 {{< /alert >}}
 
-{{< imgproc kubernetes-exposedmonopod Fit "800x800" >}}
-The Kubernetes ExposedMonopod architecture for deployed resources.
-{{< /imgproc >}}
+## Kubernetes ExposedMultipod
 
-<!-- TODO provide ExposedMonopod configuration (attributes, required/optional, type, description) -->
+**Fit:** deploy a network of containers on a Kubernetes cluster.
 
-## Kubernetes ExposedMultipod
+The Kubernetes `ExposedMultipod` helps you deploy many pods with as many deployments, services for each port of each container, ingress whenever required. It is a generalization of the [Kubernetes ExposedMonopod](#kubernetes-exposedmonopod).
 
-When you want to deploy multiple containers together (e.g. a web app with a frontend, a backend, a database and a cache), on a Kubernetes cluster, and want it to be fast and easy.
+{{< imgproc kubernetes-exposedmultipod Fit "800x800" >}}
+The Kubernetes ExposedMultipod architecture for deployed resources.
+{{< /imgproc >}}
 
-Then, the Kubernetes `ExposedMultipod` fits your needs ! Your can easily configure the containers and the networking rules between them so it deploys to production in the next seconds.
-The following shows you how easy it is to write a scenario that creates multiple deployments, services, ingresses, configmaps, ... and provide the connection information as a `curl` command.
+The following is an example from the [NoBrackets 2024](https://github.com/nobrackets-ctf/NoBrackets-2024) usage of this SDK resource such that it deploys the web _vip-only_ challenge from [Drahoxx](https://x.com/50mgDrahoxx). It is composed of a NodeJS service and a MongoDB. The first is exposed through an ingress, while the other remains internal. The single rule enables traffic from the first to the second on port `27017` (implicitely using TCP).
 
 {{< card code=true header="`main.go`" lang="go" >}}
 package main
@@ -157,9 +155,3 @@ func main() {
 {{< alert title="Requirements" color="warning" >}}
 To use ingresses, make sure your Kubernetes cluster can deal with them: have an ingress controller (e.g. [Traefik](https://traefik.io/)), and DNS resolution points to the Kubernetes cluster.
 {{< /alert >}}
-
-{{< imgproc kubernetes-exposedmultipod Fit "800x800" >}}
-The Kubernetes ExposedMultipod architecture for deployed resources.
-{{< /imgproc >}}
-
-The ExposedMultipod is a generalization of the [ExposedMonopod](#kubernetes-exposedmonopod) with \[n\] containers. In fact, the later's implementation passes its container to the first as a network of a single container.

webdocs/challmaker-guides/update-in-production/index.md

@@ -19,20 +19,18 @@ We adopted the reflexions of [The Update Framework](https://theupdateframework.i
 
 ## What to do
 
-You will have to update the [scenario](/docs/chall-manager/glossary#scenario), of course.
-Once it is fixed and validated, archive the new version.
+You will have to create a new [scenario](/docs/chall-manager/glossary#scenario), of course.
+Then, you will have to update the challenge configuration to provide this new scenario and an update strategy. If no strategy is specified, it defaults to `update-in-place`.
 
-Then, you'll have to pick up an Update Strategy.
+Chall-Manager will temporarily block operations on this challenge, and update all existing instances.
+This makes the process predictible and reproductible, thus you can test in a pre-production environment before production (and we recommend you so). It also avoids human errors during fix, and lower the burden at scale.
 
 | Update Strategy | Require Robustness¹ | Time efficiency | Cost efficiency | Availability | TL;DR; |
 |---|:---:|:---:|:---:|:---:|---|
 | Update in place | ✅ | ✅ | ✅ | ✅ | Efficient in time & cost ; require high maturity |
 | Blue-Green      | ❌ | ✅ | ❌ | ✅ | Efficient in time ; costfull |
 | Recreate        | ❌ | ❌ | ✅ | ❌ | Efficient in cost ; time consuming |
 
-¹ Robustness of both the provider and resources updates. Robustness is the capability of a resource to be finely updated without re-creation.
+¹ Robustness of both the provider and resources updates. Robustness is the capability of a scenario to be finely updated without complete re-creation.
 
-More information on the selection of those models and how they work internally is available in the [design documentation](/docs/chall-manager/design/hot-update).
-
-You'll only have to update the challenge, specifying the Update Strategy of your choice. Chall-Manager will temporarily block operations on this challenge, and update all existing instances.
-This makes the process predictible and reproductible, thus you can test in a pre-production environment before production. It also avoids human errors during fix, and lower the burden at scale.
+More information on how they work internally is available in the [design documentation](/docs/chall-manager/design/hot-update).