Home

Awesome

OpenSSF Scorecard

<img align="right" src="artwork/openssf_allstar_alt.png" width="300" height="400">

Allstar

Overview

What's new with Allstar

Disabling Unwanted Issues

Getting Started

Policies and Actions

Advanced

Contribute



Overview

What is Allstar?

Allstar is a GitHub App that continuously monitors GitHub organizations or repositories for adherence to security best practices. If Allstar detects a security policy violation, it creates an issue to alert the repository or organization owner. For some security policies, Allstar can also automatically change the project setting that caused the violation, reverting it to the expected state.

Allstar’s goal is to give you finely tuned control over the files and settings that affect the security of your projects. You can choose which security policies to monitor at both the organization and repository level, and how to handle policy violations. You can also develop or contribute new policies.

Allstar is developed as a part of the OpenSSF Scorecard project.

What's new with Allstar

Disabling Unwanted Issues

If you're getting unwanted issues created by Allstar, follow these directions to opt out.

Getting Started

Background

Allstar is highly configurable. There are three main levels of controls:

These configurations are done in the organization's .allstar repository.

Org-Level Options

Before installing Allstar at the org level, you should decide approximately how many repositories you want Allstar to run on. This will help you choose between the Opt-In and Opt-Out strategies.

<table> <thead> <tr> <th></th> <th><strong>Opt Out (Recommended)</strong><br> <strong>optOutStrategy = true</strong></th> <th><strong>Opt In</strong><br> <strong>optOutStrategy = false</strong></th> </tr> </thead> <tbody> <tr> <td>Default behavior </td> <td>All repos are enabled</td> <td>No repos are enabled </td> </tr> <tr> <td>Manually adding repositories</td> <td>Manually adding repos disables Allstar on those repos</td> <td>Manually adding repos enables Allstar on those repos</td> </tr> <tr> <td>Additional configurations</td> <td>optOutRepos: Allstar will be disabled on the listed repos<br> <br> optOutPrivateRepos: if true, Allstar will be disabled on all private repos <br> <br> optOutPublicRepos: if true, Allstar will be disabled on all public repos<br> <br> (optInRepos: this setting will be ignored)</td> <td>optInRepos: Allstar will be enabled on the listed repos <br> <br> (optOutRepos: this setting will be ignored)</td> </tr> <tr> <td>Repo Override </td> <td>If true: Repos can opt out of their organization's Allstar enforcements using the settings in their own repo file. Org level opt-in settings that apply to that repository are ignored. <br> <br> If false: repos cannot opt out of Allstar enforcements as configured at the org level. </td> <td>If true: Repos can opt in to their organization's Allstar enforcements even if they are not configured for the repo at the org level. Org level opt-out settings that apply to that repository are ignored.<br> <br> If false: Repos cannot opt into Allstar enforcements if they are not configured at the org level. </td> </tr> </tbody> </table>

Installation Options

Both the Quickstart and Manual Installation options involve installing the Allstar app. You may review the permissions requested. The app asks for read access to most settings and file contents to detect security compliance. It requests write access to issues and checks so that it can create issues and allow the block action.

Quickstart Installation

This installation option will enable Allstar using the Opt Out strategy on all repositories in your organization. All current policies will be enabled, and Allstar will alert you of policy violations by filing an issue. This is the quickest and easiest way to start using Allstar, and you can still change any configurations later.

Effort: very easy

Steps:

  1. Install the Allstar app
    1. Open the installation page and click Configure
    2. If you have multiple organizations, select the one you want to install Allstar on
    3. Select "All Repositories" under Repository Access, even if you plan to disable Allstar on some repositories later
  2. Fork the sample repository
    1. Open the sample repository and click the "Use this template" button
    2. In the field for Repository Name, type .allstar
    3. Click "Create repository from template"

That's it! All current Allstar policies are now enabled on all your repositories. Allstar will create an issue if a policy is violated.

To change any configurations, see the manual installation directions.

Manual Installation

This installation option will walk you through creating configuration files according to either the Opt In or Opt Out strategy. This option provides more granular control over configurations right from the start.

Effort: moderate

Steps:

  1. Install the Allstar app (choose "All Repositories" under Repository Access, even if you don't plan to use Allstar on all your repositories)
  2. Follow the manual installation directions to create org-level or repository-level Allstar config files and individual policy files.

Policies and Actions

Actions

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

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

Action configuration

Two settings are available to configure the issue action:

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 details of how the fix action works for each policy is detailed below. If omitted below, the fix action is not applicable.

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.

The fix action will change the branch protection settings to be in compliance with the specified policy configuration.

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.

CODEOWNERS

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

This policy checks for the presence of a CODEOWNERS file on your repositories.

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.

Dangerous Workflow

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

This policy checks the GitHub Actions workflow configuration files (.github/workflows), for any patterns that match known dangerous behavior. See the OpenSSF Scorecard documentation for more information on this check.

Generic Scorecard Check

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

This policy runs any scorecard check listed in the checks configuration. All checks run must have a score equal or above the threshold setting. Please see the OpenSSF Scorecard documentation for more information on each check.

GitHub Actions

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

This policy checks the GitHub Actions workflow configuration files (.github/workflows) (and workflow runs in some cases) in each repo to ensure they are in line with rules (eg. require, deny) defined in the organization-level config for the policy.

Repository Administrators

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

This policy checks that by default all repositories must have a user or group assigned as an Administrator. It allows you to optionally configure if users are allowed to be administrators (as opposed to teams).

Future Policies

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.

Advanced

Configuration Definitions

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:

PrecedenceRepositoryPath
Primary.allstarallstar.yaml
Secondary.githuballstar/allstar.yaml

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

Repo policy configurations in the Org Repo

Allstar will also look for repo-level policy configurations in the organization's .allstar repository, under the directory with the same name as the repository. This configuration is used regardless of whether "repo override" is disabled.

For example, Allstar will lookup the policy configuration for a given repo myapp in the following order:

RepositoryPathCondition
myapp.allstar/branch_protection.yamlWhen "repo override" is allowed.
.allstarmyapp/branch_protection.yamlAll times.
.allstarbranch_protection.yamlAll times.
.githuballstar/myapp/branch_protection.yamlIf .allstar repo does not exist.
.githuballstar/branch_protection.yamlIf .allstar repo does not exist.

Org-level Base and Merge Configuration Location

For org-level Allstar and policy configuration files, you may specify the field baseConfig to specify another repository that contains base Allstar configuration. This is best explained with an example.

Suppose you have multiple GitHub organizations, but want to maintain a single Allstar configuration. Your main organization is "acme", and the repository acme/.allstar contains allstar.yaml:

optConfig:
  optOutStrategy: true
issueLabel: allstar-acme
issueFooter: Issue created by Acme security team.

You also have a satellite GitHub organization named "acme-sat". You want to re-use the main config, but apply some changes on top by disabling Allstar on certain repositories. The repository acme-sat/.allstar contains allstar.yaml:

baseConfig: acme/.allstar
optConfig:
  optOutRepos:
  - acmesat-one
  - acmesat-two

This will use all the config from acme/.allstar as the base config, but then apply any changes in the current file on top of the base configuration. The method this is applied is described as a JSON Merge Patch. The baseConfig must be a GitHub <org>/<repository>.

Contributing

See CONTRIBUTING.md