GitHub sells a product, GitHub Advanced Security which bundles CodeQL (a static analysis tool similar to semgrep), secret scanning (similar to trufflehog), an improved UI on dependency spec files, and security overview (a way to upload static analysis findings such that they produce PR annotations, and a dashboard to view them).
Less Advanced Security is... less advanced. It enables you to bring-your-own PR annotations to any tool which outputs results in the sarif format. Sarif support is currently limited to common fields used by tools like semgrep
and brakeman
.
GitHub Advanced Security charges a per-active-commiter seat license of ~$600/yr. Less Advanced Security is free (bring your own compute, config, and maintenance).
Annotations are added to the pull request file page marking the line(s) impacted. Annotations may be notices, warnings, or failures.
If a finding is reported multiple times in the input sarif (same file, lines, finding id, and level), less-advanced-security
will deduplicate these and post only one annotation.
A check is added to the commit (and pull request) denoting the status of the most severe annotation. Failures result in a failing check, warnings result in a pending check, notices result in a passing check.
All annotations are summarized on the PR's checks page.
- Create a GitHub App for your user or org.
- The
GitHub App name
will be visible whenless-advanced-security
runs. Choose something succinct. - Set
Homepage URL
will be visible on the checks page. Choose a useful doc for your org (or use this repo's URL). - Set
Webhook
toActive
, but configure a nonsense URL (likehttps://github.com/<your_user>/dev/null
) for the destination. - Set the following permissions:
Repository permissions > Checks > Access: Read and write
Repository permissions > Pull requests > Access: Read-only
- For
Where can this GitHub App be installed?
selectOnly on this account
. - Note the
App Id
for later.
- The
- Generate a private key and save it locally.
- Note the path to the key for later.
- Install the GitHub App, granting it access to the relevant repos.
- Note the
installation.id
for later. To do this, return to your app configuration, look atAdvanced
settings, find the failed webhook delivery, and look at the payload.
- Note the
Builds of less-advanced-security
are available for common platforms and architectures, likely including your CI environment.
Download and install the latest release of less-advanced-security
for your platform and architecture.
Confirm successful installation by reading the --help
output:
less-advanced-security --help
Run your sarif-producing scan, writing the sarif file to disk.
Then run
less-advanced-security --app_id=<app_id> --install_id=<installation_id> --key_path=<path_to_key> --sha=<sha_of_target_commit> --repo=<repo_owner>/<repo_name> --pr=<pr_number> --sarif_path=<path_to_sarif_file>
For example:
less-advanced-security --app_id=12345 --install_id=87654321 --key_path=tmp/application_private_key.pem --sha=ee5dabb638b6b874c42bc3c915cf94d4b6b346b6 --repo=eliblock/less-advanced-security --pr=57 --sarif_path=/tmp/scan-results/sarif.json
Defaults to True
(disable with --filter_annotations=false
).
When set to True
, annotations are added only when they apply to a line modified in the pull request (or a line immediately around it based on the git patch). When set to False
, all annotations are added regardless of file or line.
Defaults to True
(disable with --annotate_beginning=false
).
When set to True
, annotations are submitted for the start line of a finding only (rather than the full range of lines in the finding). With this set to False
, GitHub's default of displaying annotations on the end line of a finding is used.
Defaults to the tool driver name from the submitted sarif (override with --check_name "Override name of check"
).
When set to any string, the GitHub check is named that string (rather than the name of the tool which reported the results). Use this configuration in the event that the same tool powers multiple checks on your PR.
brew install [email protected]
go build ./...
go test -v ./...
brew install goreleaser
git tag v0.1.0 # update for your version
git push origin v0.1.0 # update for your version
goreleaser release --clean --snapshot # remove --snapshot for a full release
# complete the release on GitHub