Files
clean-architecture-frontend…/docs/security/supply-chain.md
T
DongHyeonka 9655958bda fix(ci): test:system 사전 점검이 bwrap namespace를 실제로 만들어 본다
문제: FE-GATE-013의 provider sandbox는 bwrap을 --unshare-pid
--unshare-ipc --unshare-uts --unshare-net으로 띄운다. bwrap이 setuid가
아니므로 비특권 user namespace가 있어야 한다. 사전 점검
(scripts/check-system-test-prerequisites.ts)은 실행 파일·cgroup·systemd
bus만 보고 bwrap을 한 번도 실행하지 않는다. 그래서 이 제한이 있는 호스트
(Ubuntu 24.04, kernel.apparmor_restrict_unprivileged_userns=1)에서 PASS를
낸 뒤 provider 테스트 114건 중 18건이 "bwrap: loopback: Failed
RTM_NEWADDR: Operation not permitted" 또는 그 provider를 기다린 시간
초과로 실패한다. 이 조건은 runner 요구 목록, gate 정의, workflow 어디에도
없고 운영 원장의 일회성 메모에만 있다.

고른 방법:
- 사전 점검이 provider와 같은 namespace 옵션으로 bwrap에서 /bin/true를 한
  번 띄운다. 실패하면 "this host does not allow unprivileged user and
  network namespaces", bwrap stderr(최대 4줄), user namespace sysctl 값,
  고치는 방법 셋(AppArmor profile, sysctl, 다른 runner)을 적고 exit 1.
  기존 검사(실행 파일 3개, cgroup v2, systemd bus)는 그대로 둔다.
- 옵션 목록을 scripts/lib/provider-sandbox-namespaces.ts로 옮기고
  run-and-validate-provider.ts와 사전 점검이 같은 상수를 쓴다. 둘이
  갈라지면 점검이 다른 것을 시험하게 된다.
- 점검을 findSystemTestPrerequisiteFailures(host)로 내보내고 access·
  readFile·spawn을 주입받는다. CLI 동작(출력·exit 코드)은 같다.
- config/ci/gates.json의 FE-GATE-013에 hostRequirements 두 줄을 둔다.
  gate schema에 선택 필드를 더하고, generator가 그 gate를 도는 job의
  runs-on 바로 위에 "# FE-GATE-013 runner requirement: ..." 주석으로
  그린다. runner를 고르는 사람이 보는 자리다. 줄바꿈은 기존 nonEmpty
  규칙이 막으므로 주석 밖으로 나갈 수 없다. 이 필드는 gate의 명령·증거가
  아니라 runner 설명이라 기준선 gate shape 해시에는 넣지 않았다(기준선
  재기록 불필요).
- 요구 목록 세 곳(docs/operations/ci-quality-gates.md,
  docs/security/supply-chain.md, docs/testing/taxonomy.md)과 README merge
  게이트 절에 조건을 적었다. ci-quality-gates.md에 AppArmor profile 예시를
  두었다.

버린 대안:
- namespace가 없으면 provider 테스트를 skip: 거짓 초록이다.
- FE-GATE-013을 release 단계로 옮김: PR마다 sandbox 검사를 잃는다.
- probe를 systemd-run --user --scope 안에서 돌림: 리뷰 11-R10에서 scope
  안과 밖의 결과가 같았다. 직접 실행이 더 단순하다.
- workflow에 요구 사항을 runs-on label로 표현: runner label 체계가 아직
  없다. 주석이 지금 가능한 가장 작은 표시다.

위험·한계:
- probe는 bwrap에 --ro-bind / /만 준다. --size 같은 provider의 다른
  옵션 지원은 여기서 보지 않는다(기존과 같다). probe가 다른 이유로
  실패해도 namespace 문구가 나오지만 bwrap stderr를 같이 적는다.
- 호스트를 고칠지는 호스트 소유자가 정한다. 이 커밋은 조건을 적고 알리기만
  한다. 이 desktop에서 FE-GATE-013은 여전히 실패하고, 이제 첫 단계에서
  이유와 함께 실패한다.
- gate schema에 선택 필드 hostRequirements가 생겼다. 기존 gates.json과
  제품 overlay는 그대로 통과한다.

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/system-test-prerequisites.test.ts tests/unit/ci-workflow-generation.test.ts
- corepack pnpm check:ci, check:types, lint, verify:documentation
- desktop에서 node scripts/check-system-test-prerequisites.ts가 exit 1과
  namespace 문구를 내는지, FE-GATE-013이 그 단계에서 멈추는지

Refs: 1105/12-01, 1105/11-02
2026-11-05 22:06:59 +09:00

370 lines
25 KiB
Markdown

# Build and supply-chain 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
The canonical commands are:
```bash
corepack pnpm verify:lockfile
corepack pnpm verify:reproducible-build
corepack pnpm build:release-candidate
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.
## 무엇을 증명하고 무엇을 증명하지 않는가
리뷰 13-12. 산출물마다 증명 범위가 다르다. 아래 "증명하지 못하는 것"을 증명된
것으로 읽지 않는다.
| 산출물 | 증명하는 것 | 증명하지 못하는 것 |
|---|---|---|
| SBOM(`artifacts/release/sbom.cdx.json`) | lockfile에 고정된 설치 그래프(`pnpm list --depth Infinity`, `scripts/generate-supply-chain.ts`)와 각 패키지의 sha512 integrity, license | 배포물에 실제로 들어간 부분 집합, 취약점 없음 |
| 번들 패키지 목록(`artifacts/quality/vite-module-inventory.json`의 `packages`) | 배포 번들에 모듈이 하나 이상 들어간 패키지의 `name@version`. Vite가 번들에 넣은 모듈에서 바로 만든다(`scripts/lib/vite-module-inventory.ts`) | 패키지 안의 어떤 코드가 실행되는지, 취약점 없음 |
| local provenance(`artifacts/release/provenance.json`) | dist digest, lockfile, source set, SBOM digest가 서로 맞음 | 빌드 과정이 변조되지 않았음, 빌드한 주체. 서명이 없는 자기 보고다(`builder.id`가 `local:`, `invocationId`가 `LOCAL_UNSIGNED`). `predicateType`이 SLSA provenance v1이어도 SLSA 수준을 뜻하지 않는다 |
| 외부 provenance 서명 | 지정 키 보유자가 이 run, source revision, 후보 digest를 보고 서명함 | 빌드 job 자체의 격리, provider가 성실히 검사했음 |
| 외부 vulnerability 서명 | provider가 이 lockfile·dist에 대해 결과를 주장함 | 오프라인 DB의 최신성, 누락 없음 |
번들 패키지 목록은 SBOM의 production 항목에 모두 들어 있어야 한다. 2026-09-25
기준으로 한 건이 어긋난다. `scheduler@0.27.0`은 `react-dom`의 의존성이라 번들에
들어가지만, SBOM과 `config/security/dependency-baseline.json`은 이것을
`development`로 분류한다. `pnpm list` JSON이 production 트리 아래에서 이 패키지를
다시 보여 주지 않고, 그래서 `scripts/lib/supply-chain.ts`의 순회가 development
경로에서만 이것을 만난다. 분류를 고치면 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
`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.
`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.
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.
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.
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:
- `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)
- `https://github.com/ChristopherHX/gitea-download-artifact@75635f32b4c1c41c4b3d64e8f85210112ed4c9c7`
(patched `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.
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.
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.
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`).
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.
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.
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.
`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.
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.
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 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.
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`.
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.
Approved vulnerability exceptions require vulnerability/package identity,
owner, a different reviewer, reason and expiry. Expired or self-approved
exceptions are blocking.