public-surface-audit
Scans git-tracked (public) files for operator-private tokens that should live only in gitignored files — real usernames, absolute home paths, companion-store names, company asset names. Reports file:line + matched token + severity, so a public/private split stays clean before publish. Triggered by "public surface audit", "did I leak anything", "check tracked files for private tokens", "private token scan", "public-surface-audit".
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 33
- Forks
- 1
01 前言 Front Matter
- name
- public-surface-audit
- model
- sonnet
- category
- Composability Gate
- description
- Scans git-tracked (public) files for operator-private tokens that should live only in gitignored files — real usernames, absolute home paths, companion-store names, company asset names. Reports file:line + matched token + severity, so a public/private split stays clean before publish. Triggered by "public surface audit", "did I leak anything", "check tracked files for private tokens", "private token scan", "public-surface-audit".
- allowed-tools
- [ "Read", "Bash", "Grep", "Glob" ]
- user-invocable
- true
02 资源文件 1
- 参考文档SKILL_detail.md11.2 KB
03 SKILL.md 正文
public-surface-audit — Operator-Private Token Leak Scan
Scans the git-tracked file set (the public surface) for operator-private tokens that were supposed
to stay in gitignored files (e.g. CLAUDE.local.md, companion store). After a public/private split,
a front-door fix is not enough — a leaked username or absolute home path anywhere in the tracked set
breaks the "public repo = model-agnostic methodology only" invariant.
While
marketplace-gateCheck 5 answers "is this repo broadly safe to publish?" (API keys, internal domains, license),public-surface-auditanswers a narrower question: "did any operator-private token survive the public/private split into a tracked file?" It scansgit ls-filesonly — gitignored files likeCLAUDE.local.mdare intentionally out of scope (they are the correct home for these tokens).
Triggers
/public-surface-audit/public-surface-audit --target <repo path>/public-surface-audit --json(machine-parseable verdict for hook-gating — see Step 5)- "Did I leak anything into the public repo?", "public surface audit", "private token scan"
- "Check tracked files for private tokens", "is my public/private split clean?"
- "Did any operator-private token survive into a tracked file?", "scan before publish"
Scope — Tracked Files Only
This skill scans only git ls-files (committed/staged tracked files). Gitignored files are
deliberately excluded — CLAUDE.local.md, the companion store, and local session data are the
correct home for operator-private tokens, so finding them there is not a leak.
ARGS="${ARGUMENTS//--json/}" # strip flags first — "--json" alone must not become the path
REPO_PATH="${ARGS#--target }"
REPO_PATH="$(printf '%s' "$REPO_PATH" | xargs)"
REPO_PATH="${REPO_PATH:-$(pwd)}"
git -C "$REPO_PATH" rev-parse --is-inside-work-tree >/dev/null 2>&1 \
|| { echo "Not a git repo — public-surface-audit scans git-tracked files only. Aborting."; exit 1; }
echo "Target: $REPO_PATH"
git -C "$REPO_PATH" ls-files | wc -l | xargs echo "Tracked files:"
Step 1. Pattern List (configurable)
The pattern source is two layers, matching the mechanical scan layer (scripts/psa_scan_lib.sh,
shared with the pre-commit/pre-push/pre-publish hooks — this skill must render the same verdict the
hooks would, or the same repo state gets two answers):
.claude/rules/.public-surface-patterns.defaults— committed, universal placeholder-grade patterns (safe to publish; carries no operator literal)..claude/rules/.public-surface-patterns— gitignored, operator literals (orPSA_PATTERNSenv override). Your real username and employer name live only here — hardcoding them in a tracked file would leak exactly what this skill hunts. Oneseverity<TAB>regexper line.
The scan reads the union of both layers. This SKILL.md carries only placeholders; the skill dogfoods its own rule.
| # | Token class | Severity | Placeholder (real value goes in the gitignored source) | Why private |
|---|---|---|---|---|
| 1 | Real username | HIGH | <your-unix-username> |
Personal identity — must not appear on public surface |
| 2 | Company / employer asset name | HIGH | <company-asset> (alternation OK) |
Company-confidential, leak-forbidden |
| 3 | Operator absolute home path | MED | /Users/[a-z0-9_-]+/ (generic — carries no literal name) |
Machine-bound, leaks username + local layout |
| 4 | Companion-store name | LOW | <companion-store-name> |
Private companion store — methodology should not name it |
| 5 | Operator-private script / handoff name | LOW | <private-script>, <private-dir>/ |
Operator-specific wiring, belongs in CLAUDE.local.md |
Severity meaning:
- HIGH — real name or company asset. A leak is a confidentiality / identity exposure. Block publish.
- MED — absolute home path. Leaks username + local filesystem layout; also a portability bug.
- LOW — companion-store / private-wiring name. Methodology should be model-agnostic; naming a private store is drift, not a confidentiality breach.
Setup: put your real values in the gitignored override (one
severity<TAB>regexper line). Degrade states, by layer — never collapse them:
- Neither layer present → NOT CONFIGURED — not CLEAN. A missing pattern source must never masquerade as a clean bill of health ("nothing scanned" misread as "nothing leaked").
- Defaults only (override absent) → scan runs, but the verdict carries the label
operator literals NOT CONFIGURED — universal patterns only; identity/company classes UNSCANNED. This mirrors what the hooks scan in the same state, instead of reporting NOT CONFIGURED while the hook path quietly scans defaults (two verdicts for one repo state — the divergence this line closes).- To declare "I genuinely have no private tokens", create the override empty — an empty file is an explicit declaration, an absent file is unconfigured.
Step 2. Allowlist (legitimate references)
Some tracked files legitimately reference otherwise-private tokens — the scan must not flag these as
leaks. Maintain an allowlist of file path :: token pairs. A match is suppressed only when both
the file and the token are on the allowlist row.
Where the filled allowlist lives: a populated allowlist row names private tokens, so it belongs
in a gitignored source beside the pattern override (.claude/rules/.public-surface-allowlist, or a
section of CLAUDE.local.md) — never in a tracked file. The table below shows generic shapes only; a
tracked copy of your real allowlist would itself be the leak this skill scans for.
| Tracked file | Allowed tokens | Reason |
|---|---|---|
.gitignore |
companion-store name, sync-script name | Must name what it ignores |
your sync script (e.g. scripts/<sync-script>) |
companion-store name, operator-dir names, home path | The sync script's whole job is the companion store |
| an install-template rules file | home path, companion-store name | Install template — the install path is its content |
| a doc describing the companion-store pattern | the *-be pattern (no literal store name) |
Documents the pattern generically |
Allowlist rule: a hit on file F matching token T is suppressed iff a row exists with file == F
and T in that row's allowed tokens. Everything else is reported. Keep the allowlist tight — when in
doubt, report and let the user confirm. Genuinely model-agnostic mentions (the *-be companion
pattern without the literal store name) should not require allowlisting because they do not match a
literal private token.
Step 3. Scan
For each pattern in Step 1, grep the tracked set, then drop allowlisted hits. Do this for every pattern row before producing the report — do not stop at the first HIT.
Binary / generated carve-out: skip binaries. Additionally note (do not auto-suppress) hits inside
generated artifacts (e.g. paper/*.html exported from a private source) — these are real leaks on the
public surface and must be reported, but the fix is "regenerate from a sanitized source," not "edit the
HTML by hand." Flag them with a (generated artifact) note.
Detail: See
SKILL_detail.md §Step3-Scan-Script— the grep-per-pattern bash implementation, flag reference (-n/-I/-E) — read when executing this step.
Step 3b. FP Hygiene — Placeholder & Example Exclusion
A scan that flags its own placeholders erodes trust. Two value-shape classes are never real leaks
and are dropped before the report — imported from gstack-redact's canonical-example allowlist, scoped
in PSA's direction to the matched token (not the whole line, so a real leak sharing a substring still
reports):
- Angle-bracket placeholders — the matched token is itself a placeholder (
<your-unix-username>,<company-asset>,{project}). PSA dogfoods these in Step 1; the scan must not report them as leaks. - Canonical dummy values — the matched token is a documented example/dummy (
EXAMPLE,dummy,changeme,REDACTED,xxxx, AWS-doc keys likeAKIAIOSFODNN7EXAMPLE). A high-entropy example is not a secret.
This differs from the Step 2 allowlist: Step 2 suppresses by file::token legitimacy, Step 3b by token value-shape. Both run — Step 2 then Step 3b. Keep it tight (PSA's "allowlist tight" rule): if a token only contains an example substring but is otherwise a real private value, it still reports.
Detail: See
SKILL_detail.md §Step3b-FP-Hygiene-Script— the token-shape-only extraction bash implementation (never line-level) — read when executing this step.
Step 3c. Ignore-Verification — the gitignore-mistake safeguard (root-cause, runs before Step 4)
Steps 3/3b scan what is tracked. This step checks the inverse and the upstream cause: a file you
intend to be private that is not actually ignored — the gitignore mistake that becomes tomorrow's
tracked leak. For each expected-private path, git check-ignore -v reports whether it is ignored and
by which layer (committed .gitignore · local .git/info/exclude · global core.excludesFile). A
path that resolves to no ignore rule is a MISS — surface it before it is ever git added.
- OK — ignored; the report names which layer covers it (operator-private files should resolve to
.git/info/excludeor.gitignore, never end up tracked). - MISS — exists but no ignore rule covers it → counts as 🟠 MED in the Step 4 verdict (a latent leak, not yet a breach).
- TRACKED — already committed: Step 3 scans its contents; this also flags it for un-tracking if it
was meant to be private. Tracked status is tested before ignore status — a file can match an
ignore rule yet still be force-added (
git add -f), the exact ignored-but-committed mechanism behind the PR #109 leak, so TRACKED must win over a false-clean OK.
Why this is the safeguard for gitignore mistakes (a wrong assumption about what is ignored):
.gitignore is committed/shared, .git/info/exclude is local/personal, and a global core.excludesFile
ignores across all repos — git check-ignore -v is the one command that says which rule (if any)
applies, so an "I thought it was ignored" error surfaces here instead of in a public PR (the PR #109
class of leak). Diagnostic-only: this step never writes — it reports, the operator adds the ignore rule.
Detail: See
SKILL_detail.md §Step3c-Ignore-Verification-Script— the expected-private-path enumeration +git check-ignore/git ls-files --error-unmatchbash implementation, bash/zsh portability note — read when executing this step.
Step 4. Report
Report per-hit file:line → matched token [class] grouped by severity, then the overall verdict.
Verdict thresholds (behavioral — these define the gate):
- ⚪ NOT CONFIGURED — no pattern layer present (nothing scanned — NOT a clean result; set up first)
- 🟢 CLEAN — pattern source present (incl. empty override), 0 HIGH + 0 MED + 0 LOW (after allowlist)
- 🟡 REVIEW — 0 HIGH + 0 MED, LOW-only (drift, not a breach)
- 🔴 LEAK — 1+ HIGH or 1+ MED (block publish / fix before commit)
Every verdict line carries a coverage: qualifier — full (both layers loaded) or
defaults-only (override absent: operator identity/company classes UNSCANNED). The qualifier exists
because the enum alone cannot preserve the defaults-only state: CLEAN (coverage: defaults-only) on
an operator-configured checkout is missing evidence, not a pass — publish-gating callers there must
require coverage: full.
Detail: See
SKILL_detail.md §Report-Template— the full human-report ASCII layout (severity buckets, allowlist-suppressed line) — read when formatting the Step 4 report.
Per HIGH/MED hit, append a one-line prescription:
- HIGH (username/company) — move the line to
CLAUDE.local.md(or regenerate the artifact from a sanitized source); never edit-in-place if it is a generated file. - MED (absolute path) — replace with a relative path, a
~-anchored path, or a{project}placeholder; absolute home paths are also a portability bug for external clones. - LOW (companion-store/wiring) — rephrase to the model-agnostic pattern (e.g. "a private companion
store" / "the
*-becompanion pattern") instead of the literal name, unless the file is the.gitignore/ sync script that must name it (allowlist those).
Simplification guard: 🟢 CLEAN → collapse the report to one line: "public surface clean — 0 private tokens in {N} tracked files (X allowlist-suppressed)." Do not print empty severity buckets.
Step 5. Machine Output (--json) — Hook-Gateable Verdict
By default PSA prints the Step 4 human report. With --json, emit a machine-parseable verdict so a
pre-publish / pre-push hook can gate on counts mechanically — turning PSA from advisory into
enforceable (FH's "enforcement is a hook, not a prompt" principle). Imported from gstack-redact --json.
Detail: See
SKILL_detail.md §JSON-Schema— the--jsonoutput object shape (findings array, counts, verdict field) — read when emitting or parsing the machine verdict.
verdict is one of CLEAN | REVIEW | LEAK | NOT_CONFIGURED (same thresholds as Step 4). verdict is
authoritative — never gate on counts alone: a counts-only check (HIGH==0 && MED==0) misreads
NOT_CONFIGURED (which also has zero counts) as a pass. A caller blocks when verdict is LEAK or
NOT_CONFIGURED — an unconfigured scan is not a pass (the same silent-failure guard as the human path:
absence ≠ CLEAN). The JSON carries the same coverage field as Step 4; on an operator-configured
checkout a publish-gating caller additionally blocks on coverage: "defaults-only" (identity/company
classes unscanned there — zero counts prove nothing about the classes that never ran).
Connected Skills
| Situation | Connected skill |
|---|---|
| Broader pre-publish repo readiness (README, license, API keys) | /marketplace-gate (Check 5 Public Safety is the wide net; this skill is the private-token detail) |
| A leak is a recurring process gap, not a one-off | log via field-harvest → candidate #rule-candidate |
| Where should the leaked content actually live? | /asset-placement-gate (hub vs project vs CLAUDE.local.md) |
| Phantom refs / stale links on the same surface | /phantom-quench (forward axis — orthogonal to this leak axis) |
External User Environment Adaptation
Usable standalone — no hub clone required.
- No companion store / no operator-private tokens → create the pattern source empty to declare this explicitly; the scan then reports CLEAN. Leaving the file absent instead yields NOT CONFIGURED (a deliberate distinction — absence is "unknown", not "clean"). The skill is only useful once you have a public/private split to protect.
- No
.gitignoreallowlist needs → Step 2 allowlist may be empty; every hit is then reported.
Done When
Step 1 pattern source resolved (both layers checked; absent/partial
states rendered as their labeled degrade state, never as CLEAN) — mandatory-pass
+ Step 2 allowlist applied (from a gitignored source) — mandatory-pass
+ Step 3 scan run for every pattern over git ls-files (tracked only —
gitignored excluded), malformed pattern rows counted and reported,
never silently dropped — measured (hit + malformed counts)
+ Step 3b/3c run (FP-hygiene on matched tokens; ignore-verification
for expected-private paths) or explicitly skipped with reason — mandatory-pass
+ Step 4 report output: per-hit file:line + token + severity, plus
overall verdict — mandatory-pass
+ "public-surface-audit Complete" declaration output — mandatory-pass
Verdict: CLEAN (0 tokens after allowlist) | REVIEW (LOW-only — drift, prescriptions noted) |
LEAK (1+ HIGH or 1+ MED — block publish, prescriptions attached) | NOT_CONFIGURED (no pattern
source — nothing scanned, not a pass; same 4-value enum as Step 5 --json. An earlier version of this
enum had 3 values here, so a session following only Done When would force absent-config into CLEAN/
REVIEW/LEAK — re-opening the exact silent-pass the body closes).
Operating Notes
- Tracked-only is the point: never scan gitignored files. A token in
CLAUDE.local.mdis correct placement, not a leak — scanning it would produce false LEAK verdicts and erode trust in the skill. - Patterns are data, not code: the Step 1 table is the configurable surface. A user with a different username/employer/companion-store edits the table; the scan logic is unchanged.
- Generated artifacts are real leaks: an exported HTML/PDF carrying a username is still a public-surface leak even though hand-editing it is wrong — report it, prescribe "regenerate from sanitized source".
- Allowlist tight, not loose: when unsure whether a reference is legitimate, report it. A false LEAK the user dismisses is cheaper than a real leak suppressed by an over-broad allowlist.
- Auto-redact deliberately not imported:
gstack-redactoffers--auto-redact(rewrite + diff). PSA's philosophy is report + prescribe; the human decides where the line goes — auto-redacting a HIGH (username/company) hit would pre-empt that judgment, and auto-editing a generated artifact is explicitly wrong (regenerate from source). If ever imported, restrict to the MED absolute-home-path class only (mechanically safe:/Users/<user>/→~/or{project}), never HIGH, never generated files.
Sister-Asset Provenance
Step 3b (FP hygiene) and Step 5 (--json) were imported from garrytan/gstack gstack-redact during
a 2026-06-06 sister-asset cross-audit.
Detail: See
SKILL_detail.md §Sister-Asset-Provenance— the full import provenance (source file, ontology adaptation, orthogonal-coverage rationale, reverse-contribution candidate) — read when tracing or extending the gstack-redact lineage.
04 同仓库更多 Skills
todo-orchestrator
TODO CLI 프로젝트의 기능 추가·버그 수정·리팩터링·테스트 보강을 개발자와 QA 에이전트로 조율한다. todo 앱 관련 코드 작업 요청에 사용한다. 다시 실행, 재실행, 수정, 보완, 이전 결과 개선, QA만 다시 같은 후속 요청에도 사용한다. 단순 질문에는 사용하지 않는다.
todo-dev
TODO CLI(todo/cli.py)에 명령을 추가하거나 버그를 고치고 테스트를 작성하는 방법. todo 앱 코드 수정·기능 추가·테스트 작성·리팩터링 작업에 사용한다. 수정, 보완, 다시 구현 요청에도 사용한다.
todo-dev-team
TODO CLI(todo/cli.py) 개발 작업을 개발자·테스터·리뷰어 팀으로 진행하는 오케스트레이터. 명령 추가, 버그 수정, 테스트 작성, 리팩터링, 커밋·푸시 요청에 사용한다. 다시 실행, 재실행, 수정, 보완, 리뷰 반영, 테스트만 다시 같은 후속 요청에도 사용한다. 단순 질문에는 쓰지 않는다.
todo-dev
TODO CLI 개발 작업(명령·기능 추가, 버그 수정, 테스트 작성, 리뷰, 커밋·push)을 개발자·테스터·리뷰어 에이전트 팀으로 진행하는 오케스트레이터. todo CLI, todo.json, todo/cli.py 관련 구현·수정·테스트 요청에 사용한다. 재실행, 수정, 보완, 이전 결과 개선, 테스트만 다시, 리뷰만 다시 요청에도 사용한다. 단순 질문에는 쓰지 않는다.
weekly-summary-write
정리된 회의록으로 주간 회의 요약 문서를 작성하는 형식과 문체 규칙. 주간 요약 작성, 요약 문서 수정·보완, 검토 의견 반영 시 사용한다.
weekly-meeting-summary
주간 회의록을 정리하고 요약 문서를 만드는 전체 작업을 조율하는 오케스트레이터. 회의록 요약, 주간 회의 정리, 주간 보고용 요약 요청 시 사용한다. 다시 실행, 재실행, 요약 수정·보완, 이전 결과를 바탕으로 한 개선, 정리만/검토만 다시 같은 후속 요청에도 사용한다.