Repository files navigation

• What Is Allstar?

• whats-new.md

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

• Background
• Org-Level Options
• Installation Options
  • Quickstart Installation
  • Manual Installation

• Actions
• Policies

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

• Contributing

Allstar is a GitHub App that continuously monitors GitHub organizations orrepositories for adherence to security best practices. If Allstar detects asecurity policy violation, it creates an issue to alert the repository ororganization owner. For some security policies, Allstar can also automaticallychange the project setting that caused the violation, reverting it to theexpected state.

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

Allstar is developed as a part of theOpenSSF Scorecard project.

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

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 usesAllstar can choose to opt their repository in or out of organization-levelenforcements. Note: these repo-level controls are only functional when "repooverride" is allowed in the org-level settings. These configurations aredone in the repository's.allstar directory.

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

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

• The Opt In strategy allows you to manually add the repositories you'dlike Allstar to run on. If you do not specify any repositories, Allstar willnot run despite being installed. Choose the Opt In strategy if you want to enforcepolicies on only a small number of your total repositories, or want to tryout Allstar on a single repository before enabling it on more. Since thev4.3 release, globs are supported to easily add multiple repositories witha similar name.

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

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 theblock action.

This installation option will enable Allstar using theOpt Out strategy on all repositories in your organization. All current policieswill be enabled, and Allstar will alert you ofpolicy 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 installationpage and click Configure
   2. If you have multiple organizations, select the one you want toinstall Allstar on
   3. Select "All Repositories" under Repository Access, even if youplan to disable Allstar on some repositories later
2. Fork the sample repository
   1. Open the sample repositoryand 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 Allstarpolicies are now enabled on allyour repositories. Allstar will create an issue if a policy is violated.

To change any configurations, see themanual installation directions.

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

Effort: moderate

Steps:

1. Install theAllstar app (choose "AllRepositories" under Repository Access, even if you don't plan to use Allstar onall your repositories)
2. Follow themanual installation directions to create org-level orrepository-level Allstar config files and individual policy files.

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

• log: This is the default action, and actually takes place for allactions. All policy run results and details are logged. Logs are currentlyonly visible to the app operator, plans to expose these are under discussion.
• issue: This action creates a GitHub issue. Only one issue is created perpolicy, and the text describes the details of the policy violation. If theissue is already open, it is pinged with a comment every 24 hours without updates(not currently user configurable). If the policy result changes, a new commentwill be left on the issue and linked in the issue body. Once the violation isaddressed, 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 theGitHub settings to correct the policy violation. Not all policies will be ableto support this (see below).

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

• block: Allstar can set aGitHub StatusCheckand 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.

Two settings are available to configure the issue action:

• issueLabel is available at the organization and repository level. Setting itwill override the defaultallstar label used by Allstar to identify itsissues.

• issueRepo is available at the organization level. Setting it will force allissues created in the organization to be created in the repository specified.

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

optConfig:  optOutStrategy: trueaction: issue

The details of how thefix action works for each policy is detailed below. If omitted below, thefix action is not applicable.

This policy's config file is namedbranch_protection.yaml, and theconfigdefinitions arehere.

The branch protection policy checks that GitHub'sbranch protectionsettingsare setup correctly according to the specified configuration. The issue textwill describe which setting is incorrect. SeeGitHub'sdocumentationfor correcting settings.

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

This policy's config file is namedbinary_artifacts.yaml, and theconfigdefinitions arehere.

This policy incorporates thecheck fromscorecard. Remove thebinary artifact from the repository to achieve compliance. As the scorecardresults can be verbose, you may need to runscorecarditself to see all the detailed information.

This policy's config file is namedcodeowners.yaml, and theconfigdefinitions arehere.

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

This policy's config file is namedoutside.yaml, and theconfig definitionsarehere.

This policy checks if anyOutsideCollaboratorshave either administrator(default) or push(optional) access to therepository. Only organization members should have this access, as otherwiseuntrusted members can change admin level settings and commit malicious code.

This policy's config file is namedsecurity.yaml, and theconfig definitionsarehere.

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

This policy's config file is nameddangerous_workflow.yaml, and theconfigdefinitions arehere.

This policy will run againstall branches, see rationalehere.

This policy checks the GitHub Actions workflow configuration files(.github/workflows), for any patterns that match known dangerousbehavior. See theOpenSSF Scorecarddocumentationfor more information on this check.

This policy's config file is namedscorecard.yaml, and theconfig definitionsarehere.

This policy runs any scorecard check listed in thechecks configuration. Allchecks run must have a score equal or above thethreshold setting. Please seetheOpenSSF Scorecarddocumentationfor more information on each check.

This policy's config file is namedactions.yaml, and theconfig definitionsarehere.

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

This policy's config file is namedadmin.yaml, and theconfig definitionsarehere.

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).

• Ensure dependabot is enabled.
• Check that dependencies are pinned/frozen.

Seethis repo as an exampleof Allstar config being used. As the organization administrator, consider aREADME.md with some information on how Allstar is being used in yourorganization.

• Organization level enable configuration
• Repository Override enable configuration

By default, org-level configuration files, such as theallstar.yaml fileabove, are expected to be in a.allstar repository. If this repository doesnot exist, then the.github repositoryallstar directory is used as asecondary location. To clarify, forallstar.yaml:

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

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

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

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

Suppose you have multiple GitHub organizations, but want to maintain a singleAllstar configuration. Your main organization is "acme", and the repositoryacme/.allstar containsallstar.yaml:

optConfig:optOutStrategy:trueissueLabel:allstar-acmeissueFooter:Issue created by Acme security team.

You also have a satellite GitHub organization named "acme-sat". You want tore-use the main config, but apply some changes on top by disabling Allstar oncertain repositories. The repositoryacme-sat/.allstar containsallstar.yaml:

baseConfig:acme/.allstaroptConfig:optOutRepos:  -acmesat-one  -acmesat-two

This will use all the config fromacme/.allstar as the base config, but thenapply any changes in the current file on top of the base configuration. Themethod this is applied is described as aJSON MergePatch. ThebaseConfig must bea GitHub<org>/<repository>.

SeeCONTRIBUTING.md