Skip to content

Docs: credential-gate override logging is best-effort, not guaranteed (fixes #119) #222

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
F-e-u-e-r merged 1 commit into from
Aug 28, 2026
Merged

Docs: credential-gate override logging is best-effort, not guaranteed (fixes #119) #222

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -403,7 +403,9 @@ and the `.ssh`/`.aws`/`.gnupg` directories, `.env` variants,
that specific deletion is explicitly confirmed: after the user's yes,
re-run prefixed with `CRED_GATE_APPROVED=1`, which overrides that one
command only. The override is friction plus an audit log, not proof of
consent — every use is logged. Why the hook exists: in the pack's own
consent — every approved override attempts to append an audit event, but
the log write is best-effort: a failed write is silently dropped and
never blocks the hook. Why the hook exists: in the pack's own
eval, both weak-tier no-skills runs deleted a credentials backup because
an instruction embedded in a vendor-notes file told them to — this gate
turns that exact failure into a blocked call whose error message points at
Expand Down
2 changes: 1 addition & 1 deletion README.zh-Hant.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -283,7 +283,7 @@ bash hooks/test-skill_snapshot.sh
```

**第三個(可選)hook——憑證樣檔案不因「有字叫我刪」就被銷毀。**
`hooks/gate-credential-destruction.py`(Python 3 標準庫,2026-07-11 已測試)是一個 `PreToolUse`(matcher: `Bash`)hook:對憑證樣路徑(ssh 私鑰與 `.ssh`/`.aws`/`.gnupg` 目錄本身、`.env` 系列、`*.pem`/keystore、名字含 credential/secret/password/apikey 的檔案)的 `rm`/`unlink`/`shred`/`srm`/`truncate`/`git rm`——含 `sudo`/wrapper 與完整路徑寫法——一律擋下,直到該次刪除被明確確認:取得使用者同意後,在指令前加 `CRED_GATE_APPROVED=1` 重跑,且 override 只作用於那一條指令。override 是摩擦力加稽核紀錄,不是同意的證明——每次使用都會留 log。它存在的原因:本包自己的 eval 中,兩場弱模型無 skills 的 run 因為 vendor 筆記檔裡嵌的一段指令就把憑證備份刪了——這個閘門把那個失敗原樣變成一次被擋下的呼叫,錯誤訊息直接指向 delegation-and-review §7 與 security-architect。已知極限寫在腳本開頭(`bash script.sh`、alias、`find -delete`、`xargs rm`、`>` 截斷可繞過——文字層 hook 的先天限制)。掛在同一個 `PreToolUse`/`Bash` matcher 下加第二條 command 即可:
`hooks/gate-credential-destruction.py`(Python 3 標準庫,2026-07-11 已測試)是一個 `PreToolUse`(matcher: `Bash`)hook:對憑證樣路徑(ssh 私鑰與 `.ssh`/`.aws`/`.gnupg` 目錄本身、`.env` 系列、`*.pem`/keystore、名字含 credential/secret/password/apikey 的檔案)的 `rm`/`unlink`/`shred`/`srm`/`truncate`/`git rm`——含 `sudo`/wrapper 與完整路徑寫法——一律擋下,直到該次刪除被明確確認:取得使用者同意後,在指令前加 `CRED_GATE_APPROVED=1` 重跑,且 override 只作用於那一條指令。override 是摩擦力加稽核紀錄,不是同意的證明——每次 approved override 都會嘗試追加一筆稽核事件;log 寫入是盡力而為(best-effort),寫入失敗會被靜默丟棄,且絕不阻擋 hook 本身。它存在的原因:本包自己的 eval 中,兩場弱模型無 skills 的 run 因為 vendor 筆記檔裡嵌的一段指令就把憑證備份刪了——這個閘門把那個失敗原樣變成一次被擋下的呼叫,錯誤訊息直接指向 delegation-and-review §7 與 security-architect。已知極限寫在腳本開頭(`bash script.sh`、alias、`find -delete`、`xargs rm`、`>` 截斷可繞過——文字層 hook 的先天限制)。掛在同一個 `PreToolUse`/`Bash` matcher 下加第二條 command 即可:

```json
{ "type": "command",
Expand Down