116 lines
6.4 KiB
Markdown
116 lines
6.4 KiB
Markdown
# Gitea Read-only 全量 Inventory Approval Package
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 日期 | 2026-05-17 |
|
||
| 狀態 | 草案，等待人工批准 |
|
||
| 來源事件 | `gitea_repo_inventory_v1` |
|
||
| Approval event | `docs/security/gitea-readonly-inventory-approval.snapshot.json` |
|
||
| Redaction checklist | `docs/security/GITEA-ADMIN-EXPORT-REDACTION-CHECKLIST.md` |
|
||
| S4.5 export request | `docs/security/GITEA-AUTHENTICATED-INVENTORY-EXPORT-REQUEST.md` |
|
||
| S4.6 import acceptance | `docs/security/GITEA-AUTHENTICATED-INVENTORY-IMPORT-ACCEPTANCE.md` |
|
||
| S4.7 coverage attestation | `docs/security/GITEA-INVENTORY-COVERAGE-ATTESTATION.md` |
|
||
| S4.9 owner response request packet / 收件包 | `docs/security/GITEA-INVENTORY-OWNER-ATTESTATION-RESPONSE.md` |
|
||
| 目的 | 補齊 Gitea private/internal server-side repo list |
|
||
| 原則 | 低摩擦、只讀、只盤 metadata、不保存 token value、不做同步或主控切換 |
|
||
|
||
## 0. 為什麼需要 approval
|
||
|
||
目前已取得 public-only Gitea repo evidence：
|
||
|
||
1. `users/wooo/repos` 可見 `wooo/awoooi`、`wooo/ewoooc`。
|
||
2. `orgs/wooo/repos` 未認證查詢回 404，已保留 blocked evidence。
|
||
3. 本機 remote inventory 顯示還有 `clawbot-v5`、`wooo-aiops`、110 internal / GitLab 類 remote 等來源。
|
||
|
||
因此 public-only evidence 不足以宣告「Gitea 所有專案版本」已盤完。下一步需要統帥或 repo owner 批准其中一條路徑：
|
||
|
||
1. 提供 Gitea read-only token，僅用環境變數執行一次 inventory。
|
||
2. 提供 Gitea 管理介面匯出的 redacted repo list JSON。
|
||
|
||
此 approval package 的目的不是提高日常開發門檻，而是只保護「會接觸 token 或管理匯出」這一個邊界。取得全量清單後，後續仍先進入 evidence / matrix / draft plan，不直接進入同步或阻擋。
|
||
|
||
S4.5 已補 `gitea_authenticated_inventory_export_request_v1`，把 read-only token API inventory 與 redacted admin export 的允許欄位、拒收欄位、coverage gap 與驗收 gate 正式文件化。批准前仍不得要求使用者貼 token value。
|
||
|
||
S4.6 已補 `gitea_authenticated_inventory_import_acceptance_v1`，把 owner / 管理者提供脫敏 payload 後的 schema 檢查、敏感值拒收、coverage gap 驗收與 mirror quarantine lane 正式文件化。payload 驗收通過仍不等於 GitHub primary cutover 被批准。
|
||
|
||
S4.7 已補 `gitea_inventory_coverage_attestation_v1`，把 public-only / local remote gap、org/user endpoint、110 internal adjacent source、canonical owner 與 legacy/inaccessible repo disposition 的 owner decision 正式文件化。attestation 只做 scope 判定，不等於 repo migration 或 primary cutover approval。
|
||
|
||
S4.9 已補 `gitea_inventory_owner_attestation_response_v1`，把 AwoooP 可顯示給 owner 的 request packet、template status ledger、audit event templates、redaction examples、display sections、collection checks、owner 回覆 S4.7 五個 items 時的必填欄位、intake preflight checks、outcome lanes、驗收規則與拒收規則正式文件化。request packet 只是填寫提示，template status ledger / audit event templates / redaction examples / display sections / collection checks 只維持 request / received / accepted 分離；audit event templates 目前全為 `template_only_not_emitted`、0 emitted，只定義脫敏 metadata 欄位；redaction examples 只供 owner 參考安全回覆形狀；display sections 只固定只讀 UI 區塊順序；response 通過只代表可更新 read-only matrix / decision table，不等於 read-only inventory 已執行或 AwoooP production ingestion 已啟用。
|
||
|
||
## 1. 申請批准的動作
|
||
|
||
| 動作 | 風險 | 批准後允許 | 仍然禁止 |
|
||
|------|------|------------|----------|
|
||
| `run_gitea_readonly_inventory` | MEDIUM | 使用 read-only token 呼叫 Gitea API 盤 repo metadata | 寫入 Gitea、保存 token、同步 refs、建 repo |
|
||
| `import_gitea_admin_export` | MEDIUM | 匯入 redacted JSON，產生 `gitea_repo_inventory_v1.status=ok` evidence | 匯入 secret value、webhook secret、deploy key private key |
|
||
|
||
## 2. Token 使用邊界
|
||
|
||
1. Token 只允許放在 `GITEA_READONLY_TOKEN` 環境變數。
|
||
2. Token 不得寫入 `.env`、shell history、文件、LOGBOOK、issue、PR、snapshot。
|
||
3. 工具輸出只保存 `token_present=true|false`。
|
||
4. Token 權限必須只讀，不能有 repo delete、push、admin、secret read/write 權限。
|
||
5. 執行後建議撤銷或輪替 token。
|
||
|
||
## 3. 批准後指令
|
||
|
||
```bash
|
||
python3 scripts/security/gitea-repo-inventory.py \
|
||
--base-url http://192.168.0.110:3001 \
|
||
--org wooo \
|
||
--scope user \
|
||
--token-env GITEA_READONLY_TOKEN \
|
||
--github-owner owenhytsai \
|
||
--output-json docs/security/gitea-repo-inventory.snapshot.json \
|
||
--output-md docs/security/GITEA-REPO-INVENTORY-SNAPSHOT.md
|
||
```
|
||
|
||
替代路徑：
|
||
|
||
```bash
|
||
python3 scripts/security/gitea-repo-inventory.py \
|
||
--base-url http://192.168.0.110:3001 \
|
||
--org wooo \
|
||
--github-owner owenhytsai \
|
||
--input-json /path/to/redacted-gitea-repos.json \
|
||
--output-json docs/security/gitea-repo-inventory.snapshot.json \
|
||
--output-md docs/security/GITEA-REPO-INVENTORY-SNAPSHOT.md
|
||
```
|
||
|
||
## 4. 驗收標準
|
||
|
||
| Gate | 必須結果 |
|
||
|------|----------|
|
||
| JSON 可解析 | `docs/security/gitea-repo-inventory.snapshot.json` 通過 parse |
|
||
| Schema 欄位 | `schema_version=gitea_repo_inventory_v1` |
|
||
| 全量狀態 | `status=ok` |
|
||
| 可見範圍 | `visibility_scope=authenticated` 或 `admin_export` |
|
||
| 敏感資訊 | 不含 token、password、secret value、private key |
|
||
| Redaction checklist | `docs/security/GITEA-ADMIN-EXPORT-REDACTION-CHECKLIST.md` 已通過 |
|
||
| Coverage gap | public-only 2 repos 與 local Gitea 4 repos 的差異已解釋 |
|
||
| Import acceptance | S4.6 驗收檢查通過；敏感 payload 必須進隔離 |
|
||
| Owner attestation response | S4.9 已收到並驗收 S4.7 五個 coverage items 的 owner response |
|
||
| 後續動作 | 只更新 matrix / decision table，不同步 refs |
|
||
|
||
## 5. 批准前不得做
|
||
|
||
1. 不要求使用者在對話中貼 token value。
|
||
2. 不把 token 寫入任何檔案。
|
||
3. 不用有寫入權限的 token。
|
||
4. 不建立 GitHub repo。
|
||
5. 不修改 GitHub repo visibility。
|
||
6. 不 push、fetch mirror、sync refs。
|
||
7. 不切 GitHub primary。
|
||
|
||
## 6. AwoooP 消費方式
|
||
|
||
AwoooP 可以把本 package mirror 成 approval candidate，但只能顯示：
|
||
|
||
1. requested action。
|
||
2. risk。
|
||
3. required reviewers。
|
||
4. evidence refs。
|
||
5. blocked_until_approved。
|
||
|
||
AwoooP 不得直接要求、保存或傳遞 token value。
|