https://github.com/ctfer-io/ctfd-setup
Utility to version your CTFd setup configuration.
https://github.com/ctfer-io/ctfd-setup
action ctfd docker golang utility versionning
Last synced: 3 months ago
JSON representation
Utility to version your CTFd setup configuration.
- Host: GitHub
- URL: https://github.com/ctfer-io/ctfd-setup
- Owner: ctfer-io
- License: apache-2.0
- Created: 2024-04-07T20:10:30.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-31T15:56:20.000Z (3 months ago)
- Last Synced: 2025-04-11T22:12:04.811Z (3 months ago)
- Topics: action, ctfd, docker, golang, utility, versionning
- Language: Go
- Homepage:
- Size: 997 KB
- Stars: 7
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
CTFd-Setup
Version your CTFd setup configuration.
CTFd does not have the concept of **configuration file**, leading to **deployment complications** and the **impossibility to version configurations**.
This is problematic for reproducibility or sharing configuration for debugging or replicating a CTF infrastructure.
Moreover, the setup API does not exist, so we had to map it to what the frontend calls in [go-ctfd](https://github.com/ctfer-io/go-ctfd/blob/main/api/setup.go).
To fit those gaps, we built `ctfd-setup` on top of the CTFd API. This utility helps setup a CTFd instance from a YAML configuration file, CLI flags and environment variables.
Thanks to this, you can integrate it using **GitHub Actions**, **Drone CI** or even as part of your **IaC provisionning**.
With `ctfd-setup` you can **setup your CTFd in a second**.
## How to use
### YAML
You can use `ctfd-setup` as a CLI tool and provision it a YAML configuration file.
```yaml
appearance:
name: 'My CTF'
description: 'My CTF description'
admin:
name: 'admin'
email: '[email protected]'
password: 'admin_password'
mode: users
```
**We encourage you to version this file** such that re-deployment is easy (e.g., for test purposes, or in case of a catastrophic failure of the infra during the event).
Nevertheless, please do not commit the admin credentials ! Use `from_env` objects instead (refer to [the YAML Schema](#schema) for more info).
It could also deploy custom pages (like the index) as follows.
This feature is not available in CLI, [GitHub Actions](#github-actions) and [Drone CI](#drone-ci).
```yaml
# ... other configuration attributes
pages:
additional:
- title: CTFer.io example index
route: index
format: markdown
content: |
Some index page content
```
For further configuration, please refer to the binary's specific API through `ctfd-setup --help`.
### GitHub Actions
To improve our own workflows and share knownledges and tooling, we built a GitHub Action: `ctfer-io/ctfd-setup`.
You can use it given the following example.
```yaml
name: 'My workflow'
on:
push:
branches:
- 'main'
jobs:
my-job:
runs-on: 'ubuntu-latest'
steps:
- name: 'Setup CTFd'
uses: 'ctfer-io/[email protected]'
with:
url: ${{ secrets.CTFD_URL }}
file: '.ctfd.yaml'
# or directly attributes
appearance_name: 'My CTF'
appearance_description: 'My CTF description'
admin_name: ${{ secrets.ADMIN_USERNAME }}
admin_email: ${{ secrets.ADMIN_EMAIL }}
admin_password: ${{ secrets.ADMIN_PASSWORD }}
# ... and so on (non-mandatory attributes)
```
### Drone CI
This could also be used as part of a Drone CI use `ctferio/ctfd-setup`.
```yaml
kind: pipeline
type: docker
name: 'My pipeline'
trigger:
branch:
- main
event:
- push
steps:
# ...
- name: 'Setup CTFd'
image: 'ctferio/[email protected]'
settings:
url:
from_secret: CTFD_URL
file: '.ctfd.yaml'
# or directly attributes
appearance_name: 'My CTF'
appearance_description: 'My CTF description'
admin_name:
from_secret: ADMIN_USERNAME
admin_email:
from_secret: ADMIN_EMAIL
admin_password:
from_secret: ADMIN_PASSWORD
# ... and so on (non-mandatory attributes)
```
## Schema
For ease of use, you can generate and use the YAML schema using `ctfd-setup schema`.
**(Optional)** In your `.ctfd.yaml` file you could then prepend `# yaml-language-server: $schema=file:///path/to/schema.json`.
> [!NOTE]
> This will appear by default if your IDE has a YAML extension with support of the [JSON SchemaStore](https://www.schemastore.org/json/).
## Security
### Signature and Attestations
For deployment purposes (and especially in the deployment case of Kubernetes), you may want to ensure the integrity of what you run.
The release assets are SLSA 3 and can be verified using [slsa-verifier](https://github.com/slsa-framework/slsa-verifier) using the following.
```bash
slsa-verifier verify-artifact "" \
--provenance-path "" \
--source-uri "github.com/ctfer-io/ctfd-setup" \
--source-tag ""
```
The Docker image is SLSA 3 and can be verified using [slsa-verifier](https://github.com/slsa-framework/slsa-verifier) using the following.
```bash
slsa-verifier slsa-verifier verify-image "ctferio/ctfd-setup:@sha256:" \
--source-uri "github.com/ctfer-io/ctfd-setup" \
--source-tag ""
```
Alternatives exist, like [Kyverno](https://kyverno.io/) for a Kubernetes-based deployment.
### SBOMs
A SBOM for the whole repository is generated on each release and can be found in the assets of it.
They are signed as SLSA 3 assets. Refer to [Signature and Attestations](#signature-and-attestations) to verify their integrity.
A SBOM is generated for the Docker image in its manifest, and can be inspected using the following.
```bash
docker buildx imagetools inspect "ctferio/ctfd-setup:" \
--format "{{ json .SBOM.SPDX }}"
```