Skip to content

Latest commit

 

History

History
345 lines (302 loc) · 14.8 KB

README.md

File metadata and controls

345 lines (302 loc) · 14.8 KB
Raw

Kubescape action

Run security scans on your Kubernetes manifests and Helm charts as a part of your CI using the Kubescape action. Kubescape scans Kubernetes clusters, YAML files, and HELM charts, detecting misconfigurations according to multiple frameworks (such as the NSA-CISA , MITRE ATT&CK® and CIS Benchmark), software vulnerabilities.

Usage

Scanning with Kubescape

To scan your repository with Kubescape in your Github workflow, add the following steps to your workflow configuration:

name: Kubescape scanning for misconfigurations
on: [push, pull_request]
jobs:
  kubescape:
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write
    steps:
    - uses: actions/checkout@v3
    - uses: kubescape/github-action@main
      continue-on-error: true
      with:
        format: sarif
        outputFile: results
        # # Optional: Specify the Kubescape Portal credentials 
        # account: ${{secrets.KUBESCAPE_ACCOUNT}}
        # accessKey: ${{secrets.KUBESCAPE_ACCESS_KEY}}
        # server: ${{ vars.KUBESCAPE_SERVER }}
        # # Optional: Scan a specific path. Default will scan the whole repository
        # files: "examples/*.yaml"
    - name: Upload Kubescape scan results to Github Code Scanning
      uses: github/codeql-action/upload-sarif@v2
      with:
        sarif_file: results.sarif

This workflow definition scans your repository with Kubescape and publishes the results to Github. You can then see the results in the Pull Request that triggered the scan and the Security → Code scanning tab.

Automatically Suggest Fixes

To make Kubescape automatically suggest fixes to your pull requests by code review, use the following workflow:

name: Suggest autofixes with Kubescape for PR by reviews
on:
  pull_request_target:

jobs:
  kubescape-fix-pr-reviews:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write

    steps:
    - uses: actions/checkout@v3
      with:
        fetch-depth: 0
        ref: ${{github.event.pull_request.head.ref}}
        repository: ${{github.event.pull_request.head.repo.full_name}}
    - name: Get changed files
      id: changed-files
      uses: tj-actions/changed-files@v35
    - uses: kubescape/github-action@main
      with:
        account: ${{secrets.KUBESCAPE_ACCOUNT}}
        accessKey: ${{secrets.KUBESCAPE_ACCESS_KEY}}
        server: ${{ vars.KUBESCAPE_SERVER }}
        files: ${{ steps.changed-files.outputs.all_changed_files }}
        fixFiles: true
        format: "sarif"
    - name: PR Suggester according to SARIF file
      if: github.event_name == 'pull_request_target'
      uses: HollowMan6/[email protected]
      with:
        file: 'results.sarif'
        level: warning

The above workflow works by collecting the SARIF (Static Analysis Results Interchange Format) file that kubescape generates. Then, with the help of HollowMan6/sarif4reviewdog, convert the SARIF file into RDFormat (Reviewdog Diagnostic Format) and generate reviews using Reviewdog.

You can also make Kubescape automatically suggest fixes for the pushes to your main branch by opening new PRs with the following workflow:

name: Suggest autofixes with Kubescape for direct commits by PR
on: 
  push:
    branches: [ main ]

jobs:
  kubescape-fix-commit:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

    steps:
    - uses: actions/checkout@v3
      with:
        fetch-depth: 0
    - name: Get changed files
      id: changed-files
      uses: tj-actions/changed-files@v35
    - uses: kubescape/github-action@main
      with:
        account: ${{secrets.KUBESCAPE_ACCOUNT}}
        accessKey: ${{secrets.KUBESCAPE_ACCESS_KEY}}
        server: ${{ vars.KUBESCAPE_SERVER }}
        files: ${{ steps.changed-files.outputs.all_changed_files }}
        fixFiles: true
        format: "sarif"
    - uses: peter-evans/create-pull-request@v4
      # Remember to allow GitHub Actions to create and approve pull requests
      # https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests
      if: github.event_name != 'pull_request_target'
      with:
        add-paths: |
          *.yaml
        commit-message: "chore: fix K8s misconfigurations"
        title: "[Kubescape] chore: fix K8s misconfigurations"
        body: |
          # What this PR changes

          [Kubescape](https://github.com/kubescape/kubescape) has found misconfigurations in the targeted branch. This PR fixes the misconfigurations that have automatic fixes available.

          You may still need to fix misconfigurations that do not have automatic fixes.
        base: ${{ github.head_ref }}
        branch: kubescape-auto-fix-${{ github.head_ref || github.ref_name }}
        delete-branch: true

The above workflow works by collecting the changes made directly to the original files. In the example above, a separate step that runs a different action opens the appropriate pull request. Due to how Github works, there are limitations on running and opening pull requests to forks. The action running in this step is maintained by its respective maintainers, and not the Kubescape team, so you should review its documentation when troubleshooting the process of triggering the workflow run and opening pull requests.

Please note that since Kubescape provides automatic fixes only to the rendered YAML manifests, the workflow above will not produce correct fixes for Helm charts.

The next important thing to note is that Kubescape only fixes the files. It does not open pull requests or generate code reviews on its own.

Scanning images

The Kubescape Github Action is also able to scan images. But you should be aware that image scanning cannot run in parallel with configuration scanning and file fixing at the moment. If you would like to run both image and configuration scanning, you should define at least two separate steps with the same action but different arguments: one for image scanning and the other for configuration scanning.

To scan a container image with a Kubescape Github Action, use the following workflow definition, keeping in mind that you need to replace image: "quay.io/kubescape/kubescape" with the appropriate image name:

name: Kubescape scanning for image vulnerabilities
on: [push, pull_request]
jobs:
  kubescape-scan-image:
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write
    steps:
    - uses: actions/checkout@v3
    - uses: kubescape/github-action@main
      continue-on-error: true
      with:
        image: nginx
        format: sarif
        outputFile: results.sarif
        # severityThreshold: "critical"
        # # Username for a private registry with the image
        # registryUsername: ${{secrets.REGISTRY_USERNAME}}
        # # Password for a private registry with the image
        # registryPassword: ${{secrets.REGISTRY_PASSWORD}}
        # # Fail at or above the specified vulnerability severity threshold
        # Kubescape Portal credentials
        # account: ${{secrets.KUBESCAPE_ACCOUNT}}
        # accessKey: ${{secrets.KUBESCAPE_ACCESS_KEY}}
        # server: ${{ vars.KUBESCAPE_SERVER }}
    - name: Upload Kubescape scan results to Github Code Scanning
      uses: github/codeql-action/upload-sarif@v2
      with:
        sarif_file: results.sarif

Inputs

Name Description Required
files YAML files or Helm charts to scan for misconfigurations. The files need to be provided with the complete path from the root of the repository. No (default is . which scans the whole repository)
outputFile Name of the output file where the scan result will be stored without the extension. No (default is results)
frameworks Security framework(s) to scan the files against. Multiple frameworks can be specified separated by a comma with no spaces. Example - nsa,devopsbest. Run kubescape list frameworks in the Kubescape CLI to get a list of all frameworks. Either frameworks have to be specified or controls. No
controls Security control(s) to scan the files against. Multiple controls can be specified separated by a comma with no spaces. Example - Configured liveness probe,Pods in default namespace. Run kubescape list controls in the Kubescape CLI to get a list of all controls. You can use either the complete control name or the control ID such as C-0001 to specify the control you want use. You must specify either the control(s) or the framework(s) you want used in the scan. No
account account ID for integrating with a third-party server No
accessKey access-key for integrating with a third-party server No
server URL for integrating with a third-party server No
failedThreshold Failure threshold is the percent above which the command fails and returns exit code 1 (default 0 i.e, action fails if any control fails) No (default 0)
severityThreshold Severity threshold is the severity of a failed control at or above which the command terminates with an exit code 1 (default is high, i.e. the action fails if any High severity control fails) No
verbose Display all of the input resources and not only failed resources. Default is off No
exceptions The JSON file containing at least one resource and one policy. Refer exceptions docs for more info. Objects with exceptions will be presented as exclude and not fail. No
controlsConfig The file containing controls configuration. Use kubescape download controls-inputs to download the configured controls-inputs. No
image The image you wish to scan. Launches an image scan, which cannot run together with configuration scans. No
registryUsername Username to a private registry that hosts the scanned image. No
registryPassword Password to a private registry that hosts the scanned image. No

Examples

Scan and submit results to the Kubescape Cloud

name: Kubescape scanning for misconfigurations
on: [push, pull_request]
jobs:
  kubescape:
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write
    steps:
    - uses: actions/checkout@v3
    - uses: kubescape/github-action@main
      continue-on-error: true
      with:
        format: sarif
        outputFile: results
        # Specify the Kubescape cloud account ID
        account: ${{secrets.KUBESCAPE_ACCOUNT}}
        accessKey: ${{secrets.KUBESCAPE_ACCESS_KEY}}
        server: ${{ vars.KUBESCAPE_SERVER }}
    - name: Upload Kubescape scan results to Github Code Scanning
      uses: github/codeql-action/upload-sarif@v2
      with:
        sarif_file: results.sarif

Scan specific file paths

Scan a spefic pathspec, for example examples/kubernetes-manifests/*.yaml:

name: Kubescape scanning for misconfigurations
on: [push, pull_request]
jobs:
  kubescape:
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write
    steps:
    - uses: actions/checkout@v3
    - uses: kubescape/github-action@main
      continue-on-error: true
      with:
        format: sarif
        outputFile: results
        # Scan a specific path. Default will scan the whole repository
        files: "examples/kubernetes-manifests/*.yaml"
    - name: Upload Kubescape scan results to Github Code Scanning
      uses: github/codeql-action/upload-sarif@v2
      with:
        sarif_file: results.sarif

Scan against specific frameworks

Perform a Kubescape scan against a list of specific frameworks (NSA and MITRE in this example):

name: Kubescape scanning for misconfigurations
on: [push, pull_request]
jobs:
  kubescape:
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v3
      - uses: kubescape/github-action@main
        continue-on-error: true
        with:
          format: sarif
          outputFile: results
          frameworks: |
            nsa,mitre
      - name: Upload Kubescape scan results to Github Code Scanning
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: results.sarif

Fail Kubescape scanning based on the percentage of failed controls

Scan a repository with Kubescape and fail the scanning step if the percent of failed controls is more than the specified failedThreshold:

name: Kubescape scanning for misconfigurations
on: [push, pull_request]
jobs:
  kubescape:
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v3
      - uses: kubescape/github-action@main
        continue-on-error: false
        with:
          format: sarif
          outputFile: results
          failedThreshold: 50
      - name: Upload Kubescape scan results to Github Code Scanning
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: results.sarif

Fail Kubescape scanning based on maximum severity of a failed control

Scan a repository with Kubescape and fail the scanning step if the scan has found failed controls with severity of Medium and above:

name: Kubescape scanning for misconfigurations
on: [push, pull_request]
jobs:
  kubescape:
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write
    steps:
      - uses: action/checkout@v3
      - uses: kubescape/github-action@main
        continue-on-error: false
        with:
          format: sarif
          outputFile: results
          severityThreshold: medium
      - name: Upload Kubescape scan results to Github Code Scanning
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: results.sarif