Allstar

[!IMPORTANT] OpenSSF가 호스팅하는 Allstar GitHub App은 더 이상 제공되지 않습니다. OpenSSF Scorecard 하위 프로젝트인 Allstar 자체는 계속 유지 관리되며, 이제 직접 실행해야 합니다. GitHub Action으로 실행하거나 서비스 데몬으로 실행할 수 있습니다.

자세한 내용은 ossf/allstar#881을 참조하세요.

조직에서 호스팅 앱을 사용 중이었다면 호스팅 앱에서 마이그레이션을 참조하세요.

개요

Allstar란 무엇인가?

Allstar의 새로운 기능

whats-new.md

원치 않는 이슈 비활성화

도움말! Allstar가 만든 이슈가 생기는데 원하지 않아요!

정책 및 작업

작업
정책

고급

기여

기여하기

개요

Allstar란 무엇인가?

Allstar는 GitHub 조직 또는 저장소의 보안 모범 사례 준수 여부를 지속적으로 모니터링하는 GitHub App입니다. Allstar가 보안 정책 위반을 감지하면 저장소 또는 조직 소유자에게 알리기 위해 이슈를 생성합니다. 일부 보안 정책의 경우 Allstar는 위반을 유발한 프로젝트 설정을 자동으로 변경하여 예상 상태로 되돌릴 수도 있습니다.

Allstar의 목표는 프로젝트 보안에 영향을 미치는 파일과 설정을 세밀하게 제어할 수 있도록 하는 것입니다. 조직 및 저장소 수준에서 모니터링할 보안 정책을 선택하고 정책 위반을 처리하는 방법을 결정할 수 있습니다. 또한 새로운 정책을 개발하거나 기여할 수도 있습니다.

Allstar는 OpenSSF Scorecard 프로젝트의 일부로 개발되었습니다.

Allstar의 새로운 기능

원치 않는 이슈 비활성화

Allstar가 만든 원치 않는 이슈가 발생하는 경우 이 지침에 따라 옵트아웃하세요.

시작하기

배경

Allstar는 매우 유연하게 구성할 수 있습니다. 제어 수준은 크게 세 가지입니다:

조직 수준: 조직 관리자는 Allstar를 다음에 대해 활성화하도록 선택할 수 있습니다:
- 조직의 모든 저장소;
- 일부를 옵트아웃한 대부분의 저장소;
- 옵트인한 소수의 저장소만.

이러한 구성은 조직의 .allstar 저장소에서 수행됩니다.

저장소 수준: Allstar를 사용하는 조직의 저장소 유지관리자는 저장소를 조직 수준의 적용 대상에 옵트인하거나 옵트아웃할 수 있습니다. 참고: 이러한 저장소 수준 제어는 조직 수준 설정에서 "저장소 재정의"가 허용된 경우에만 작동합니다. 이러한 구성은 저장소의 .allstar 디렉터리에서 수행됩니다.
정책 수준: 관리자 또는 유지관리자는 특정 저장소에서 활성화할 정책과 정책 위반 시 Allstar가 수행할 작업을 선택할 수 있습니다. 이러한 구성은 조직의 .allstar 저장소(관리자) 또는 저장소의 .allstar 디렉터리(유지관리자)에 있는 정책 yaml 파일에서 수행됩니다.

조직 수준 옵션

조직 수준에서 Allstar를 설치하기 전에 Allstar를 실행할 저장소 수를 대략적으로 결정해야 합니다. 이는 옵트인(Opt-In) 전략과 옵트아웃(Opt-Out) 전략 중에서 선택하는 데 도움이 됩니다.

옵트인 전략을 사용하면 Allstar를 실행할 저장소를 수동으로 추가할 수 있습니다. 저장소를 지정하지 않으면 설치되어 있어도 Allstar는 실행되지 않습니다. 전체 저장소 중 소수에만 정책을 적용하려는 경우 또는 더 많은 저장소에 활성화하기 전에 단일 저장소에서 Allstar를 시험해 보려는 경우 옵트인 전략을 선택하세요. v4.3 릴리스부터 유사한 이름의 여러 저장소를 쉽게 추가할 수 있도록 glob이 지원됩니다.
옵트아웃 전략(권장)은 모든 저장소에서 Allstar를 활성화하고 Allstar 적용에서 제외할 저장소를 수동으로 선택할 수 있게 합니다. 또한 모든 공개 저장소 또는 모든 비공개 저장소를 옵트아웃하도록 선택할 수도 있습니다. 조직의 모든 저장소에서 Allstar를 실행하려는 경우 또는 소수의 저장소나 특정 유형(예: 공개 vs 비공개)의 저장소만 옵트아웃하려는 경우 이 옵션을 선택하세요. v4.3 릴리스부터 유사한 이름의 여러 저장소를 쉽게 추가할 수 있도록 glob이 지원됩니다.

	옵트아웃 (권장) optOutStrategy = true	옵트인 optOutStrategy = false
기본 동작	모든 저장소가 활성화됨	활성화된 저장소 없음
저장소 수동 추가	저장소를 수동으로 추가하면 해당 저장소에서 Allstar가 비활성화됨	저장소를 수동으로 추가하면 해당 저장소에서 Allstar가 활성화됨
추가 구성	optOutRepos: 나열된 저장소에서 Allstar가 비활성화됨 optOutPrivateRepos: true이면 모든 비공개 저장소에서 Allstar가 비활성화됨 optOutPublicRepos: true이면 모든 공개 저장소에서 Allstar가 비활성화됨 (optInRepos: 이 설정은 무시됨)	optInRepos: 나열된 저장소에서 Allstar가 활성화됨 (optOutRepos: 이 설정은 무시됨)
저장소 재정의	true인 경우: 저장소는 자체 저장소 파일의 설정을 사용하여 조직의 Allstar 적용에서 옵트아웃할 수 있습니다. 해당 저장소에 적용되는 조직 수준 옵트인 설정은 무시됩니다. false인 경우: 저장소는 조직 수준에서 구성된 Allstar 적용에서 옵트아웃할 수 없습니다.	true인 경우: 저장소는 조직 수준에서 구성되지 않았더라도 조직의 Allstar 적용에 옵트인할 수 있습니다. 해당 저장소에 적용되는 조직 수준 옵트아웃 설정은 무시됩니다. false인 경우: 저장소는 조직 수준에서 구성되지 않은 경우 Allstar 적용에 옵트인할 수 없습니다.

설치 옵션

Allstar는 GitHub App으로 조직에서 작동합니다. 앱을 만들고 해당 앱으로 인증하는 프로세스를 직접 실행합니다. 따라서 모든 배포에 공통적인 두 단계 설정이 필요합니다 — 앱 만들기와 제어 저장소 만들기 — 그리고 실행 방법을 선택합니다:

	GitHub Action	서비스 데몬
실행 방식	`.allstar` 저장소의 예약 작업	직접 호스팅하는 상주 프로세스
제공 항목	GitHub 외에는 없음	서버 또는 컨테이너 오케스트레이터
주기	`cron`으로 설정한 대로	연속 실행, 5-10분 내 결과 확인
설정 노력	보통	높음
적합한 경우	최소 인프라 옵션을 원할 때	최대 제어를 원하거나 이미 서비스를 운영 중일 때

Action은 두 옵션 중 오버헤드가 낮으며 대부분의 조직이 시작하기에 적합합니다. 나중에 정책 구성을 변경하지 않고 데몬으로 전환할 수 있습니다.

GitHub App 만들기

App은 조직에서 일련의 권한을 가진 사용자와 유사한 ID입니다. Allstar는 규정 준수를 감지하기 위해 대부분의 설정과 파일 내용에 대한 읽기 권한이 필요하며, 이슈를 제기하고 block 작업을 지원하기 위해 이슈 및 검사에 대한 쓰기 권한이 필요합니다.

운영자 지침 - GitHub App 만들기를 따르고 App ID와 개인 키를 기록해 두세요. 두 실행 모드 모두 필요합니다.

`.allstar` 제어 저장소 만들기

Allstar는 조직의 .allstar라는 저장소에서 구성을 읽습니다.

가장 빠른 생성 방법은 샘플을 사용하는 것입니다:

샘플 저장소 열기 및 "Use this template" 버튼 클릭
Repository Name 필드에 .allstar 입력
"Create repository from template" 클릭

이렇게 하면 옵트아웃 전략과 issue 작업을 사용하여 모든 저장소에서 현재 모든 Allstar 정책이 활성화됩니다. 이후 언제든지 변경할 수 있습니다.

처음부터 세밀한 제어가 필요한 경우 — 옵트인 또는 옵트아웃 전략을 선택하고 정책 파일을 직접 작성 — 수동 설치 지침을 대신 따르세요.

GitHub Action으로 Allstar 실행

이 옵션은 GitHub Actions를 사용하여 예약 작업으로 Allstar를 실행하므로 GitHub 자체 외에 운영할 인프라가 없습니다.

GitHub Actions 설치 지침에 따라 .allstar 저장소에서 반복 Action을 설정하고 강화한 다음 결과를 모니터링하세요.

서비스 데몬으로 Allstar 실행

이 옵션은 Allstar를 상주 프로세스로 실행하여 일정이 아닌 지속적으로 위반을 감지하고 해결합니다.

프로세스 실행, 비밀 관리, 크기 조정 및 사용 가능한 환경 변수에 대한 자세한 내용은 운영자 지침을 참조하세요.

호스팅 앱에서 마이그레이션

조직에서 OpenSSF 호스팅 앱을 사용 중이었다면 구성이 그대로 유지됩니다. .allstar 제어 저장소, allstar.yaml 및 모든 정책 파일은 변경 없이 계속 작동합니다. 교체되는 것은 이를 읽는 프로세스뿐입니다.

마이그레이션하려면:

자체 GitHub App 만들기 및 호스팅 앱과 동일한 저장소 액세스 권한으로 조직에 설치합니다.
기존 .allstar 저장소를 그대로 유지합니다.
Allstar를 Action으로 또는 데몬으로 실행합니다.
조직에서 allstar-app을 제거합니다(설정 -> GitHub Apps에 여전히 표시되는 경우).

호스팅 앱이 이전에 제기한 이슈는 저장소에 남아 있습니다. 자체 인스턴스는 동일한 allstar 레이블(또는 구성된 issueLabel)로 이슈를 식별하므로 위반이 해결됨에 따라 중복을 제기하지 않고 해당 이슈를 인수하여 닫습니다.

정책 및 작업

작업

각 정책은 Allstar가 저장소가 규정을 위반한 것으로 감지할 때 수행할 작업으로 구성할 수 있습니다.

log: 기본 작업이며 실제로 모든 작업에 대해 수행됩니다. 모든 정책 실행 결과와 세부 정보가 기록됩니다. 로그는 현재 앱 운영자에게만 표시되며, 이를 공개하는 계획은 논의 중입니다.
issue: 이 작업은 GitHub 이슈를 생성합니다. 정책당 하나의 이슈만 생성되며 텍스트는 정책 위반의 세부 정보를 설명합니다. 이슈가 이미 열려 있으면 업데이트 없이 24시간마다 댓글로 알림이 전송됩니다(현재 사용자 구성 불가). 정책 결과가 변경되면 이슈에 새 댓글이 남고 이슈 본문에 연결됩니다. 위반이 해결되면 Allstar가 5-10분 내에 이슈를 자동으로 닫습니다.
fix: 이 작업은 정책별로 다릅니다. 정책은 GitHub 설정을 변경하여 정책 위반을 수정합니다. 모든 정책이 이를 지원할 수 있는 것은 아닙니다(아래 참조).

제안되었지만 아직 구현되지 않은 작업입니다. 정의는 향후 추가될 예정입니다.

block: Allstar는 GitHub 상태 검사를 설정하고 검사가 실패하면 저장소의 모든 PR 병합을 차단할 수 있습니다.
email: Allstar는 저장소 관리자에게 이메일을 보냅니다.
rpc: Allstar는 조직별 시스템에 rpc를 보냅니다.

작업 구성

issue 작업을 구성하는 데 사용할 수 있는 두 가지 설정이 있습니다:

issueLabel은 조직 및 저장소 수준에서 사용할 수 있습니다. 설정하면 Allstar가 이슈를 식별하는 데 사용하는 기본 allstar 레이블을 재정의합니다.
issueRepo는 조직 수준에서 사용할 수 있습니다. 설정하면 조직에서 생성된 모든 이슈가 지정된 저장소에 생성되도록 강제합니다.

정책

Allstar 앱 활성화 구성과 유사하게 모든 정책은 조직의 .allstar 저장소 또는 저장소의 .allstar 디렉터리에 있는 yaml 파일로 활성화 및 구성됩니다. 앱과 마찬가지로 정책은 기본적으로 옵트인이며 기본 log 작업은 표시되는 결과를 생성하지 않습니다. 모든 정책을 활성화하는 간단한 방법은 각 정책에 대해 다음 내용으로 yaml 파일을 만드는 것입니다:```yaml optConfig: optOutStrategy: true action: issue

각 정책에 대한 `fix` 작업의 작동 방식은 아래에 자세히 설명되어 있습니다. 아래에 생략된 경우 `fix` 작업은 적용되지 않습니다.

### Branch Protection

이 정책의 구성 파일 이름은 `branch_protection.yaml`이며, [구성 정의는
여기](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/branch#OrgConfig)에서
확인할 수 있습니다.

Branch protection 정책은 GitHub의 [branch protection
설정](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)이
지정된 구성에 따라 올바르게 설정되었는지 확인합니다. 이슈 텍스트에는
어떤 설정이 잘못되었는지 설명됩니다. 설정 수정에 대한 자세한 내용은 [GitHub
문서](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)를
참조하세요.

`fix` 작업은 branch protection 설정을 지정된 정책 구성에 부합하도록 변경합니다.

### Binary Artifacts

이 정책의 구성 파일 이름은 `binary_artifacts.yaml`이며, [구성 정의는
여기](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/binary#OrgConfig)에서
확인할 수 있습니다.

이 정책은 [scorecard의
검사](https://github.com/ossf/scorecard/#scorecard-checks)를 통합합니다. 규정을
준수하려면 저장소에서 바이너리 아티팩트를 제거하세요. scorecard
결과는 장황할 수 있으므로, 모든 세부 정보를 확인하려면 [scorecard
자체](https://github.com/ossf/scorecard)를 실행해야 할 수도 있습니다.

### CODEOWNERS

이 정책의 구성 파일 이름은 `codeowners.yaml`이며, [구성 정의는
여기](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/codeowners#OrgConfig)에서
확인할 수 있습니다.

이 정책은 저장소에 [`CODEOWNERS` 파일](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)이
있는지 확인합니다.

### Outside Collaborators

이 정책의 구성 파일 이름은 `outside.yaml`이며, [구성 정의는
여기](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/outside#OrgConfig)에서
확인할 수 있습니다.

이 정책은 [Outside
Collaborators](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization)가
관리자(기본값) 또는 푸시(선택 사항) 접근 권한을 저장소에
가지고 있는지 확인합니다. 조직 구성원만 이 접근 권한을 가져야 합니다. 그렇지 않으면
신뢰할 수 없는 구성원이 관리자 수준 설정을 변경하고 악성 코드를 커밋할 수 있기 때문입니다.

### SECURITY.md

이 정책의 구성 파일 이름은 `security.yaml`이며, [구성 정의는
여기](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/security#OrgConfig)에서
확인할 수 있습니다.

이 정책은 저장소에 `SECURITY.md` 보안 정책 파일이 있고 비어 있지 않은지
확인합니다. 생성된 이슈에는 저장소에 보안 정책을 커밋하는 데 도움이 되는
[GitHub
탭](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository)에 대한
링크가 포함됩니다.

### Dangerous Workflow

이 정책의 구성 파일 이름은 `dangerous_workflow.yaml`이며, [구성 정의는
여기](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/workflow#OrgConfig)에서
확인할 수 있습니다.

이 정책은 **모든** 브랜치에 대해 실행됩니다. 근거는 [여기](https://github.com/ossf/allstar/issues/569)에서
확인할 수 있습니다.

이 정책은 GitHub Actions 워크플로우 구성 파일
(`.github/workflows`)에서 알려진 위험한 동작과 일치하는 패턴이 있는지
확인합니다. 이 검사에 대한 자세한 내용은 [OpenSSF Scorecard
문서](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow)를
참조하세요.

### Generic Scorecard Check

이 정책의 구성 파일 이름은 `scorecard.yaml`이며, [구성 정의는
여기](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/scorecard#OrgConfig)에서
확인할 수 있습니다.

이 정책은 `checks` 구성에 나열된 모든 scorecard 검사를 실행합니다. 실행되는 모든
검사는 `threshold` 설정 이상의 점수를 가져야 합니다. 각 검사에 대한
자세한 내용은 [OpenSSF Scorecard
문서](https://github.com/ossf/scorecard/blob/main/docs/checks.md)를
참조하세요.

#### SARIF Upload

Scorecard 정책은 선택적으로 결과를
[SARIF](https://sarifweb.azurewebsites.net/) 형식으로 각 저장소의
**Security > Code Scanning** 탭에 업로드할 수 있습니다. 이를 통해 조직 관리자는
저장소별 워크플로우 설정 없이도 다른 보안 도구(CodeQL,
Dependabot 등)와 함께 Scorecard 결과를 확인할 수 있습니다.

SARIF 업로드를 활성화하려면 `scorecard.yaml`에 `upload` 필드를 추가하세요.```yaml
optConfig:
  optOutStrategy: true
action: issue
checks:
  - Binary-Artifacts
  - Signed-Releases
threshold: 8
upload:
  sarif: true

요구 사항:

Allstar GitHub App에는 코드 검사 알림 저장소 권한이 읽기 및 쓰기로 설정되어 있어야 합니다(API 범위: security_events). 이는 Allstar가 그 외에 필요로 하는 권한에 포함되지 않으므로, SARIF 업로드를 활성화하기 전에 앱에 추가하세요.
SARIF 업로드는 비차단 방식입니다. 업로드가 실패하더라도(예: 권한 누락) 정책 검사는 정상적으로 계속됩니다.
변경 감지는 저장소 HEAD 커밋 SHA를 비교하며, 마지막 업로드 이후 저장소에 푸시가 없으면 검사 및 업로드를 건너뜁니다.

SARIF 업로드는 Allstar를 실행하는 두 가지 방식 모두에서 작동합니다: 서비스 데몬 또는 GitHub Action으로 실행하는 방식입니다.

GitHub Actions

이 정책의 구성 파일 이름은 actions.yaml이며, 구성 정의는 여기에서 확인할 수 있습니다.

이 정책은 각 저장소의 GitHub Actions 워크플로 구성 파일(.github/workflows)(경우에 따라 워크플로 실행)을 검사하여, 조직 수준 구성에서 정의된 규칙(예: 요구, 금지)에 부합하는지 확인합니다.

저장소 관리자

이 정책의 구성 파일 이름은 admin.yaml이며, 구성 정의는 여기에서 확인할 수 있습니다.

이 정책은 기본적으로 모든 저장소에 사용자 또는 그룹이 관리자로 지정되어 있어야 하는지 확인합니다. 사용자가 관리자가 될 수 있는지(팀이 아닌) 여부를 선택적으로 구성할 수 있습니다.

향후 정책

dependabot이 활성화되어 있는지 확인.
종속성이 고정(pinned/frozen)되어 있는지 확인.

구성 저장소 예시

Allstar 구성이 사용되는 예시로 이 저장소를 참조하세요. 조직 관리자로서, 조직에서 Allstar가 어떻게 사용되고 있는지에 대한 정보가 담긴 README.md를 고려해 보세요.

고급

구성 정의

보조 조직 수준 구성 위치

기본적으로 위의 allstar.yaml 파일과 같은 조직 수준 구성 파일은 .allstar 저장소에 있어야 합니다. 이 저장소가 존재하지 않으면 .github 저장소의 allstar 디렉터리가 보조 위치로 사용됩니다. allstar.yaml의 경우를 명확히 하면 다음과 같습니다:

우선순위	저장소	경로
기본	`.allstar`	`allstar.yaml`
보조	`.github`	`allstar/allstar.yaml`

이 내용은 아래에 설명된 개별 정책의 조직 수준 구성 파일에도 동일하게 적용됩니다.

조직 저장소의 저장소 정책 구성

Allstar는 또한 조직의 .allstar 저장소에서 저장소 이름과 동일한 이름의 디렉터리 아래에 있는 저장소 수준 정책 구성을 찾습니다. 이 구성은 "저장소 재정의"가 비활성화되어 있는지 여부와 관계없이 사용됩니다.

예를 들어, Allstar는 특정 저장소 myapp에 대한 정책 구성을 다음 순서로 조회합니다:

저장소	경로	조건
`myapp`	`.allstar/branch_protection.yaml`	"저장소 재정의"가 허용된 경우.
`.allstar`	`myapp/branch_protection.yaml`	항상.
`.allstar`	`branch_protection.yaml`	항상.
`.github`	`allstar/myapp/branch_protection.yaml`	`.allstar` 저장소가 존재하지 않는 경우.
`.github`	`allstar/branch_protection.yaml`	`.allstar` 저장소가 존재하지 않는 경우.

조직 수준 기본 및 병합 구성 위치

조직 수준 Allstar 및 정책 구성 파일의 경우, 기본 Allstar 구성을 포함하는 다른 저장소를 지정하기 위해 baseConfig 필드를 지정할 수 있습니다. 이는 예시를 통해 가장 잘 설명됩니다.

여러 GitHub 조직이 있지만 단일 Allstar 구성을 유지 관리하려는 경우를 가정해 보겠습니다. 기본 조직이 "acme"이고 저장소 acme/.allstar에 allstar.yaml이 포함되어 있습니다:```yaml optConfig: optOutStrategy: true issueLabel: allstar-acme issueFooter: Issue created by Acme security team.

You also have a satellite GitHub organization named "acme-sat". You want to
re-use the main config, but apply some changes on top by disabling Allstar on
certain repositories. The repository `acme-sat/.allstar` contains
`allstar.yaml`:```yaml
baseConfig: acme/.allstar
optConfig:
  optOutRepos:
  - acmesat-one
  - acmesat-two

이 설정은 acme/.allstar의 모든 구성을 기본 구성으로 사용하되, 현재 파일의 변경 사항을 기본 구성 위에 적용합니다. 이 적용 방식은 JSON Merge Patch로 설명됩니다. baseConfig는 GitHub <org>/<repository> 형식이어야 합니다.

기여하기

CONTRIBUTING.md를 참조하세요.

allstar v4.6

카테고리

allstar v4.6

Allstar

개요

Allstar의 새로운 기능

원치 않는 이슈 비활성화

시작하기

정책 및 작업

고급

기여

개요

Allstar란 무엇인가?

Allstar의 새로운 기능

원치 않는 이슈 비활성화

시작하기

배경

조직 수준 옵션

설치 옵션

GitHub App 만들기

.allstar 제어 저장소 만들기

GitHub Action으로 Allstar 실행

서비스 데몬으로 Allstar 실행

호스팅 앱에서 마이그레이션

정책 및 작업

작업

작업 구성

정책

GitHub Actions

저장소 관리자

향후 정책

구성 저장소 예시

고급

구성 정의

보조 조직 수준 구성 위치

조직 저장소의 저장소 정책 구성

조직 수준 기본 및 병합 구성 위치

기여하기

카테고리

`.allstar` 제어 저장소 만들기