Skip to content

Commit e9689f0

Browse files
committed
Add trusted file scanning and the scan-cost baseline
scanFiles clears every file under a candidate directory with the execution's scanner, so a future Workflow snapshot is held to exactly the rules its journal was. Reads go straight to @effectionx/fs rather than the runtime Fs Context Api. That Api exists so a document can be given a stubbed or sandboxed filesystem, and its middleware is reachable from inside an execution — routing a security scan through it would let the thing being inspected choose what the inspector sees. A test installs hostile middleware, confirms an ordinary read is blinded by it, and proves the trusted scan still finds the credential. The baseline records per-scan cost rather than gating on it: a throughput threshold measured on a laptop and enforced on a shared runner is a flaky test, not a guarantee. Refs #199
1 parent dc77a1e commit e9689f0

4 files changed

Lines changed: 226 additions & 0 deletions

File tree

‎packages/core/mod.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,3 +146,5 @@ export { createSecretScanner } from "./src/secrets/scanner.ts";
146146
export type { SecretScanner } from "./src/secrets/scanner.ts";
147147
export { SecretDetectedError, SecretScannerError } from "./src/secrets/findings.ts";
148148
export type { SecretFinding } from "./src/secrets/findings.ts";
149+
export { scanFiles } from "./src/secrets/files.ts";
150+
export type { FileSecretFinding } from "./src/secrets/files.ts";

‎packages/core/src/secrets/files.ts‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
/**
2+
* Scanning candidate files with the execution's scanner.
3+
*
4+
* The Workflow snapshot path materializes candidate files under a scope-owned
5+
* temporary directory and must clear every one of them before any Git object
6+
* exists. It reuses the execution's scanner so a snapshot is held to exactly
7+
* the rules the journal was.
8+
*
9+
* Reads go straight to `@effectionx/fs` rather than through the runtime's
10+
* `Fs` Context Api. That Api exists so a document can be given a stubbed or
11+
* sandboxed filesystem, and its middleware is reachable from inside an
12+
* execution — routing a security scan through it would let the thing being
13+
* inspected choose what the inspector sees. A trusted scan reads the real
14+
* files.
15+
*/
16+
17+
import { each, type Operation } from "effection";
18+
import { readTextFile, walk } from "@effectionx/fs";
19+
import type { SecretFinding } from "./findings.ts";
20+
import type { SecretScanner } from "./scanner.ts";
21+
22+
/** A finding together with the file it came from. */
23+
export interface FileSecretFinding extends SecretFinding {
24+
/** Path of the file the finding was found in. */
25+
path: string;
26+
}
27+
28+
/**
29+
* Scan every file under `root`, in memory, and return all findings.
30+
*
31+
* Returning findings rather than throwing on the first one lets the caller
32+
* report everything a snapshot would have leaked instead of one file at a
33+
* time. An empty result means the candidate is clear.
34+
*/
35+
export function* scanFiles(root: string, scanner: SecretScanner): Operation<FileSecretFinding[]> {
36+
const findings: FileSecretFinding[] = [];
37+
38+
for (const entry of yield* each(walk(root, { includeFiles: true, includeDirs: false }))) {
39+
const content = yield* readTextFile(entry.path);
40+
for (const finding of yield* scanner.scan(content)) {
41+
findings.push({ ...finding, path: entry.path });
42+
}
43+
yield* each.next();
44+
}
45+
46+
return findings;
47+
}
Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
/**
2+
* Trusted scanning of candidate snapshot files.
3+
*
4+
* The scan reads through `@effectionx/fs` directly rather than the runtime
5+
* `Fs` Context Api, so a document cannot decide what the inspector sees. One
6+
* test proves that by installing hostile middleware and checking the scan
7+
* still reads the real bytes.
8+
*/
9+
10+
import { describe, it } from "@executablemd/test-support/bdd";
11+
import { expect } from "@executablemd/test-support/expect";
12+
import { ensure } from "effection";
13+
import { ensureDir, rm, writeTextFile } from "@effectionx/fs";
14+
import * as fs from "node:fs";
15+
import * as os from "node:os";
16+
import * as path from "node:path";
17+
import { API } from "@executablemd/runtime";
18+
import { readTextFile } from "@executablemd/runtime";
19+
import type { Operation } from "effection";
20+
import { scanFiles } from "../src/secrets/files.ts";
21+
import { createSecretScanner } from "../src/secrets/scanner.ts";
22+
23+
const A = "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
24+
const CANARY = `ghp_${A.slice(0, 36)}`;
25+
26+
/**
27+
* `@effectionx/fs` has no temp-directory operation, so the one call that has
28+
* to reach past it is this. Everything else in these tests uses the library.
29+
*/
30+
function makeTmpDir(): string {
31+
return fs.mkdtempSync(path.join(os.tmpdir(), "xmd-secret-files-"));
32+
}
33+
34+
/** Middleware that hides file contents from anything reading through Fs. */
35+
function* useHostileFs(): Operation<void> {
36+
yield* API.Fs.around({
37+
// deno-lint-ignore require-yield
38+
*readTextFile() {
39+
return "nothing to see here";
40+
},
41+
// deno-lint-ignore require-yield
42+
*glob() {
43+
return [];
44+
},
45+
});
46+
}
47+
48+
describe("scanFiles", () => {
49+
it("clears a candidate whose every file is clean", function* () {
50+
const dir = makeTmpDir();
51+
yield* ensure(() => rm(dir, { recursive: true, force: true }));
52+
53+
yield* writeTextFile(path.join(dir, "journal.jsonl"), '{"type":"close","result":"ok"}\n');
54+
yield* writeTextFile(path.join(dir, "manifest.json"), '{"secretDetection":true}\n');
55+
56+
expect(yield* scanFiles(dir, createSecretScanner())).toEqual([]);
57+
});
58+
59+
it("reports the file a credential was found in", function* () {
60+
const dir = makeTmpDir();
61+
yield* ensure(() => rm(dir, { recursive: true, force: true }));
62+
63+
yield* ensureDir(path.join(dir, "artifacts"));
64+
yield* writeTextFile(path.join(dir, "journal.jsonl"), '{"type":"close"}\n');
65+
yield* writeTextFile(path.join(dir, "artifacts", "report.md"), `token: ${CANARY}\n`);
66+
67+
const findings = yield* scanFiles(dir, createSecretScanner());
68+
69+
expect(findings.length).toBeGreaterThan(0);
70+
expect(findings[0]!.path).toContain("report.md");
71+
expect(JSON.stringify(findings)).not.toContain(CANARY);
72+
});
73+
74+
it("reports every offending file rather than stopping at the first", function* () {
75+
const dir = makeTmpDir();
76+
yield* ensure(() => rm(dir, { recursive: true, force: true }));
77+
78+
yield* writeTextFile(path.join(dir, "one.txt"), `a: ${CANARY}\n`);
79+
yield* writeTextFile(path.join(dir, "two.txt"), `b: npm_${A.slice(0, 36)}\n`);
80+
81+
const paths = new Set((yield* scanFiles(dir, createSecretScanner())).map((f) => f.path));
82+
83+
expect(paths.size).toBe(2);
84+
});
85+
86+
it("reads the real file even when hostile Fs middleware is installed", function* () {
87+
const dir = makeTmpDir();
88+
yield* ensure(() => rm(dir, { recursive: true, force: true }));
89+
yield* writeTextFile(path.join(dir, "leak.txt"), `token: ${CANARY}\n`);
90+
91+
yield* useHostileFs();
92+
93+
// The middleware is in scope and does blind anything going through the
94+
// Fs Api — including this read, which is what a document's own code would
95+
// get.
96+
expect(yield* readTextFile(path.join(dir, "leak.txt"))).toBe("nothing to see here");
97+
98+
// The trusted scan bypasses that Api entirely, so it still finds the
99+
// credential a compromised or sandboxed document tried to conceal.
100+
const findings = yield* scanFiles(dir, createSecretScanner());
101+
102+
expect(findings.length).toBeGreaterThan(0);
103+
expect(findings[0]!.path).toContain("leak.txt");
104+
expect(JSON.stringify(findings)).not.toContain(CANARY);
105+
});
106+
});
Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
/**
2+
* Recorded scan cost.
3+
*
4+
* Default-on detection means every journal append pays for a scan, so the cost
5+
* is a property worth watching. This records it rather than gating on it: a
6+
* throughput threshold measured on a developer laptop and enforced on a shared
7+
* CI runner is a flaky test, not a performance guarantee.
8+
*
9+
* The guard here is only against a change that makes scanning pathological —
10+
* orders of magnitude, not percentages. Read the logged numbers to see drift.
11+
*/
12+
13+
import { describe, it } from "@executablemd/test-support/bdd";
14+
import { expect } from "@executablemd/test-support/expect";
15+
import type { Operation } from "effection";
16+
import { createSecretScanner } from "../src/secrets/scanner.ts";
17+
import type { SecretScanner } from "../src/secrets/scanner.ts";
18+
19+
/** A journal event of the size the great majority actually are. */
20+
const SMALL = JSON.stringify({
21+
type: "yield",
22+
coroutineId: "root.0",
23+
description: { type: "call", name: "stepA" },
24+
result: { status: "ok", value: "alpha" },
25+
});
26+
27+
/** An exec block that captured a large amount of process output. */
28+
const LARGE = JSON.stringify({
29+
type: "yield",
30+
coroutineId: "root.1",
31+
description: { type: "exec", name: "build" },
32+
result: { status: "ok", value: { stdout: "output line\n".repeat(16_000) } },
33+
});
34+
35+
function* measure(
36+
label: string,
37+
scanner: SecretScanner,
38+
content: string,
39+
runs: number,
40+
): Operation<number> {
41+
yield* scanner.scan(content); // warm the rule set before timing
42+
43+
const started = performance.now();
44+
for (let run = 0; run < runs; run++) {
45+
yield* scanner.scan(content);
46+
}
47+
const perScan = (performance.now() - started) / runs;
48+
49+
console.log(
50+
` ${label.padEnd(22)} ${perScan.toFixed(3)} ms/scan over ${runs} runs ` +
51+
`(${content.length} bytes)`,
52+
);
53+
return perScan;
54+
}
55+
56+
describe("secret scanning cost", () => {
57+
it("records the per-scan baseline for small and large events", function* () {
58+
const scanner = createSecretScanner();
59+
60+
const small = yield* measure("small event", scanner, SMALL, 200);
61+
const large = yield* measure("large event", scanner, LARGE, 20);
62+
63+
// Reference measurement, Deno 2.9.1 on an M-series laptop:
64+
// small event ~1.8 ms/scan (125 bytes)
65+
// large event ~4.2 ms/scan (200 KB)
66+
// Cost is dominated by fixed per-call overhead rather than content size,
67+
// so a 44-event journal pays well under a tenth of a second.
68+
expect(small).toBeLessThan(500);
69+
expect(large).toBeLessThan(2000);
70+
});
71+
});

0 commit comments

Comments
 (0)