deep-security / smartcheck-scan-action

A GitHub Action for scanning using Deep Security Smart Check.
Apache License 2.0
15 stars 9 forks source link
github-action

Deep Security Smart Check Scan Action

Scan your containers with Deep Security Smart Check.

This project was built by the Deep Security Smart Check team to help you to scan your containers in your CI/CD pipeline, you can use as a standalone Docker container published in the Dockerhub to scan your images. This tool is also used by the Deep Security Smart Check plugin for Jenkins and the GitHub Action, that wraps the container published in Dockerhub.

Requirements

Usage

Add an Action in your .github/workflow yml file to scan your image with Deep Security Smart Check.

- name: Deep Security Smart Check
  # Be sure to specify the latest version of smartcheck-scan-action
  uses: deep-security/smartcheck-scan-action@v1.1.0
   with:
      # Mandatory
      DSSC_IMAGE_NAME: registryhost/myimage
      DSSC_SMARTCHECK_HOST: smartcheck.example.com
      DSSC_SMARTCHECK_USER: admin
      DSSC_SMARTCHECK_PASSWORD: 12345
      DSSC_IMAGE_PULL_AUTH: {"username":"<user>","password":"<password>"}

      # Optional
      DSSC_INSECURE_SKIP_TLS_VERIFY: true
      DSSC_INSECURE_SKIP_REGISTRY_TLS_VERIFY: true
      DSSC_PREREGISTRY_SCAN: false
      DSSC_PREREGISTRY_HOST: pre-registryhost.com
      DSSC_PREREGISTRY_USER: admin
      DSSC_PREREGISTRY_PASSWORD: 12345
      DSSC_RESULTS_FILE: /results.json
      DSSC_FINDINGS_THRESHOLD: '{"malware": 100, "vulnerabilities": { "defcon1": 100, "critical": 100, "high": 100 }, "contents": { "defcon1": 100, "critical": 100, "high": 100 }, "checklists": { "defcon1": 100, "critical": 100, "high": 100 }}'    

Parameters

All parameters can be passed as CLI parameters or environment variables by switching to all caps and prefixing with DSSC_. Example: --image-name could be given with DSSC_IMAGE_NAME.

[deep security smart check api reference]: https://deep-security.github.io/smartcheck-docs/api/index.html [creating a scan]: https://deep-security.github.io/smartcheck-docs/api/index.html#operation/createScan

Example Workflow Using Github Actions

name: Deep Security Smart Check

on: 
  push:
    branches: 
      - master

jobs:      
    SmartCheck-Scan-Action:
       runs-on: ubuntu-latest
       steps:

       # AWS Example:
        - name: Deep Security Smart Check Scan ECR
          # Be sure to specify the latest version of smartcheck-scan-action
          uses: deep-security/smartcheck-scan-action@v1.1.0
          with:
            DSSC_IMAGE_NAME: myECRrepo/myimage
            DSSC_SMARTCHECK_HOST: ${{ secrets.DSSC_SMARTCHECK_HOST }}
            DSSC_SMARTCHECK_USER: ${{ secrets.DSSC_SMARTCHECK_USER }}
            DSSC_SMARTCHECK_PASSWORD: ${{ secrets.DSSC_SMARTCHECK_PASSWORD }}
            # You will need to generate an access key and secret for your AWS user
            DSSC_IMAGE_PULL_AUTH: '{"aws":{"region":"us-east-1","accessKeyID":"$AWS_ACCESS_KEY_ID","secretAccessKey":"$AWS_SECRET_ACCESS_KEY"}}'
            DSSC_FINDINGS_THRESHOLD: '{"malware": 100, "vulnerabilities": { "defcon1": 100, "critical": 100, "high": 100 }, "contents": { "defcon1": 100, "critical": 100, "high": 100 }, "checklists": { "defcon1": 100, "critical": 100, "high": 100 }}'
            DSSC_INSECURE_SKIP_TLS_VERIFY: true
            DSSC_INSECURE_SKIP_REGISTRY_TLS_VERIFY: true

        # Azure Example:
        - name: Deep Security Smart Check Scan ACR
          # Be sure to specify the latest version of smartcheck-scan-action
          uses: deep-security/smartcheck-scan-action@v1.1.0
          with:
            DSSC_IMAGE_NAME: myrepo.azurecr.io/myimage
            DSSC_SMARTCHECK_HOST: ${{ secrets.DSSC_SMARTCHECK_HOST }}
            DSSC_SMARTCHECK_USER: ${{ secrets.DSSC_SMARTCHECK_USER }}
            DSSC_SMARTCHECK_PASSWORD: ${{ secrets.DSSC_SMARTCHECK_PASSWORD }}
            DSSC_IMAGE_PULL_AUTH: '{"username": "${{ secrets.ACR_USER }}","password": "${{ secrets.ACR_PASSWORD }}"}'
            DSSC_FINDINGS_THRESHOLD: '{"malware": 100, "vulnerabilities": { "defcon1": 100, "critical": 100, "high": 100 }, "contents": { "defcon1": 100, "critical": 100, "high": 100 }, "checklists": { "defcon1": 100, "critical": 100, "high": 100 }}'            DSSC_INSECURE_SKIP_TLS_VERIFY: true
            DSSC_INSECURE_SKIP_REGISTRY_TLS_VERIFY: true

        - name: Cloud One Container Security Scan GCR
          # Be sure to specify the latest version of smartcheck-scan-action
          uses: deep-security/smartcheck-scan-action@v1.1.0
          with:
            DSSC_IMAGE_NAME: region.gcr.io/projectname/myimage
            DSSC_SMARTCHECK_HOST: ${{ secrets.DSSC_SMARTCHECK_HOST }}
            DSSC_SMARTCHECK_USER: ${{ secrets.DSSC_SMARTCHECK_USER }}
            DSSC_SMARTCHECK_PASSWORD: ${{ secrets.DSSC_SMARTCHECK_PASSWORD }}
            # You will need to generate a JSON service account key in GCP and save it as a secret
            DSSC_IMAGE_PULL_AUTH: '{"username": "_json_key", "password": "${{ secrets.GCP_JSON_KEY }}"}'
            DSSC_FINDINGS_THRESHOLD: '{"malware": 100, "vulnerabilities": { "defcon1": 100, "critical": 100, "high": 100 }, "contents": { "defcon1": 100, "critical": 100, "high": 100 }, "checklists": { "defcon1": 100, "critical": 100, "high": 100 }}'            DSSC_INSECURE_SKIP_TLS_VERIFY: true
            DSSC_INSECURE_SKIP_REGISTRY_TLS_VERIFY: true

The example above demonstrates how to add a Smartcheck Scan action as a step in your Github Worflow. This can be used to scan an image from a container registry in either Google Container Registry, Microsoft Azure Container Registry or Amazon Elastic Container Registry.

For Google Container Registry and Microsoft Azure Container Registry, the username and password required for DSSC_IMAGE_PULL_AUTH are the same as the docker login credentials you would use to authenticate to a registry in the provided platform:

To authenticate to an Amazon Elastic Container Registry the DSSC_IMAGE_PULL_AUTH should be formatted to match the credentials.aws object specified in the Smartcheck API Documentation to create a Scan.

Example Workflow Running a Docker Container

name: Deep Security Smart Check Pipeline Example

on: 
  push:
    branches: 
      - master

jobs:      
    SmartCheck-Scan-Action:
       runs-on: ubuntu-latest
       steps:
        - name: Deep Security Smart Check
          run: |
          docker run deepsecurity/smartcheck-scan-action --image-name registryhost/myimage --smartcheck-host=smartcheck.example.com --smartcheck-user=admin --smartcheck-password=12345 --image-pull-auth='{"username":"<user>","password":"<password>"}'          

Pre-registry scanning

To enable pre-registry scanning, you will need to provide the preregistry-scan, preregistry-user, and preregistry-password parameters to the scan. If you are running the temporary registry as a separate service or on a port other than 5000, you will also need to provide the preregistry-host parameter, specifying the hostname and port number where you are running the temporary registry.

IMPORTANT: The pre-registry scan needs access to the Docker daemon through the Docker socket, so if you are running the scan action as a container, make sure to mount /var/run/docker.sock. If you are using smartcheck-scan-action as a GitHub Action, the runtime environment will do this step for you.

Contributing

If you encounter a bug, think of a useful feature, or find something confusing in the docs, please create a new issue!

We :heart: pull requests. If you'd like to fix a bug, contribute to a feature or just correct a typo, please feel free to do so.

If you're thinking of adding a new feature, consider opening an issue first to discuss it to ensure it aligns to the direction of the project (and potentially save yourself some time!).

Support

Official support from Trend Micro is not available. Individual contributors may be Trend Micro employees, but are not official support.