github-security-report-action

A GitHub Action for generating PDF reports for GitHub Advanced Security Code Scan Results and Dependency Vulnerabilities.

The action comes with some predefined HTML templates using Nunjucks, along with the ability to in the future provide your own templates to the renderer.

Due to the nature of CodeQL Analysis this action ideally should be executed after the github/codeql-action/analyze action step, as this will generate the SARIF files on the runner which can be used to identify ALL the rules that were applied during the analysis. The results stored on your repository will only contain the results that generated an alert.

Processing

The action will use the provided token to load all the dependencies, dependency vulnerabilities and the Code Scanning results for the specified repository. It will then look in the directory specified for any SARIF reports.

With this data it will construct a JSON payload that it then passes into the template system (using Nunjucks a Jinja like templating system for JavaScript) and will generate a Summary Report (with more of these to come in the future) providing a roll up summary security report in HTML.

Using this HTML, it then passes it over to Puppeteer to render this in a headless Chromium before generating a PDF and saving it in the specified directory.

Parameters

token: A GitHub Personal Access Token with access to repo scope
sarifReportDir: The directory to look for SARIF reports (from the CodeQL analyze action this defaults to ../results)
outputDir: The output directory for the PDF reports, defaults to github.workspace
repository: The repository in <owner>/<repo_name> form, defaults to github.repository
template: The report template type used to render the report, defaults to summary

Templates

Currently there is partial support for templates that are included in the action. Extenders of the action are welcome to author additional templates by creating HTML templates using Nunjucks inside the templates folder.

You can specify a template by using the template parameter. Currently the following templates are available:

summary: The classic summary report from previous versions.
report: A more detailed report that includes a list of open alerts broken down by their severity.
report_sca: A report that includes Software Composition Analysis

Examples

name: Generate Security Report
uses: ctcampbell/github-security-report-action@v1
with:
  token: ${{ secrets.GITHUB_TOKEN }}

Example summary report output:

Standalone execution

For the v2 version, there are bundles that can be used to provide a command line client executable for Linux, MacOS and Windows platforms. The bundles can be downloaded from the v2 Release assets.

Installation

Just download and extract the zip bundle for your target platform. Inside there is a file starting with github-security-report with a target platform suffix or .exe extension in the case of Windows.

Running

Just call the platform executable and pass in the arguments as required. The arguments are the same as that of the GitHub Action, and you can get the full details from invoking the --help option on the executable as it will output detailed help

Options:

-t, --token: The GitHub Personal Access Token that has the necessary access for security and dependency API endpoints.
-r, --repository: The repository that contains the source code, in <owner>/<repository_name> form, e.g. peter-murray/node-hue-api
-s, --sarif-directory: The directory containing the SARIF report files
-o, --output-directory: The directory to output the PDF report to. This will be created if it does not exist.
--template: The report template type used to render the report. This defaults to summary.

An example of running the MacOS command line executable from the un:

$ ./github-security-report-mac-x64 -t <GitHub PAT Token> -r peter-murray/node-hue-api -s <directory containing CodeQL SARIF file(s)>

The above command would output a summary.pdf file in the current working directory.

Future improvements

Additional work on the currently available reports
Example of extending html templates and using them

mcantu / github-security-report-action