Runners

Runners are nothing but Traceable CLI installed on your server as a service. You can download and install a runner either through the Traceable Platform or as a service using the install.sh script available on Traceable's download site or by using Helm chart. Traceable also allows you to set up custom certificates for runners according to your requirements. For more information, see Set up custom certificates for runners.

The following table compares Traceable CLI and runner on various parameters along with their use case and recommendations:

Before you begin

Make a note of the following before proceeding with setting up Runner:

• A runner needs at least 2 CPUs and 4 GB of memory. This number may increase with an increase in the number of tests. Contact Traceable support for exact sizing by sending an email to support@traceable.ai.

• Ensure that the machine where you are installing the Runner can communicate with the APIs and Traceable Platform.

• DAST does not need an app to be instrumented, but an environment still needs to be created for DAST scan to create a default service and list APIs under it.

• Runners are not scoped by the environment. They are available for all environments.

• Ensure you are assigned the Security admin or Account Owner role to start a runner. For more information about different roles, see Teams and roles - RBAC.

Option 1 — Download runner from UI

Navigate to Testing → Settings → Runners to start the runner configuration. Provide a name for the runner and the token. The binary CLI command and docker option are displayed. You can use either of the options to configure the runner on your server.

Copy the binary CLI command or the docker command to configure the runner.

By default, the binary command runs in the background. The Docker command given in the UI runs in the foreground in an interactive way. If you wish to run the Docker command in the background, use the following command. Replace the runner's name with the name of your runner:

docker run --rm -d -v ~/.traceable_docker:/app/userdata traceableai/traceable-cli:latest runner start --traceable-server api.traceable.ai --runner-name newrunner --token **** 

Following is an explanation of the Docker command:

• docker run is the command to run a Docker container.

• --rm removes the container automatically after it exits.

• -d runs the container in detached mode.

• -v ~/.traceable_docker:/app/userdata mounts the local directory ~/.traceable_docker to the /app/userdata directory inside the container. This allows the container to access and modify files in the local directory.

• traceableai/traceable-cli:latest specifies the image to use for the container.

• runner start runs the start command of the Traceable Runner program within the container.

• --traceable-server api.traceable.ai specifies the URL of the Traceable Server to connect to.

• --runner-name newrunner sets the name of the runner to “newrunner”.

• --token **** sets the authorization token required to connect to the Traceable Server.

Option 2 — Download and install Runner as a service

You can configure the runner as a systemd service. Download the installation script from Traceable's download site to configure Runner as a service. Navigate to cli → release → latest → install.sh to download the installation script.

Note

The install.sh script is supported on a Linux machine.

Run the script's help ( install.sh --help) command to know the various options.

You can run more than one runner on the same machine for both option 1 and option 2. For more information on how to run more than one runner on a single machine, contact Traceable support at support@traceable.ai. 

Option 3 — Install runner using Helm chart

Complete the following steps to install runner using Helm chart:

1. Enter the following command to add the repo:

   helm repo add traceableai https://helm.traceable.ai

2. Enter the following command to update the repo:

   helm repo update

Create values.yml file

Create a values.yml file based on the sample provided below. Make sure to add the correct values for traceableToken and traceableServer in the file.

replicaCount: 1

resources:
  limits:
    cpu: 2.0
    memory: 4Gi
  requests:
    cpu: 2.0
    memory: 4Gi

astRunnerArgs:
  name: traceable-runner-helm   # Name of the runner
  traceableServer: api.traceable.ai   # Traceable Server
  traceableToken: ""   # Replace this with actual token value
  maxRetries: 1   # Number of Request Retries
  idleTimeout: 10   # Idle Timeout before aborting a scan
  requestDelay: 0   # Request delay delay between requests
  threads: 20   # Number of threads to run on
  logfile: stdout   # Log file name
  loglevel: INFO   # Set log level

Enter the following command:

helm install <deployment_name>  traceableai/traceable-runner -f values.yaml

Set up custom certificates for runners

You can set up custom certificates for runners according to your requirements. These certificates are useful when you need private certificate authority (CA) files or to verify the client’s identity.

Note

All custom certificate files should be in PEM format.

Following are the custom SSL/TLS configurations for the Traceable runner:

Custom internal certificate authority (CA)

The Traceable runner CLI allows you to configure a custom root CA file if your organization uses a private CA file to sign server certificates. Adding the custom CA file ensures secure communication between the runner and both the Traceable platform and your organization’s servers. This security is achieved using the certificates signed by the private CA file.

To set up a custom CA file, you must set the TRACEABLE_ROOT_CA_FILE environment variable with the path to the CA public certificate file in the instance where the Traceable runner is installed.

Mutual TLS configuration

The Traceable runner CLI allows you to use environment variables to set the path to the custom certificate files. This is useful for verifying the client’s identity when calling your organization’s servers. You can set the following environment variables:

• TRACEABLE_CLI_CERT_FILE — Set the path to the client’s certificate file for authenticating the client to the server.

• TRACEABLE_CLI_KEY_FILE — Set the path to the certificate’s private key.

Uninstall a Runner

You can uninstall a runner from your terminal; however, the steps to do this depend on the option you choose while installing it:

Runner installed using install.sh

Option 1 - As a systemd service

Complete the following steps:

1. Enter the following command to stop the service if it is currently running:

   systemctl stop traceable-runner.service

2. Enter the following command to check the status of the service:

   systemctl status traceable-runner.service

   The above command and recent log entries show whether the service is active, inactive, or has failed.

3. Enter the following command to disable the service:

   systemctl disable traceable-runner.service

   The above command prevents the service from starting automatically at boot time.

4. Enter the following command to remove the service unit file from your custom location:

   rm /etc/systemd/system/traceable-runner.service

   The above command removes the file from the /etc/systemd/system directory. This directory usually contains the systemd service files created or customized by the system administrator.

5. Enter the following command to remove the service unit file from the standard location:

   rm /user/lib/systemd/system/traceable-runner.service

   The above command removes the file from the /user/lib/systemd/system/ directory. This directory usually contains systemd service files provided by installation packages.

6. Enter the following command to reload the systemd manager configuration:

   systemctl daemon-reload

   The above command reloads the manager configuration. You must run this command to ensure that systemd is aware of the above steps.

Option 2 - Not as a service

Complete the following steps:

1. Enter the following command to stop the runner:

   traceable runner stop <runner_name>

2. Ensure that the Traceable runner process is currently not running:

   ps -ef | grep traceable

3. Enter the following command to remove the Traceable CLI installation:

   delete $HOME/.local/traceable directory

Runner installed using a Helm chart

Enter the following command to uninstall the runner:

helm uninstall <deployment_name>