docs: runbook·보안·스타일·접근성·계약·테스트 문서와 모듈 README를 한국어로 옮긴다

문제: docs/runbooks, docs/security, docs/styling/design-tokens.md,
docs/accessibility, docs/contracts, docs/testing/taxonomy.md와
src/adapters/browser-transfer/image-cdn/README.md는 본문이 영어다.
PRODUCT.md는 「~합니다」 체라 한 문서 안 문체 규칙(「~한다」)과 다르다.

고른 방법: 뜻을 바꾸지 않고 옮긴다. runbook 제목의 ID와 오류 code,
기록 양식의 영어 키(`Status:`, `M1 Keyboard:` 등, 코드 블록 안)는 그대로
둔다. PRODUCT.md는 디자인 도구가 읽는 제목(`## Users` 등)을 두고 문장
끝만 바꾼다.

위험: 이 커밋으로 문서 검사의 예외 목록이 빈다. 앞으로 영어 문서나 높임
문체를 더하면 verify:documentation이 실패한다.

검증: 백틱 span·링크 대상·코드 블록을 옮기기 전과 python으로 비교해 같다.
문서 검사 여섯이 모두 0건이고 예외 목록과 FROZEN이 비었다.
This commit is contained in:
DongHyeonka
2026-11-08 21:57:47 +09:00
parent 45e8cb774c
commit 11530b1adf
15 changed files with 687 additions and 761 deletions
+25 -25
View File
@@ -1,28 +1,28 @@
# Browser security boundary
# 브라우저 보안 경계
The browser bundle is public. Secrets, token lifecycle, raw HTML injection,
dynamic code execution, untrusted script URLs, and public production source
maps are prohibited defaults.
브라우저 bundle은 공개된다. 그래서 다음은 기본으로 금지한다: 비밀값, 토큰 수명
주기 관리, raw HTML 주입, 동적 코드 실행, 믿을 수 없는 script URL, 공개된
production source map.
`config/hosting/security-headers.json` is the declared header set. Hosting
verification compares that declaration with live responses. CSP deliberately
omits `unsafe-inline` and `unsafe-eval`; production code and built assets must
remain compatible with that baseline. `tests/e2e/production-csp.spec.ts` (part of
`test:e2e`, FE-GATE-008) serves the build with these headers and fails on a
`securitypolicyviolation` event or console error (review 13-08). zod probes
`Function("")` on its first object schema, which the policy would report on
every boot. `src/contracts/zod.ts` sets `jitless` to skip that probe, and every
module that builds a schema imports `z` from there, so the setting is applied
before the first schema whatever order the bundler evaluates chunks in.
`z.config` in the entry module would be too late. Import `z` from
`src/contracts/zod.ts`, not from `zod`, in new schema code. Features that are off by
default need CSP additions when a project selects them; see step 9 in
[optional adapter recipes](../architecture/optional-adapter-recipes.md).
`connect-src 'self' https:` lets script reach any HTTPS origin. Narrowing it to
the runtime config's `API_BASE_URL` and `TELEMETRY_ENDPOINT` origins needs a
header generated per environment at deploy time, because those values are set
per deployment (`scripts/generate-runtime-config.ts`). That generator does not
exist yet; a project that deploys should add it with its provider adapter.
선언된 header 집합은 `config/hosting/security-headers.json`이다. hosting 검증은
이 선언과 실제 응답을 비교한다. CSP는 일부러 `unsafe-inline`과 `unsafe-eval`을
뺀다. production 코드와 빌드된 asset은 이 기준선에서도 동작해야 한다.
`tests/e2e/production-csp.spec.ts`(`test:e2e`의 일부, FE-GATE-008)는 이 header로
빌드를 서빙한다. 그리고 `securitypolicyviolation` 이벤트나 console 오류가 나면
실패한다(리뷰 13-08). zod는 첫 object schema에서 `Function("")`을 시험 삼아
실행한다. 그러면 정책이 부트할 때마다 이것을 위반으로 보고한다.
`src/contracts/zod.ts`는 `jitless`를 켜서 이 시험을 건너뛴다. schema를 만드는
모든 모듈은 `z`를 그 파일에서 import한다. 그래서 bundler가 chunk를 어떤 순서로
평가하든 이 설정이 첫 schema보다 먼저 적용된다. entry 모듈에서 `z.config`를
부르면 너무 늦다. 새 schema 코드에서는 `z`를 `zod`가 아니라
`src/contracts/zod.ts`에서 import한다. 기본으로 꺼진 기능은 프로젝트가 그 기능을
고를 때 CSP에 항목을 더해야 한다.
[선택형 adapter recipe](../architecture/optional-adapter-recipes.md)의 9단계를 본다.
`connect-src 'self' https:`는 script가 모든 HTTPS origin에 닿게 둔다. 이것을
runtime config의 `API_BASE_URL`과 `TELEMETRY_ENDPOINT` origin으로 좁히려면
배포할 때 환경마다 header를 만들어야 한다. 그 값들은 배포마다 정해지기
때문이다(`scripts/generate-runtime-config.ts`). 그런 header 생성기는 아직 없다.
배포하는 프로젝트는 provider adapter를 만들 때 함께 더해야 한다.
Route guards are UX hints and client validation does not replace backend
authorization or validation.
route guard는 UX 힌트일 뿐이다. 클라이언트 검증은 백엔드의 인가(authorization)나
검증을 대신하지 않는다.
+253 -264
View File
@@ -1,30 +1,31 @@
# Build and supply-chain gate
# 빌드·공급망 gate
## Local blocking controls
## 로컬 차단 통제
- `pnpm install --frozen-lockfile --ignore-scripts` and a real manifest/lock
mismatch fixture; contract loading applies the root-only graph and lifecycle
policy to every registered command before the gate runner can spawn one, and
rejects nested installs without effective `--ignore-scripts`; npm script
traversal includes existing pre/post hooks unless an ordered bare or explicit
true `--ignore-scripts` suppresses them. Workspace/prefix and indirect
user/global config authority are rejected in npm options, direct or dynamic
assignments, exact `command`/`exec`/`env` prefix chains, cross-segment shell
state, and the inherited runner environment. Unknown or cwd-changing `env`
options and unquoted pre-delimiter pathname expansion fail closed, while the
explicitly modeled non-scope `env` options remain usable
- all direct and transitive lockfile rows with package SHA-512 integrity
- production/development, direct/transitive and platform-optional classification
- package-manifest license allow/deny policy
- approved inventory baseline digest and actual add/remove/change/upgrade diff
- independent review for new direct production dependencies
- CycloneDX 1.6 SBOM and inventory component/edge coherence
- source/lock/SBOM/dist-linked local provenance statement
- source, opt-in recipes, scripts, tests, tracked config/schema, public, built asset and generated
release metadata secret scan
- two-build `SOURCE_DATE_EPOCH` reproducibility check
- `pnpm install --frozen-lockfile --ignore-scripts`, 그리고 manifest와 lock이
실제로 어긋나는 fixture. contract를 읽을 때 등록된 모든 명령에 root 전용
그래프 정책과 lifecycle 정책을 적용한다. gate runner가 명령을 띄우기 전이다.
실제로 효력이 있는 `--ignore-scripts` 없이 하는 중첩 설치는 거부한다. npm
script를 따라갈 때는 이미 있는 pre/post hook도 따라간다. 단, 순서상 앞에 있는
`--ignore-scripts`가 hook을 막으면 따라가지 않는다. 값 없이 쓴(bare) 경우와
명시적으로 true를 준 경우가 그렇다. workspace·prefix 설정 권한과 간접적인
user·global 설정 권한은 다음 어디에 있어도 거부한다: npm 옵션, 직접 할당이나
동적 할당, 정확한 `command`/`exec`/`env` 접두 체인, segment를 넘나드는 shell
상태, 물려받은 runner 환경. 알 수 없거나 cwd를 바꾸는 `env` 옵션, 그리고
구분자 앞의 따옴표 없는 경로 확장은 허용하지 않고 실패한다(fail closed).
명시적으로 모델링한, scope와 무관한 `env` 옵션은 계속 쓸 수 있다
- 직접·전이 의존성의 lockfile 행 전부와 각 패키지의 SHA-512 integrity
- production/development, 직접/전이, platform 선택(platform-optional) 분류
- 패키지 manifest license의 허용·거부 정책
- 승인된 inventory baseline digest와 실제 추가·삭제·변경·업그레이드 diff
- 새 직접 production 의존성에 대한 독립 리뷰
- CycloneDX 1.6 SBOM, 그리고 inventory와의 component·edge 일치
- source·lock·SBOM·dist를 묶은 local provenance 문서(statement)
- secret scan. 대상은 source, 선택해서 켜는(opt-in) recipe, script, 테스트,
추적되는 config/schema, public 폴더, 빌드된 asset, 생성된 release metadata다
- 두 번 빌드해 비교하는 `SOURCE_DATE_EPOCH` 재현성 검사
The canonical commands are:
기준 명령은 다음과 같다.
```bash
corepack pnpm verify:lockfile
@@ -34,10 +35,9 @@ corepack pnpm verify:local-evidence
corepack pnpm check:supply-chain:fixtures
```
`config/security/dependency-baseline.json` is the approved local baseline.
Changing it requires `DEPENDENCY_BASELINE_OWNER` and
`DEPENDENCY_BASELINE_REASON`; editing the digest or hardcoding an empty diff is
rejected.
승인된 로컬 baseline은 `config/security/dependency-baseline.json`이다. 이것을
바꾸려면 `DEPENDENCY_BASELINE_OWNER`와 `DEPENDENCY_BASELINE_REASON`이 있어야
한다. digest를 직접 고치거나 빈 diff를 하드코딩하면 거부한다.
## 무엇을 증명하고 무엇을 증명하지 않는가
@@ -55,9 +55,11 @@ rejected.
번들 패키지 목록은 SBOM의 production 항목에 모두 들어 있어야 한다. 2026-09-25
기준으로 한 건이 어긋난다. `scheduler@0.27.0`은 `react-dom`의 의존성이라 번들에
들어가지만, SBOM과 `config/security/dependency-baseline.json`은 이것을
`development`로 분류한다. `pnpm list` JSON이 production 트리 아래에서 이 패키지를
`development`로 분류한다. `pnpm list` JSON이 production 트리 아래에서 이
패키지를
다시 보여 주지 않고, 그래서 `scripts/lib/supply-chain.ts`의 순회가 development
경로에서만 이것을 만난다. 분류를 고치면 dependency baseline을 다시 승인해야 하므로
경로에서만 이것을 만난다. 분류를 고치면 dependency baseline을 다시 승인해야
하므로
(`update:dependency-baseline`) 이 문서에 알려진 차이로 남긴다.
## 최소 구성과 전체 구성
@@ -74,7 +76,8 @@ workflow 전체를 한 번도 돌리지 않았다. 그래서 두 구성을 나
최소 구성으로 운영할 때 승격은 수동 승인이다. 승인자는 `immutable_build`가
올린 후보 archive의 SHA-256(job output `archive_sha256`)과 local evidence를
기록하고, 그 archive를 그대로 배포한다. 다시 빌드하지 않는다. `production_gate`는
기록하고, 그 archive를 그대로 배포한다. 다시 빌드하지 않는다.
`production_gate`는
`promotion` 뒤에만 돌므로 이 구성의 workflow에서는 실행되지 않는다. 운영
게이트(FE-GATE-019, 021~025)는 배포한 release를 대상으로
`corepack pnpm ci:gate -- FE-GATE-0xx`로 따로 돌려 기록한다.
@@ -108,262 +111,248 @@ SHA-256을 남긴다.
archive를 대상으로 한 새 provider 실행이 필요하고, 다시 빌드하지 않는다. 이
repo에는 이 재검증 전용 job이 없다. 필요한 프로젝트가 만든다.
## External promotion controls
## 외부 승격(promotion) 통제
Promotion reads the provider files named by `VULNERABILITY_REPORT_PATH` and
`PROVENANCE_ATTESTATION_PATH`. The vulnerability report must bind both the
exact lockfile digest and candidate `distSha256`; the provenance attestation
must name `dist` with that same digest. Both documents use strict schemas and
Ed25519 signatures verified with separately configured trusted public keys and
key IDs (`VULNERABILITY_PUBLIC_KEY_PATH`, `VULNERABILITY_KEY_ID`,
`PROVENANCE_PUBLIC_KEY_PATH`, and `PROVENANCE_KEY_ID`). Keys of another curve,
including Ed448, are rejected even if a document labels its algorithm
`Ed25519`. The two roles must use different key IDs and different canonical
DER-SPKI key bytes; giving the same key two IDs is rejected.
승격은 `VULNERABILITY_REPORT_PATH`와 `PROVENANCE_ATTESTATION_PATH`가 가리키는
provider 파일을 읽는다. 취약점 보고서(vulnerability report)는 정확한 lockfile
digest와 후보 `distSha256`을 둘 다 묶어야(bind) 한다. provenance attestation은
같은 digest로 `dist`를 명시해야 한다. 두 문서 모두 엄격한 schema와 Ed25519
서명을 쓴다. 서명은 따로 설정한 신뢰 공개 키와 key
ID(`VULNERABILITY_PUBLIC_KEY_PATH`, `VULNERABILITY_KEY_ID`,
`PROVENANCE_PUBLIC_KEY_PATH`, `PROVENANCE_KEY_ID`)로 검증한다. 다른 curve의 키는
거부한다. 문서가 알고리즘을 `Ed25519`라고 적어도 Ed448 키 같은 것은 거부한다. 두
역할은 서로 다른 key ID와 서로 다른 canonical DER-SPKI 키 바이트를 써야 한다.
같은 키에 ID 두 개를 붙여도 거부한다.
`immutable_build` archives the raw `pnpm-lock.yaml`, `dist` (including hidden
`.vite` files), the build manifest, module inventory, release verification,
secret-scan result, and local supply-chain evidence once. The candidate
manifest hashes the raw lockfile bytes and requires that digest to equal the
dependency inventory's `lockfileSha256`. Before upload, the producer validates
the manifest-bound exact archive member set and every member digest, then
publishes the archive SHA-256 as an immutable job output. The two provider jobs
download this same archive separately, compare that output digest, validate the
exact member set before extracting only into isolated roots, and receive
`CANDIDATE_LOCKFILE_PATH` and `CANDIDATE_DIST_SHA256`; configured
`VULNERABILITY_PROVIDER_COMMAND` and `PROVENANCE_PROVIDER_COMMAND` must emit the
signed reports. After each external command returns, provider upload validation
rechecks the unchanged archive and extracted candidate, parses the provider JSON
with its strict schema, and binds its dist and lockfile digests before upload.
`immutable_build`는 다음을 한 번만 archive로 묶는다: 가공하지 않은
`pnpm-lock.yaml`, `dist`(숨은 `.vite` 파일 포함), build manifest, module
inventory, release 검증 결과, secret scan 결과, 로컬 공급망 증거. 후보
manifest는 가공하지 않은 lockfile 바이트의 hash를 구하고, 그 digest가 의존성
inventory의 `lockfileSha256`과 같기를 요구한다. 올리기 전에 만드는
쪽(producer)은 manifest에 묶인 정확한 archive member 집합과 member마다의
digest를 검증한다. 그다음 archive SHA-256을 바뀌지 않는 job output으로 내보낸다.
두 provider job은 같은 archive를 각자 내려받아 그 output digest와 비교한다.
정확한 member 집합을 검증한 뒤 격리된 root에만 풀고, `CANDIDATE_LOCKFILE_PATH`와
`CANDIDATE_DIST_SHA256`을 받는다. 설정된 `VULNERABILITY_PROVIDER_COMMAND`와
`PROVENANCE_PROVIDER_COMMAND`는 서명된 보고서를 내야 한다. 외부 명령이 하나 끝날
때마다 provider upload 검증이 다음을 한다: archive와 풀어 둔 후보가 바뀌지
않았는지 다시 확인하고, provider JSON을 엄격한 schema로 파싱하고, 올리기 전에 그
dist digest와 lockfile digest를 묶는다.
If either provider input is absent, local verification remains meaningful but
`artifacts/security/supply-chain-verification.json` records
`promotionStatus: FAIL_UNVERIFIED`. The finalizer and downstream
`verify:promotion` exact-five validator then exit non-zero. Promotion derives
the candidate file set and digests only from the captured tar bytes, then
read-only revalidates archived executable schemas, archived policy/verifier
source bytes, raw lockfile, module inventory, build outputs, release coherence,
SBOM, provenance and supply-chain coherence. Candidate-internal checks are
recomputed; for the checkout-dependent secret scan, promotion independently
checks the archived policy, exact rule set, strict SARIF, zero findings and all
manifest/assessment digest bindings. It does not claim to rescan source bytes
that are not candidate members. It never rebuilds or rewrites candidate
evidence and never falls back to the checkout tree.
Promotion uploads the already verified archive itself with the two provider
reports and generated verification records; it does not create a replacement
archive from extracted files. Scanner or signing outages are not converted to
an empty PASS.
provider 입력이 하나라도 없으면 로컬 검증은 여전히 의미가 있다. 다만
`artifacts/security/supply-chain-verification.json`에
`promotionStatus: FAIL_UNVERIFIED`가 기록된다. 그러면 finalizer와 뒤에 오는
`verify:promotion` exact-five 검증기가 0이 아닌 코드로 끝난다. 승격은 후보 파일
집합과 digest를 붙잡아 둔(captured) tar 바이트에서만 얻는다. 그다음 읽기
전용으로 다음을 다시 검증한다: archive에 든 실행 schema, archive에 든
policy·verifier source 바이트, 가공하지 않은 lockfile, module inventory, build
출력, release 일관성, SBOM, provenance, 공급망 일관성. 후보 내부 검사는 다시
계산한다. checkout에 따라 달라지는 secret scan은 승격이 따로 확인한다: archive에
든 policy, 정확한 rule 집합, 엄격한 SARIF, 발견 0건, manifest·assessment digest
연결 전부. 후보 member가 아닌 source 바이트를 다시 검사했다고 주장하지 않는다.
후보 증거를 다시 빌드하거나 다시 쓰지 않고, checkout tree로 대신 가지도 않는다.
승격은 이미 검증한 archive 자체를 provider 보고서 두 개, 생성된 검증 기록과 함께
올린다. 풀어 둔 파일로 대체 archive를 만들지 않는다. scanner나 서명 서비스가
멈춰도 빈 PASS로 바꾸지 않는다.
The generated workflow is also a supply-chain control. `config/ci/gates.json`
is its sole typed authority. Run `corepack pnpm generate:ci-workflow` after a
contract change and `corepack pnpm check:ci-workflow` (or the encompassing
`corepack pnpm check:ci`) to reject byte drift in the checked-in Gitea adapter.
생성된 workflow도 공급망 통제다. 그 workflow의 유일한 타입 있는 원천(typed
authority)은 `config/ci/gates.json`이다. contract를 바꾼 뒤
`corepack pnpm generate:ci-workflow`를 돌린다. 그리고
`corepack pnpm check:ci-workflow`(또는 이것을 포함하는
`corepack pnpm check:ci`)로 commit된 Gitea adapter의 바이트 어긋남을 거부한다.
Action resolution is separately closed over one typed, runtime-frozen registry
in `scripts/contracts/ci-gates.ts`. Every generated `uses:` value is an absolute
upstream URL pinned to a full commit SHA:
action 해석은 따로, `scripts/contracts/ci-gates.ts`에 있는 타입 있는 registry
하나 안에서만 닫혀 있다. 이 registry는 runtime에 얼려 둔다(frozen). 생성된
`uses:` 값은 모두 전체 commit SHA로 고정한 절대 upstream URL이다.
- `https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5`
(`v4.3.1`)
- `https://github.com/actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020`
(`v4.4.0`)
- `https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7`
(patched `v4` branch)
(패치한 `v4` branch)
- `https://github.com/ChristopherHX/gitea-download-artifact@75635f32b4c1c41c4b3d64e8f85210112ed4c9c7`
(patched `v4` branch)
(패치한 `v4` branch)
Unknown actions, relative repositories, tags/branches and short SHAs are
rejected. Gitea 1.22's official Actions documentation recommends the
`ChristopherHX` patched artifact forks for v4 compatibility; the supported
deployment baseline is nevertheless Gitea 1.26.4+ with Gitea Runner 1.0.0+.
A real end-to-end provider smoke on the staging Gitea instance remains
mandatory before any generated job becomes a required check.
알 수 없는 action, 상대 repository, tag·branch, 짧은 SHA는 거부한다. Gitea 1.22
공식 Actions 문서는 v4 호환을 위해 `ChristopherHX`가 패치한 artifact fork를
권한다. 그래도 지원하는 배포 기준선은 Gitea 1.26.4 이상과 Gitea Runner 1.0.0
이상이다. 생성된 job을 필수 검사(required check)로 만들기 전에 staging Gitea
인스턴스에서 실제 end-to-end provider smoke를 꼭 돌려야 한다.
External provider supervision is fail-closed and requires a Linux runner with
executable `/usr/bin/bwrap`, `/usr/bin/prlimit`, `/usr/bin/systemd-run`, and
`/usr/bin/systemctl`, bubblewrap support for `--size`, an active user bus, a
systemd user manager version 254 or newer, unified cgroup v2, and delegated
memory, pids, and CPU controllers. The runner must also let an unprivileged
process create user and network namespaces with bubblewrap: the sandbox runs
`bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`, and Ubuntu
23.10 and later refuse that while
`kernel.apparmor_restrict_unprivileged_userns=1` unless `/usr/bin/bwrap` has
an AppArmor profile that allows `userns` (1105/12-01). The same holds for
FE-GATE-013, whose `test:system` probes it first
(`scripts/check-system-test-prerequisites.ts`); the fixes are in
`docs/operations/ci-quality-gates.md`. Executable access, user-manager/version,
trust, archive, and path failures are rejected before raw creation. Bubblewrap
`--size` acceptance and effective delegated controller values can only be
verified after the owned raw inode exists inside a new scope; failures there
remove that inode by identity and fail closed. Each invocation runs in a unique collected user scope and verifies
its effective cgroup membership and limits before bubblewrap starts: memory is
exactly 1 GiB, swap is zero, `TasksMax` is 64, and CPU quota is 100% per 100 ms.
The inner process also has zero core size, a 8,388,607-byte file-size limit,
64 open files and at most 1,200 CPU seconds. `TasksMax=64` is the authoritative
aggregate PID boundary; no per-provider `RLIMIT_NPROC=32` claim is made because
that limit is counted across the runner's same-UID process population.
외부 provider 감독은 fail closed다. 다음을 갖춘 Linux runner가 필요하다: 실행할
수 있는 `/usr/bin/bwrap`, `/usr/bin/prlimit`, `/usr/bin/systemd-run`,
`/usr/bin/systemctl`, `--size`를 지원하는 bubblewrap, 동작 중인 user bus, 254
이상인 systemd user manager, 통합(unified) cgroup v2, 위임된 memory·pids·CPU
controller. runner는 권한 없는 프로세스가 bubblewrap으로 user namespace와
network namespace를 만들 수 있게도 해야 한다. sandbox는
`bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`을 실행한다.
Ubuntu 23.10 이상은 `kernel.apparmor_restrict_unprivileged_userns=1`이면 이것을
거부한다. 단, `/usr/bin/bwrap`에 `userns`를 허용하는 AppArmor profile이 있으면
허용한다(1105/12-01). FE-GATE-013도 마찬가지다. 그 gate의 `test:system`이 이것을
먼저 검사한다(`scripts/check-system-test-prerequisites.ts`). 고치는 법은
`docs/operations/ci-quality-gates.md`에 있다. 실행 권한, user manager·버전,
신뢰, archive, 경로 실패는 raw 파일을 만들기 전에 거부한다. bubblewrap이
`--size`를 받아들이는지와 실제로 위임된 controller 값은, 새 scope 안에 자기가
소유한 raw inode가 생긴 뒤에만 검증할 수 있다. 거기서 실패하면 그 inode를
identity로 찾아 지우고 fail closed한다. 호출마다 고유한 user scope 안에서 돌고,
그 scope는 끝나면 수거된다(collected). bubblewrap이 시작하기 전에 실제 cgroup
소속과 제한을 검증한다: memory는 정확히 1 GiB, swap은 0, `TasksMax`는 64, CPU
quota는 100 ms마다 100%다. 안쪽 프로세스에는 core 크기 0, 파일 크기 제한
8,388,607바이트, 열린 파일 64개, CPU 시간 최대 1,200초도 걸린다. 전체 PID 수의
기준 경계는 `TasksMax=64`다. provider마다 `RLIMIT_NPROC=32`가 걸린다고 주장하지
않는다. 그 제한은 runner에서 같은 UID로 도는 프로세스를 모두 함께 세기 때문이다.
Bubblewrap uses a private network namespace (`--unshare-net`), mounts the
workspace and verified candidate read-only, hides `.git`, and read-only binds
the trusted `process.execPath` at `/tmp/node`. The supervisor creates and pins
the exact configured raw-report inode only after sandbox/trust/archive
preflight; that inode is the only provider evidence path mounted read-write.
The provider cannot write the surrounding `untrusted` directory, workspace,
candidate, host home/toolcache, sealed evidence path, or general temporary
filesystem. Pre-execution and provider failures remove only the supervisor-
owned raw inode so the same job can retry without a stale empty report.
bubblewrap은 전용 network namespace(`--unshare-net`)를 쓴다. workspace와 검증된
후보를 읽기 전용으로 mount하고, `.git`을 숨기고, 신뢰하는 `process.execPath`를
`/tmp/node`에 읽기 전용으로 bind한다. supervisor는 sandbox·신뢰·archive 사전
점검(preflight)이 끝난 뒤에만 설정에 적힌 바로 그 raw 보고서 inode를 만들고
고정(pin)한다. 그 inode가 읽기·쓰기로 mount되는 유일한 provider 증거 경로다.
provider는 둘러싼 `untrusted` 디렉터리, workspace, 후보, host home·toolcache,
봉인된 증거 경로, 일반 임시 파일 시스템에 쓸 수 없다. 실행 전 실패와 provider
실패는 supervisor가 소유한 raw inode만 지운다. 그래서 같은 job이 낡은 빈 보고서
없이 다시 시도할 수 있다.
The complete bwrap argument/environment vector, including the provider command
and provider-prefixed environment, is carried in a bounded length-prefixed frame over
`systemd-run` stdin rather
than placed in the supervisor, systemd, or bwrap wrapper argv. This prevents
credentials from entering unit metadata and wrapper command lines. The final
provider executable and its ordinary arguments remain visible to same-UID
process inspection, so commands must never contain tokens or secrets. The same
stdin remains open as a parent-liveness channel until normal provider exit; EOF
caused by supervisor death makes the in-scope wrapper kill the provider process
group and remove only the dev/inode-matched raw report. Supply
credentials only through the provider-kind prefix
(`VULNERABILITY_PROVIDER_*` or `PROVENANCE_PROVIDER_*`, excluding `*_COMMAND`).
bwrap 인자·환경 벡터 전체는 provider 명령과 provider 접두 환경 변수를 포함해,
길이를 앞에 붙인 크기 제한 frame에 담겨 `systemd-run` stdin으로 전달된다.
supervisor, systemd, bwrap wrapper의 argv에는 넣지 않는다. 그래서 자격 증명이
unit metadata와 wrapper 명령줄에 들어가지 않는다. 마지막 provider 실행 파일과 그
일반 인자는 같은 UID의 프로세스 조회로 여전히 보인다. 그러므로 명령에는 토큰이나
비밀값을 절대 넣지 않는다. 같은 stdin은 provider가 정상 종료할 때까지 부모 생존
확인 채널로 열려 있다. supervisor가 죽어서 EOF가 오면 scope 안 wrapper가
provider 프로세스 그룹을 죽이고, dev/inode가 맞는 raw 보고서만 지운다. 자격
증명은 provider 종류 접두(`VULNERABILITY_PROVIDER_*` 또는
`PROVENANCE_PROVIDER_*`, `*_COMMAND` 제외)로만 넘긴다.
A separate trusted guardian starts outside the provider scope and owns the
filesystem transaction. Before spawn, the client opens and identity-checks the
canonical raw and evidence directories with `O_DIRECTORY|O_NOFOLLOW`, derives
the exact canonical and nonce-private leaves, and exclusively allocates empty
mode-`0600` raw-staging and sealed-temp files. It records both dev/inode pairs
before spawn and inherits the directory descriptors as guardian fd 3/fd 4 and
the private file descriptors as fd 5/fd 6. Its argv contains only the trusted
Node and helper paths. A bounded canonical v2 request carries only provider
kind, an absolute deadline, and a random 32-byte control nonce.
신뢰하는 별도 guardian이 provider scope 밖에서 시작해 파일 시스템 트랜잭션을
맡는다. 띄우기(spawn) 전에 client는 canonical raw 디렉터리와 증거 디렉터리를
`O_DIRECTORY|O_NOFOLLOW`로 열고 identity를 확인한다. 정확한 canonical leaf와
nonce 전용 leaf를 정하고, mode `0600`인 빈 raw-staging 파일과 sealed-temp 파일을
배타적으로 만든다. 띄우기 전에 두 dev/inode 쌍을 기록한다. 디렉터리 descriptor는
guardian의 fd 3/fd 4로, 전용 파일 descriptor는 fd 5/fd 6으로 물려준다.
guardian의 argv에는 신뢰하는 Node 경로와 helper 경로만 있다. 크기 제한이 있는
canonical v2 요청에는 provider 종류, 절대 마감 시각, 무작위 32바이트 control
nonce만 담긴다.
At bootstrap the guardian fstats fd 5/fd 6 before reading their procfs links.
Each procfs target is accepted only as a direct-child alias whose exact grammar,
descriptor-relative lstat, type, mode, size, link count, and dev/inode match the
already-recorded descriptor identity. The guardian publishes raw staging to the
fixed raw leaf with a no-overwrite hard link, verifies both aliases at link
count two, removes the private raw alias, syncs the raw directory, and verifies
the canonical raw alias at link count one before authenticated READY. If startup
ends before READY is accepted, the client cleans raw staging/canonical only when
they match its pre-spawn raw identity and sealed temp/final only when they match
its pre-spawn sealed identity. It never derives cleanup ownership by opening a
current canonical pathname, so an external file or a concurrent same-kind
winner is preserved. Provider execution starts only after the supervisor
confirms that the returned identities and canonical targets match exactly.
시작(bootstrap)할 때 guardian은 procfs link를 읽기 전에 fd 5/fd 6을 fstat한다.
각 procfs 대상은 바로 아래 자식(direct-child) alias일 때만 받아들인다. 그리고
정확한 문법, descriptor 기준 lstat, 종류, mode, 크기, link 수, dev/inode가 이미
기록한 descriptor identity와 맞아야 한다. guardian은 raw staging을 덮어쓰지 않는
hard link로 고정된 raw leaf에 게시한다. 이어서 두 alias의 link 수가 2인지
확인하고, 전용 raw alias를 지우고, raw 디렉터리를 sync하고, canonical raw
alias의 link 수가 1인지 확인한다. 이 모두가 인증된 READY 전에 일어난다. READY가
받아들여지기 전에 시작이 끝나면 client는 다음만 치운다: 띄우기 전 raw identity와
맞는 raw staging·canonical, 띄우기 전 sealed identity와 맞는 sealed temp·final.
지금 있는 canonical 경로 이름을 열어서 치울 권한을 정하지 않는다. 그래서 외부
파일이나 동시에 돈 같은 종류의 승자(winner)는 보존된다. provider 실행은 돌려받은
identity와 canonical 대상이 정확히 맞는다고 supervisor가 확인한 뒤에만 시작한다.
After evidence validation, the supervisor writes schema-validated bytes to the
pinned temp inode, changes it to `0400`, fsyncs it, and sends authenticated
size/hash/identity metadata. The guardian verifies the held descriptor and
pathname, publishes without replacement using same-directory `link`, removes
the temp name, fsyncs the directory, and returns authenticated PUBLISHED. Only
after successful `GITHUB_OUTPUT` append does the supervisor send commit. Commit
removes the raw inode and enters `commitPending`; clean control EOF is the sole
success terminal and preserves the sealed final. EOF without that terminal,
deadline expiry, malformed/trailing control data, a wrong nonce, or premature
guardian exit cleans every matching raw/temp/final identity and fails closed.
Guardian loss while the provider scope is active also triggers whole-scope kill
and collection.
증거 검증이 끝나면 supervisor는 schema로 검증한 바이트를 고정한 temp inode에
쓰고, `0400`으로 바꾸고, fsync한 뒤, 인증된 크기·hash·identity metadata를
보낸다. guardian은 쥐고 있는 descriptor와 경로 이름을 검증하고, 같은 디렉터리 안
`link`로 교체 없이 게시하고, temp 이름을 지우고, 디렉터리를 fsync한 뒤, 인증된
PUBLISHED를 돌려준다. supervisor는 `GITHUB_OUTPUT` 덧붙이기가 성공한 뒤에만
commit을 보낸다. commit은 raw inode를 지우고 `commitPending`에 들어간다. 깨끗한
control EOF만이 성공 종료이고, 봉인된 final을 보존한다. 다음 경우에는 맞는
raw·temp·final identity를 모두 치우고 fail closed한다: 그 종료 없이 온 EOF, 마감
시각 초과, 형식이 틀리거나 뒤에 남는 control 데이터, 틀린 nonce, guardian의 이른
종료. provider scope가 살아 있는 동안 guardian을 잃어도 scope 전체를 죽이고
수거한다.
`GITHUB_OUTPUT` is assumed to be a runner-owned regular file. This protocol
does not claim OS-level cancellation of sealing or output I/O. If the guardian
exits after scope collection, the scope-active latch records the lifecycle error
without starting a late kill. Publication or terminal commit observes the
nonzero exit and the client removes every identity-pinned raw/temp/final
fallback before failing closed. The lease is bounded by the 30-minute provider
wall limit plus a fixed ten-minute post-processing allowance.
`GITHUB_OUTPUT`은 runner가 소유한 일반 파일이라고 가정한다. 이 protocol은
봉인이나 output I/O를 OS 수준에서 취소한다고 주장하지 않는다. scope를 수거한 뒤
guardian이 끝나면, scope-active latch가 lifecycle 오류를 기록하되 뒤늦은 kill은
시작하지 않는다. 게시나 마지막 commit 단계가 0이 아닌 종료를 보면, client는
identity로 고정한 raw·temp·final 잔여 파일(fallback)을 모두 지우고 fail closed
한다. lease는 provider 실제 시간(wall) 제한 30분에 고정 후처리 여유 10분을
더한 시간으로 제한된다.
A client hard stop after private allocation but before guardian spawn can leave
only empty mode-`0600` nonce-private leaves. Automatic sweeping is intentionally
omitted because an unrecorded pathname does not prove ownership; these private
leaves cannot occupy the fixed raw or final names and do not block a retry.
전용 파일을 만든 뒤 guardian을 띄우기 전에 client가 강제로 멈추면, mode `0600`인
빈 nonce 전용 leaf만 남을 수 있다. 자동 정리는 일부러 넣지 않았다. 기록되지 않은
경로 이름은 소유를 증명하지 못하기 때문이다. 이 전용 leaf는 고정된 raw 이름이나
final 이름을 차지할 수 없고, 재시도를 막지 않는다.
Provider stdout and stderr are untrusted secret-bearing bytes. The supervisor
does not retain or forward them to CI logs; it counts them only to enforce one
1 MiB aggregate limit. Guardian diagnostics are best effort, so closed stderr
or control descriptors cannot bypass cleanup or the required nonzero exit. The
provider wall-clock limit is 30 minutes. Wall timeout, output overflow, parent-liveness loss,
and active-scope guardian loss explicitly SIGKILL the whole provider process group. Ordinary command and
RLIMIT failures complete through systemd with their concrete exit/signal; every
path still waits for wrapper closure and requires the systemd unit/cgroup to be
collected before returning. Provider adapters must therefore operate entirely from pre-populated
offline data, consume the supplied candidate bindings, and write exactly the
pinned report inode. Missing prerequisites, cgroup drift, stale or misplaced
outputs, post-command candidate drift, and residual scope cleanup all stop
publication.
provider stdout과 stderr는 비밀값을 담고 있을 수 있는 믿을 수 없는 바이트다.
supervisor는 이것을 보관하지도, CI 로그로 넘기지도 않는다. 합계 1 MiB 제한
하나를 지키려고 바이트 수만 센다. guardian 진단은 최선 노력(best effort)이다.
그래서 stderr나 control descriptor가 닫혀도 정리 작업이나 필수인 0이 아닌 종료를
건너뛸 수 없다. provider 실제 시간 제한은 30분이다. 실제 시간 초과, 출력 초과,
부모 생존 확인 끊김, scope가 살아 있을 때의 guardian 손실은 provider 프로세스
그룹 전체에 명시적으로 SIGKILL을 보낸다. 일반 명령 실패와 RLIMIT 실패는
systemd를 거쳐 구체적인 exit·signal로 끝난다. 어느 경로든 wrapper가 닫히기를
기다리고, 돌아오기 전에 systemd unit·cgroup이 수거되기를 요구한다. 그러므로
provider adapter는 미리 채워 둔 오프라인 데이터만으로 동작하고, 받은 후보
binding을 쓰고, 고정된 보고서 inode에 정확히 써야 한다. 다음은 모두 게시를
멈춘다: 전제 조건 누락, cgroup 어긋남(drift), 낡았거나 엉뚱한 곳에 있는 출력,
명령 뒤 후보 어긋남, scope 정리 잔여물.
Provider documents are strict schema v2. Their Ed25519 signature covers the
supervisor-supplied evidence type, validity window, run ID/attempt, independent
32-byte invocation nonce, archived source identity, and all four candidate
digests. Each provider job exposes its supervisor-generated nonce as a job
output; promotion treats those outputs as the independent expected values and
never lets a report define its own expected nonce. A report from another
attempt, source, archive, nonce, or key fingerprint is fail-closed even when it
has been correctly re-signed.
provider 문서는 엄격한 schema v2다. Ed25519 서명이 덮는 범위는 다음과 같다:
supervisor가 준 증거 종류, 유효 기간, run ID·attempt, 독립된 32바이트 호출
nonce, archive에 든 source identity, 후보 digest 네 개 전부. provider job마다
supervisor가 만든 nonce를 job output으로 내보낸다. 승격은 그 output을 독립된
기대값으로 쓰고, 보고서가 자기 기대 nonce를 정하게 두지 않는다. 다른 attempt,
source, archive, nonce, 키 지문에서 온 보고서는 올바르게 다시 서명됐더라도 fail
closed다.
The immutable archive contains a strict producer-local assessment plus the
policy and verifier source bytes needed to validate its archived relationships.
Promotion recomputes candidate-internal checks and validates the captured
secret-scan policy/rules/SARIF/digest relationships from an isolated extraction
root; it does not reopen checkout policy or source paths or claim to rescan
unarchived checkout source. The finalizer captures the archive,
both reports, and both public keys once, generates both verification v3 records
in memory, and writes exactly five mode-`0400` files beneath a random
mode-`0700` directory in `RUNNER_TEMP`, independently of a restrictive runner
umask. The exact five are the captured archive, captured vulnerability report,
captured provenance attestation, generated provider-verification v3, and
generated promotion-verification v3. Before returning, the finalizer validates
those exact bytes again with live-time provider signature/freshness checks. The
promotion record binds the exact provider-record hash, local-assessment hash,
both report hashes, run/source/candidate identities, both nonces, both key
IDs/fingerprints, canonical trust-policy hash, and the vulnerability provider's
signed `secretScanAttestation`. That strict attestation says `PASS` and binds
the captured local-assessment, source-set, secret-scan policy, SARIF, and actual
scan-input digests. The supervisor derives the expected tuple from the captured
archive and exact equality is rechecked at upload and finalization. The trusted
vulnerability provider remains responsible for independently scanning that
source set and refusing to sign a forged empty SARIF or incomplete scan input;
the signature proves the provider made the claim, not that an untrusted
provider performed the scan honestly. It never creates or reuses
`.release/promoted-staging`.
바뀌지 않는(immutable) archive에는 producer 쪽의 엄격한 로컬 assessment와,
archive 안 관계를 검증하는 데 필요한 policy·verifier source 바이트가 들어 있다.
승격은 격리된 압축 해제 root에서 후보 내부 검사를 다시 계산하고, 붙잡아 둔
secret scan의 policy·rule·SARIF·digest 관계를 검증한다. checkout의 policy나
source 경로를 다시 열지 않고, archive에 없는 checkout source를 다시 검사했다고
주장하지 않는다. finalizer는 archive, 보고서 두 개, 공개 키 두 개를 한 번 붙잡아
두고, 검증 v3 기록 두 개를 메모리에서 만든다. 그리고 `RUNNER_TEMP` 안 무작위
mode `0700` 디렉터리 아래에 mode `0400` 파일을 정확히 다섯 개 쓴다. runner
umask가 엄격해도 이 mode는 그대로다. 다섯 개는 붙잡아 둔 archive, 붙잡아 둔
취약점 보고서, 붙잡아 둔 provenance attestation, 생성한 provider-verification
v3, 생성한 promotion-verification v3다. 돌아오기 전에 finalizer는 바로 그
바이트를 현재 시각 기준의 provider 서명·신선도 검사로 다시 검증한다. 승격 기록은
다음을 묶는다: 정확한 provider 기록 hash, 로컬 assessment hash, 보고서 hash 두
개, run·source·후보 identity, nonce 두 개, key ID·지문 두 개, canonical trust
policy hash, 취약점 provider가 서명한 `secretScanAttestation`. 그 엄격한
attestation은 `PASS`라고 적고, 붙잡아 둔 로컬 assessment, source 집합, secret
scan policy, SARIF, 실제 scan 입력의 digest를 묶는다. supervisor는 붙잡아 둔
archive에서 기대 tuple을 얻는다. upload와 마무리(finalization) 때 그 tuple과
정확히 같은지 다시 확인한다. 그 source 집합을 독립적으로 검사하고, 위조된 빈
SARIF나 불완전한 scan 입력에는 서명을 거부할 책임은 여전히 신뢰하는 취약점
provider에게 있다. 서명은 provider가 그 주장을 했다는 것을 증명할 뿐이다. 믿을
수 없는 provider가 검사를 성실히 했다는 것은 증명하지 않는다. finalizer는
`.release/promoted-staging`을 만들지도 재사용하지도 않는다.
The final promotion verification/staging step must be immediately adjacent to
the promoted-release upload, and that upload must not use `always()`. This
reduces the post-verification mutation window but does not seal a pathname
across two action steps. The runner is therefore required to be trusted,
exclusive and single-tenant, with no provider command or other same-UID process
surviving from staging into the immediately following upload. The artifact
service and transfer actions also remain outside the candidate's cryptographic
identity: every downstream consumer must revalidate the downloaded archive,
manifest member digests and signed provider evidence. Producer-side adjacency
does not provide consumer-side digest revalidation.
The promotion job has no job-level `if`: ordinary `needs` success semantics
require immutable build and both provider jobs to succeed, and cancellation is
not overridden with `always()` or `cancelled()`. Cleanup alone uses bare `always()`
and is guarded by all six finalizer outputs: staging path, token, parent
device/inode, and staging-leaf device/inode. Cleanup opens the pinned leaf,
requires the exact five names, unlinks only those known files through the
descriptor, and uses a non-recursive `rmdir`; an exchanged directory or canary
is never recursively removed.
The immediately following upload action still reopens pathnames. The
descriptor-relative staging and cleanup code does not claim an atomic
`renameat2` handoff or close a malicious same-UID Gitea upload adapter; the
staging Gitea smoke/native platform adapter remains the required closure for
that boundary. That smoke must exercise exact-five upload and download plus
cleanup on success, validation failure, upload failure, and cancellation. No
native uploader or `renameat2` guarantee exists in this repository today.
Portable Node also cannot make `mkdir` plus the first pathname `lstat` atomic.
The implementation compares the immediate post-`mkdir` identity with the
subsequent `O_DIRECTORY|O_NOFOLLOW` descriptor before changing permissions, but
a malicious same-UID actor that wins before that first `lstat` remains part of
the native/privilege boundary. The private `0700` runner-temp ancestor and
single-tenant runner requirement are therefore security controls, not merely
hardening.
Failure cleanup is armed only after that created device/inode matches the opened
descriptor. If the opened descriptor is a replacement, it is closed without
unlinking or removing anything; the visible replacement is likewise untouched.
Portable Node cannot safely rediscover an attacker-moved original directory by
scanning the parent, so that residual must be removed by the isolated test
fixture or trusted runner/native cleanup after the attacker is excluded.
마지막 승격 검증·staging 단계는 승격된 release upload 바로 앞에 붙어 있어야
하고, 그 upload는 `always()`를 쓰면 안 된다. 이렇게 하면 검증 뒤 내용이 바뀔 수
있는 시간 틈이 준다. 하지만 두 action 단계에 걸쳐 경로 이름을 봉인하지는 못한다.
그래서 runner는 신뢰할 수 있고, 독점적이고, 단일 tenant여야 한다. staging에서
바로 다음 upload까지 provider 명령이나 같은 UID의 다른 프로세스가 살아남으면 안
된다. artifact 서비스와 전송 action도 후보의 암호학적 identity 밖에 있다.
그러므로 뒤에 오는 모든 소비자는 내려받은 archive, manifest member digest,
서명된 provider 증거를 다시 검증해야 한다. producer 쪽에서 단계를 붙여 둔다고
소비자 쪽 digest 재검증이 되지는 않는다.
승격 job에는 job 수준 `if`가 없다. 일반 `needs` 성공 규칙에 따라 immutable
build와 provider job 두 개가 모두 성공해야 한다. 취소는 `always()`나
`cancelled()`로 덮어쓰지 않는다. 정리(cleanup) 단계만 조건 없는 `always()`를
쓰고, finalizer output 여섯 개 전부로 보호된다: staging 경로, token, 부모
device/inode, staging leaf device/inode. 정리 단계는 고정한 leaf를 열고, 정확히
그 다섯 이름을 요구하고, descriptor를 거쳐 그 알려진 파일만 unlink하고, 재귀하지
않는 `rmdir`를 쓴다. 바꿔치기된 디렉터리나 canary는 절대 재귀로 지우지 않는다.
바로 다음 upload action은 여전히 경로 이름을 다시 연다. descriptor 기준
staging·정리 코드는 원자적인 `renameat2` 넘겨주기를 한다고 주장하지 않는다.
악의적인 같은 UID의 Gitea upload adapter를 막는다고도 주장하지 않는다. 그 경계를
닫으려면 여전히 staging Gitea smoke와 native platform adapter가 필요하다. 그
smoke는 exact-five upload·download를 돌리고, 성공·검증 실패·upload 실패·취소
때의 정리도 실제로 돌려 봐야 한다. 지금 이 repository에는 native uploader도
`renameat2` 보장도 없다.
이식 가능한(portable) Node는 `mkdir`와 첫 경로 이름 `lstat`를 하나의 원자적
동작으로 만들 수도 없다. 구현은 권한을 바꾸기 전에 `mkdir` 직후의 identity를
그다음 `O_DIRECTORY|O_NOFOLLOW` descriptor와 비교한다. 그러나 첫 `lstat` 전에
끼어든 악의적인 같은 UID 행위자는 native·권한 경계가 맡아야 할 몫으로 남는다.
그러므로 전용 `0700` runner-temp 상위 디렉터리와 단일 tenant runner 요구는
단순한 강화(hardening)가 아니라 보안 통제다.
실패 정리는 만든 device/inode가 연 descriptor와 맞은 뒤에만 켜진다. 연
descriptor가 바꿔치기된 것이면 아무것도 unlink하거나 지우지 않고 닫는다. 눈에
보이는 바꿔치기 대상도 마찬가지로 건드리지 않는다. 이식 가능한 Node는 부모
디렉터리를 훑어서 공격자가 옮긴 원래 디렉터리를 안전하게 다시 찾을 수 없다.
그래서 그 잔여물은 공격자를 배제한 뒤 격리된 test fixture나, 신뢰하는
runner·native 정리가 지워야 한다.
Approved vulnerability exceptions require vulnerability/package identity,
owner, a different reviewer, reason and expiry. Expired or self-approved
exceptions are blocking.
승인된 취약점 예외에는 취약점·패키지 identity, owner, owner와 다른 리뷰어, 이유,
만료일이 있어야 한다. 만료됐거나 스스로 승인한 예외는 차단한다.