awoooi/docs/security/PACKAGE-SUPPLY-CHAIN-BASELINE.md

# Package / Docker 供應鏈基線

| 項目 | 內容 |
|------|------|
| 日期 | 2026-06-15 |
| 狀態 | `repo_only_inventory_ready_needs_owner_policy` |
| 腳本 | `scripts/security/package-supply-chain-baseline.py` |
| Snapshot | `docs/security/package-supply-chain-baseline.snapshot.json` |
| Owner policy gate | `docs/security/PACKAGE-SUPPLY-CHAIN-OWNER-POLICY-GATE.md` / `docs/security/package-supply-chain-owner-policy-gate.snapshot.json` |
| Schema | `docs/schemas/package_supply_chain_baseline_v1.schema.json` |
| 模式 | repo snapshot only，不 install、不連外、不做 CVE scan、不改 image |
| runtime gate | `0` |

## 1. 目的

此 baseline 把 AWOOOI repo 內的 package manifest、Python dependency file、lockfile、Dockerfile 與 docker-compose image refs 收成一份只讀供應鏈證據。它先回答「目前有哪些供應鏈入口需要控管」，不直接處理 CVE、升級套件、重寫 lockfile、pin digest、pull image 或部署。

本檔目前是 P2 repo-only evidence artifact，尚未列入 `security-supply-chain-contract-manifest.snapshot.json` 的 36 個正式 AwoooP 消費 contract。若後續要讓 AwoooP / IwoooS 前台直接消費，必須另行更新 manifest、readiness、route、rollup、dry-run、posture projection 與 guard count，不可只改本檔。

## 2. 目前盤點

| 指標 | 數量 | 判讀 |
|------|------|------|
| `package.json` | `6` | Node / pnpm workspace manifest 已可由 root `pnpm-lock.yaml` 追蹤 |
| `pyproject.toml` | `4` | Python project metadata 已盤點 |
| `requirements.txt` | `2` | 共 `26` 條 entry，目前皆非 `==` pin |
| lockfile | `1` | `pnpm-lock.yaml` 存在；未發現 `package-lock.json` / `yarn.lock` |
| Python lockfile | `0` | 尚未有 `poetry.lock` / `uv.lock` / `Pipfile.lock` |
| Dockerfile | `2` | 外部 `FROM` image 共 `3` 個，digest pinning `0` |
| Docker `COPY --from` 外部 image | `1` | digest pinning `0` |
| docker-compose | `6` | image refs 共 `16` 個，digest pinning `0` |
| owner response received / accepted | `0 / 0` | 尚未進入 owner policy 驗收 |
| runtime gate | `0` | 不提供執行或修復按鈕 |

## 3. 目前缺口

| 缺口 | 說明 | 本階段處置 |
|------|------|------------|
| `python_lockfile_absent` | Python 專案尚未有 lock policy / lockfile 基線 | 先列 owner policy gap，不自動產生 lockfile |
| `requirements_unpinned_entries_present` | `requirements.txt` entry 目前未使用 `==` pin | 先列相容性 / policy gap，不自動 pin |
| `docker_base_images_not_all_digest_pinned` | Dockerfile 外部 base image 未全數 digest pinning | 先列 image policy gap，不自動改 tag |
| `docker_copy_from_images_not_all_digest_pinned` | Dockerfile 外部 `COPY --from` image 未 digest pinning | 先列 image policy gap，不自動改 tag |
| `compose_images_not_all_digest_pinned` | docker-compose image refs 未全數 digest pinning | 先列 compose image policy gap，不自動改 compose |

## 4. Owner Evidence 欄位

後續若要把 baseline 往驗收推進，只收下列 metadata，不收 secret value：

1. `package_manager_policy`
2. `lockfile_owner`
3. `python_lock_policy`
4. `docker_base_image_policy`
5. `compose_image_policy`
6. `registry_owner`
7. `cve_scan_window`
8. `rollback_owner`

## 5. Owner Policy Gate

2026-06-15 已新增 `docs/security/PACKAGE-SUPPLY-CHAIN-OWNER-POLICY-GATE.md` 與 `docs/security/package-supply-chain-owner-policy-gate.snapshot.json`，把 baseline 缺口轉成六個 owner policy request：

| Request | 對應治理項 | 狀態 |
|---------|------------|------|
| package manager / lockfile owner | Node / pnpm lockfile owner 與更新窗口 | waiting owner policy response |
| Python lockfile policy | Python lockfile 缺席 | waiting owner policy response |
| requirements pinning policy | `requirements.txt` 未 pin | waiting owner policy response |
| Docker digest pinning policy | Dockerfile base image 與 `COPY --from` image 未 digest pin | waiting owner policy response |
| compose image digest policy | docker-compose image 未 digest pin | waiting owner policy response |
| CVE / license / SBOM window | 掃描工具、窗口與噪音處理策略未定 | waiting owner policy response |

此 gate 只補「誰能決定、用什麼政策決定、何時驗證、誰負責 rollback」的收件前規範。request_sent、owner_response_received、owner_response_accepted、runtime_gate 與 action_button 仍全部是 `0 / false`。

## 6. 指令

```bash
python3 scripts/security/package-supply-chain-baseline.py \
  --root . \
  --output docs/security/package-supply-chain-baseline.snapshot.json
```

固定 committed snapshot 時間：

```bash
python3 scripts/security/package-supply-chain-baseline.py \
  --root . \
  --generated-at 2026-06-15T06:20:00+08:00 \
  --output docs/security/package-supply-chain-baseline.snapshot.json
```

預期輸出：

```text
PACKAGE_SUPPLY_CHAIN_BASELINE_OK package_json=6 pyproject=4 requirements=2 dockerfiles=2 compose=6 gaps=5 runtime_gate=0
```

Owner policy gate 驗證：

```bash
python3 scripts/security/package-supply-chain-owner-policy-guard.py --root .
```

預期輸出：

```text
PACKAGE_SUPPLY_CHAIN_OWNER_POLICY_GUARD_OK
```

## 7. 邊界

此 baseline 通過不代表：

- 套件已安裝、升級、降級或修補。
- CVE、license、SBOM、Trivy、npm audit、pip audit 已完成。
- Docker image 已 pull、build、push、retag 或 digest pinning。
- registry login、Harbor policy、image immutability 或 scanner policy 已驗收。
- workflow、runner、secret、production deploy 或 runtime gate 已授權。

## 8. 完成度

| 工作 | 完成度 | 說明 |
|------|--------|------|
| Package / Docker supply-chain repo-only baseline | `100%` | 已新增腳本、snapshot 與人讀文件 |
| Package / Docker supply-chain owner policy gate | `100%` | 已新增 guard、snapshot 與人讀文件；六個 request 仍 waiting owner policy response |
| Node lockfile 基線 | `80%` | `pnpm-lock.yaml` 存在；owner policy gate 已補，但尚未收到 lockfile owner / update window |
| Python lock policy | `45%` | 已盤點 pyproject / requirements 並補 owner policy request；尚缺正式 owner response 與 lockfile 決策 |
| requirements pinning policy | `35%` | 已盤點 26 條未 pin entry 並補 owner policy request；尚未批准 pinning 或相容性窗口 |
| Docker / compose image policy | `45%` | 已盤點 image refs 並補 C0 owner policy request；尚缺 digest pinning policy、registry owner、rollback owner |
| CVE / license / SBOM 驗證 | `15%` | 已補 owner policy request；未執行外部掃描，需 owner window 與工具策略 |
| runtime gate | `0%` | 未開啟任何執行期閘門 |