feat: add generated documentation

README.md

@@ -23,7 +23,7 @@ Terraform is used to manage resources that have lifecycles, configurations, to s
 That is the case of CTFd: it handles challenges that could be created, modified and deleted.
 With some work to leverage the unsteady CTFd's API, Terraform is now able to manage them as cloud resources bringing you to opportunity of **CTF as Code**.
 
-It avoids shitty scripts, `ctfcli` and other tools that does not solve the problem of reproductibility, ease of deployment and resiliency.
+With a paradigm-shifting vision of setting up CTFs, the Terraform Provider for CTFd avoid shitty scripts, `ctfcli` and other tools that does not solve the problem of reproductibility, ease of deployment and resiliency.
 
 ## How to use it ?
 

docs/data-sources/challenges.md

@@ -0,0 +1,88 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "ctfd_challenges Data Source - terraform-provider-ctfd"
+subcategory: ""
+description: |-
+  
+---
+
+# ctfd_challenges (Data Source)
+
+
+
+
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Read-Only
+
+- `challenges` (Attributes List) (see [below for nested schema](#nestedatt--challenges))
+- `id` (String) The ID of this resource.
+
+<a id="nestedatt--challenges"></a>
+### Nested Schema for `challenges`
+
+Read-Only:
+
+- `category` (String) Category of the challenge that CTFd groups by on the web UI.
+- `connection_info` (String) Connection Information to connect to the challenge instance, usefull for pwn or web pentest.
+- `decay` (Number)
+- `description` (String) Description of the challenge, consider using multiline descriptions for better style.
+- `files` (Attributes List) List of files given to players to flag the challenge. (see [below for nested schema](#nestedatt--challenges--files))
+- `flags` (Attributes List) List of challenge flags that solves it. (see [below for nested schema](#nestedatt--challenges--flags))
+- `function` (String) Decay function to define how the challenge value evolve through solves, either linear or logarithmic.
+- `hints` (Attributes List) List of hints about the challenge displayed to the end-user. (see [below for nested schema](#nestedatt--challenges--hints))
+- `id` (String) Identifier of the challenge.
+- `initial` (Number)
+- `max_attempts` (Number) Maximum amount of attempts before being unable to flag the challenge.
+- `minimum` (Number)
+- `name` (String) Name of the challenge, displayed as it.
+- `requirements` (Attributes) List of required challenges that needs to get flagged before this one being accessible. Usefull for skill-trees-like strategy CTF. (see [below for nested schema](#nestedatt--challenges--requirements))
+- `state` (String) State of the challenge, either hidden or visible.
+- `tags` (List of String) List of challenge tags that will be displayed to the end-user. You could use them to give some quick insights of what a challenge involves.
+- `topics` (List of String) List of challenge topics that are displayed to the administrators for maintenance and planification.
+- `type` (String) Type of the challenge defining its layout, either standard or dynamic.
+- `value` (Number)
+
+<a id="nestedatt--challenges--files"></a>
+### Nested Schema for `challenges.files`
+
+Read-Only:
+
+- `content` (String)
+- `contentb64` (String)
+- `id` (String)
+- `location` (String)
+- `name` (String)
+
+
+<a id="nestedatt--challenges--flags"></a>
+### Nested Schema for `challenges.flags`
+
+Read-Only:
+
+- `content` (String)
+- `data` (String)
+- `id` (String)
+- `type` (String)
+
+
+<a id="nestedatt--challenges--hints"></a>
+### Nested Schema for `challenges.hints`
+
+Read-Only:
+
+- `content` (String)
+- `cost` (Number)
+- `id` (String)
+- `requirements` (List of String)
+
+
+<a id="nestedatt--challenges--requirements"></a>
+### Nested Schema for `challenges.requirements`
+
+Read-Only:
+
+- `behavior` (String) Behavior if not unlocked, either hidden or anonymized.
+- `prerequisites` (List of String) List of the challenges ID.

docs/index.md

@@ -0,0 +1,30 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "ctfd Provider"
+subcategory: ""
+description: |-
+  Interact with a CTFd https://github.com/ctfd/ctfd.
+---
+
+# ctfd Provider
+
+Interact with a [CTFd](https://github.com/ctfd/ctfd).
+
+## Example Usage
+
+```terraform
+provider "ctfd" {
+  url     = "https://my-ctfd.lan"
+  api_key = "ctfd_somerandomvalue"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Optional
+
+- `api_key` (String, Sensitive) User API key. Could use `CTFD_API_KEY` environment variable instead. Despite being the most convenient way to authenticate yourself, we do not recommend it as you will probably generate a long-live token without any rotation policy.
+- `nonce` (String, Sensitive) User session nonce, comes with session. Could use `CTFD_NONCE` environment variable instead.
+- `session` (String, Sensitive) User session token, comes with nonce. Could use `CTFD_SESSION` environment variable instead.
+- `url` (String) CTFd base URL (e.g. `https://my-ctf.lan`). Could use `CTFD_URL` environment variable instead.

docs/resources/challenge.md

@@ -0,0 +1,158 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "ctfd_challenge Resource - terraform-provider-ctfd"
+subcategory: ""
+description: |-
+  
+---
+
+# ctfd_challenge (Resource)
+
+
+
+## Example Usage
+
+```terraform
+resource "ctfd_challenge" "http" {
+  name        = "HTTP Authentication"
+  category    = "network"
+  description = <<-EOT
+        Oh no ! I did not see my connection was no encrypted !
+        I hope no one spied me...
+
+        Authors:
+        - NicolasFgrx
+    EOT
+  value       = 500
+  initial     = 500
+  decay       = 17
+  minimum     = 50
+  state       = "visible"
+  function    = "logarithmic"
+
+  flags = [{
+    content = "24HIUT{Http_1s_n0t_s3cuR3}"
+  }]
+
+  topics = [
+    "Network"
+  ]
+  tags = [
+    "network",
+    "http"
+  ]
+
+  hints = [{
+    content = "HTTP exchanges are not ciphered."
+    cost    = 50
+    }, {
+    content = "Content is POSTed in HTTP :)"
+    cost    = 50
+  }]
+
+  files = [{
+    name       = "capture.pcapng"
+    contentb64 = filebase64("${path.module}/capture.pcapng")
+  }]
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `category` (String) Category of the challenge that CTFd groups by on the web UI.
+- `description` (String) Description of the challenge, consider using multiline descriptions for better style.
+- `name` (String) Name of the challenge, displayed as it.
+
+### Optional
+
+- `connection_info` (String) Connection Information to connect to the challenge instance, usefull for pwn or web pentest.
+- `decay` (Number)
+- `files` (Attributes List) List of files given to players to flag the challenge. (see [below for nested schema](#nestedatt--files))
+- `flags` (Attributes List) List of challenge flags that solves it. (see [below for nested schema](#nestedatt--flags))
+- `function` (String) Decay function to define how the challenge value evolve through solves, either linear or logarithmic.
+- `hints` (Attributes List) List of hints about the challenge displayed to the end-user. (see [below for nested schema](#nestedatt--hints))
+- `initial` (Number)
+- `max_attempts` (Number) Maximum amount of attempts before being unable to flag the challenge.
+- `minimum` (Number)
+- `requirements` (Attributes) List of required challenges that needs to get flagged before this one being accessible. Usefull for skill-trees-like strategy CTF. (see [below for nested schema](#nestedatt--requirements))
+- `state` (String) State of the challenge, either hidden or visible.
+- `tags` (List of String) List of challenge tags that will be displayed to the end-user. You could use them to give some quick insights of what a challenge involves.
+- `topics` (List of String) List of challenge topics that are displayed to the administrators for maintenance and planification.
+- `type` (String) Type of the challenge defining its layout, either standard or dynamic.
+- `value` (Number)
+
+### Read-Only
+
+- `id` (String) Identifier of the challenge.
+
+<a id="nestedatt--files"></a>
+### Nested Schema for `files`
+
+Required:
+
+- `name` (String) Name of the file as displayed to end-users.
+
+Optional:
+
+- `content` (String, Sensitive) Raw content of the file, perfectly fit the use-cases of a .txt document or anything with a simple binary content. You could provide it from the file-system using `file("${path.module}/...")`.
+- `contentb64` (String, Sensitive) Base 64 content of the file, perfectly fit the use-cases of complex binaries. You could provide it from the file-system using `filebase64("${path.module}/...")`.
+
+Read-Only:
+
+- `id` (String) Identifier of the file, used internally to handle the CTFd corresponding object.
+- `location` (String) Location where the file is stored on the CTFd instance, for download purposes.
+
+
+<a id="nestedatt--flags"></a>
+### Nested Schema for `flags`
+
+Required:
+
+- `content` (String, Sensitive) The actual flag to match. Consider using the convention `MYCTF{value}` with `MYCTF` being the shortcode of your event's name and `value` depending on each challenge.
+
+Optional:
+
+- `data` (String) The flag sensitivity information, either case_sensitive or case_insensitive
+- `type` (String) The type of the flag, could be either static or regex
+
+Read-Only:
+
+- `id` (String) Identifier of the flag, used internally to handle the CTFd corresponding object.
+
+
+<a id="nestedatt--hints"></a>
+### Nested Schema for `hints`
+
+Required:
+
+- `content` (String) Content of the hint as displayed to the end-user.
+
+Optional:
+
+- `cost` (Number) Cost of the hint, and if any specified, the end-user will consume its own (or team) points to get it.
+- `requirements` (List of String) Other hints required to be consumed before getting this one. Usefull for cost-increasing hint strategies with more and more help.
+
+Read-Only:
+
+- `id` (String) Identifier of the hint, used internally to handle the CTFd corresponding object.
+
+
+<a id="nestedatt--requirements"></a>
+### Nested Schema for `requirements`
+
+Optional:
+
+- `behavior` (String) Behavior if not unlocked, either hidden or anonymized.
+- `prerequisites` (List of String) List of the challenges ID.
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Challenge can be imported by the CTFd ID (check URLs)
+terraform import ctfd_challenge.http 1
+```

examples/provider/provider.tf

@@ -0,0 +1,4 @@
+provider "ctfd" {
+  url     = "https://my-ctfd.lan"
+  api_key = "ctfd_somerandomvalue"
+}

examples/resources/ctfd_challenge/import.sh

@@ -0,0 +1,2 @@
+# Challenge can be imported by the CTFd ID (check URLs)
+terraform import ctfd_challenge.http 1

examples/resources/ctfd_challenge/resource.tf

@@ -0,0 +1,42 @@
+resource "ctfd_challenge" "http" {
+  name        = "HTTP Authentication"
+  category    = "network"
+  description = <<-EOT
+        Oh no ! I did not see my connection was no encrypted !
+        I hope no one spied me...
+
+        Authors:
+        - NicolasFgrx
+    EOT
+  value       = 500
+  initial     = 500
+  decay       = 17
+  minimum     = 50
+  state       = "visible"
+  function    = "logarithmic"
+
+  flags = [{
+    content = "24HIUT{Http_1s_n0t_s3cuR3}"
+  }]
+
+  topics = [
+    "Network"
+  ]
+  tags = [
+    "network",
+    "http"
+  ]
+
+  hints = [{
+    content = "HTTP exchanges are not ciphered."
+    cost    = 50
+    }, {
+    content = "Content is POSTed in HTTP :)"
+    cost    = 50
+  }]
+
+  files = [{
+    name       = "capture.pcapng"
+    contentb64 = filebase64("${path.module}/capture.pcapng")
+  }]
+}

go.mod

@@ -4,22 +4,29 @@ go 1.21.3
 
 require (
 	github.com/ctfer-io/go-ctfd v0.3.7
+	github.com/hashicorp/terraform-plugin-docs v0.16.0
 	github.com/hashicorp/terraform-plugin-framework v1.4.2
 	github.com/hashicorp/terraform-plugin-go v0.19.1
 	github.com/hashicorp/terraform-plugin-log v0.9.0
 	github.com/hashicorp/terraform-plugin-testing v1.6.0
 )
 
 require (
+	github.com/Masterminds/goutils v1.1.1 // indirect
+	github.com/Masterminds/semver/v3 v3.1.1 // indirect
+	github.com/Masterminds/sprig/v3 v3.2.2 // indirect
 	github.com/ProtonMail/go-crypto v0.0.0-20230828082145-3c4c8a2d2371 // indirect
 	github.com/agext/levenshtein v1.2.2 // indirect
 	github.com/apparentlymart/go-textseg/v15 v15.0.0 // indirect
+	github.com/armon/go-radix v1.0.0 // indirect
+	github.com/bgentry/speakeasy v0.1.0 // indirect
 	github.com/cloudflare/circl v1.3.3 // indirect
 	github.com/fatih/color v1.13.0 // indirect
 	github.com/golang/protobuf v1.5.3 // indirect
 	github.com/google/go-cmp v0.6.0 // indirect
+	github.com/google/uuid v1.3.1 // indirect
 	github.com/gorilla/schema v1.2.1 // indirect
-	github.com/hashicorp/errwrap v1.0.0 // indirect
+	github.com/hashicorp/errwrap v1.1.0 // indirect
 	github.com/hashicorp/go-checkpoint v0.5.0 // indirect
 	github.com/hashicorp/go-cleanhttp v0.5.2 // indirect
 	github.com/hashicorp/go-cty v1.4.1-0.20200414143053-d3edf31b6320 // indirect
@@ -37,15 +44,22 @@ require (
 	github.com/hashicorp/terraform-registry-address v0.2.3 // indirect
 	github.com/hashicorp/terraform-svchost v0.1.1 // indirect
 	github.com/hashicorp/yamux v0.0.0-20181012175058-2f1d1f20f75d // indirect
-	github.com/mattn/go-colorable v0.1.12 // indirect
-	github.com/mattn/go-isatty v0.0.14 // indirect
+	github.com/huandu/xstrings v1.3.2 // indirect
+	github.com/imdario/mergo v0.3.15 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
+	github.com/mattn/go-isatty v0.0.16 // indirect
+	github.com/mitchellh/cli v1.1.5 // indirect
 	github.com/mitchellh/copystructure v1.2.0 // indirect
 	github.com/mitchellh/go-testing-interface v1.14.1 // indirect
 	github.com/mitchellh/go-wordwrap v1.0.0 // indirect
 	github.com/mitchellh/mapstructure v1.5.0 // indirect
 	github.com/mitchellh/reflectwalk v1.0.2 // indirect
 	github.com/oklog/run v1.0.0 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
+	github.com/posener/complete v1.2.3 // indirect
+	github.com/russross/blackfriday v1.6.0 // indirect
+	github.com/shopspring/decimal v1.3.1 // indirect
+	github.com/spf13/cast v1.5.0 // indirect
 	github.com/vmihailenco/msgpack v4.0.4+incompatible // indirect
 	github.com/vmihailenco/msgpack/v5 v5.4.1 // indirect
 	github.com/vmihailenco/tagparser/v2 v2.0.0 // indirect