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 description of the task to be found on its dedicated page.

Markdown format can be used to enter this description.

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
  • When execution ends ( = fails, is aborted, or completes successfully)
  • When execution fails or is aborted

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, an optional label, a default value, and some have constraints on allowed values (max length, …).

When a task is executed, each parameter value is initialized with the default one, then replaced if necessary by the one communicated by the user when executing the task via the web interface or API.

An execution launched via a webhook, workflow or scheduling will therefore always use the default values (this may change in future versions).

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 the webapp or REST API)
  • 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, …)
  • A workflow task

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 with an empty payload or a JSON format payload.

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

Execution condition

When the execution condition field is filled in, the payload (in JSON format) must 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.