repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs(leaks): document spec-shaped redaction

853cfa4fc4b2e47c7af58881a4e01b4b0e87dda6

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (5)

extensions/leaks/README.md

Modified
2 2 # leaks
4 4 Provider-bound secret redaction for Pi.
6 +`leaks` redacts secrets before provider requests.
7 +Local Pi behavior stays transparent when placeholders round-trip exactly.
6 9 ## Install / load
8 -Loaded through the root [pi-ext package](../../README.md).
11 +Loaded through the root pi-ext package. See [../../README.md](../../README.md).
13 +## Threat model
15 +Provider sees placeholders, not classified secret values.
16 +Pi keeps restore mappings in memory only.
17 +Mappings are lost on process exit, reload, new session, or `/leaks clear`.
19 +`leaks` does not stop tool exfiltration, malicious model behavior, prompt
20 +injection, or unsafe commands.
21 +Use Pi permissions, sandboxing, and tool policy for that.
23 +## Placeholder model
25 +Provider text uses this shape:
27 +```text
28 +__LEAK_<TAG>[_<TAG>...]_<HMAC12>[_N]__
29 +```
31 +Examples use fake metadata only:
33 +```text
34 +__LEAK_STRIPE_LIVE_SECRET_KEY_STRIPE_TOKEN_8f31aa77c901__
35 +__LEAK_DATABASE_URL_DB_PASSWORD_POSTGRES_URL_ba29d4ff8810__
36 +```
38 +The digest is HMAC12 with a random in-memory key.
39 +Tags are safe metadata.
40 +Secret length, prefix, suffix, alphabet, and entropy are not encoded.
10 42 ## Commands / tools / settings
12 44 Commands:
14 -- `/leaks status`
15 -- `/leaks reload`
16 -- `/leaks test <text>`
17 -- `/leaks clear`
46 +- `/leaks status` reports safe counters and labels.
47 +- `/leaks reload` reloads settings and dotenv/env learning.
48 +- `/leaks test <text>` redacts local diagnostic text.
49 +- `/leaks clear` clears volatile placeholder mappings after confirmation.
19 -Tools:
20 -none.
51 +Tools: none.
22 -Hooks:
23 -`beforeProviderRequest`, `context`, `toolCall`, `messageEnd`.
25 -Settings namespace:
26 -`leaks` in Pi `settings.json`.
28 -Settings:
30 -- `enabled`: boolean, default `true`
31 -- `keywords`: string[], default `[]`
32 -- `regex`: string[] or `{ pattern, flags, label }[]`, default `[]`
33 -- `secretFiles`: string[], default `[".env", ".env.local", ".env.*.local"]`
34 -- `exclude`: string[], default `[]`
53 +Settings: only custom regex rules are accepted.
36 55 ```json
38 57 "leaks": {
39 - "enabled": true,
40 - "keywords": ["acme-internal"],
41 - "regex": [{ "pattern": "foo_[A-Za-z0-9]{32}", "label": "FOO_TOKEN" }],
42 - "secretFiles": [".env", ".env.local", ".env.*.local"],
43 - "exclude": ["localhost", "127.0.0.1"]
58 + "regex": [{ "pattern": "foo_[A-Za-z0-9]{32}", "label": "FOO_TOKEN" }]
63 +Labels must match `[A-Z0-9_]{1,64}`.
64 +Invalid or missing labels fall back to `CUSTOM_REGEX` and warn.
65 +Flags and unsupported fields are ignored with warnings.
66 +Unsafe patterns are rejected.
68 +Rejected settings: `enabled`, `keywords`, `exclude`, `secretFiles`.
69 +They are intentionally not compatibility features.
48 71 ## Behavior
50 -Redacts provider-bound copies before model requests.
51 -Context-message copies are redacted without mutating originals.
52 -Local tool calls receive restored args before execution.
53 -Final assistant messages are restored locally.
73 +Built-ins are always active.
74 +They cover high-confidence AI, VCS, package, cloud, payment, messaging, webhook,
75 +mail, auth, OAuth, JWT, cookie, session, database, cache, private-key, and
76 +sensitive-assignment patterns.
55 -Secret values are loaded from configured files relative to Pi cwd.
56 -Settings are read from Pi settings, with `.pi/settings.json` fallback when the
57 -runtime settings API is absent.
78 +Dotenv learning reads only cwd files:
59 -Built-in rules cover common AI provider tokens, developer tokens, cloud keys,
60 -JWTs, private keys, and selected connection strings.
61 -Custom `keywords` use smart boundaries.
62 -Custom `regex` entries may be strings or objects with `pattern`, `flags`, and
63 -`label`.
64 -Generic assignment redaction requires sufficiently random values and skips
65 -common false positives.
80 +- `.env`
81 +- `.env.local`
82 +- `.env.*.local`
67 -`/leaks status` reports enabled state, rule counts, secret-file values, provider
68 -redactions, and mapping counts.
69 -`/leaks reload` reloads settings and secret-file values.
70 -`/leaks clear` clears stored placeholder mappings.
71 -`/leaks test` is a dry run; its placeholders do not persist.
84 +Process environment values use the same classifier.
85 +Status collapses process env names to `ENV_KEY`.
73 -Placeholders are generic:
87 +URLs, query params, headers, cookies, and assignments preserve safe structure.
88 +Only secret components are redacted.
89 +JWTs and private-key material redact as whole logical values.
90 +Public keys and certificates stay visible.
75 -`__LEAK_<12 hex>__`.
92 +Provider-bound context and provider request payloads are redacted on copied
93 +values.
94 +Original local objects are not mutated.
95 +Provider authentication headers are preserved.
97 +Tool-call args and finalized assistant messages are restored locally when they
98 +contain exact placeholders.
99 +Restore only matches complete placeholders.
101 +Traversal is bounded.
102 +Cycles are preserved.
103 +Primitive and callable values pass through.
104 +Detector failures fail open and warn once.
106 +Mappings and learned values are capped at 8192 entries.
107 +Overflow placeholders may not be restorable.
109 +## False-positive policy
111 +Metadata stays visible aggressively.
112 +No entropy-only redaction.
113 +Names, hosts, domains, ordinary URLs, refs, branch names, package names, IDs,
114 +codenames, env references, public keys, and certificates stay visible unless a
115 +custom regex explicitly matches them.
117 +## Limitations
119 +Out of scope:
121 +- image, audio, binary, OCR redaction
122 +- semantic secret-byte editing
123 +- homomorphic encryption
124 +- symbolic secret transforms
125 +- arbitrary DLP/privacy redaction
126 +- tool sandboxing
127 +- permission enforcement
128 +- repository secret scanning
129 +- git history cleanup

extensions/leaks/__tests__/ledger.test.ts

Modified
63 63 for (let index = 0; index < matches.length; index++) {
64 64 const match = matches[index];
65 65 const next = matches[index + 1];
66 + const start = match.index ?? 0;
66 67 result.push({
67 68 name: String(match[1]),
68 - body: spec.slice(match.index! + match[0].length, next?.index),
69 + body: spec.slice(start + match[0].length, next?.index),
71 72 return result;

extensions/leaks/index.ts

Modified
1 -import { builtinRegexFuzzTargets, builtinRules, findBuiltinSpans } from "./src/detectors.ts";
1 +import {
2 + builtinRegexFuzzTargets,
3 + builtinRules,
4 + findBuiltinSpans,
5 +} from "./src/detectors.ts";
2 6 import {
3 7 discoverDotenvFiles,
4 8 highConfidenceSecretShape,
11 15 import { LeaksEngine } from "./src/engine.ts";
12 16 import leaks from "./src/pi.ts";
13 17 import { PlaceholderStore } from "./src/placeholders.ts";
18 +import {
19 + isExistingPlaceholder,
20 + isPlainObject,
21 + isWeakValue,
22 + maskDiagnostic,
23 + sanitizeTag,
24 +} from "./src/safety.ts";
14 25 import { selectSecretSpans } from "./src/selector.ts";
15 26 import {
16 27 compileCustomRegex,
30 41 findStructureSpans,
31 42 structureRegexFuzzTargets,
32 43 } from "./src/structures.ts";
33 -import {
34 - isExistingPlaceholder,
35 - isPlainObject,
36 - isWeakValue,
37 - maskDiagnostic,
38 - sanitizeTag,
39 -} from "./src/safety.ts";
41 45 export const RUNTIME_SETTING_KEYS = ["regex"] as const;
45 49 PlaceholderStore,
46 50 builtinRules,
47 51 findBuiltinSpans,
48 - runtimeRegexFuzzTargets: [...builtinRegexFuzzTargets, ...structureRegexFuzzTargets],
52 + runtimeRegexFuzzTargets: [
53 + ...builtinRegexFuzzTargets,
54 + ...structureRegexFuzzTargets,
55 + ],
49 56 discoverDotenvFiles,
50 57 parseDotenv,
51 58 loadDotenvValues,

extensions/leaks/src/engine.ts

Modified
1 1 import { builtinRules, findBuiltinSpans } from "./detectors.ts";
2 2 import {
3 + type LearnedValue,
3 4 learnEnvironmentValues,
4 5 learnedValueSpans,
5 6 loadDotenvValues,
6 - type LearnedValue,
7 7 } from "./dotenv.ts";
8 8 import { PlaceholderStore } from "./placeholders.ts";
9 9 import { isPlainObject } from "./safety.ts";
10 10 import { selectSecretSpans } from "./selector.ts";
11 -import { findStructureSpans } from "./structures.ts";
12 11 import {
12 + type CompiledCustomRule,
13 13 compileCustomRegex,
14 14 customRegexSpans,
15 - type CompiledCustomRule,
16 15 } from "./settings.ts";
16 +import { findStructureSpans } from "./structures.ts";
17 17 import type {
18 18 DeepRedactionResult,
19 19 Detector,
60 60 this.learn(cwd, env);
63 - redactText(text: string, origin: RedactionOrigin = "provider"): RedactionResult {
63 + redactText(
64 + text: string,
65 + origin: RedactionOrigin = "provider",
66 + ): RedactionResult {
64 67 let spans: SecretSpan[] = [
65 68 ...findStructureSpans(text),
66 69 ...findBuiltinSpans(text),
71 74 try {
72 75 spans = spans.concat(detector(text));
73 76 } catch {
74 - this.warnOnce("detector.failure", "detector failure; redaction pass left unchanged");
77 + this.warnOnce(
78 + "detector.failure",
79 + "detector failure; redaction pass left unchanged",
80 + );
75 81 if (origin === "provider") this.lastProviderRedactionCount = 0;
76 82 return { text, count: 0, labels: [], placeholders: [] };
96 102 if (labels.length > 0) this.recentLabels = labels.slice(-12);
97 103 if (placeholders.length > 0) {
98 104 this.latestTags = placeholders.map((placeholder) =>
99 - placeholder.replace(/^__LEAK_?/, "").replace(/_[a-f0-9]{12}(?:_\d+)?__$/, ""),
105 + placeholder
106 + .replace(/^__LEAK_?/, "")
107 + .replace(/_[a-f0-9]{12}(?:_\d+)?__$/, ""),
102 110 return { text: redacted, count, labels, placeholders };
105 - redactDeep<T>(value: T, origin: RedactionOrigin = "provider"): DeepRedactionResult<T> {
113 + redactDeep<T>(
114 + value: T,
115 + origin: RedactionOrigin = "provider",
116 + ): DeepRedactionResult<T> {
106 117 return this.walk(value, origin, false);
126 137 active: true,
127 138 builtInRuleCount: builtinRules.length,
128 139 customRegexCount: this.customRules.length,
129 - regexWarningCount: this.warnings.filter((warning) => warning.code.startsWith("settings.regex.")).length,
140 + regexWarningCount: this.warnings.filter((warning) =>
141 + warning.code.startsWith("settings.regex."),
142 + ).length,
130 143 warningCount: this.warnings.length,
131 144 invalidRegexCount: this.invalidRegexCount,
132 145 learnedCount: this.learned.length,
150 163 const dotenv = loadDotenvValues(cwd);
151 164 const processEnv = learnEnvironmentValues(env);
152 165 this.learned = [...dotenv.values, ...processEnv.values].slice(0, 8192);
153 - for (const warning of [...dotenv.warnings, ...processEnv.warnings]) this.addWarning(warning);
166 + for (const warning of [...dotenv.warnings, ...processEnv.warnings])
167 + this.addWarning(warning);
156 - private walk<T>(input: T, origin: RedactionOrigin, restore: boolean): DeepRedactionResult<T> {
170 + private walk<T>(
171 + input: T,
172 + origin: RedactionOrigin,
173 + restore: boolean,
174 + ): DeepRedactionResult<T> {
157 175 const seen = new WeakMap<object, unknown>();
158 176 let count = 0;
159 177 let changed = false;
175 193 if (value === null || typeof value !== "object") return value;
176 194 if (depth >= 64) {
177 - this.warnOnce("traversal.depth", "maximum redaction traversal depth reached");
195 + this.warnOnce(
196 + "traversal.depth",
197 + "maximum redaction traversal depth reached",
198 + );
178 199 return value;
180 201 const cached = seen.get(value);
190 211 const source = value as Record<string, unknown>;
191 212 const copy: Record<string, unknown> = {};
192 213 seen.set(value, copy);
193 - for (const [key, item] of Object.entries(source)) copy[key] = visit(item, depth + 1);
194 - if (Object.keys(copy).some((key) => copy[key] !== source[key])) changed = true;
214 + for (const [key, item] of Object.entries(source))
215 + copy[key] = visit(item, depth + 1);
216 + if (Object.keys(copy).some((key) => copy[key] !== source[key]))
217 + changed = true;
195 218 return copy;
197 220 return { value: visit(input, 0) as T, changed, count };

extensions/leaks/src/settings.ts

Modified
1 1 import { isPlainObject } from "./safety.ts";
2 -import type { CustomRegexInput, LeaksSettings, SecretSpan, WarningRecord } from "./types.ts";
2 +import type {
3 + CustomRegexInput,
4 + LeaksSettings,
5 + SecretSpan,
6 + WarningRecord,
7 +} from "./types.ts";
4 9 export type LoadedSettings = {
5 10 settings: LeaksSettings;
28 33 const regex: CustomRegexInput[] = [];
29 34 for (const entry of input) {
30 35 if (!isPlainObject(entry)) continue;
31 - const unsupported = Object.keys(entry).filter((key) => key !== "pattern" && key !== "label" && key !== "flags");
32 - if (unsupported.length > 0) warnings.push(warn("settings.regex.unsupported-field", "unsupported regex setting fields ignored"));
33 - if ("flags" in entry) warnings.push(warn("settings.regex.flags", "regex flags are not supported and were ignored"));
36 + const unsupported = Object.keys(entry).filter(
37 + (key) => key !== "pattern" && key !== "label" && key !== "flags",
38 + );
39 + if (unsupported.length > 0)
40 + warnings.push(
41 + warn(
42 + "settings.regex.unsupported-field",
43 + "unsupported regex setting fields ignored",
44 + ),
45 + );
46 + if ("flags" in entry)
47 + warnings.push(
48 + warn(
49 + "settings.regex.flags",
50 + "regex flags are not supported and were ignored",
51 + ),
52 + );
34 53 regex.push({ pattern: entry.pattern, label: entry.label });
36 55 return { settings: { regex }, warnings };
39 -export function compileCustomRegex(settings: LeaksSettings): CompiledCustomRegex {
58 +export function compileCustomRegex(
59 + settings: LeaksSettings,
60 +): CompiledCustomRegex {
40 61 const rules: CompiledCustomRule[] = [];
41 62 const warnings: WarningRecord[] = [];
42 63 let invalidRegexCount = 0;
43 64 for (const entry of settings.regex) {
44 65 if (typeof entry.pattern !== "string" || entry.pattern.length === 0) {
45 - warnings.push(warn("settings.regex.missing-pattern", "custom regex pattern missing"));
66 + warnings.push(
67 + warn("settings.regex.missing-pattern", "custom regex pattern missing"),
68 + );
46 69 invalidRegexCount++;
47 70 continue;
49 72 if (entry.pattern.length > 512) {
50 - warnings.push(warn("settings.regex.pattern-too-long", "custom regex pattern too long"));
73 + warnings.push(
74 + warn(
75 + "settings.regex.pattern-too-long",
76 + "custom regex pattern too long",
77 + ),
78 + );
51 79 invalidRegexCount++;
52 80 continue;
54 82 if (isUnsafeRegex(entry.pattern)) {
55 - warnings.push(warn("settings.regex.unsafe", "custom regex rejected by safety checks"));
83 + warnings.push(
84 + warn("settings.regex.unsafe", "custom regex rejected by safety checks"),
85 + );
56 86 invalidRegexCount++;
57 87 continue;
60 90 let label = "CUSTOM_REGEX";
61 91 if (typeof entry.label !== "string" || entry.label.length === 0) {
62 - warnings.push(warn("settings.regex.missing-label", "custom regex label missing; using CUSTOM_REGEX"));
92 + warnings.push(
93 + warn(
94 + "settings.regex.missing-label",
95 + "custom regex label missing; using CUSTOM_REGEX",
96 + ),
97 + );
63 98 } else if (!LABEL_RE.test(entry.label)) {
64 - warnings.push(warn("settings.regex.invalid-label", "custom regex label invalid; using CUSTOM_REGEX"));
99 + warnings.push(
100 + warn(
101 + "settings.regex.invalid-label",
102 + "custom regex label invalid; using CUSTOM_REGEX",
103 + ),
104 + );
65 105 } else {
66 106 label = entry.label;
69 109 const captures = countCaptures(entry.pattern);
70 - if (captures > 1) warnings.push(warn("settings.regex.multiple-captures", "custom regex has multiple captures; using group 1"));
110 + if (captures > 1)
111 + warnings.push(
112 + warn(
113 + "settings.regex.multiple-captures",
114 + "custom regex has multiple captures; using group 1",
115 + ),
116 + );
73 119 rules.push({
77 123 captureGroup: captures === 0 ? 0 : 1,
79 125 } catch {
80 - warnings.push(warn("settings.regex.syntax", "custom regex syntax invalid"));
126 + warnings.push(
127 + warn("settings.regex.syntax", "custom regex syntax invalid"),
128 + );
81 129 invalidRegexCount++;
84 132 return { rules, warnings, invalidRegexCount };
87 -export function customRegexSpans(text: string, rules: CompiledCustomRule[]): SecretSpan[] {
135 +export function customRegexSpans(
136 + text: string,
137 + rules: CompiledCustomRule[],
138 +): SecretSpan[] {
88 139 const spans: SecretSpan[] = [];
89 140 for (const rule of rules) {
90 141 rule.regex.lastIndex = 0;
91 - let match: RegExpExecArray | null;
92 - while ((match = rule.regex.exec(text))) {
142 + let match = rule.regex.exec(text);
143 + while (match) {
93 144 const range = match.indices?.[rule.captureGroup];
94 145 const value = match[rule.captureGroup];
95 146 if (range && typeof value === "string" && value.length > 0) {
106 157 if (match[0] === "") rule.regex.lastIndex++;
158 + match = rule.regex.exec(text);
109 161 return spans;