Common characteristics

A task corresponds to a process that can be executed.

Tasks are grouped by project.

Several types of tasks can be created (shell or sql script, workflow, etc.), but they all share certain characteristics.

Name

The name of the task.

Description

A detailed description of the task in markdown format.

Multiple execution policy

When receiving an execution request while an execution is already running for a given task, several scenarios are possible.

Reject

One execution at a time is allowed, so any new execution request will be rejected until the current execution is finished.

Smart chaining

A new execution is created with a pending status and will only start when the current one is finished.

Any new execution request will be rejected as long as an execution with a pending status already exists.

This execution policy is recommended for setting up a CI/CD pipeline (for example, a build task triggered by an incoming webhook following a push on a Github/Gitlab repository).

Replacement

The current execution receives an aborting request.

A new execution is created with a pending status and will only start when the current one is completely aborted.

Any new execution request will be rejected as long as an execution with a pending status already exists.

Concurrency

A new execution is created and started concurrently with the current one.

Make sure that your task is designed to support concurrent executions before using this execution policy.

Notifications

If notifiers (Slack, Microsoft Teams, email, etc.) have been configured for your project, you can assign one to your task to send a notification when execution:

Starts
Ends ( = fails, is aborted, or completes successfully)
Fails or is aborted
Ends differently from previous execution (well suited to monitoring to prevent being flooded with notifications of consecutive failures or success)

Parameters

It is possible to define a list of parameters for a given task (for the task types that support them) to influence its behavior.

The following parameter types can be distinguished:

Selector
Checkbox
Integer
Date
Text

Each parameter has:

A name (always uppercase)
An optional label: only used in the task execution web form (if left blank, the name will be used instead)
A default value
Eventual constraints on allowed values (max length, …)
Confirmation whether the parameter can be populated by a webhook payload (only for text parameter)

When a task is executed, each parameter is first initialized with its default value, then overridden by:

The value specified in the API request (and therefore indirectly in the web interface execution form)
The value specified in an incoming webhook (from a URL query parameter, a form data or a payload)

An execution launched via a workflow task or schedule will therefore always use the default parameter values.

Scheduling

Each task can be scheduled using a cron expression that follows this format.

For example, to execute a task at 3 AM every 8th and 13th day of the month, you simply need to use this expression:

0 3 8,23 * *

Timeout

Overrides the global and project timeout (in seconds/minutes/hours/days) for executions.

Executions still running after the timeout will be aborted.

Execution retention period

Overrides the global and project retention period (in days) for executions.

Once a day, executions that have exceeded the retention period will be deleted.

In the special case of a retention period of 0, executions are deleted as soon as they are completed.

Execution triggering

Task executions can be triggered by:

Admin users or Users attached to the task’s project (via REST API or indirectly the webapp)
CTFreak’s internal scheduler (every monday at 2pm, …)
Incoming webhooks (push to a branch in a github/gitlab repo, event in a home automation server, alert received from third-party software, …)
Workflow tasks

Incoming Webhooks

Incoming webhooks allow for the execution of a task without going through the authentication process.

It’s the perfect way to trigger the execution of tasks by third-party software (for example, trigger a compilation script after a push to a branch in a git repository).

Creation

To add a webhook, go to Projects → Select a task → Incoming webhooks → New webhook → Select a webhook type and complete the form.

After validating the creation form, the URL for calling your webhook is available.

Webhook and task

An incoming webhook is attached to a single task, and it is possible to set up multiple incoming webhooks to execute a task.

Webhook call

Calling a webhook always involves an HTTP POST request.

We receive a JSON in the following format in return:

{
  "status": <HTTP status code>,
  "executionId": "<Execution ID that was just created, or null in case of failure>",
  "message": "<Status or error message>"
}

Parameters

If the webhook is used to launch a parameterizable task, parameters can be set by:

Query parameters in the URL:

curl --request POST --url http://localhost:6700/wh/MudO63QwyeoI5bpQ0FXgZjb6Kxtizg1U6y5pphgpJnme5OhBPW4GBLjmZZhT \
-G \
-d "SERVICE_NAME=postgresql" \
-d "COMMAND=restart"

Form data with application/x-www-form-urlencoded format

curl --request POST --url http://localhost:6700/wh/MudO63QwyeoI5bpQ0FXgZjb6Kxtizg1U6y5pphgpJnme5OhBPW4GBLjmZZhT \
-d "SERVICE_NAME=postgresql" \
-d "COMMAND=restart"

The payload content for text parameters with the “Fill with webhook payload” property enabled

curl --request POST --url http://localhost:6700/wh/MudO63QwyeoI5bpQ0FXgZjb6Kxtizg1U6y5pphgpJnme5OhBPW4GBLjmZZhT \
-d ".........payload content........."

Execution condition

When the execution condition field is filled in, the payload must be in JSON format and satisfy this condition (in JMESPATH format) for the task associated with the webhook to be executed.

For example, with this received payload:

{
   "pusher":{
      "email":"bob@ctfreak.com",
      "name":"Bob"
   },
   "ref":"refs/heads/master"
}

and this execution condition:

(ref == 'refs/heads/master' && pusher.name == 'Alfred')

The associated task will not execute because the pusher.name does not match.

Note: When the execution condition is not satisfied, CTFreak still returns an HTTP status code 200.

Webhook types

Generic webhook

This type of webhook only includes the common characteristics of webhooks.

For example, it can be called with a simple curl request:

curl --request POST --url http://localhost:6700/wh/MudO63QwyeoI5bpQ0FXgZjb6Kxtizg1U6y5pphgpJnme5OhBPW4GBLjmZZhT

And in return, receive the ID of the execution that was just created.

{
  "status": 200,
  "executionId": "01GSNB2678YM5DZS6X2FZPZAJY",
  "message": "I got the payload!"
}

Github webhook

You can specify a secret token to validate received payloads.

Note: A signature is sent with the hook request in the X-Hub-Signature-256 header. To verify that the request is legitimate, CTFreak will calculate a hash using the secret token and ensure that the result matches the signature.

When a new webhook is setup in GitHub a ping event is sent to confirm the webhook. CTFreak will receive the ping event and return a success response, but will not run the related task.

When creating a github webhook, the default execution condition restricts execution to pushes on the master branch:

ref == 'refs/heads/master'

Feel free to customize it according to your needs.

Gitlab webhook

You can specify a secret token to validate received payloads.

Note: The token is sent with the hook request in the X-Gitlab-Token HTTP header. CTFreak will check the token to verify that the request is legitimate.

When creating a gitlab webhook, the default execution condition restricts execution to pushes on the master branch:

ref == 'refs/heads/master'

Feel free to customize it according to your needs.