From 9de5e3d6172863c3373ea151879d128abed2b62e Mon Sep 17 00:00:00 2001 From: Rory Carson Date: Mon, 25 Sep 2023 13:54:05 +0200 Subject: [PATCH 1/2] [SEC-3230]Update Allstar Documentation --- README.md | 97 +++++++++++++++++++++--------------------- architecture.md | 1 + create-a-new-policy.md | 2 + deployment.md | 2 + whats-new.md | 94 ---------------------------------------- 5 files changed, 53 insertions(+), 143 deletions(-) create mode 100644 architecture.md create mode 100644 create-a-new-policy.md create mode 100644 deployment.md delete mode 100644 whats-new.md diff --git a/README.md b/README.md index 432c19c6..dd2a9a90 100644 --- a/README.md +++ b/README.md @@ -8,14 +8,6 @@ - [What Is Allstar?](#what-is-allstar) -## What's new with Allstar - -- [whats-new.md](whats-new.md) - -## Disabling Unwanted Issues - -- [Help! I'm getting issues created by Allstar and I don't want them!](#disabling-unwanted-issues-1) - ## Getting Started - [Background](#background) @@ -27,14 +19,15 @@ ## Policies and Actions - [Actions](#actions) - [Policies](#policies) +- [Enabled Policies](#enabled-policies) ## Advanced - [Configuration Definitions](#configuration-definitions) - [Example Configurations](#example-config-repository) - [Run Your Own Instance of Allstar](operator.md) - -## Contribute -- [Contributing](#contributing) +- [Contentful Architecture](architecture.md) +- [Creating a New Policy](create-a-new-policy.md) +- [Deploying Changes](deployment.md) ________ ________ @@ -58,11 +51,6 @@ Allstar is developed under the [OpenSSF](https://openssf.org/) organization, as a part of the [Securing Critical Projects Working Group](https://github.com/ossf/wg-securing-critical-projects). -## [What's new with Allstar](whats-new.md) - -## Disabling Unwanted Issues -If you're getting unwanted issues created by Allstar, follow [these directions](opt-out.md) to opt out. - ## Getting Started ### Background @@ -165,34 +153,6 @@ configured at the org level. 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](https://github.com/apps/allstar-app) and click Configure - 1. If you have multiple organizations, select the one you want to - install Allstar on - 1. Select "All Repositories" under Repository Access, even if you - plan to disable Allstar on some repositories later -1. Fork the sample repository - 1. [Open the sample repository](https://github.com/jeffmendoza/dot-allstar-quickstart) - and click the "Use this template" button - 1. In the field for Repository Name, type `.allstar` - 1. Click "Create repository from template" - -That's it! All current Allstar [policies](#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-install.md). - #### Manual Installation This installation option will walk you through creating configuration files according to either the Opt In or Opt Out strategy. This @@ -264,6 +224,49 @@ 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. +## **Enabled Policies** +The status of controls currently applied to the Contentful Github Org + +|Policy Name|Tracked|Enforced| +|-----------|-------|--------| +|[CODEOWNERS](#codeowners)|Yes|No| +|[Roadie Info](#roadie-info)|In Progress|No| +|[Branch Protection](#branch-protection)|Yes|No| +|Binary Artifact|No|No| +|Outside Collaborators|No|No| +|SECURITY.md|No|No| +|Dangerous Workflow|No|No| +|Generic Scorecard|No|No| +|Github Actions|No|No| +|Repository Admins|No|No| + + +### CODEOWNERS + +This policy's config file is named `codeowners.yaml`, and the [config +definitions are +here](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/codeowners#OrgConfig). + +The branch protection policy checks that a valid [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) file exists in the repo +are setup correctly according to the specified configuration. The issue text +will describe which setting is incorrect. See [GitHub's +documentation](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) +for correcting settings. + +The `fix` action will open a PR creating a CODEOWNERS that sets the populates the owner based on the `owner` field in the repos catalog-info.yaml. + +### Roadie Info + +This policy's config file is named `roadie.yaml`, and the [config +definitions are +here](TODO). + +The branch protection policy checks that a valid [catalog-info.yaml](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) file exists in the repo are setup correctly according to the specified configuration. See [Backstages' +documentation](https://backstage.io/docs/features/software-catalog/descriptor-format/#contents) +for correcting settings. + +The `fix` action will open a PR creating a catalog-info.yaml with some default values. The annotations are service/repo specific and will need to be updated to be accurate. + ### Branch Protection This policy's config file is named `branch_protection.yaml`, and the [config @@ -444,8 +447,4 @@ 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](https://datatracker.ietf.org/doc/html/rfc7396). The `baseConfig` must be -a GitHub `/`. - -## **Contributing** - -See [CONTRIBUTING.md](CONTRIBUTING.md) +a GitHub `/`. \ No newline at end of file diff --git a/architecture.md b/architecture.md new file mode 100644 index 00000000..bfe3b65b --- /dev/null +++ b/architecture.md @@ -0,0 +1 @@ +[Miro board with current architecture](https://miro.com/app/board/uXjVM2g_HGQ=/?share_link_id=272309503681) \ No newline at end of file diff --git a/create-a-new-policy.md b/create-a-new-policy.md new file mode 100644 index 00000000..10e5dcc1 --- /dev/null +++ b/create-a-new-policy.md @@ -0,0 +1,2 @@ +1. Create a new folder in pkg/policies +2. Create your check and unit test in that folder \ No newline at end of file diff --git a/deployment.md b/deployment.md new file mode 100644 index 00000000..645abeb1 --- /dev/null +++ b/deployment.md @@ -0,0 +1,2 @@ +* When changes are merged to `main` a [Github Action](.github/workflows/docker-image.yaml) is kicked off that builds a new image and uploads it to ECR. +* This image is used by [allstar-agent](https://github.com/contentful/allstar-agent) and will kick off a new deployment(automatically??) of the agent to the `contentful-security-sandbox` organization. \ No newline at end of file diff --git a/whats-new.md b/whats-new.md deleted file mode 100644 index b65a1fca..00000000 --- a/whats-new.md +++ /dev/null @@ -1,94 +0,0 @@ -# What's new with Allstar - -Major features and changes added to Allstar. - -## Added since last release - -- - -## Release v3.0 - -- Branch Protection policy is more complete with support for - `requireSignedCommits`,` enforceOnAdmins`, - `requireCodeOwnerReviews`. [Link](pkg/policies/branch/branch.go) - -- You may now opt-out repos that are forks with the `optOutForkedRepos` option. - -- GitHub Actions policy added to allow/require/deny configured actions in - workflows. [Docs](README.md#github-actions) - -- Generic Scorecard policy added to run any Scorecard check with a score - threshold. [Docs](README.md#generic-scorecard-check) - -- Issue creation and pinging can be enabled / disabled based on a weekly - schedule. [Link](pkg/config/config.go) - -- The Outside Collaborators policy now allows - exemptions. [Link](pkg/policies/outside/outside.go) - -- When the Allstar action is changed from `issue` to `fix`. Existing issues - will be closed. - -- Issue ping duration is configurable at the operator level with - `NOTICE_PING_DURATION_HOURS`. [Link](pkg/config/operator/operator.go) - -- Org config may now point to a secondary repository for config and merge - overrides. [Docs](README.md#org-level-base-and-merge-configuration-location) - -- Individual repo config files are now allowed to be placed in the central org - config repository. Example: in the `.allstar` repo, you can have a - `/branch_protection.yaml` file with specific settings for that - repo. [Docs](README.md#repo-policy-configurations-in-the-org-repo) - -- Binary Artifacts policy configuration updated to have an ignore - list. [Link](pkg/policies/binary/binary.go) - -- Dangerous Workflow policy added. This policy checks the GitHub Actions - workflow configuration files (.github/workflows), for any patterns that match - known dangerous behavior. [Docs](README.md#dangerous-workflow) - -## Release v2.0 - -- Branch Protection added the `requireStatusChecks` setting to ensure listed - status checks are set in protection settings. Also enforces the - `requireUpToDateBranch` option, if `requireStatusChecks` is set. - -- You may now opt-out of repos marked as "archived" in GitHub with the - `optOutArchivedRepos` option. - -- Binary Artifacts policy issue text improved. - -- A custom footer can be added to all issues created in an organization with - the `issueFooter` option. - -- Branch Protection now supports the "fix" action. - -## Proposed functionality changes in v2.0 - -- Option `testingOwnerlessAllowed` in Outside Collaborator policy. Currently - defaults true, proposal to default to false in next release. - - - Note: this was temporarily enabled in Jan, but then turned off due to a bug. - -## Pre v2.0 - -Regular releases were not made before v2.0, so all previous notes are here. - -- All issues for an org can be routed to a single repo using the `issueRepo` - setting. - -- Org config can now be located in `.github/allstar` as a secondary location - after the `.allstar` repo. - -- Issues can be created with a custom label using the `issueLabel` option. - -- Private or Public repositories can be opt-out as a group with the - `optOutPrivateRepos` or `optOutPublicRepos` options. - -- We will retroactively call this Allstar v1.0: Allstar announced - https://openssf.org/blog/2021/08/11/introducing-the-allstar-github-app/ - -- Initial policies and features built - -- Allstar was proposed to the OpenSSF Securing Critical Projects WG and - accepted https://youtu.be/o3SiBDUTCrw?t=300 From d7386008d90259bf4a7289287300686395ac451b Mon Sep 17 00:00:00 2001 From: Rory Carson Date: Tue, 26 Sep 2023 10:51:34 +0200 Subject: [PATCH 2/2] add opt out strategy --- README.md | 1 + opt-out.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 opt-out.md diff --git a/README.md b/README.md index dd2a9a90..db10707a 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ - [Contentful Architecture](architecture.md) - [Creating a New Policy](create-a-new-policy.md) - [Deploying Changes](deployment.md) +- [Opt-out of Checks](opt-out.md) ________ ________ diff --git a/opt-out.md b/opt-out.md new file mode 100644 index 00000000..519683a6 --- /dev/null +++ b/opt-out.md @@ -0,0 +1,55 @@ +# How to disable Allstar +If you are receiving unwanted issues created by Allstar, follow the instructions on this page to disable the app on your project. + +[Disable Allstar, org-level opt-out strategy](#disable-allstar-org-level-opt-out-strategy) +[Disable Check, repository level](#disable-a-specific-check-with-repo-override) +[Disable Allstar, repo level](#disable-allstar-with-repo-override) + + +## Disable Allstar, org-level opt-out strategy + +These instructions disable Allstar on a repository when Allstar is configured at the organization level using the opt-out strategy. + +In the `.allstar` repository in your organization, open the file named +`allstar.yaml`. + +Find the `optOutStrategy` setting: + +``` +optConfig: + optOutStrategy: true +``` + +To opt-out, submit a PR to the `.allstar` repo, and add the name of your +repository to the opt-out list: + +``` +optConfig: + optOutStrategy: true + optOutRepos: + - my-repo-name-here +``` + +Allstar will be disabled on your repository when the pull request is merged. + +### Disable a specific check with repo-override + +To opt-out of a specific check in your repo create `.allstar/control-name.yaml` and add +``` +optConfig: + optOut: true +``` + +Merge this file to disable Allstar on your repository. + +### Disable allstar with repo-override + +To disable Allstar using repo-override, create a file in your repo named +`.allstar/allstar.yaml` with the contents: + +``` +optConfig: + optOut: true +``` + +Merge this file to disable Allstar on your repository.