
GitHub Action
Introduction
The Xanitizer Github Action runs a security analysis in a GitHub workflow using Xanitizer to automatically detect vulnerabilities in your code by:
- Downloading and installing the latest version of Xanitizer.
- Running a security analysis with default or with project specific settings.
- Optionally breaking the build in case of e.g. some finding has a rating that is equal or larger than a defined value.
- Exporting the detected vulnerabilties as report files which can optionally be archived using the actions/upload-artifact action or uploaded via the github/codeql-action/upload-sarif action into the GitHub code scanning alert section of your repository.
Compatibility
GitHub Action | Xanitizer |
---|---|
1.0.1 | ≥ 5.1 |
Prerequisites
To use this xanitizer-action
in a GitHub workflow, some prerequisites have to be fullfilled.
Xanitizer license
Xanitizer needs a license file to be executed. For this, the content of the license file has to be stored as a GitHub secret, e.g. XANITIZER_LICENSE
inside the repository settings (Creating and storing encrypted secrets). After storing the content as a GitHub secret, the license can be referenced like this:
- uses: RIGS-IT/xanitizer-action@v1 with: license: ${{ secrets.XANITIZER_LICENSE }}
Prerequisite for Java Projects
Xanitizer needs a compiled Java project, because Xanitizer does not only look at the source code, but it primarily analyzes the byte code. As a static application security testing (SAST) tool, Xanitizer requires that all dependencies of analyzed artifacts can be successfully resolved. So you have to compile your project before running the security analysis, e.g. via Maven:
# Compile the code for Java projects and get all libraries, e.g. via Maven - run: mvn -B compile # Run the security analysis with default settings - name: Xanitizer Security Analysis uses: RIGS-IT/xanitizer-action@v1 with: license: ${{ secrets.XANITIZER_LICENSE }}
Prerequisite for JavaScript Projects
Xanitizer requires that all dependencies of artifacts being analyzed can be successfully resolved. To support this all used libraries have to be installed before running the security analysis, e.g. via npm install
:
# Install all dependend libraries for JavaScript/TypeScript project, e.g. via npm - run: npm install # Run the security analysis with default settings - name: Xanitizer Security Analysis uses: RIGS-IT/xanitizer-action@v1 with: license: ${{ secrets.XANITIZER_LICENSE }}
Usage
This action can be run on ubuntu-latest
and windows-latest
GitHub Actions runners.
An example workflow which runs a Xanitizer security analysis and then archives the findings list reports and uploads the findings into the GitHub code scanning alert section of your repository can be found here.
Basic
The basic configuration runs a security analysis with the Xanitizer default settings and exports a Xanitizer-Findings-List.pdf
and Xanitizer-Findings-List.sarif
report containing all problematic findings with their details in the root directory of the repository that has been checked out.
name: "Xanitizer Security Analysis" on: # Run the workflow on each push # push: # Run the workflow each day at 5 am # schedule: # - cron: '0 5 * * *' # Run the workflow manually workflow_dispatch: jobs: xanitizer-security-analysis: # Xanitizer runs on ubuntu-latest and windows-latest. runs-on: ubuntu-latest steps: # Check out the repository - uses: actions/checkout@v2 # Compile the code for Java projects and get all libraries, e.g. via Maven - run: mvn -B compile # Install all dependent libraries for JavaScript/TypeScript project, e.g. via npm - run: npm install # Run the security analysis with default settings - name: Xanitizer Security Analysis uses: RIGS-IT/xanitizer-action@v1 with: license: ${{ secrets.XANITIZER_LICENSE }}
Integration into the GitHub Code Scanning Alert Section
In the basic configuration, Xanitizer exports a Xanitizer-Findings-List.sarif
report containing all problematic findings with their details into the root directory of the repository that has been checked out. This exported SARIF file can be uploaded to the GitHub code scanning alert section of your repository via the github/codeql-action/upload-sarif
action.
steps: # Check out the repository - uses: actions/checkout@v2 # Compile the code for Java projects and get all libraries, e.g. via Maven - run: mvn -B compile # Install all dependent libraries for JavaScript/TypeScript project, e.g. via npm - run: npm install # Run the security analysis with default settings - name: Xanitizer Security Analysis uses: RIGS-IT/xanitizer-action@v1 with: license: ${{ secrets.XANITIZER_LICENSE }} # Uploads results.sarif to GitHub using the upload-sarif action - uses: github/codeql-action/upload-sarif@v1 with: sarif_file: Xanitizer-Findings-List.sarif
Exporting and Archiving Overview and Finding Lists Reports
If none of the parameters overviewReportOutputFile
, overviewReportOutputFiles
, findingsListReportOutputFile
, or findingsListReportOutputFiles
are specified, Xanitizer exports only a Xanitizer-Findings-List.pdf
and Xanitizer-Findings-List.sarif
report containing all problematic findings with their details into the root directory of the repository that has been checked out.
To export and archive an overview report or to export and archive a findings list report in another format, you can use:
steps: # Check out the repository - uses: actions/checkout@v2 # Compile the code for Java projects and get all libraries, e.g. via Maven - run: mvn -B compile # Install all dependent libraries for JavaScript/TypeScript project, e.g. via npm - run: npm install # Run the security analysis with a configuration file - name: Xanitizer Security Analysis uses: RIGS-IT/xanitizer-action@v1 with: license: ${{ secrets.XANITIZER_LICENSE }} overviewReportOutputFile: relative/path/to/the/Overview-Report.pdf findingsListReportOutputFiles: relative/path/to/the/Findings-List.pdf,relative/path/to/the/Findings-List.html # Findings list reports have to contain also non problematic findings # onlyProblemsInFindingsListReport: false # Findings list reports contain no details e.g. all steps of a path # generateDetailsInFindingsListReport: false # Archiving - uses: actions/upload-artifact@v2 with: name: Xanitizer-Reports path: relative/path/to/the
Please note that the HTML report format is not only a single HTML file, it's a list of files with a subdirectory containing images.
Configuration File
To improve the accuracy of the security analysis, the xanitizer-action
can also be executed based on a Xanitizer configuration file containing project specific settings. This configuration file can only be edited with the standalone version of Xanitizer not directly with the GitHub action.
steps: # Check out the repository - uses: actions/checkout@v2 # Compile the code for Java projects and get all libraries, e.g. via Maven - run: mvn -B compile # Install all dependent libraries for JavaScript/TypeScript project, e.g. via npm - run: npm install # Run the security analysis with a configuration file - name: Xanitizer Security Analysis uses: RIGS-IT/xanitizer-action@v1 with: license: ${{ secrets.XANITIZER_LICENSE }} configFile: relative/path/to/the/configuration/file
Another Checkout Path
It is possible to use the parameter path
of the Git checkout action actions/checkout@v2
to check out the repository to a path under $GITHUB_WORKSPACE. If this parameter is used, the corresponding parameter checkoutPath
of this action xanitizer-action
has to be set to the same value.
steps: # Check out the repository - uses: actions/checkout@v2 with: path: path/to/checkout # Compile the code for Java projects and get all libraries, e.g. via Maven - run: | cd path/to/checkout mvn -B compile # Install all dependent libraries for JavaScript/TypeScript project, e.g. via npm - run: | cd path/to/checkout npm install # Run the security analysis with default settings - name: Xanitizer Security Analysis uses: RIGS-IT/xanitizer-action@v1 with: license: ${{ secrets.XANITIZER_LICENSE }} checkoutPath: path/to/checkout
Break the Build
Normally, Xanitizer will no break any build, unless the xanitizer-action
is configured to do so. Breaking the build is not recommended if the SARIF report file should be uploaded to the GitHub code scanning alert section of your repository, because no SARIF report file is generated if the build breaks.
steps: # Check out the repository - uses: actions/checkout@v2 # Compile the code for Java projects and get all libraries, e.g. via Maven - run: mvn -B compile # Install all dependent libraries for JavaScript/TypeScript project, e.g. via npm - run: npm install # Run the security analysis, breaking the build if necessary - name: Xanitizer Security Analysis uses: RIGS-IT/xanitizer-action@v1 with: license: ${{ secrets.XANITIZER_LICENSE }} # Whether the task should fail if in an exiting Xanitizer configuration file there are search paths configured that do not exist. # haltOnMissingSearchPaths: true # A comma - separated list of issue groups that will let the task fail if for any of them, a Xanitizer error issue occurs. # haltOnIssues: WORKSPACE_ERRORS, CALL_GRAPH_ERRORS, ANALYSIS_ERRORS, MIGRATION_ERRORS # Whether the task should fail if there are findings with a rating equal or higher than the value defined for `findingsRatingThreshold`. haltOnFindings: true # A rating value. Only used if the parameter `haltOnFindings` is set. findingsRatingThreshold: 5.0
Inputs
See action.yml for all supported input parameters.
Outputs
All output streams of the running Xanitizer installation will be redirected to the GitHub action logging framework.
Furthermore, the status messages containing i.a. the result of the security analysis are exported and can be used by subsequent steps via the parameter security_analysis
.
steps: # Check out the repository - uses: actions/checkout@v2 # Compile the code for Java projects and get all libraries, e.g. via Maven - run: mvn -B compile # Install all dependent libraries for JavaScript/TypeScript project, e.g. via npm - run: npm install # Run the security analysis with default settings - name: Xanitizer Security Analysis id: xanitizer uses: RIGS-IT/xanitizer-action@v1 with: license: ${{ secrets.XANITIZER_LICENSE }} # Use the output from the `xanitizer` step - run: echo "Status messages from Xanitizer's security analysis - ${{ steps.xanitizer.outputs.security_analysis }}"