allstar

module
Version: v0.0.0-...-17bd44a Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 11, 2022 License: Apache-2.0

README

Allstar

Overview

Disabling Unwanted Issues

Getting Started

Policies and Actions

Advanced

Contribute



Overview

What is 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.

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.

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

Opt Out (Recommended)
optOutStrategy = true
Opt In
optOutStrategy = false
Default behavior All repos are enabled No repos are enabled
Manually adding repositories Manually adding repos disables Allstar on those repos Manually adding repos enables Allstar on those repos
Additional configurations optOutRepos: Allstar will be disabled on the listed repos

optOutPrivateRepos: if true, Allstar will be disabled on all private repos

optOutPublicRepos: if true, Allstar will be disabled on all public repos

(optInRepos: this setting will be ignored)
optInRepos: Allstar will be enabled on the listed repos

(optOutRepos: this setting will be ignored)
Repo Override 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.

If false: repos cannot opt out of Allstar enforcements as configured at the org level.
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.

If false: Repos cannot opt into Allstar enforcements if they are not configured at the org level.
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 (choose "All Repositories" under Repository Access, even if you plan to disable Allstar on some repositories later)
  2. Fork the sample repository

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.

  • 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.
Action configuration

Two settings are available to configure the issue action:

  • issueLabel is available at the organization and repository level. Setting it will override the default allstar label used by Allstar to identify its issues.

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

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

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:

Prescedence Repository Path
Primary .allstar allstar.yaml
Secondary .github allstar/allstar.yaml

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

Contribute Policies

Interface definition.

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

Directories

Path Synopsis
cmd
pkg
config
Package config defines and grabs overall bot config.
Package config defines and grabs overall bot config.
config/operator
Package operator contains config to be set by the GitHub App operator
Package operator contains config to be set by the GitHub App operator
enforce
Package enforce is a central engine to Allstar that contains various enforcement logic.
Package enforce is a central engine to Allstar that contains various enforcement logic.
ghclients
Package ghclients stores ghclients with caching and auth for installations of a GitHub App THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
Package ghclients stores ghclients with caching and auth for installations of a GitHub App THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
issue
Package issue handles creating notification GitHub issues for Allstar
Package issue handles creating notification GitHub issues for Allstar
policies
Package policies is used to iterate through the available policies in Allstar.
Package policies is used to iterate through the available policies in Allstar.
policies/binary
Package binary implements the Binary Artifacts security policy check from scorecard.
Package binary implements the Binary Artifacts security policy check from scorecard.
policies/branch
Package branch implements the Branch Protection security policy.
Package branch implements the Branch Protection security policy.
policies/outside
Package Outside implements the Outside Collaborators security policy.
Package Outside implements the Outside Collaborators security policy.
policies/security
Package security implements the SECURITY.md security policy.
Package security implements the SECURITY.md security policy.
policydef
Package policydef defines the interface that policies must implement to be included in Allstar.
Package policydef defines the interface that policies must implement to be included in Allstar.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL