@yeison.restrepo.r/code-conductor 1.31.2 → 1.32.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -186,7 +186,7 @@ Fires before `Read`, `Write`, `Edit`, `create_file`, `write_file` and `Bash`. A
|
|
|
186
186
|
|
|
187
187
|
**Bash scan guard (Guard 3)** - every `Bash` command is matched against twelve mass content-dump patterns before it runs: deep `find` without `-maxdepth 1`, `find -exec` with readers or shells, `xargs` with readers, `cat` or a pager followed by an unquoted glob, command substitution as a reader's argument, `grep -r` with a match-all pattern, `ls -R`, shell loops, `mapfile` and `readarray`, `eval`, `source` and the dot operator, alias remapping to a reader, and obfuscation sequences. Commands over 8192 characters and unclosed quotes are denied fail-closed.
|
|
188
188
|
|
|
189
|
-
Permanent exceptions live in `.claude/memory/bash-scan-allowlist.txt`, one entry per line, blank lines and `#` comments ignored and whitespace trimmed. An entry ending in `/` covers paths under that prefix, rejecting any suffix that walks up the tree with `..`; any other entry matches a whole command token. **Entries match literally: regex metacharacters carry no special meaning, so `file.ts` matches `file.ts` and nothing else.** The installer
|
|
189
|
+
Permanent exceptions live in `.claude/memory/bash-scan-allowlist.txt`, one entry per line, blank lines and `#` comments ignored and whitespace trimmed. An entry ending in `/` covers paths under that prefix, rejecting any suffix that walks up the tree with `..`; any other entry matches a whole command token. **Entries match literally: regex metacharacters carry no special meaning, so `file.ts` matches `file.ts` and nothing else.** The installer ships this file once as a commented template and creates it only when it is absent; it never overwrites an existing one. Every line in it disarms patterns for matching commands, so give each entry a comment saying why it exists; an uncommented entry is a review smell.
|
|
190
190
|
|
|
191
191
|
Hit a block you believe is wrong? Re-run the command with `CC_GUARD3_WARN=1` and the guard asks instead of denying, carrying the same pattern ids. That is a triage aid for reporting a false positive while you keep working, not a configuration mode: the allowlist is the sanctioned permanent exception. The variable affects Guard 3 alone.
|
|
192
192
|
|
|
@@ -23,15 +23,20 @@ export const GLOBAL_HOST_OWNED = new Map([
|
|
|
23
23
|
['settings.local.json', 'skip'],
|
|
24
24
|
]);
|
|
25
25
|
|
|
26
|
-
// <cwd>/.claude/.
|
|
27
|
-
//
|
|
28
|
-
//
|
|
29
|
-
//
|
|
26
|
+
// <cwd>/.claude/. Every 'skip' below is a file the host or a conductor command writes
|
|
27
|
+
// at runtime and the template must never start shipping; each is protected today only
|
|
28
|
+
// by its absence from the template, which is exactly what this table replaces.
|
|
29
|
+
//
|
|
30
|
+
// bash-scan-allowlist.txt is the exception and the reason the policy is a table: it is
|
|
31
|
+
// host-owned like the skips, but BUG-044 ships a comment-only template for it so the deny
|
|
32
|
+
// message names a path that resolves. hostOwnedFilter excludes it from the copy and
|
|
33
|
+
// seedHostOwned writes it only when absent, so shipping the filename cannot overwrite
|
|
34
|
+
// operator policy the way it could before BUG-039 filtered the copy.
|
|
30
35
|
export const PROJECT_HOST_OWNED = new Map([
|
|
31
36
|
['memory/project.md', 'seed'],
|
|
32
37
|
['memory/context-threshold.txt', 'seed'],
|
|
33
38
|
['memory/personal.md', 'skip'],
|
|
34
|
-
['memory/bash-scan-allowlist.txt', '
|
|
39
|
+
['memory/bash-scan-allowlist.txt', 'seed'],
|
|
35
40
|
['memory/session-snapshot.json', 'skip'],
|
|
36
41
|
['memory/session-snapshot.md', 'skip'],
|
|
37
42
|
['memory/turn-count.txt', 'skip'],
|
package/package.json
CHANGED
|
@@ -155,6 +155,7 @@ function g3JoinContinuations(input) {
|
|
|
155
155
|
// unclosed quote). "glob" reports whether an unquoted glob character appears, and
|
|
156
156
|
// treats malformed input as a glob, which is the authority's fail-closed choice.
|
|
157
157
|
function g3Scan(mode, input) {
|
|
158
|
+
const emit = mode === 'strip' || mode === 'mask';
|
|
158
159
|
let state = 'UNQUOTED';
|
|
159
160
|
let result = '';
|
|
160
161
|
let i = 0;
|
|
@@ -163,34 +164,35 @@ function g3Scan(mode, input) {
|
|
|
163
164
|
const ch = input[i];
|
|
164
165
|
const two = input.slice(i, i + 2);
|
|
165
166
|
if (state === 'UNQUOTED') {
|
|
166
|
-
if (two === "$'") { if (
|
|
167
|
-
else if (two === '$"') { if (
|
|
168
|
-
else if (ch === '\\') { if (
|
|
169
|
-
else if (ch === "'") { if (
|
|
170
|
-
else if (ch === '"') { if (
|
|
167
|
+
if (two === "$'") { if (emit) result += two; i += 2; state = 'ANSI_C_QUOTED'; }
|
|
168
|
+
else if (two === '$"') { if (emit) result += two; i += 2; state = 'LOCALE_QUOTED'; }
|
|
169
|
+
else if (ch === '\\') { if (emit) result += input.slice(i, i + 2); i += 2; }
|
|
170
|
+
else if (ch === "'") { if (emit) result += ch; i += 1; state = 'SINGLE_QUOTED'; }
|
|
171
|
+
else if (ch === '"') { if (emit) result += ch; i += 1; state = 'DOUBLE_QUOTED'; }
|
|
171
172
|
else if (ch === '#' && mode === 'strip') { while (i < len && input[i] !== '\n') i += 1; }
|
|
172
173
|
else {
|
|
173
174
|
if (mode === 'glob' && (ch === '*' || ch === '?' || ch === '{' || ch === '[')) return { glob: true };
|
|
174
|
-
if (
|
|
175
|
+
if (emit) result += ch;
|
|
175
176
|
i += 1;
|
|
176
177
|
}
|
|
177
178
|
} else if (state === 'SINGLE_QUOTED') {
|
|
178
179
|
// Backslash is literal here and ANY quote exits: there is no escape mechanism.
|
|
179
180
|
if (mode === 'strip') result += ch;
|
|
181
|
+
else if (mode === 'mask') result += ch === "'" ? ch : 'x';
|
|
180
182
|
if (ch === "'") state = 'UNQUOTED';
|
|
181
183
|
i += 1;
|
|
182
184
|
} else if (state === 'DOUBLE_QUOTED' || state === 'LOCALE_QUOTED') {
|
|
183
|
-
if (ch === '\\') { if (mode === 'strip') result += input.slice(i, i + 2); i += 2; }
|
|
184
|
-
else if (ch === '"') { if (
|
|
185
|
-
else { if (mode === 'strip') result += ch; i += 1; }
|
|
185
|
+
if (ch === '\\') { if (mode === 'strip') result += input.slice(i, i + 2); else if (mode === 'mask') result += 'xx'; i += 2; }
|
|
186
|
+
else if (ch === '"') { if (emit) result += ch; i += 1; state = 'UNQUOTED'; }
|
|
187
|
+
else { if (mode === 'strip') result += ch; else if (mode === 'mask') result += 'x'; i += 1; }
|
|
186
188
|
} else {
|
|
187
|
-
if (ch === '\\') { if (mode === 'strip') result += input.slice(i, i + 2); i += 2; }
|
|
188
|
-
else if (ch === "'") { if (
|
|
189
|
-
else { if (mode === 'strip') result += ch; i += 1; }
|
|
189
|
+
if (ch === '\\') { if (mode === 'strip') result += input.slice(i, i + 2); else if (mode === 'mask') result += 'xx'; i += 2; }
|
|
190
|
+
else if (ch === "'") { if (emit) result += ch; i += 1; state = 'UNQUOTED'; }
|
|
191
|
+
else { if (mode === 'strip') result += ch; else if (mode === 'mask') result += 'x'; i += 1; }
|
|
190
192
|
}
|
|
191
193
|
}
|
|
192
|
-
if (state !== 'UNQUOTED') return
|
|
193
|
-
return
|
|
194
|
+
if (state !== 'UNQUOTED') return emit ? { result, malformed: true } : { glob: true };
|
|
195
|
+
return emit ? { result, malformed: false } : { glob: false };
|
|
194
196
|
}
|
|
195
197
|
|
|
196
198
|
// Each check returns true when it FIRES (the authority's shell functions returned 1).
|
|
@@ -427,14 +429,28 @@ const g3Chomp = (s) => s.replace(/\n+$/, '');
|
|
|
427
429
|
// keeps working instead of filing an uninstall. It is documented as triage, not as
|
|
428
430
|
// configuration: the allowlist is the sanctioned permanent exception. It has no
|
|
429
431
|
// relationship to CC_HOOK_ALLOW, whose scope stays the two pre-verdict conditions.
|
|
430
|
-
|
|
432
|
+
// The three alternatives are the only remedy every denial shares, so they are the
|
|
433
|
+
// message's constant part.
|
|
434
|
+
const G3_ALTERNATIVES =
|
|
435
|
+
'Authorized alternatives: 1. Grep for targeted content search with file and pattern scope. ' +
|
|
436
|
+
'2. Glob for path listing without file content. 3. Read with an explicit offset and limit.';
|
|
437
|
+
|
|
438
|
+
// The allowlist sentence rides ONLY on a pattern denial. g3AllowlistCovers runs at the end
|
|
439
|
+
// of guard3BashScan; the length and malformed denials return before it, so on those two the
|
|
440
|
+
// allowlist cannot lift the block and naming it would promise a remedy that provably does
|
|
441
|
+
// not apply. It is worded as operator policy because the agent reading it mid-denial is
|
|
442
|
+
// instructed never to bypass this hook: it may propose an entry, never self-serve one.
|
|
443
|
+
// Uptake staying at zero is that instruction working, not a discoverability failure.
|
|
444
|
+
// [BUG-044]
|
|
445
|
+
const G3_OPERATOR_POLICY =
|
|
446
|
+
'A permanent exception is operator policy, not a self-serve step: entries live in ' +
|
|
447
|
+
'.claude/memory/bash-scan-allowlist.txt, are reviewed in git, and an agent may propose ' +
|
|
448
|
+
'one but must not add it to clear its own denial.';
|
|
449
|
+
|
|
450
|
+
function g3Blocked(detail, { allowlistApplies = false } = {}) {
|
|
431
451
|
const decide = process.env.CC_GUARD3_WARN ? ask : deny;
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
'Authorized alternatives: 1. Grep for targeted content search with file and pattern scope. ' +
|
|
435
|
-
'2. Glob for path listing without file content. 3. Read with an explicit offset and limit. ' +
|
|
436
|
-
'To permit a path permanently, add a commented entry to .claude/memory/bash-scan-allowlist.txt.'
|
|
437
|
-
);
|
|
452
|
+
const policy = allowlistApplies ? ` ${G3_OPERATOR_POLICY}` : '';
|
|
453
|
+
return decide(`BASH SCAN BLOCKED. ${detail} ${G3_ALTERNATIVES}${policy}`);
|
|
438
454
|
}
|
|
439
455
|
|
|
440
456
|
// Guard 3: the bash command scanner, ported from tests/fixtures/guard3-reference.sh.
|
|
@@ -451,12 +467,21 @@ function guard3BashScan(input) {
|
|
|
451
467
|
}
|
|
452
468
|
// Real newlines become semicolons so a multi-line script reads as a command
|
|
453
469
|
// sequence to every position-anchored pattern above.
|
|
454
|
-
|
|
470
|
+
//
|
|
471
|
+
// The mask is built from the STRIPPED string and BEFORE the newline join, so a
|
|
472
|
+
// newline inside a quoted region can never become a command-position anchor.
|
|
473
|
+
// Exactly two checks read quoted content BY DESIGN: P6 reads the grep pattern and
|
|
474
|
+
// P12 reads the alias value. Everything else reads code and gets the mask. The
|
|
475
|
+
// allowlist reads the unmasked string. [BUG-043].
|
|
476
|
+
const chomped = g3Chomp(scan.result);
|
|
477
|
+
const pre = chomped.split('\n').join(';');
|
|
478
|
+
const masked = g3Scan('mask', chomped).result.split('\n').join(';');
|
|
479
|
+
const UNMASKED_CHECKS = new Set(['P6', 'P12']);
|
|
455
480
|
const ids = [];
|
|
456
|
-
for (const { id, check } of G3_CHECKS) if (check(pre)) ids.push(id);
|
|
481
|
+
for (const { id, check } of G3_CHECKS) if (check(UNMASKED_CHECKS.has(id) ? pre : masked)) ids.push(id);
|
|
457
482
|
if (ids.length === 0) return null;
|
|
458
483
|
if (g3AllowlistCovers(pre, g3ReadAllowlist())) return null;
|
|
459
|
-
return g3Blocked(`The command triggered a mass content-dump pattern. Pattern ids: ${ids.join(' ')}
|
|
484
|
+
return g3Blocked(`The command triggered a mass content-dump pattern. Pattern ids: ${ids.join(' ')}.`, { allowlistApplies: true });
|
|
460
485
|
}
|
|
461
486
|
|
|
462
487
|
const DISPATCH = {
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Guard 3 bash-scan allowlist. OPERATOR POLICY, reviewed in git.
|
|
2
|
+
#
|
|
3
|
+
# This file is empty on purpose. It disarms nothing until you add a line.
|
|
4
|
+
#
|
|
5
|
+
# Format:
|
|
6
|
+
# One entry per line. Blank lines and lines starting with # are ignored, and
|
|
7
|
+
# surrounding whitespace is trimmed.
|
|
8
|
+
#
|
|
9
|
+
# An entry ending in / covers paths under that prefix, and rejects any suffix
|
|
10
|
+
# that walks up the tree with .. so an entry cannot become a traversal gift.
|
|
11
|
+
# Any other entry matches a whole command token.
|
|
12
|
+
#
|
|
13
|
+
# Entries match LITERALLY. Regex metacharacters carry no special meaning, so
|
|
14
|
+
# file.ts matches file.ts and nothing else.
|
|
15
|
+
#
|
|
16
|
+
# Review rule:
|
|
17
|
+
# Every line here disarms Guard 3 patterns for matching commands, so give each
|
|
18
|
+
# entry a comment saying why it exists and ideally the issue it came from. An
|
|
19
|
+
# uncommented entry is a review smell.
|
|
20
|
+
#
|
|
21
|
+
# Example, shown commented out so this file stays inert:
|
|
22
|
+
# # docs/ is a small hand-written tree; bulk reads there are intended [BUG-000]
|
|
23
|
+
# docs/
|
|
24
|
+
#
|
|
25
|
+
# An agent that hits a Guard 3 denial may propose an entry here. It must not add
|
|
26
|
+
# one to clear its own denial: that is the bypass the project forbids. Permanent
|
|
27
|
+
# exceptions are the operator's call, which is why they are reviewed in git.
|
|
28
|
+
#
|
|
29
|
+
# The installer creates this file only when it is absent and never overwrites it.
|