REST API

All actions performed via CTFreak’s web UI can also be performed via its RESTful JSON API.

Some use cases

Execute a task

To execute a given task, start by retrieving its Task Id from its dedicated page in the web UI, then run the following query:

  • HTTP POST: https://{YOUR CTFREAK INSTANCE}/api/v1/executions

  • Body:

    {
  "taskId": "01G9SAGYJM6544WZR8P3W7XB5Q"
}

If you launch a parameterizable task, each parameter is initialized with its default value, but you can override it.

For example, for a task with the parameters:

  • COUNTRY_CODE of type selector
  • CLEAN of type checkbox
  • MAX_RETRY of type integer
  • START_DATE of type date

You can attempt to run the following query:

  • HTTP POST: https://{YOUR CTFREAK INSTANCE}/api/v1/executions

  • Body:

    {
  "taskId": "01G9SAGYJM6544WZR8P3W7XB5Q",
  "parameterMap": {
      "COUNTRY_CODE": "US",
      "CLEAN": true,
      "MAX_RETRY": 5,
      "START_DATE": "2024-01-25"
  }
}

Create a local command task (without shell)

  • HTTP POST: https://{YOUR CTFREAK INSTANCE}/api/v1/tasks

  • Body:

    {
  "projectId": "my-awesome-project",
  "name": "My awesome task",
  "description": "This is really an awesome task",
  "multipleExecutionPolicy": "REJECT",
  "notifyAtStartupFg": false,
  "notifyAtEndFg": false,
  "notifyOnFailureFg": false,
  "notifierId": null,
  "scheduledFg": true,
  "cronExpression": "0 9 * * *",
  "timeout": 30,
  "timeoutDurationUnit": "MINUTE",
  "executionRetentionPeriod": 30,
  "taskType": "LOCAL_COMMAND",
  "parameters": [],
  "localCommandTask": {
      "useShellFg": false,
      "commandLine": null,
      "program": "ip",
      "args": [
          "-c",
          "address"
      ],
      "logOutput": "ALWAYS"
  }
}

  • Response:

    {
  "taskId": "01J8ZWXQ1572KC6XGE7T74PT4P",
  "creationTs": 1727647374373505276,
  "updateTs": 1727647374373505276,
  "userId": "01GV1PR26RXBMV4PCPV5TEK1E9",
  "projectId": "my-awesome-project",
  "name": "My awesome task",
  "description": "This is really an awesome task",
  "parameters": [],
  "multipleExecutionPolicy": "REJECT",
  "notifyAtStartupFg": false,
  "notifyAtEndFg": false,
  "notifyOnFailureFg": false,
  "notifierId": null,
  "scheduledFg": true,
  "cronExpression": "0 9 * * *",
  "timeout": 30,
  "timeoutDurationUnit": "MINUTE",
  "executionRetentionPeriod": 30,
  "taskType": "LOCAL_COMMAND",
  "localCommandTask": {
      "useShellFg": false,
      "commandLine": null,
      "program": "ip",
      "args": [
          "-c",
          "address"
      ],
      "logOutput": "ALWAYS"
  }
}