Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): block attached output flags, pin exec read-only contract (#4054)

tim-inkeep1fa19dead72e
diff --git a/.changeset/exec-read-only-contract.md b/.changeset/exec-read-only-contract.md
new file mode 100644
index 000000000..cb567531f
--- /dev/null
+++ b/.changeset/exec-read-only-contract.md
@@ -0,0 +1,17 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Agent `exec` can no longer write to the project.
+
+`exec` is documented read-only, and that promise was enforced by comparing each argument against a list of blocked flags. The comparison was exact, so it caught `sort -o notes.md` and missed `sort -onotes.md` — the same flag with its value attached, which `sort` accepts. A command that only reads was able to create a file, and to replace an existing document with the contents of another:
+
+```
+sort -oimportant.md other.md
+```
+
+Nothing about that goes through `write` or `edit`, so the replacement carried no attribution and left no history to restore from.
+
+`sort` is the only one of the ten allowed commands whose `-o` writes, so the guard is scoped to it and now covers the flag however it is spelled, including bundled forms like `-ro`. `--output-delimiter`, which only changes how output is printed, keeps working. A bare `-o` on its own stays refused for every command, as it was before this change, so `grep -o` still asks for `--only-matching` instead; the clustered forms it appears in, such as `grep -oE`, are unaffected.
+
+A companion suite runs every write and delete attempt we know of through the real command pipeline and asserts the project is byte-identical afterwards, so the read-only promise is checked rather than assumed.
diff --git a/packages/server/src/bash/mtime-scan.test.ts b/packages/server/src/bash/mtime-scan.test.ts
index 379cd5603..1500c6172 100644
--- a/packages/server/src/bash/mtime-scan.test.ts
+++ b/packages/server/src/bash/mtime-scan.test.ts
@@ -76,7 +76,9 @@ describe('deriveScanRoots', () => {
});
test('grep drops the pattern positional but keeps operands', () => {
- expect(deriveScanRoots([stage('grep', '-rn', 'oauth', 'articles/')])).toEqual(['articles/']);
+ const roots = deriveScanRoots([stage('grep', '-rn', 'oauth', 'articles/')]);
+ expect(roots).toContain('articles/');
+ expect(roots).not.toContain('oauth');
});
test('recursive grep with no operand scans the whole tree', () => {
@@ -96,14 +98,15 @@ describe('deriveScanRoots', () => {
});
test('find roots are the leading non-flag args; glob predicates are skipped', () => {
- expect(deriveScanRoots([stage('find', 'specs', '-name', '*.md')])).toEqual(['specs']);
+ const roots = deriveScanRoots([stage('find', 'specs', '-name', '*.md')]);
+ expect(roots).toContain('specs');
+ expect(roots).not.toContain('*.md');
});
test('find literal predicate values stay watched', () => {
- expect(deriveScanRoots([stage('find', 'specs', '-newer', 'ref.md')]).sort()).toEqual([
- 'ref.md',
- 'specs',
- ]);
+ expect(deriveScanRoots([stage('find', 'specs', '-newer', 'ref.md')])).toEqual(
+ expect.arrayContaining(['ref.md', 'specs']),
+ );
});
test('find with no path root scans the whole tree', () => {
@@ -119,9 +122,9 @@ describe('deriveScanRoots', () => {
});
test('glob-bearing attached flag values are match patterns, not paths', () => {
- expect(deriveScanRoots([stage('grep', '-rn', '--include=*.md', 'oauth', 'articles/')])).toEqual(
- ['articles/'],
- );
+ const roots = deriveScanRoots([stage('grep', '-rn', '--include=*.md', 'oauth', 'articles/')]);
+ expect(roots).toContain('articles/');
+ expect(roots).not.toContain('*.md');
});
test('literal attached flag values are watched as candidate write targets', () => {
@@ -287,3 +290,29 @@ describe('diffMtimes', () => {
}
});
});
+
+describe('deriveScanRoots — over-inclusion is the correct bias for a detective layer', () => {
+ test('an extension-less attached write target is still watched', () => {
+ expect(deriveScanRoots([stage('sort', '--out=notes', 'other.md')])).toContain('notes');
+ expect(deriveScanRoots([stage('sort', '-onotes', 'other.md')])).toContain('notes');
+ });
+
+ test('a delimiter argument never becomes a scan root', () => {
+ expect(deriveScanRoots([stage('cut', '-d.', '-f1', 'other.md')])).not.toContain('.');
+ expect(deriveScanRoots([stage('sort', '-t.', 'other.md')])).not.toContain('.');
+ expect(deriveScanRoots([stage('cut', '-d/', '-f1', 'other.md')])).not.toContain('/');
+ });
+
+ test('the scan base is what resolveWithinRoot turns into the whole-tree sentinel', () => {
+ expect(SCAN_WHOLE_TREE).toBe('');
+ expect(deriveScanRoots([stage('cut', '-d.', '-f1', 'other.md')])).toContain('other.md');
+ });
+});
+
+describe('deriveScanRoots — a match-pattern flag value is not a path', () => {
+ test('an exclude-dir value does not become a root the sweep then walks', () => {
+ const roots = deriveScanRoots([stage('grep', '-rn', '--exclude-dir=node_modules', 'x', 'a/')]);
+ expect(roots).toContain('a/');
+ expect(roots).not.toContain('node_modules');
+ });
+});
diff --git a/packages/server/src/bash/mtime-scan.ts b/packages/server/src/bash/mtime-scan.ts
index 8c5015639..35c791cec 100644
--- a/packages/server/src/bash/mtime-scan.ts
+++ b/packages/server/src/bash/mtime-scan.ts
@@ -36,6 +36,23 @@ function literalDirPrefix(token: string): string {
return slash >= 0 ? head.slice(0, slash) : SCAN_WHOLE_TREE;
}
+const NON_PATH_VALUE_FLAGS: ReadonlySet<string> = new Set([
+ '--exclude',
+ '--exclude-dir',
+ '--include',
+ '--regexp',
+]);
+
+function isScanBase(value: string): boolean {
+ const trimmed = value.trim().replace(/\/+$/, '');
+ return trimmed === '' || trimmed === '.';
+}
+
+function carriesPathValue(arg: string): boolean {
+ const name = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
+ return !NON_PATH_VALUE_FLAGS.has(name);
+}
+
export function deriveScanRoots(stages: Stage[]): string[] {
const roots = new Set<string>();
for (const stage of stages) {
@@ -83,9 +100,9 @@ export function deriveScanRoots(stages: Stage[]): string[] {
candidates = positional;
}
const attached = args
- .filter((a) => a.startsWith('-') && a.includes('='))
- .map((a) => a.slice(a.indexOf('=') + 1))
- .filter((v) => v.length > 0 && !GLOB_RE.test(v));
+ .filter((a) => a.startsWith('-') && a.length > 2 && carriesPathValue(a))
+ .map((a) => (a.includes('=') ? a.slice(a.indexOf('=') + 1) : a.slice(2)))
+ .filter((v) => v.length > 0 && !GLOB_RE.test(v) && !isScanBase(v));
for (const c of [...candidates, ...attached]) {
roots.add(GLOB_RE.test(c) ? literalDirPrefix(c) : c);
}
diff --git a/packages/server/src/bash/parse-command.ts b/packages/server/src/bash/parse-command.ts
index cf0725f81..78e7fa1eb 100644
--- a/packages/server/src/bash/parse-command.ts
+++ b/packages/server/src/bash/parse-command.ts
@@ -134,7 +134,8 @@ const SHELL_CONSTRUCT_OPS: ReadonlySet<string> = new Set([
]);
const UNIVERSAL_FLAG_DENY: ReadonlySet<string> = new Set(['-o', '--output-file', '--output']);
-const UNIVERSAL_FLAG_PREFIX_DENY = ['-o=', '--output-file=', '--output='];
+const UNIVERSAL_FLAG_PREFIX_DENY = ['--output-file=', '--output='];
+const SORT_OUTPUT_FLAG_RE = /^-[a-zA-Z]*o/;
const FIND_FLAG_DENY: ReadonlySet<string> = new Set([
'-exec',
@@ -143,6 +144,7 @@ const FIND_FLAG_DENY: ReadonlySet<string> = new Set([
'-fprint',
'-fprintf',
'-fprint0',
+ '-fls',
'-ok',
'-okdir',
]);
@@ -225,7 +227,11 @@ function checkStage(stage: Stage): ParseCommandError | null {
};
}
for (const arg of stage.args.slice(1)) {
- if (UNIVERSAL_FLAG_DENY.has(arg) || UNIVERSAL_FLAG_PREFIX_DENY.some((p) => arg.startsWith(p))) {
+ if (
+ UNIVERSAL_FLAG_DENY.has(arg) ||
+ UNIVERSAL_FLAG_PREFIX_DENY.some((p) => arg.startsWith(p)) ||
+ (stage.command === 'sort' && SORT_OUTPUT_FLAG_RE.test(arg))
+ ) {
return {
category: 'write_blocked',
message: `Write operation blocked: '${arg}'. exec is read-only. For document changes, use the \`write\` or \`edit\` tool.`,
diff --git a/packages/server/src/bash/read-only-contract.test.ts b/packages/server/src/bash/read-only-contract.test.ts
new file mode 100644
index 000000000..e23cff0ed
--- /dev/null
+++ b/packages/server/src/bash/read-only-contract.test.ts
@@ -0,0 +1,189 @@
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative } from 'node:path';
+import { afterAll, describe, expect, test } from 'vitest';
+import { createBashInstance, execBash } from './index.ts';
+import { deriveScanRoots } from './mtime-scan.ts';
+import { augmentStagesWithExcludes, parseCommand, serializeStages } from './parse-command.ts';
+
+const built: string[] = [];
+afterAll(() => {
+ for (const dir of built) rmSync(dir, { recursive: true, force: true });
+});
+
+function build(): string {
+ const root = mkdtempSync(join(tmpdir(), 'read-only-contract-'));
+ built.push(root);
+ mkdirSync(join(root, 'specs'));
+ writeFileSync(join(root, 'important.md'), '# Important\nDo not lose this\n');
+ writeFileSync(join(root, 'other.md'), 'zzz\naaa\n');
+ writeFileSync(join(root, 'specs/one.md'), 'ONE\n');
+ writeFileSync(join(root, '-delete'), 'flag-shaped filename\n');
+ return root;
+}
+
+function snapshot(dir: string, root = dir): string[] {
+ return readdirSync(dir, { withFileTypes: true })
+ .flatMap((entry) => {
+ const full = join(dir, entry.name);
+ return entry.isDirectory()
+ ? snapshot(full, root)
+ : [`${relative(root, full)}=${readFileSync(full, 'utf8')}`];
+ })
+ .sort();
+}
+
+type Disposition = 'parse-blocked' | 'ran' | 'exec-threw';
+
+interface Attempt {
+ command: string;
+ expect: Disposition;
+ category?: string;
+}
+
+async function attempt(
+ root: string,
+ command: string,
+): Promise<{ disposition: Disposition; category?: string }> {
+ const parsed = parseCommand(command);
+ if ('error' in parsed) return { disposition: 'parse-blocked', category: parsed.error.category };
+ try {
+ const effective = serializeStages(augmentStagesWithExcludes(parsed.stages));
+ await execBash(createBashInstance(root), effective);
+ return { disposition: 'ran' };
+ } catch {
+ return { disposition: 'exec-threw' };
+ }
+}
+
+const WRITE_ATTEMPTS: Attempt[] = [
+ { command: 'sort -o important.md other.md', expect: 'parse-blocked', category: 'write_blocked' },
+ {
+ command: 'sort --output important.md other.md',
+ expect: 'parse-blocked',
+ category: 'write_blocked',
+ },
+ {
+ command: 'sort --output-file important.md other.md',
+ expect: 'parse-blocked',
+ category: 'write_blocked',
+ },
+ { command: 'sort -o=important.md other.md', expect: 'parse-blocked', category: 'write_blocked' },
+ { command: 'sort -oimportant.md other.md', expect: 'parse-blocked', category: 'write_blocked' },
+ {
+ command: 'sort -r -o important.md other.md',
+ expect: 'parse-blocked',
+ category: 'write_blocked',
+ },
+ { command: 'sort -ro important.md other.md', expect: 'parse-blocked', category: 'write_blocked' },
+ {
+ command: 'sort -nro important.md other.md',
+ expect: 'parse-blocked',
+ category: 'write_blocked',
+ },
+ { command: 'sort -uo important.md other.md', expect: 'parse-blocked', category: 'write_blocked' },
+ {
+ command: 'sort -o important.md -r other.md',
+ expect: 'parse-blocked',
+ category: 'write_blocked',
+ },
+ { command: 'find . -delete', expect: 'parse-blocked', category: 'write_blocked' },
+ { command: 'find . -name *.md -delete', expect: 'parse-blocked', category: 'write_blocked' },
+ { command: 'find . -exec rm {} +', expect: 'parse-blocked', category: 'write_blocked' },
+ { command: 'find . -execdir rm {} +', expect: 'parse-blocked', category: 'write_blocked' },
+ { command: 'find . -ok rm {} +', expect: 'parse-blocked', category: 'write_blocked' },
+ { command: 'find . -okdir rm {} +', expect: 'parse-blocked', category: 'write_blocked' },
+ { command: 'find . -fprint important.md', expect: 'parse-blocked', category: 'write_blocked' },
+ {
+ command: 'find . -fprintf important.md %p',
+ expect: 'parse-blocked',
+ category: 'write_blocked',
+ },
+ { command: 'find . -fls important.md', expect: 'parse-blocked', category: 'write_blocked' },
+ { command: 'find . -exec rm {} ;', expect: 'parse-blocked', category: 'shell_construct_blocked' },
+ {
+ command: 'find . -execdir rm {} ;',
+ expect: 'parse-blocked',
+ category: 'shell_construct_blocked',
+ },
+ { command: 'find . -ok rm {} ;', expect: 'parse-blocked', category: 'shell_construct_blocked' },
+ { command: 'cat other.md > important.md', expect: 'parse-blocked', category: 'write_blocked' },
+ { command: 'cat other.md >> important.md', expect: 'parse-blocked', category: 'write_blocked' },
+ {
+ command: 'cat other.md | tee important.md',
+ expect: 'parse-blocked',
+ category: 'unknown_command',
+ },
+ {
+ command: 'cut -f1 other.md -o important.md',
+ expect: 'parse-blocked',
+ category: 'write_blocked',
+ },
+ {
+ command: 'sort other.md `rm important.md`',
+ expect: 'parse-blocked',
+ category: 'shell_construct_blocked',
+ },
+ {
+ command: 'sort other.md $(rm important.md)',
+ expect: 'parse-blocked',
+ category: 'shell_construct_blocked',
+ },
+ { command: 'find {*,-delete}', expect: 'ran' },
+ { command: 'find {.,-delete}', expect: 'ran' },
+ { command: 'find *', expect: 'ran' },
+ { command: 'uniq other.md important.md', expect: 'ran' },
+];
+
+describe('exec is read-only — no allowlisted command may alter the tree', () => {
+ test.each(
+ WRITE_ATTEMPTS,
+ )('$command is refused at the layer that owns it and changes nothing', async ({
+ command,
+ expect: expected,
+ category,
+ }) => {
+ const root = build();
+ const before = snapshot(root);
+ const result = await attempt(root, command);
+ expect(result.disposition).toBe(expected);
+ if (category !== undefined) expect(result.category).toBe(category);
+ expect(snapshot(root)).toEqual(before);
+ });
+
+ test('the write guard and the mtime backstop read an attached value the same way', () => {
+ const roots = deriveScanRoots([{ command: 'sort', args: ['sort', '-onotes', 'other.md'] }]);
+ expect(roots).toContain('notes');
+ });
+
+ test('the corpus itself would register a change, so the assertion is not vacuous', () => {
+ const root = build();
+ const before = snapshot(root);
+ writeFileSync(join(root, 'important.md'), 'clobbered\n');
+ expect(snapshot(root)).not.toEqual(before);
+ });
+
+ test('a read-only command that names an output-shaped flag still works', () => {
+ const parsed = parseCommand('cut -f1 --output-delimiter=x other.md');
+ expect('error' in parsed).toBe(false);
+ });
+});
+
+describe('the write guard does not reach commands whose -o only reads', () => {
+ test.each([
+ 'grep -oE PRD-[0-9]+ other.md',
+ 'grep -on needle other.md',
+ 'grep -orn needle .',
+ 'grep -oh needle other.md',
+ 'find . -name a.md -or -name b.md',
+ 'cut -f1 --output-delimiter=x other.md',
+ 'sort -r other.md',
+ 'sort -n other.md',
+ ])('%s parses', (command) => {
+ const parsed = parseCommand(command);
+ if ('error' in parsed) {
+ throw new Error(`expected '${command}' to parse, got: ${parsed.error.message}`);
+ }
+ expect('error' in parsed).toBe(false);
+ });
+});