Prisma Public Cloud Vulnerability Scan API (BETA)

Scan docker images & VMs for vulnerabilities for free!

Prisma Public Cloud Vulnerability Scan API is a free public API service that helps developers and security teams identify vulnerabilities in packages installed in their OS. It accepts a list of packages installed in the OS and responds with details about the vulnerabilities found in those packages. You can use this service to scan docker images and VMs.

Quickstart

Here is an example to get started. To scan a repo/imagename:tag docker image, run the following command:

docker run --env rl_args="report=detail" --rm --user 0 --entrypoint "/bin/sh" repo/imagename:tag -c 'SCAN_CMD=$(eval "curl -s https://vscanapidoc.redlock.io/scan.sh") && echo "$SCAN_CMD" | sh'

Just replace repo/imagename:tag with values e.g.

docker run --env rl_args="report=detail" --rm --user 0 --entrypoint "/bin/sh" linuxserver/mysql -c 'SCAN_CMD=$(eval "curl -s https://vscanapidoc.redlock.io/scan.sh") && echo "$SCAN_CMD" | sh'

Note that the curl package must be installed in the image that you scanning. You may save the following script as ./scan-general.sh which installs the curl package and then simply scan any image by running ./scan-general.sh image e.g. ./scan-general.sh harisekhon/hbase-dev

image=$1
docker run --env rl_args="report=detail"  -it --rm --user 0 --entrypoint "/bin/sh" $image -c '(apt-get update && apt-get install curl -y) || (apk update && apk add curl) || (yum install curl -y );SCAN_CMD=$(eval "curl -s https://vscanapidoc.redlock.io/scan.sh") && echo "$SCAN_CMD" | sh'

FAQs

  1. What if I want to prevent docker images from being built if they have vulnerabilities?

    Sure, here is an example. Given the following Dockerfile,

     FROM redmine:4.0.1
     ARG rl_args
     RUN apt-get update && apt-get install -yq curl
     RUN SCAN_CMD=$(eval "curl https://vscanapidoc.redlock.io/scan.sh 2>/dev/null") && echo "$SCAN_CMD" | sh
    

    Buliding this image docker build -t redmine -f Dockerfile . will result in the following output:

      {
       "Report": {
         "Summary": {
           "high_cve_count": 39,
           "medium_cve_count": 324,
           "low_cve_count": 103,
           "unknown_cve_count": 12,
           "total_cve_count": 478,
           "total_packages_count": 147,
           "failure_reason": "threshold_exceeded"
         }
       }
     }
     The command '/bin/sh -c SCAN_CMD=$(eval "curl https://vscanapidoc.redlock.io/scan.sh 2>/dev/null") && echo "$SCAN_CMD" | sh' returned a non-zero code: 1
    

    Oops! Turns out we are building an image which has vulnerable packages installed and as such the build fails.

  2. How do I fail the build only if there are certain number of severe vulnerabilities? Here is an example. --build-arg rl_args="max_medium=1" By specifying your build-arg with the value for the max_medium flag, your image will be built successfully if it has at most one medium vulnerability. The general format is max_{severity} flags (where severity is either critical, high, or medium).

    To get a more detailed information about the vulnerabilities while bypassing the vulnerability check: docker build -t foobar/foo:bar -f Dockerfile . --build-arg rl_args="report=detail;bypass_scan_result=true"

  3. What’s the availability of your service? What if your service is down?

    Our service is run in three different geographic data centers (AWS Regions) to provide the best possible experience and availability for users across the world.

    If the service is down, we take a fail-close approach. If you want to bypass the failure in your builds if our service is down, you can set the bypass_scan_service flag to true e.g

    docker build -t foobar/foo:bar -t service_down_example -f Dockerfile . --build-arg rl_args="bypass_scan_service=true"

  4. Can I see a list of available arguments?

    See the list below. Just make sure that you have ARG rl_args specified in the Dockerfile before you use them. You can combine multiple arguments like this- rl_args="rl-arg-1=foo;rl-arg-2=bar". Notice that they are separated by a ;

    Build Argument Subparameter Examples / Options Description
    report detail, summary (default=summary) If the report is set to detail, the JSON response will have in-depth information about the image’s vulnerabilities. If the report is set to summary, the JSON response will just showcase a count of different severities in the image.
    group_by package, vuln (default=package) The report will aggregate JSON by either packages or vulnerabilities (CVE).
    bypass_scan_result true, false (default=false) If set to true, the image will successfully build even if it has vulnerabilities.
    bypass_scan_service true, false (default=false) If set to true, the image will successfully build even if the service is down, skipping the scan.
    whitelist_package_list curl, libssh A sequence of comma-separated packages that are whitelisted from the results of the vulnerability scan. Note: If a package is whitelisted, but a CVE of the package is blacklisted, then the whitelist will take priority.
    whitelist_cve_list CVE-2019-123, CVE-2019-124 A sequence of comma-separated CVEs that are whitelisted from the results of the vulnerability scan.
    blacklist_package_list curl, libssh A sequence of comma-separated packages that are blacklisted from the results of the vulnerability scan. Note: In the case that a CVE is whitelisted but the package that contains the vulnerability is under the blacklist, the blacklist will take priority.
    blacklist_cve_list CVE-2019-123, CVE-2019-124 A sequence of comma-separated CVEs that are blacklisted from the results of the vulnerability scan.
    required_package_list SELinux, bash A sequence of comma-separated packages that are required in the image.
    max_critical 0 (default=0) If there are more critical severity vulnerabilities than this parameter, the image is deemed vulnerable and the image build will fail.
    max_high 5 (default=0) If there are more high severity vulnerabilities than this parameter, the image is deemed vulnerable and the image build will fail.
    max_medium 10 (default=0) If there are more medium severity vulnerabilities than this parameter, the image is deemed vulnerable and the image build will fail.
    ignore_no_patch true (default=false) If set to true, ignore vulnerabilities that has no package version with a fix.
  5. Does the service work only for Docker containers?

    No. Our service is container-agnostic and can even work on Amazon AMIs. As long as your OS distribution is supported by our API, and the corresponding files exist in your filesystem, you are able to detect vulnerabilities in your packages.

  6. How often can I call the API? This service limits your usage to 1 call per second per caller IP address.

  7. Does the service work for all images? Our service works for most images. For example, the Dockerhub official image busybox fails because it is so minimal it does not have the necessary package information for a scan. To get more information about the server response, look at the X-RedLock-Scancode header.

    X-RedLock-Scancode Description
    pass The packages pass the vulnerability scan.
    fail The packages do not pass the vulnerability scan.
    missingData The request is missing data.
    invalidRequest The request is invalid.
    internalError The server failed to generate a response.
  8. Are you seriously asking me to run a script that you host?

    Curl bash piping is frowned upon. You are welcome to call our API directly. After all, the script we provide effectively fetches the list of packages, OS version and calls the API. Here are a couple examples of how to call our service directly:

    Alpine Example:

     FROM alpine
     RUN apk add curl
     RUN curl -i -s -X POST https://scanapi.redlock.io/v1/vuln/os  \
     -F "fileName=/etc/alpine-release" -F "file=@/etc/alpine-release" \
     -F "fileName=/lib/apk/db/installed" -F "file=@/lib/apk/db/installed" \
     -F "rl_args=report=detail" | grep -i "x-redlock-scancode: pass"
    

    Debian/Ubuntu Example:

     FROM ubuntu
     RUN apt-get update && apt-get install -y curl
     RUN curl -i -s -X POST https://scanapi.redlock.io/v1/vuln/os  \
     -F "fileName=/etc/os-release" -F "file=@/etc/os-release" \
     -F "fileName=/var/lib/dpkg/status" -F "file=@/var/lib/dpkg/status" \
     -F "rl_args=report=detail" | grep -i "x-redlock-scancode: pass"
    

    RHEL/Centos Example:

     FROM centos
     RUN yum install curl
     RUN rpm -qa --qf '%{NAME} %{EPOCH}:%{VERSION}-%{RELEASE}\n' \
     | curl -i -s -X POST https://scanapi.redlock.io/v1/vuln/os  \
     -F "fileName=/etc/os-release" -F "file=@/etc/os-release" \
     -F "fileName=rpm_output" -F "file=@-" -F "rl_args=report=detail" | grep -i "x-redlock-scancode: pass"
    
  9. How can I version control the scan argments Simply store the value of rl_args in a file and read arguments from the file:

     $ cat rl_args.txt
     report=detail;bypass_scan_result=true
    
     $ rl_args=$(cat rl_args.txt); docker build --build-arg rl_args="$rl_args" .
    

    How do I get help on these services? You can contact us at prisma-scanapi-support@paloaltonetworks.com

Integrations

Azure Pipelines

Simply update the task which builds the docker image. For example, if you have the following pipeline:

# Docker  
# Build a Docker image   
# [https://docs.microsoft.com/azure/devops/pipelines/languages/docker](https://docs.microsoft.com/azure/devops/pipelines/languages/docker)  
  
trigger:  
- master  
  
resources:  
- repo: self  
  
variables:  
  tag: '$(Build.BuildId)'  
  
stages:  
- stage: Build  
  displayName: Build image  
  jobs:    
  - job: Build  
    displayName: Build  
    pool:  
      vmImage: 'ubuntu-latest'  
    steps:  
  
    - task: CmdLine@2  
      inputs:  
       script: |  
         docker build --tag dotnet . 

all you have to do is add the following line after docker build command:

docker run --env rl_args="" --rm --user 0 --entrypoint "/bin/sh" dotnet -c '(apt-get update && apt-get install curl -y) || (apk update && apk add curl) || (yum install curl -y );SCAN_CMD=$(eval "curl -s [https://vscanapidoc.redlock.io/scan.sh"](https://vscanapidoc.redlock.io/scan.sh%22)) && echo "$SCAN_CMD" | sh'

Here is a complete example:

# Docker  
# Build a Docker image   
# [https://docs.microsoft.com/azure/devops/pipelines/languages/docker](https://docs.microsoft.com/azure/devops/pipelines/languages/docker)  
  
trigger:  
- master  
  
resources:  
- repo: self  
  
variables:  
  tag: '$(Build.BuildId)'  
  
stages:  
- stage: Build  
  displayName: Build image  
  jobs:    
  - job: Build  
    displayName: Build  
    pool:  
      vmImage: 'ubuntu-latest'  
    steps:  
  
    - task: CmdLine@2  
      inputs:  
       script: |  
         docker build --tag  foo .  
         docker run --env rl_args="report=detail" --rm --user 0 --entrypoint "/bin/sh" foo -c 'SCAN_CMD=$(eval "curl -s https://vscanapidoc.redlock.io/scan.sh") && echo "$SCAN_CMD" | sh'