1. Home
    2. Prisma
    3. Prisma Cloud
    4. Prisma Cloud Compute Edition Administrator’s Guide
    5. Runtime defense
    6. Image analysis sandbox
    End-of-Life (EoL)

    Image analysis sandbox

    The image analysis sandbox lets you dynamically analyze the runtime behaviour of images before running them in your development and production environments.
    The analysis mechanism collects and displays container behaviours by safely exercising the image in a sandbox machine. It also exposes risks and identifies suspicious dependencies buried deep in your software supply chain that would otherwise be missed by static analysis for vulnerabilities and compliance issues.
    Running the analysis is supported for Linux images on Docker container runtime.

    Setup the sandbox machine

    In order to run a sandbox analysis for an image, you first need to set up a dedicated sandbox virtual machine.
    Prerequisites
    :
    • The twistcli tool should exist on the machine.
    • The sandbox machine should have connectivity to Prisma Cloud Compute Console.
    • The machine must be a Linux VM.
    • Docker should be installed on the machine.
    When setting up the VM, follow the guidelines below to make sure potential malware doesn’t exploit your sandbox:
    • Make sure that the kernel is up to date.
    • Make sure that Docker and Runc are up to date.
    • Make sure all the software components on the machine are up to date (to make sure there is no other vulnerable component on the machine).
    • The VM should be as isolated as possible. Run the VM in a dedicated network, separate from production. If other services run alongside the sandbox VM in the same local network, set up firewall rules to ensure the sandbox VM cannot reach them.
    • If the VM runs in the cloud, it shouldn’t run with any service account.
    It is recommended to avoid running a Defender on the same machine used as the sandbox VM. Running a Defender on this machine might cause the image that is being analyzed in the sandbox to also be presented under
    Monitor > Vulnerabilities/Compliance > Images > Deployed images
     as an image running in the environment.

    Setup the sandbox user

    Create a dedicated, least-privileged user for running the image analysis sandbox.
    Running the sandbox with a privileged role (Admin, Operator) is a risk in case a malware escapes (by using a zero day, one day, exploit misconfiguration, etc.), and can potentially use this role to take over Prisma.
    1. Create a custom role under
      Manage > Authentication > Roles
       with Write permissions for Container Runtime Results and Read permissions for CI Results. For roles created via the API, also add Write permission for User.
    2. Create a sandbox user and assign it with the new custom role you created.
    3. When triggering the sandbox analysis via twistcli, use the sandbox user credentials. It is recommended to use a short-lived token (available under
      Manage > System > Utilities
      ) rather then a username and password.

    Running the sandbox command

    Description

    Triggering a sandbox analysis is done by executing the twistcli sandbox command on an image. After the command is triggered, Prisma Cloud’s sandbox mechanism runs the container, and starts tracing its behaviour. The events occuring on the running container are collected, and are later being analyzed to discover suspicious behaviours.

    Synopsis

    The usage of the twistcli sandbox command is very similar to running a container image using docker:
    $ twistcli sandbox [OPTIONS] IMAGE [COMMAND] [ARG...]
    For example:
    $ twistcli sandbox --address https://<console-address>:8083 --token 'your-api-token' --analysis-duration 2m -v "$PWD":/app python:3 python3 /app/server.py
    To specify an image to scan, use either the image ID, or repository name and tag. The image should be present on the sandbox machine, having either been built or pulled there. If a repository is specified without a tag, twistcli looks for an image tagged latest.
    The entrypoint and arguments should be specified after the image. If an entrypoint isn’t specified, the default entrypoint of the image will be used.

    Options

    • Complete URL for Console, including the protocol and port. Only the HTTPS protocol is supported. By default, Console listens to HTTPS on port 8083, although your administrator can configure Console to listen on a different port. Defaults to https://127.0.0.1:8083.
      Example: --address https://console.example.com:8083
    • Username to access Console. If not provided, the TWISTLOCK_USER environment variable will be used if defined, or "admin" is used as the default.
    • Password for the user specified with -u, --user. If not specified on the command-line, the TWISTLOCK_PASSWORD environment variable will be used if defined, or otherwise will prompt for the user’s password before the scan runs.
    • Interface with a specific supervisor Console to publish the results.
    • Write the results of the analysis to a file in JSON format.
    • The duration of the analysis in a Go duration string format. The default duration is 1 minute.
      Adjust the duration according to your image. A longer duration may allow detecting more behaviours. An analysis duration that is too short might cause missing some of the suspicious findings that could have been detected on the container.
      The analysis duration can be shorter than the duration you specified, if the container exits before the analysis time ends.
      When WildFire integration is enabled, the analysis duration can be longer than specified, since the communication with WildFire may take longer than the analysis duration. When the specified duration is met, Prisma Cloud stops the container, so no more events are collected, but is waiting for WildFire verdict to publish the results.
    • A key=value pair to define an environment variable in the running container. Repeat flag for each environment variable.
    • A src:dst pair to mount a volume to the running container. Repeat flag for each mount.
      Any volume that is shared with the sandbox will be accessible to a potential malware exists on the container. Therefore, carefully consider the usage of volumes.
    • Working directory inside the container.
    • A host_port:container_port[/tcp|udp] pair to bind a host port the running container’s port. Repeat for each port. Port ranges are not supported.
    • Path to Prisma Cloud CA certificate file. If no CA certificate is specified, the connection to Console is insecure.
    • Token to use for Prisma Cloud Console authentication. Tokens can be retrieved from the API endpoint api/v1/authenticate or from the
      Manage > System > Utilities
       page in Console.
    • --
      Show help

    Return value

    The twistcli sandbox command exits with a success or failure return value. The exit code is 1 if twistcli sandbox failed due to an error. Otherwise, the exit code is 0.
    When an exit code of 0 is returned, meaning the analysis completed successfully, check the analysis data to determine the verdict for the image.

    Sandbox analysis results

    After twistcli dynamically analyzes the image, twistcli:
    • Exits with a return value.
    • Outputs a summary of the results, including a verdict.