ctfdsetup

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.

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.

How to use

For the CLI configuration, please refer to the binary's specific API through ctfd-setup --help. In use of IaC provisionning scenario, the corresponding environment variables are also mapped to the output, so please refer to it.

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.

name: 'My workflow'

on:
  push:
    branches:
      - 'main'

jobs:
  my-job:
    runs-on: 'ubuntu-latest'
    steps:
      - name: 'Setup CTFd'
        uses: 'ctfer-io/ctfd-setup@v1.3.0'
        with:
          url: ${{ secrets.CTFD_URL }}
          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.

kind: pipeline
type: docker
name: 'My pipeline'

trigger:
  branch:
  - main
  event:
  - push

steps:
  # ...

  - name: 'Setup CTFd'
    image: 'ctferio/ctfd-setup@v1.3.0'
    settings:
      url:
        from_secret: CTFD_URL
      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)

Documentation

Index

• func Log() *zap.Logger
• func Setup(ctx context.Context, url string, apiKey string, conf *Config) error
• type Accounts
• type Admin
• type Appearance
• type Config
  • func (conf Config) Validate() error
• type Email
• type EmailContent
• type ErrClient
  • func (err ErrClient) Error() string
• type ErrRequired
  • func (err ErrRequired) Error() string
• type ExternalReference
• type File
  • func (file *File) UnmarshalYAML(node *yaml.Node) error
• type Legal
• type MajorLeagueCyber
• type Pages
• type Security
• type Settings
• type Social
• type Theme
• type Time

Functions

func Log

func Log() *zap.Logger

func Setup

func Setup(ctx context.Context, url string, apiKey string, conf *Config) error

Types

type Accounts

type Accounts struct {
	DomainWhitelist               *string `yaml:"domain_whitelist"`
	VerifyEmails                  bool    `yaml:"verify_emails"`
	TeamCreation                  *bool   `yaml:"team_creation"`
	TeamSize                      *int    `yaml:"team_size"`
	NumTeams                      *int    `yaml:"num_teams"`
	NumUsers                      *int    `yaml:"num_users"`
	TeamDisbanding                *string `yaml:"team_disbanding"`
	IncorrectSubmissionsPerMinute *int    `yaml:"incorrect_submissions_per_minutes"`
	NameChanges                   *bool   `yaml:"name_changes"`
}

type Admin

type Admin struct {
	Name     string `yaml:"name"`     // required
	Email    string `yaml:"email"`    // required
	Password string `yaml:"password"` // required
}

type Appearance

type Appearance struct {
	Name          string  `yaml:"name"`        // required
	Description   string  `yaml:"description"` // required
	DefaultLocale *string `yaml:"default_locale"`
}

type Config

type Config struct {
	Appearance Appearance `yaml:"appearance"`
	Theme      Theme      `yaml:"theme"`
	Accounts   Accounts   `yaml:"accounts"`
	Pages      Pages      `yaml:"pages"`
	// Don't handle brackets here, should not be part of those settings but CRUD objects
	// CustomFields are not handled as they are not predictable and would be hard to handle + bad practice (API changes on the fly)
	MajorLeagueCyber MajorLeagueCyber `yaml:"major_league_cyber"`
	Settings         Settings         `yaml:"settings"`
	Security         Security         `yaml:"security"`
	Email            Email            `yaml:"email"`
	Time             Time             `yaml:"time"`
	Social           Social           `yaml:"social"`
	Legal            Legal            `yaml:"legal"`
	Mode             string           `yaml:"mode"`

	Admin Admin `yaml:"admin"`
}

func (Config) Validate

func (conf Config) Validate() error

type Email

type Email struct {
	Registration              EmailContent `yaml:"registration"`
	Confirmation              EmailContent `yaml:"confirmation"`
	NewAccount                EmailContent `yaml:"new_account"`
	PasswordReset             EmailContent `yaml:"password_reset"`
	PasswordResetConfirmation EmailContent `yaml:"password_reset_confirmation"`
	From                      *string      `yaml:"from"`
	Server                    *string      `yaml:"server"`
	Port                      *string      `yaml:"port"`
	Username                  *string      `yaml:"username"`
	Password                  *string      `yaml:"password"`
	TLS_SSL                   *bool        `yaml:"tls_ssl"`
	STARTTLS                  *bool        `yaml:"starttls"`
}

type EmailContent

type EmailContent struct {
	Subject *string `yaml:"subject"`
	Body    *string `yaml:"body"`
}

type ErrClient

type ErrClient struct {
	// contains filtered or unexported fields
}

func (ErrClient) Error

func (err ErrClient) Error() string

type ErrRequired

type ErrRequired struct {
	Attribute string
}

func (ErrRequired) Error

func (err ErrRequired) Error() string

type ExternalReference

type ExternalReference struct {
	URL     *string `yaml:"url"`
	Content *string `yaml:"content"`
}

type File

type File struct {
	Name    string
	Content []byte
}

func (*File) UnmarshalYAML

func (file *File) UnmarshalYAML(node *yaml.Node) error

type Legal

type Legal struct {
	TOS           ExternalReference `yaml:"tos"`
	PrivacyPolicy ExternalReference `yaml:"privacy_policy"`
}

type MajorLeagueCyber

type MajorLeagueCyber struct {
	ClientID     *string `yaml:"client_id"`
	ClientSecret *string `yaml:"client_secret"`
}

type Pages

type Pages struct {
	RobotsTxt *File `yaml:"robots_txt"`
}

type Security

type Security struct {
	HTMLSanitization *bool   `yaml:"html_sanitization"`
	RegistrationCode *string `yaml:"registration_code"`
}

type Settings

type Settings struct {
	ChallengeVisibility    string `yaml:"challenge_visibility"`
	AccountVisibility      string `yaml:"account_visibility"`
	ScoreVisibility        string `yaml:"score_visibility"`
	RegistrationVisibility string `yaml:"registration_visibility"`
	Paused                 *bool  `yaml:"paused"`
}

type Social

type Social struct {
	Shares *bool `yaml:"shares"`
}

type Theme

type Theme struct {
	Logo      *File  `yaml:"logo"`
	SmallIcon *File  `yaml:"small_icon"`
	Name      string `yaml:"name"`
	Color     string `yaml:"color"`
	// Banner is only supported by bare setup, need to be at least support by PatchConfigs
	Header   *File `yaml:"header"`
	Footer   *File `yaml:"footer"`
	Settings *File `yaml:"settings"`
}

type Time

type Time struct {
	Start     *string `yaml:"start"`
	End       *string `yaml:"end"`
	Freeze    *string `yaml:"freeze"`
	ViewAfter *bool   `yaml:"view_after"`
}