{"id":13467745,"url":"https://github.com/ossf/allstar","last_synced_at":"2025-05-14T15:08:01.826Z","repository":{"id":37048346,"uuid":"370773729","full_name":"ossf/allstar","owner":"ossf","description":"GitHub App to set and enforce security policies","archived":false,"fork":false,"pushed_at":"2025-04-27T00:40:51.000Z","size":1727,"stargazers_count":1296,"open_issues_count":73,"forks_count":127,"subscribers_count":32,"default_branch":"main","last_synced_at":"2025-04-27T01:26:28.217Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ossf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-05-25T17:20:50.000Z","updated_at":"2025-04-27T00:40:54.000Z","dependencies_parsed_at":"2023-02-18T08:46:02.946Z","dependency_job_id":"f44235d7-afbc-4e2a-bebc-b1747be8b869","html_url":"https://github.com/ossf/allstar","commit_stats":{"total_commits":427,"total_committers":29,"mean_commits":"14.724137931034482","dds":0.7634660421545667,"last_synced_commit":"0ae052c6ea41d9e3c9c7a0e8007f1b583e06a885"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ossf%2Fallstar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ossf%2Fallstar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ossf%2Fallstar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ossf%2Fallstar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ossf","download_url":"https://codeload.github.com/ossf/allstar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254169803,"owners_count":22026215,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T15:01:00.030Z","updated_at":"2025-05-14T15:08:01.777Z","avatar_url":"https://github.com/ossf.png","language":"Go","readme":"[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ossf/allstar/badge)](https://api.scorecard.dev/projects/github.com/ossf/allstar)\n\n\u003cimg align=\"right\" src=\"artwork/openssf_allstar_alt.png\" width=\"300\" height=\"400\"\u003e\n\n# **Allstar**\n\n## Overview\n\n-  [What Is Allstar?](#what-is-allstar)\n\n## What's new with Allstar\n\n- [whats-new.md](whats-new.md)\n\n## Disabling Unwanted Issues\n\n-  [Help! I'm getting issues created by Allstar and I don't want them!](#disabling-unwanted-issues-1)\n\n## Getting Started\n\n-  [Background](#background)\n-  [Org-Level Options](#org-level-options)\n-  [Installation Options](#installation-options)\n    - [Quickstart Installation](#quickstart-installation)\n    - [Manual Installation](#manual-installation)\n\n## Policies and Actions\n- [Actions](#actions)\n- [Policies](#policies)\n\n## Advanced\n- [Configuration Definitions](#configuration-definitions)\n- [Example Configurations](#example-config-repository)\n- [Run Your Own Instance of Allstar](operator.md)\n\n## Contribute\n- [Contributing](#contributing)\n________\n________\n\n## Overview\n\n### What is Allstar?\n\nAllstar is a GitHub App that continuously monitors GitHub organizations or\nrepositories for adherence to security best practices.  If Allstar detects a\nsecurity policy violation, it creates an issue to alert the repository or\norganization owner.  For some security policies, Allstar can also automatically\nchange the project setting that caused the violation, reverting it to the\nexpected state.\n\nAllstar’s goal is to give you finely tuned control over the files and settings\nthat affect the security of your projects.  You can choose which security\npolicies to monitor at both the organization and repository level, and how to\nhandle policy violations.  You can also develop or contribute new policies.\n\nAllstar is developed as a part of the [OpenSSF Scorecard](https://github.com/ossf/scorecard) project.\n\n## [What's new with Allstar](whats-new.md)\n\n## Disabling Unwanted Issues\nIf you're getting unwanted issues created by Allstar, follow [these directions](opt-out.md) to opt out.\n\n## Getting Started\n\n### Background\n\nAllstar is highly configurable. There are three main levels of controls:\n\n- **Org level**: Organization administrators can choose to enable Allstar on:\n   -  all repositories in the org;\n   -  most repositories, except some that are opted out;\n   -  just a few repositories that are opted in.\n\nThese configurations are done in the organization's `.allstar` repository.\n\n- **Repo level:** Repository maintainers in an organization that uses\n   Allstar can choose to opt their repository in or out of organization-level\n   enforcements. Note: these repo-level controls are only functional when \"repo\n   override\" is allowed in the org-level settings. These configurations are\n   done in the repository's `.allstar` directory.\n\n- **Policy level:** Administrators or maintainers can choose which policies\n   are enabled on specific repos and which actions Allstar takes when a policy\n   is violated. These configurations are done in a policy yaml file in either\n   the organization's `.allstar` repository (admins), or the repository's\n   `.allstar` directory (maintainers).\n\n### Org-Level Options\n\nBefore installing Allstar at the org level, you should decide approximately how many repositories\nyou want Allstar to run on. This will help you choose between the Opt-In and\nOpt-Out strategies.\n\n-  The Opt In strategy allows you to manually add the repositories you'd\n   like Allstar to run on. If you do not specify any repositories, Allstar will\n   not run despite being installed. Choose the Opt In strategy if you want to enforce\n   policies on only a small number of your total repositories, or want to try\n   out Allstar on a single repository before enabling it on more. Since the\n   v4.3 release, globs are supported to easily add multiple repositories with\n   a similar name.\n\n-  The Opt Out strategy (recommended) enables Allstar on all repositories\n   and allows you to manually select the repositories to opt out of Allstar\n   enforcements. You can also choose to opt out all public repos, or all\n   private repos. Choose this option if you want to run Allstar on all\n   repositories in an organization, or want to opt out only a small number of\n   repositories or specific type (i.e., public vs. private) of repository.\n   Since the v4.3 release, globs are supported to easily add multiple\n   repositories with a similar name.\n\n\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003e\u003c/th\u003e\n\u003cth\u003e\u003cstrong\u003eOpt Out (Recommended)\u003c/strong\u003e\u003cbr\u003e\n\u003cstrong\u003eoptOutStrategy = true\u003c/strong\u003e\u003c/th\u003e\n\u003cth\u003e\u003cstrong\u003eOpt In\u003c/strong\u003e\u003cbr\u003e\n\u003cstrong\u003eoptOutStrategy = false\u003c/strong\u003e\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd\u003eDefault behavior \u003c/td\u003e\n\u003ctd\u003eAll repos are enabled\u003c/td\u003e\n\u003ctd\u003eNo repos are enabled \u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003eManually adding repositories\u003c/td\u003e\n\u003ctd\u003eManually adding repos disables Allstar on those repos\u003c/td\u003e\n\u003ctd\u003eManually adding repos enables Allstar on those repos\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003eAdditional configurations\u003c/td\u003e\n\u003ctd\u003eoptOutRepos: Allstar will be disabled on the listed repos\u003cbr\u003e\n\u003cbr\u003e\noptOutPrivateRepos: if true, Allstar will be disabled on all private repos\n\u003cbr\u003e\n\u003cbr\u003e\noptOutPublicRepos: if true, Allstar will be disabled on all public\nrepos\u003cbr\u003e\n\u003cbr\u003e\n(optInRepos: this setting will be ignored)\u003c/td\u003e\n\u003ctd\u003eoptInRepos: Allstar will be enabled on the listed repos \u003cbr\u003e\n\u003cbr\u003e\n(optOutRepos: this setting will be ignored)\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003eRepo Override \u003c/td\u003e\n\u003ctd\u003eIf true: Repos can opt out of their organization's Allstar enforcements\nusing the settings in their own repo file. Org level opt-in settings that\napply to that repository are ignored. \u003cbr\u003e\n\u003cbr\u003e\nIf false: repos cannot opt out of Allstar enforcements as configured at the\norg level. \u003c/td\u003e\n\u003ctd\u003eIf true: Repos can opt in to their organization's Allstar enforcements even\nif they are not configured for the repo at the org level. Org level opt-out\nsettings that apply to that repository are ignored.\u003cbr\u003e\n\u003cbr\u003e\nIf false: Repos cannot opt into Allstar enforcements if they are not\nconfigured at the org level. \u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\n### Installation Options\n\nBoth 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.\n\n#### Quickstart Installation\nThis installation option will enable Allstar using the\nOpt Out strategy on all repositories in your  organization. All current policies\nwill be enabled, and Allstar will alert you of\npolicy violations by filing an issue. This is the quickest and easiest way to start using Allstar, and you can still change any configurations later.\n\nEffort: very easy\n\nSteps:\n\n1.  Install the Allstar app\n    1.  [Open the installation\n        page](https://github.com/apps/allstar-app) and click Configure\n    1.  If you have multiple organizations, select the one you want to\n        install Allstar on\n    1.  Select \"All Repositories\" under Repository Access, even if you\n        plan to disable Allstar on some repositories later\n1.  Fork the sample repository\n    1.  [Open the sample repository](https://github.com/jeffmendoza/dot-allstar-quickstart)\n        and click the \"Use this template\" button\n    1.  In the field for Repository Name, type `.allstar`\n    1.  Click \"Create repository from template\"\n\nThat's it! All current Allstar [policies](#policies) are now enabled on all\nyour repositories. Allstar will create an issue if a policy is violated.\n\nTo change any configurations, see the [manual installation directions](manual-install.md).\n\n#### Manual Installation\nThis installation option will walk you through creating\nconfiguration files according to either the Opt In or Opt Out strategy. This\noption provides more granular control over configurations right from the start.\n\nEffort: moderate\n\nSteps:\n1) Install the [Allstar app](https://github.com/apps/allstar-app) (choose \"All\nRepositories\" under Repository Access,  even if you don't plan to use Allstar on\nall your repositories)\n2) Follow the [manual installation directions](manual-install.md) to create org-level or\nrepository-level Allstar config files and individual policy files.\n\n## Policies and Actions\n\n## **Actions**\n\nEach policy can be configured with an action that Allstar will take when it\ndetects a repository to be out of compliance.\n\n- `log`: This is the default action, and actually takes place for all\n  actions. All policy run results and details are logged. Logs are currently\n  only visible to the app operator, plans to expose these are under discussion.\n- `issue`: This action creates a GitHub issue. Only one issue is created per\n  policy, and the text describes the details of the policy violation. If the\n  issue is already open, it is pinged with a comment every 24 hours without updates\n  (not currently user configurable). If the policy result changes, a new comment\n  will be left on the issue and linked in the issue body. Once the violation is\n  addressed, the issue will be automatically closed by Allstar within 5-10 minutes.\n- `fix`: This action is policy specific. The policy will make the changes to the\n  GitHub settings to correct the policy violation. Not all policies will be able\n  to support this (see below).\n\nProposed, but not yet implemented actions. Definitions will be added in the\nfuture.\n\n- `block`: Allstar can set a [GitHub Status\n  Check](https://docs.github.com/en/github/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/about-status-checks)\n  and block any PR in the repository from being merged if the check fails.\n- `email`: Allstar would send an email to the repository administrator(s).\n- `rpc`: Allstar would send an rpc to some organization-specific system.\n\n### **Action configuration**\n\nTwo settings are available to configure the issue action:\n\n- `issueLabel` is available at the organization and repository level. Setting it\n  will override the default `allstar` label used by Allstar to identify its\n  issues.\n\n- `issueRepo` is available at the organization level. Setting it will force all\n  issues created in the organization to be created in the repository specified.\n\n## **Policies**\n\nSimilar to the Allstar app enable configuration, all policies are enabled and\nconfigured with a yaml file in either the organization's `.allstar` repository,\nor the repository's `.allstar` directory. As with the app, policies are opt-in\nby default, also the default `log` action won't produce visible results. A\nsimple way to enable all policies is to create a yaml file for each policy with\nthe contents:\n\n```\noptConfig:\n  optOutStrategy: true\naction: issue\n```\n\nThe details of how the `fix` action works for each policy is detailed below. If omitted below, the `fix` action is not applicable.\n\n### Branch Protection\n\nThis policy's config file is named `branch_protection.yaml`, and the [config\ndefinitions are\nhere](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/branch#OrgConfig).\n\nThe branch protection policy checks that GitHub's [branch protection\nsettings](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)\nare setup correctly according to the specified configuration. The issue text\nwill describe which setting is incorrect. See [GitHub's\ndocumentation](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)\nfor correcting settings.\n\nThe `fix` action will change the branch protection settings to be in compliance with the specified policy configuration.\n\n### Binary Artifacts\n\nThis policy's config file is named `binary_artifacts.yaml`, and the [config\ndefinitions are\nhere](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/binary#OrgConfig).\n\nThis policy incorporates the [check from\nscorecard](https://github.com/ossf/scorecard/#scorecard-checks). Remove the\nbinary artifact from the repository to achieve compliance. As the scorecard\nresults can be verbose, you may need to run [scorecard\nitself](https://github.com/ossf/scorecard) to see all the detailed information.\n\n### CODEOWNERS\n\nThis policy's config file is named `codeowners.yaml`, and the [config\ndefinitions are\nhere](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/codeowners#OrgConfig).\n\nThis policy checks for the presence of a [`CODEOWNERS` file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) on your repositories.\n\n### Outside Collaborators\n\nThis policy's config file is named `outside.yaml`, and the [config definitions\nare\nhere](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/outside#OrgConfig).\n\nThis policy checks if any [Outside\nCollaborators](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization)\nhave either administrator(default) or push(optional) access to the\nrepository. Only organization members should have this access, as otherwise\nuntrusted members can change admin level settings and commit malicious code.\n\n### SECURITY.md\n\nThis policy's config file is named `security.yaml`, and the [config definitions\nare\nhere](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/security#OrgConfig).\n\nThis policy checks that the repository has a security policy file in\n`SECURITY.md` and that it is not empty. The created issue will have a link to\nthe [GitHub\ntab](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository)\nthat helps you commit a security policy to your repository.\n\n### Dangerous Workflow\n\nThis policy's config file is named `dangerous_workflow.yaml`, and the [config\ndefinitions are\nhere](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/workflow#OrgConfig).\n\nThis policy will run against **all** branches, see rationale [here](https://github.com/ossf/allstar/issues/569).\n\nThis policy checks the GitHub Actions workflow configuration files\n(`.github/workflows`), for any patterns that match known dangerous\nbehavior. See the [OpenSSF Scorecard\ndocumentation](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow)\nfor more information on this check.\n\n### Generic Scorecard Check\n\nThis policy's config file is named `scorecard.yaml`, and the [config definitions\nare\nhere](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/scorecard#OrgConfig).\n\nThis policy runs any scorecard check listed in the `checks` configuration. All\nchecks run must have a score equal or above the `threshold` setting. Please see\nthe [OpenSSF Scorecard\ndocumentation](https://github.com/ossf/scorecard/blob/main/docs/checks.md)\nfor more information on each check.\n\n### GitHub Actions\n\nThis policy's config file is named `actions.yaml`, and the [config definitions\nare\nhere](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/action#OrgConfig).\n\nThis policy checks the GitHub Actions workflow configuration files\n(`.github/workflows`) (and workflow runs in some cases) in each repo to ensure\nthey are in line with rules (eg. require, deny) defined in the\norganization-level config for the policy.\n\n### Repository Administrators\n\nThis policy's config file is named `admin.yaml`, and the [config definitions\nare\nhere](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/admin#OrgConfig).\n\nThis 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).\n\n### Future Policies\n\n- Ensure dependabot is enabled.\n- Check that dependencies are pinned/frozen.\n\n## **Example Config Repository**\n\nSee [this repo](https://github.com/GoogleContainerTools/.allstar) as an example\nof Allstar config being used. As the organization administrator, consider a\nREADME.md with some information on how Allstar is being used in your\norganization.\n\n## Advanced\n\n### Configuration Definitions\n\n- [Organization level enable configuration](https://pkg.go.dev/github.com/ossf/allstar/pkg/config#OrgOptConfig)\n- [Repository Override enable configuration]( https://pkg.go.dev/github.com/ossf/allstar/pkg/config#RepoOptConfig)\n\n### Secondary Org-Level configuration location\n\nBy default, org-level configuration files, such as the `allstar.yaml` file\nabove, are expected to be in a `.allstar` repository. If this repository does\nnot exist, then the `.github` repository `allstar` directory is used as a\nsecondary location. To clarify, for `allstar.yaml`:\n\n| Precedence | Repository | Path |\n| - | - | - |\n| Primary | `.allstar` | `allstar.yaml` |\n| Secondary | `.github` | `allstar/allstar.yaml` |\n\nThis is also true for the org-level configuration files for the individual\npolicies, as described below.\n\n### Repo policy configurations in the Org Repo\n\nAllstar will also look for repo-level policy configurations in the\norganization's `.allstar` repository, under the directory with the same name as\nthe repository. This configuration is used regardless of whether \"repo override\"\nis disabled.\n\nFor example, Allstar will lookup the policy configuration for a given repo\n`myapp` in the following order:\n\n| Repository | Path | Condition |\n| - | - | - |\n| `myapp` | `.allstar/branch_protection.yaml` | When \"repo override\" is allowed. |\n| `.allstar` | `myapp/branch_protection.yaml` | All times. |\n| `.allstar` | `branch_protection.yaml` | All times. |\n| `.github` | `allstar/myapp/branch_protection.yaml` | If `.allstar` repo does not exist. |\n| `.github` | `allstar/branch_protection.yaml` | If `.allstar` repo does not exist. |\n\n### Org-level Base and Merge Configuration Location\n\nFor org-level Allstar and policy configuration files, you may specify the field\n`baseConfig` to specify another repository that contains base Allstar\nconfiguration. This is best explained with an example.\n\nSuppose you have multiple GitHub organizations, but want to maintain a single\nAllstar configuration. Your main organization is \"acme\", and the repository\n`acme/.allstar` contains `allstar.yaml`:\n\n```yaml\noptConfig:\n  optOutStrategy: true\nissueLabel: allstar-acme\nissueFooter: Issue created by Acme security team.\n```\n\nYou also have a satellite GitHub organization named \"acme-sat\". You want to\nre-use the main config, but apply some changes on top by disabling Allstar on\ncertain repositories. The repository `acme-sat/.allstar` contains\n`allstar.yaml`:\n\n```yaml\nbaseConfig: acme/.allstar\noptConfig:\n  optOutRepos:\n  - acmesat-one\n  - acmesat-two\n```\n\nThis will use all the config from `acme/.allstar` as the base config, but then\napply any changes in the current file on top of the base configuration. The\nmethod this is applied is described as a [JSON Merge\nPatch](https://datatracker.ietf.org/doc/html/rfc7396). The `baseConfig` must be\na GitHub `\u003corg\u003e/\u003crepository\u003e`.\n\n## **Contributing**\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n","funding_links":[],"categories":["Go","Build techniques","DevSecOps","Compliance \u0026 Policy","Risk Management","Application Security","Autonomous Repo Management"],"sub_categories":["Supply chain beyond libraries","Policy enforcement","Network Security","Supply chain security"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fossf%2Fallstar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fossf%2Fallstar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fossf%2Fallstar/lists"}