Skip to main content Link Menu Expand (external link) Document Search Copy Copied

Security Checks

Security checks are one of SourceShield’s main features. Security checks run when a pull request is opened and help enforce supply chain security best practices and surface potential risks. Security checks are configured entirely via code within the .github/sourceshield.yml configuration file in a repository.

Setting up Checks

Setting up a security check is as simple as adding its configuration to the repository’s .github/sourceshield.yml config file. Select one or more SourceShield checks that are defined in the reference section, add them to the security_checks section of the sourceshield.yml file, and commit the change to the main branch of your repository.

Enforcing Checks on Pull Requests

For SourceShield to effectively block pull requests until the required security checks are met, you must configure GitHub’s branch protection rules accordingly, using these steps (as a GitHub repository administrator or organization owner).

These steps cannot be completed until SourceShield pull request checks run at least once on the specified repository.

  1. Navigate to your repository and click “Settings”
  2. Under “Code and automation” select “Branches”
  3. Under “Branch protection rules” click “Add branch protection rule” Add branch protection rule
  4. Enter your branch name pattern (e.g., “main”)
  5. Under “Protect matching branches” check the box that says “Require a pull request before merging”
  6. Check “Require status checks to pass before merging”
  7. Search for the check “SourceShield - Supply Chain Security Checks” and select it Add required status check
  8. Scroll to the bottom of the page and click “Save”

Now, when a pull request is opened, SourceShield’s status check must pass before the PR can be merged. Required status check

Comments

Some security checks support “comments” in which SourceShield will add a comment on the pull request summarizing information discovered while running the check. This is designed to provide more context for pull request reviewers.

Required status check

This feature can be disabled by setting comment: false in the config of checks that support comments.

security_checks:
  author_account_age:
    behavior: review
    comment: false

Currently, if comments are enabled, SourceShield will comment after each commit on a PR. A feature is in progress to customize this behavior.

Required Reviews

When a SourceShield security check fails, it can either block the pull request, or the check can enter a pending state until the pull request is reviewed. This feature allows you to “soft block” a pull request until additional it has been reviewed further. For example, you could require that any failed checks be reviewed by someone from the security team before the PR can be merged.

SourceShield uses the reviews section of the .github/sourceshield.yml file to determine the review criteria:

reviews:
  count: 2
  required:
    - userA

security_checks:
  author_account_age:
    behavior: review

This config tells SourceShield to require two approvals, one of which must be from the user userA, if the author_account_age check fails. If the author_account_age check passes, then no review is required (you may still configure GitHub to require reviews on PRs separately from SourceShield’s checks).

Security Checks Reference

See the full list of supported checks below:

Table of contents