Skip to content

Latest commit

 

History

History
97 lines (60 loc) · 5.21 KB

README.md

File metadata and controls

97 lines (60 loc) · 5.21 KB
Raw

ghas-cli

CodeQL Downloads Supported Versions Contributors

CLI utility to interact with GitHub Advanced Security ("GHAS").

It allows to deploy GHAS features individually or at scale, while taking into account each repository configuration.

More specifically, it automates the following:

  • Ensure GitHub Actions are properly enabled for the repository (required for CodeQL),
  • Enable Secret Scanner, and create an informative issue
  • Enable Push Protection, and create an informative issue
  • Enable Dependabot and create an informative issue
  • Enable the Dependency Reviewer and create an informative issue
  • Open a PR to deploy Code Scanning with a custom configuration tuned for each repository's languages and non-main default branch (e.g main or master are not hardcoded, it determines the proper default branch automatically),
  • Cleanup legacy Mend issues on each repository

Each of these actions can also open an issue explaining each feature, how to use them, and what to eventually do before they are fully enabled. See ./templates to get an overview of these issues!

To follow your deployment, ghas-cli outputs results in a csv file indicating the deployment status of each feature for each repository.

You can work on a single repository or on thousands of them. In that case, ghas-cli does its best to overcome GitHub's rate limits...

Installation

Builds are available in the Releases tab.

  • Pypi:
pip install ghas-cli
  • Manually:
python -m pip install /full/path/to/ghas-cli-xxx.whl

# e.g: python3 -m pip install Downloads/ghas-cli-0.5.0-none-any.whl

Usage

ghas-cli -h or see the wiki.

Development

Build

Install Poetry first, then:

make dev

Bump the version number

  • Bump the version number: poetry version x.x.x
  • Update the __version__ field in src/cli.py accordingly.

Publish a new version

Requires syft to be installed to generate the sbom.

  1. Bump the version number as described above
  2. make deps to update the dependencies
  3. make release to build the packages
  4. git commit -a -S Bump to version 1.1.2 and git tag -s v1.1.2 -m "1.1.2"
  5. Upload dist/*, checksums.sha512 and checksums.sha512.asc to a new release in GitHub.
  6. Upload to PyPi: poetry publish.

Why not use ghas-enablement?

GitHub suggests using ghas-enablement to deploy GHAS at scale. Unfortunately, it has many limitations that make it a non viable tool as you understood if you read the beginning of this README, including:

  • Only support for one default branch name: If you repositories are mixing master, main, dev, test... as the repository default branch, you will end up creating the CodeQL config to another branch than the default's.
    • ghas-cli uses the correct default branch for each repo.
  • Non per-language CodeQL workflow configuration: You can only automate the PR creation for a single CodeQL workflow config file. Your repositories are likely a mix of many languages combinations, so pushing a single workflow configuration accross an organization is not efficient.
    • ghas-cli adjusts the CodeQL configuration to each repository languages.
  • Doesn't check if Actions are properly enabled on your organization repositories: Running ghas-enablement when Actions are disabled will fail.
    • ghas-cli makes sure Actions are enabled before doing anything else. If they're not, it enables them.
  • More broadly, ghas-cli creates more educative issues on each repositories. It also provides more flexibility with an extensive CLI to pipe in/out data.

Miscellaneous

This repository is provided as-is and isn't bound to Malwarebytes' SLA.