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

Allstar

Overview

• What Is Allstar?

What's new with Allstar

• whats-new.md

Disabling Unwanted Issues

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

Getting Started

• Background
• Org-Level Options
• Installation Options
  • Using the public AllStar app
    • Quickstart Installation
    • Manual Installation
  • Self-hosting AllStar
    • Running AllStar as a GitHub Action
    • Running AllStar as a service daemon

Policies and Actions

• Actions
• Policies

Advanced

• Configuration Definitions
• Example Configurations
• Run Your Own Instance of Allstar

Contribute

• Contributing

---

---

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:

• Org level: Organization administrators can choose to enable Allstar on:
  • all repositories in the org;
  • most repositories, except some that are opted out;
  • just a few repositories that are opted in.

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

• Repo level: Repository maintainers in an organization that uses Allstar can choose to opt their repository in or out of organization-level enforcements. Note: these repo-level controls are only functional when "repo override" is allowed in the org-level settings. These configurations are done in the repository's .allstar directory.

• Policy level: Administrators or maintainers can choose which policies are enabled on specific repos and which actions Allstar takes when a policy is violated. These configurations are done in a policy yaml file in either the organization's .allstar repository (admins), or the repository's .allstar directory (maintainers).

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.

• The Opt In strategy allows you to manually add the repositories you'd like Allstar to run on. If you do not specify any repositories, Allstar will not run despite being installed. Choose the Opt In strategy if you want to enforce policies on only a small number of your total repositories, or want to try out Allstar on a single repository before enabling it on more. Since the v4.3 release, globs are supported to easily add multiple repositories with a similar name.

• The Opt Out strategy (recommended) enables Allstar on all repositories and allows you to manually select the repositories to opt out of Allstar enforcements. You can also choose to opt out all public repos, or all private repos. Choose this option if you want to run Allstar on all repositories in an organization, or want to opt out only a small number of repositories or specific type (i.e., public vs. private) of repository. Since the v4.3 release, globs are supported to easily add multiple repositories with a similar name.

<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 into your GitHub Organization. The Allstar app is operated by OpenSSF and is a good choice for most open source repositories. 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.

If you do not want to use the OpenSSF operated Allstar app you may self-host Allstar, creating your own Allstar app. This provides direct control of the app with a trade off of needing to configure, secure, monitor, and maintain the app.

Using the Allstar app

Quickstart or Manual installation are recommended unless you have specific security or compliance constraints that prevent you from using the OpenSSF managed Allstar app.

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.

Self-hosting Allstar

Only self-host if you must! The Allstar app requires configuration, securing, and ongoing maintenance. When a new Allstar version is released you will need to upgrade your self-hosted solution.

Two self-hosting approaches are described:

• Running AllStar as a GitHub Action - This option is relatively lightweight and leverages GitHub Actions to run Allstar checks.
• Running AllStar as a service daemon - This option has the highest level of control and assumes you are able to run a persistent service on a reliable server or container orchestrator.

Running Allstar as a GitHub Action

This i