Allstar

Allstar is a GitHub App installed on organizations or repositories to set and enforce security policies. Its goal is to be able to continuously monitor and detect any GitHub setting or repository file contents that may be risky or do not follow security best practices. If Allstar finds a repository to be out of compliance, it will take an action such as create an issue or restore security settings.

The specific policies are intended to be highly configurable, to try to meet the needs of different project communities and organizations. Also, developing and contributing new policies is intended to be easy.

Allstar is developed under the OpenSSF organization, as a part of the Securing Critical Projects Working Group. The OpenSSF runs an instance of Allstar here for anyone to install and use on their GitHub organizations. However, Allstar can be run by anyone if need be, see the operator docs for more details.

Quick start

Install Allstar GitHub App on your organizations and repositories. When installing Allstar, you may review the permissions requested. Allstar asks for read access to most settings and file contents to detect security compliance. It requests write access to issues to create issues, and to checks to allow the block action.

Follow the quick start instructions to setup the configuration files needed to enable Allstar on your repositories. For more details on advanced configuration, see below.

Help! I'm getting issues created by Allstar and I don't want them.

Enable Configuration

Allstar can be enabled on individual repositories at the app level, with the option of enabling or disabling each security policy individually. For organization-level configuration, create a repository named .allstar in your organization. Then create a file called allstar.yaml in that repository.

Allstar can either be set to an opt-in or opt-out strategy. In opt-in, only those repositories explicitly listed are enabled. In opt-out, all repositories are enabled, and repositories would need to be explicitly added to opt-out. Allstar is set to opt-in by default, and therefore is not enabled on any repository immediately after installation. To continue with the default opt-in strategy, list the repositories for Allstar to be enabled on in your organization like so:

optConfig:
  optInRepos:
  - repo-one
  - repo-two

To switch to the opt-out strategy (recommended), set that option to true:

optConfig:
  optOutStrategy: true

If you wish to enable Allstar on all but a few repositories, you may use opt-out and list the repositories to disable:

optConfig:
  optOutStrategy: true
  optOutRepos:
  - repo-one
  - repo-two

To opt-out all private/public repositories, add optOutPrivateRepos or optOutPublicRepos. ex:

optConfig:
  optOutStrategy: true
  optOutPrivateRepos: true
  optOutPublicRepos: false

Secondary Org-Level configuration location

By default, org-level configuration files, such as the allstar.yaml file above, are expected to be in a .allstar repository. If this repository does not exist, then the .github repository allstar directory is used as a secondary location. To clarify, for allstar.yaml:

This is also true for the org-level configuration files for the individual policies, as described below.

Repository Override

Individual repositories can also opt in or out using configuration files inside those repositories. For example, if the organization is configured with the opt-out strategy, a repository may opt itself out by including the file .allstar/allstar.yaml with the contents:

optConfig:
  optOut: true

Conversely, this allows repositories to opt-in and enable Allstar when the organization is configured with the opt-in strategy. Because opt-in is the default strategy, this is how Allstar works if the .allstar repository doesn't exist.

At the organization-level allstar.yaml, repository override may be disabled with the setting:

optConfig:
  disableRepoOverride: true

This allows an organization-owner to have a central point of approval for repositories to request an opt-out through a GitHub PR. Understandably, Allstar or individual policies may not make sense for all repositories.

Policy Enable

Each individual policy configuration file (see below) also contains the exact same optConfig configuration object. This allows granularity to enable policies on individual repositories. A policy will not take action unless it is enabled and Allstar is enabled as a whole.

Definition

• Organization level enable configuration
• Repository Override enable configuration

Actions

Each policy can be configured with an action that Allstar will take when it detects a repository to be out of compliance.

• log: This is the default action, and actually takes place for all actions. All policy run results and details are logged. Logs are currently only visible to the app operator, plans to expose these are under discussion.
• issue: This action creates a GitHub issue. Only one issue is created per policy, and the text describes the details of the policy violation. If the issue is already open, it is pinged with a comment every 24 hours (not currently user configurable). Once the violation is addressed, the issue will be automatically closed by Allstar within 5-10 minutes.
• fix: This action is policy specific. The policy will make the changes to the GitHub settings to correct the policy violation. Not all policies will be able to support this (see below).

Proposed, but not yet implemented actions. Definitions will be added in the future.

• block: Allstar can set a GitHub Status Check and block any PR in the repository from being merged if the check fails.
• email: Allstar would send an email to the repository administrator(s).
• rpc: Allstar would send an rpc to some organization-specific system.

Policies

Similar to the Allstar app enable configuration, all policies are enabled and configured with a yaml file in either the organization's .allstar repository, or the repository's .allstar directory. As with the app, policies are opt-in by default, also the default log action won't produce visible results. A simple way to enable all policies is to create a yaml file for each policy with the contents:

optConfig:
  optOutStrategy: true
action: issue

The fix action is not implemented in any policy yet, but will be implemented in those policies where it is applicable soon.

Branch Protection

This policy's config file is named branch_protection.yaml, and the config definitions are here.

The branch protection policy checks that GitHub's branch protection settings are setup correctly according to the specified configuration. The issue text will describe which setting is incorrect. See GitHub's documentation for correcting settings.

Binary Artifacts

This policy's config file is named binary_artifacts.yaml, and the config definitions are here.

This policy incorporates the check from scorecard. Remove the binary artifact from the repository to achieve compliance. As the scorecard results can be verbose, you may need to run scorecard itself to see all the detailed information.

Outside Collaborators

This policy's config file is named outside.yaml, and the config definitions are here.

This policy checks if any Outside Collaborators have either administrator(default) or push(optional) access to the repository. Only organization members should have this access, as otherwise untrusted members can change admin level settings and commit malicious code.

SECURITY.md

This policy's config file is named security.yaml, and the config definitions are here.

This policy checks that the repository has a security policy file in SECURITY.md and that it is not empty. The created issue will have a link to the GitHub tab that helps you commit a security policy to your repository.

Future Policies

• Ensure dependabot is enabled.
• Check that dependencies are pinned/frozen.
• More checks from scorecard.

Example Config Repository

See this repo as an example of Allstar config being used. As the organization administrator, consider a README.md with some information on how Allstar is being used in your organization.

Contribute Policies

Interface definition.

Both the SECURITY.md and Outside Collaborators policies are quite simple to understand and good examples to copy.