From 987ee1cee2f5f337d36021af61b813f7387d41ea Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 23:20:36 +0900 Subject: [PATCH] docs(supply-chain): document the provider-less configuration and trust-key rotation (13-13) Promotion needs two offline signing providers and a bwrap/systemd/cgroup v2 runner that this repository never ran end to end, and no document said what a project without them gets or how to rotate or revoke a provider key. Co-Authored-By: Claude Opus 5.5 --- docs/security/supply-chain.md | 48 +++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/docs/security/supply-chain.md b/docs/security/supply-chain.md index eb34200b..1c9c505f 100644 --- a/docs/security/supply-chain.md +++ b/docs/security/supply-chain.md @@ -60,6 +60,54 @@ rejected. 경로에서만 이것을 만난다. 분류를 고치면 dependency baseline을 다시 승인해야 하므로 (`update:dependency-baseline`) 이 문서에 알려진 차이로 남긴다. +## 최소 구성과 전체 구성 + +리뷰 13-13. 승격 단계까지 쓰려면 이 문서 아래의 runner 조건(bwrap, prlimit, +systemd-run, systemd user manager 254 이상, cgroup v2 위임)과 오프라인 데이터로 +Ed25519 서명 보고서를 내는 provider 두 개가 필요하다. 이 repo는 그 환경에서 +workflow 전체를 한 번도 돌리지 않았다. 그래서 두 구성을 나눠 적는다. + +| 구성 | 켜는 것 | 보장하는 것 | 보장하지 않는 것 | +|---|---|---|---| +| 최소 구성(provider 없음) | merge·release stage 게이트, `immutable_build`(FE-GATE-015·027). provider 변수는 비워 둔다 | lockfile 무결성과 설치 스크립트 차단, SBOM과 local provenance의 digest 정합, secret scan, 재현 빌드, 후보 archive의 exact member와 digest, release 대상 환경 승인(FE-GATE-027) | 외부 취약점 검사, 서명된 provenance. provider job은 명령과 키가 없어 실패하고, `promotion` job은 두 provider job의 성공을 요구하므로 돌지 않는다. 승격은 사람이 결정한다 | +| 전체 구성 | 위 전부와 `vulnerability_provider`·`provenance_provider`·`promotion` job, 아래 runner 조건과 provider 키 | 위 전부와, 지정 키 보유자가 이 후보 digest·run·source에 서명했다는 것, 승격된 exact-five bundle(`verify:promotion`) | provider가 성실히 검사했는지, 빌드 job 격리(위 "무엇을 증명하고" 표 참고) | + +최소 구성으로 운영할 때 승격은 수동 승인이다. 승인자는 `immutable_build`가 +올린 후보 archive의 SHA-256(job output `archive_sha256`)과 local evidence를 +기록하고, 그 archive를 그대로 배포한다. 다시 빌드하지 않는다. `production_gate`는 +`promotion` 뒤에만 돌므로 이 구성의 workflow에서는 실행되지 않는다. 운영 +게이트(FE-GATE-019, 021~025)는 배포한 release를 대상으로 +`corepack pnpm ci:gate -- FE-GATE-0xx`로 따로 돌려 기록한다. + +### provider 신뢰 키 교체와 폐기 + +신뢰 키는 repo 변수 `VULNERABILITY_PUBLIC_KEY_PATH`·`VULNERABILITY_KEY_ID`, +`PROVENANCE_PUBLIC_KEY_PATH`·`PROVENANCE_KEY_ID`가 가리키는 공개 키 파일이다 +(`scripts/lib/provider-trust.ts`). 두 provider는 서로 다른 키를 써야 한다 +(`assertDistinctProviderTrust`). 승격 기록은 키 ID·지문과 trust policy +SHA-256을 남긴다. + +교체 순서: + +1. provider가 새 키 쌍을 만들고 공개 키만 넘긴다. +2. 새 공개 키 파일을 runner가 읽을 수 있는 경로에 두고, 두 변수를 새 경로와 새 + key ID로 한꺼번에 바꾼다. 키 ID는 새 값을 쓴다. 이전 ID를 재사용하면 기록만 + 보고 어느 키였는지 구분할 수 없다. +3. provider 쪽 서명 키를 새 키로 바꾼 뒤 release를 한 번 돌려 `promotion`이 + 통과하는지 확인한다. +4. 이전 공개 키 파일은 지우지 않고 보관한다. 이전 키로 승격된 release를 나중에 + 배포하거나 그 release로 롤백할 때 `verify:promotion -- --archived`가 그 키를 + 요구한다(`docs/operations/release-cache-rollback.md`). + +폐기 순서(키 유출 등): + +1. 해당 변수에서 그 키를 즉시 뺀다. 그 키로 서명된 새 승격은 이때부터 실패한다. +2. 보관 중인 이전 공개 키 파일도 지운다. 그 키로만 서명된 과거 release는 + `verify:promotion -- --archived`를 통과하지 못한다. +3. 그런 release를 다시 써야 하면 새 키로 provider 검증을 다시 받는다. 같은 후보 + archive를 대상으로 한 새 provider 실행이 필요하고, 다시 빌드하지 않는다. 이 + repo에는 이 재검증 전용 job이 없다. 필요한 프로젝트가 만든다. + ## External promotion controls Promotion reads the provider files named by `VULNERABILITY_REPORT_PATH` and