An open API service indexing awesome lists of open source software.

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.

Awesome Lists containing this project

README

        


CTFd-Setup


Version your CTFd setup configuration.



reference
License
Coverage Status


CodeQL
OpenSSF Scoreboard
SLSA Level 3


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


ctfd-setup utility used in GitHub Actions, Drone CI and Docker and Kubernetes initial container

### 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 }}"
```