1. Overview

You can automate the deployment of Defenders using the Prisma Cloud API.

To steps to deploy Defender using the Prisma Cloud API are:

  1. Authenticate with Console.

  2. Retrieve the Defender install script from Console.

  3. Execute the install script on the host where you want Defender to run.

  4. Validate that Defender has been installed and it is running.

You should create a service account for the system that will install Defender. The service account should have the role of Defender Manager, or higher, and you should use a long, random string for the password.

This procedure shows you how to access the API using an auth token, which is retrieved from the /api/v1/authenticate endpoint.

When you’re installing Defender into a Kubernetes, OpenShift 3.11, OpenShift 4, or Docker Swarm cluster, use the deployment method documented in each respective install guide as a reference. Prisma Cloud supports these setups using orchestrator-native constructs, such as DaemonSet (for Kubernetes and OpenShift) and global services (for Docker Swarm), to automate Defender deployment. Deployment files can be generated from the Console web interface, the twistcli utility, and the Prisma Cloud API.

2. Install a stand-alone Defender

Single Container Defenders are installed on hosts that are not part of a cluster.

Prerequisites:

  • Console has been installed and deployed on a host in your environment.

  • Console is reachable over the network from the host where you want to install Defender.

  • You have created a service account with the role of Defender Manager, or higher.

  1. Validate that the node where you will install Defender can reach Console over the network.

    $ curl -k https://<COMPUTE_CONSOLE>:8083/api/v1/_ping
  2. Retrieve an auth token from Console.

    $ curl -H "Content-Type: application/json" \
      -d '{"username":"<USERNAME>", "password":"<PASSWORD>"}' \
      https://<COMPUTE_CONSOLE>:8083/api/v1/authenticate

    Where:

    -H

    Extra header in the HTTP request, specifying that the message content is JSON.

    -d

    Data to be sent in the POST request.

    <USERNAME>

    User with the role of Defender Manager or higher.

    <PASSWORD>

    User’s password.

  3. Validate that you are authorized to access the Prisma Cloud API. Use the token you just retrieved to get a list of deployed Defenders.

    $ curl \
      -H "authorization: Bearer <TOKEN>" \
      https://<COMPUTE_CONSOLE>:8083/api/v1/defenders
  4. Download and run the Defender install script.

    $ curl \
      -H "authorization: Bearer <TOKEN>" \
      -X POST \
      https://<COMPUTE_CONSOLE>:8083/api/v1/scripts/defender.sh \
      -o defender.sh && \
      chmod a+x defender.sh && \
      sudo ./defender.sh -c "<CONSOLE>" -d "none"

    To see what options can be passed to the install script, go the Defender deployment page in Console at Manage > Defenders > Deploy, play with the various configuration settings, and observe the changes to the resulting curl-bash script.

3. Install a stand-alone Defender (no Docker)

Prisma Cloud Defender can be installed on hosts that do not run Docker. In this setup, Defender is installed as a service rather than a container. After downloading the Defender install script from the API, run it with the mandatory --install-host option.

Other options that can be passed to the install script include:

--install-folder

Specifies the install folder. By default, it is /opt/twistlock.

--install-data-folder

Specifies the data folder. By default, it is /var/lib/twistlock.

--ws-port

Specifies the websocket communication port. By default, it is 8084.

  1. Retrieve an auth token from Console, where <USER> must have the role of Defender Manager, or higher.

    $ curl -H "Content-Type: application/json" \
      -d '{"username":"<USERNAME>", "password":"<PASSWORD>"}' \
      https://<COMPUTE_CONSOLE>:8083/api/v1/authenticate
  2. Download and run the Defender install script with the --install-host option.

    $ curl \
      -H "authorization: Bearer <TOKEN>" \
      -X POST \
      https://<COMPUTE_CONSOLE>:8083/api/v1/scripts/defender.sh \
      -o defender.sh && \
      chmod a+x defender.sh && \
      sudo ./defender.sh -c "<COMPUTE_CONSOLE>" -d "none" --install-host

4. Install a Defender DaemonSet

You can deploy a Defender DaemonSet to your Kubernetes or OpenShift cluster using the Prisma Cloud API. Use the /api/v1/defenders/daemonset.yaml API endpoint to create a DaemonSet configuration file for Defender. This endpoint accepts a number of parameters to customize the configuration file for your environment.

Defender requires a handful of kernel capabilities to function. When AppArmor is enabled in your cluster, which is the case when nodes run Ubuntu, Defenders must run as privileged to acquire those capabilities. With AppArmor, pods are started with the default runtime profile, runtime/default, unless a specific profile is explicitly specified. The YAML file generated by the Prisma Cloud tools (twistcli, API) does not explicitly set a profile, but sets privileged to true. When privileged is true, Defender runs unconfined (no profile).

A deployment consists of the following steps:

  • Delete any old Defender deployment configurations.

  • Retrieve a daemon set configuration from the Prisma Cloud API.

  • Create the Defender daemon set.

  1. (Optional) Delete any old Kubernetes/OpenShift configurations:

    Before installing or upgrading, any existing Prisma Cloud DaemonSet components must be removed. They will be re-installed again right after this step. The following items should be deleted from the namespace they were created in:

    • The .twistlock directory in the current path, which is a remnant of previous Prisma Cloud installations.

    • DaemonSet: twistlock-defender-ds

    • ServiceAccount: twistlock-service

    • Secrets: twistlock-secrets

    • Security Context Constraints (OpenShift only): twistlock-scc

    • Namespace: The default namespace is twistlock, but it can be overridden by the user at install time.

  2. Retrieve a Defender DaemonSet configuration file, setting the appropriate parameters for your environment.

    The following call generates the same YAML file as the default twistcli invocation for Kubernetes:

    $ curl -k \
      -u <USER> \
      -X POST \
      'https://<COMPUTE_CONSOLE>:8083/api/v1/defenders/daemonset.yaml?consoleaddr=<COMPUTE_CONSOLE>&namespace=twistlock&orchestration=kubernetes&privileged=true' \
      > defender.yaml

    The following command generates the same YAML file as the default twistcli invocation for OpenShift:

    $ curl -k \
      -u <USER> \
      -X POST \
      'https://<COMPUTE_CONSOLE>:8083/api/v1/defenders/daemonset.yaml?consoleaddr=<COMPUTE_CONSOLE>&namespace=twistlock&orchestration=openshift' \
      > defender.yaml
  3. Create the DaemonSet.

    For Kubernetes:

    kubectl create -f defender.yaml

    For OpenShift:

    oc create -f defender.yaml

    For Google Cloud deployments, you might not have access to the cluster’s master node. In this case, use kubectl proxy. Click the Connect button beside your cluster, gives you a command like this:

    $ gcloud container clusters get-credentials aqsa-test \
      --zone us-central1-a --project twistlock

    Then run:

    $ kubectl proxy