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 torepo
scopesarifReportDir
: 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 togithub.workspace
repository
: The repository in<owner>/<repo_name>
form, defaults togithub.repository
template
: The report template type used to render the report, defaults tosummary
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 tosummary
.
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