Security Hygiene
Security Philosophy
This is a self-modifying system. Security should work like a helpful companion, not an adversarial checkpoint — zen and the art of programming. Tools protect by default, guide by suggestion, block only when there is a real reason.
Threat Surface
| Vector |
Risk |
Check |
| Path traversal |
Skill names used in file paths could escape directory |
Sanitize all skill names: alphanumeric, hyphens, underscores only. Reject .., /, \. |
| YAML deserialization |
Unsafe YAML loading executes arbitrary code |
Use safe parsing only (yaml.safe_load or equivalent). Never yaml.load with untrusted input. |
| Data poisoning |
Append-only JSONL could contain injected entries |
Validate entries on read: check schema, reject oversized entries, verify timestamps are monotonic. |
| Permission bypass |
Automated workflows might skip user confirmation |
Never bypass user confirmation for skill application, even in YOLO mode. YOLO applies to GSD workflow commands, not skill modifications. |
| Cross-project leakage |
User-level skills might expose project-specific patterns |
User-level skills must be generic. Project-specific patterns stay in project-level skills. |
| Observation privacy |
Pattern data could leak into shared repos |
.planning/patterns/ must be in .gitignore. Verify on any git operation. |
Content Hygiene Rules
When processing community-contributed content (skills, chipsets, LoRA adapters):
- Check for embedded commands or script execution
- Verify YAML does not contain unsafe tags (
!!python/object, etc.)
- Validate that skill descriptions match their actual content
- Quarantine new community content for review before activation
Privacy Tier Taxonomy (4-tier, OOPS-08-P03)
All telemetry, observation data, and skill artefacts are classified into one
of four privacy tiers. Telemetry writers MUST stamp every record with its
tier and MUST NOT mix tiers in a single sink.
| Tier |
Name |
Description |
Examples |
| A |
Public |
No PII, no proprietary content; safe to publish externally. |
Open-source skill descriptions, public release notes, anonymised aggregate metrics. |
| B |
Internal |
Non-PII operational data; safe to share within the project team. |
Phase activity counts, commit-type distributions, hook firing rates, build-time profiles. |
| C |
Sensitive |
PII, credentials, authentication tokens, individual session transcripts. |
.env contents, OAuth tokens, individual user prompts, raw conversation logs. |
| D |
Restricted |
Regulated data, proprietary IP, Fox Companies content. |
.planning/fox-companies/ artefacts, wasteland/ content, customer-identifiable records, anything subject to legal hold. |
Defaults and enforcement:
- New telemetry writers default to Tier B unless an explicit tier label
is supplied at construction.
- Tier C data MUST be encrypted at rest and MUST be excluded from any
artefact published outside the local repository (no
git push of files
containing Tier C content; no FTP sync; no inclusion in release notes).
- Tier D data MUST never leave the
.planning/ tree or
wasteland/ branch. Surface alignments in conversation only; never
commit Tier D content to a public-facing path.
- Mixed-tier sinks are FORBIDDEN — a writer that mixes Tier A and Tier C
records loses the ability to safely publish the Tier A subset.
Referenced by C5 W3.P6 tool-tracker (telemetry writer wiring) and the
post-tool-use observation hook.
Authoring around the leak-scanner — don't re-trip the control (Lesson #10462)
The release-history publisher (tools/release-history/publish.mjs, leakScan) runs
a hard leak-scan gate over every published chapter. Its effective patterns combine
committed base patterns with operator-private patterns loaded from the gitignored
release-history.local.json, so the scan is operator-machine-specific: a fresh
CI checkout sees only the base patterns and never the local ones.
Two failure modes recur whenever you DOCUMENT leak-scan or security-hardening work:
- The control's own documentation re-trips it. A retrospective that quotes a
leak pattern verbatim (e.g. v1.49.588 quoting the narrowed private-path regex
it was describing) matches that pattern and is HARD-BLOCKED — even though it
contains no real secret.
- The recursion trap. Documenting the fix for #1 by enumerating the private
literals the control guards (company / email / credential-var) embeds those
values into published content — a genuine leak the scanner correctly blocks.
The v1.49.916 retrospective re-tripped exactly this way while documenting the
v916 AC7 allowlist fix.
Authoring rule: describe the pattern, never quote the literal. In release notes,
retrospectives, or docs that touch leak-scan work, refer to a pattern by name or
shape ("the company-name local pattern", "the credential-var form") — never paste
the regex source and never paste the private value.
Allowlist-vs-scrub decision rule:
- The doc legitimately quotes a leak PATTERN (a regex, for self-referential
documentation) → add a narrow
leak_scan_allowlist entry in the committed
release-history.config.json, keyed on the EXACT version + file + pattern
source, with a reason. Never widen to a global pattern exemption.
- The content embeds a genuinely-private VALUE → SCRUB the value from the
content. Never allowlist a private value into published output — the allowlist is
for pattern-quoting docs only, never for secrets.
This pairs the loud surface (the leak-scan gate) with the authoring discipline that
keeps it from firing on its own documentation. See
docs/failure-mode-contracts.md (#10427
silent-vs-loud surfaces) and
docs/known-unwired-ledger-discipline.md
(#10461 gate-enforce-every-runnable-surface + drift-guard).
The Staging Layer Principle
"The user's ability to work should be reasonable. Security should also be reasonable. We strive for the clean intersection." Do not over-alert. Do not create friction for normal operations. Surface findings only when something genuinely warrants attention.
1---2name: security-hygiene3description: Security hygiene for GSD's self-modifying skill and agent system. Use this skill whenever: creating, editing, or deleting skill files (.claude/skills/, .claude/commands/), modifying agent definitions (.claude/agents/), working with YAML configuration or chipset files, handling JSONL observation data (.planning/patterns/), processing community-contributed skills or chipsets, any file path operations that could involve user input, or when installing/updating project-claude configuration. Also activates for discussions about skill-creator security, trust models, or content hygiene.4---56# Security Hygiene78## Security Philosophy910This is a self-modifying system. Security should work like a helpful companion, not an adversarial checkpoint — zen and the art of programming. Tools protect by default, guide by suggestion, block only when there is a real reason.1112## Threat Surface1314| Vector | Risk | Check |15|---|---|---|16| **Path traversal** | Skill names used in file paths could escape directory | Sanitize all skill names: alphanumeric, hyphens, underscores only. Reject `..`, `/`, `\`. |17| **YAML deserialization** | Unsafe YAML loading executes arbitrary code | Use safe parsing only (`yaml.safe_load` or equivalent). Never `yaml.load` with untrusted input. |18| **Data poisoning** | Append-only JSONL could contain injected entries | Validate entries on read: check schema, reject oversized entries, verify timestamps are monotonic. |19| **Permission bypass** | Automated workflows might skip user confirmation | **Never bypass user confirmation for skill application**, even in YOLO mode. YOLO applies to GSD workflow commands, not skill modifications. |20| **Cross-project leakage** | User-level skills might expose project-specific patterns | User-level skills must be generic. Project-specific patterns stay in project-level skills. |21| **Observation privacy** | Pattern data could leak into shared repos | `.planning/patterns/` must be in `.gitignore`. Verify on any git operation. |2223## Content Hygiene Rules2425When processing community-contributed content (skills, chipsets, LoRA adapters):26- Check for embedded commands or script execution27- Verify YAML does not contain unsafe tags (`!!python/object`, etc.)28- Validate that skill descriptions match their actual content29- Quarantine new community content for review before activation3031## Privacy Tier Taxonomy (4-tier, OOPS-08-P03)3233All telemetry, observation data, and skill artefacts are classified into one34of four privacy tiers. Telemetry writers MUST stamp every record with its35tier and MUST NOT mix tiers in a single sink.3637| Tier | Name | Description | Examples |38|------|------|-------------|----------|39| **A** | **Public** | No PII, no proprietary content; safe to publish externally. | Open-source skill descriptions, public release notes, anonymised aggregate metrics. |40| **B** | **Internal** | Non-PII operational data; safe to share within the project team. | Phase activity counts, commit-type distributions, hook firing rates, build-time profiles. |41| **C** | **Sensitive** | PII, credentials, authentication tokens, individual session transcripts. | `.env` contents, OAuth tokens, individual user prompts, raw conversation logs. |42| **D** | **Restricted** | Regulated data, proprietary IP, Fox Companies content. | `.planning/fox-companies/` artefacts, `wasteland/` content, customer-identifiable records, anything subject to legal hold. |4344Defaults and enforcement:4546- New telemetry writers default to **Tier B** unless an explicit tier label47 is supplied at construction.48- **Tier C** data MUST be encrypted at rest and MUST be excluded from any49 artefact published outside the local repository (no `git push` of files50 containing Tier C content; no FTP sync; no inclusion in release notes).51- **Tier D** data MUST never leave the `.planning/` tree or52 `wasteland/` branch. Surface alignments in conversation only; never53 commit Tier D content to a public-facing path.54- Mixed-tier sinks are FORBIDDEN — a writer that mixes Tier A and Tier C55 records loses the ability to safely publish the Tier A subset.5657Referenced by C5 W3.P6 tool-tracker (telemetry writer wiring) and the58post-tool-use observation hook.5960## Authoring around the leak-scanner — don't re-trip the control (Lesson #10462)6162The release-history publisher (`tools/release-history/publish.mjs`, `leakScan`) runs63a hard leak-scan gate over every published chapter. Its effective patterns combine64committed base patterns with operator-private patterns loaded from the gitignored65`release-history.local.json`, so the scan is **operator-machine-specific**: a fresh66CI checkout sees only the base patterns and never the local ones.6768Two failure modes recur whenever you DOCUMENT leak-scan or security-hardening work:69701. **The control's own documentation re-trips it.** A retrospective that quotes a71 leak *pattern* verbatim (e.g. v1.49.588 quoting the narrowed private-path regex72 it was describing) matches that pattern and is HARD-BLOCKED — even though it73 contains no real secret.742. **The recursion trap.** Documenting the *fix* for #1 by enumerating the private75 literals the control guards (company / email / credential-var) embeds those76 values into published content — a genuine leak the scanner correctly blocks.77 The v1.49.916 retrospective re-tripped exactly this way while documenting the78 v916 AC7 allowlist fix.7980**Authoring rule: describe the pattern, never quote the literal.** In release notes,81retrospectives, or docs that touch leak-scan work, refer to a pattern by name or82shape ("the company-name local pattern", "the credential-var form") — never paste83the regex source and never paste the private value.8485**Allowlist-vs-scrub decision rule:**8687- The doc legitimately quotes a leak **PATTERN** (a regex, for self-referential88 documentation) → add a narrow `leak_scan_allowlist` entry in the committed89 `release-history.config.json`, keyed on the EXACT `version` + `file` + `pattern`90 source, with a `reason`. Never widen to a global pattern exemption.91- The content embeds a genuinely-private **VALUE** → **SCRUB the value** from the92 content. Never allowlist a private value into published output — the allowlist is93 for pattern-quoting docs only, never for secrets.9495This pairs the loud surface (the leak-scan gate) with the authoring discipline that96keeps it from firing on its own documentation. See97[`docs/failure-mode-contracts.md`](../../../docs/failure-mode-contracts.md) (#1042798silent-vs-loud surfaces) and99[`docs/known-unwired-ledger-discipline.md`](../../../docs/known-unwired-ledger-discipline.md)100(#10461 gate-enforce-every-runnable-surface + drift-guard).101102## The Staging Layer Principle103104"The user's ability to work should be reasonable. Security should also be reasonable. We strive for the clean intersection." Do not over-alert. Do not create friction for normal operations. Surface findings only when something genuinely warrants attention.
Tibsfox