Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(cli): exclude declared sensitive values from parser diagnostics (#6258)

Kaoru0822c083fedaf4bb
diff --git a/src/cli.ts b/src/cli.ts
index b987af093..c0869e502 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -58,6 +58,7 @@ import {
} from "./cli/cliResultOutput.js";
import { registerReverseEngineeringCommands } from "./cli/reverseEngineeringCommands.js";
import { registerCutterCommands } from "./cli/cutterCommands.js";
+import { excludeDeclaredSensitiveArguments } from "./cli/explicitSensitiveArguments.js";
export { closeCliJavaScriptResources } from "./cli/javascriptApplicationAnalysis.js";
@@ -169,8 +170,9 @@ export const createCli = (
registerApplicationCommands(cli, logger);
presentOmittableDefaults(cli);
if (resultOutput !== undefined) streamCliCommandResults(cli, resultOutput);
+ const serveDeclared = excludeDeclaredSensitiveArguments(cli);
const serve = cli.serve.bind(cli);
cli.serve = (arguments_ = process.argv.slice(2), options) =>
- serve(normalizeCliArguments(arguments_), options);
+ serveDeclared(normalizeCliArguments(arguments_), options ?? {}, serve);
return cli;
};
diff --git a/src/cli/explicitSensitiveArguments.ts b/src/cli/explicitSensitiveArguments.ts
new file mode 100644
index 000000000..fefef3cff
--- /dev/null
+++ b/src/cli/explicitSensitiveArguments.ts
@@ -0,0 +1,183 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import { Errors, Formatter, z, type MiddlewareHandler } from "incur";
+
+import {
+ cliOutputValueRejection,
+ splitIncurBuiltinArguments,
+ type IncurBuiltinArgumentSplit,
+} from "../cliOutput.js";
+import { redactExplicitText } from "../domain/explicitSensitiveValues.js";
+import type { CliInstance } from "./types.js";
+import { visitRegisteredCommands } from "./visitRegisteredCommands.js";
+
+/** Repeatable option whose literals the command and its CLI diagnostics exclude. */
+export const explicitSensitiveValueOptions = {
+ sensitiveValue: z
+ .array(z.string().min(1))
+ .default([])
+ .describe(
+ "Literal string values explicitly marked sensitive; repeat as needed",
+ ),
+};
+
+const OPTION =
+ "sensitiveValue" satisfies keyof typeof explicitSensitiveValueOptions;
+/** Incur accepts the schema key and its kebab-case spelling. */
+const FLAGS = ["--sensitive-value", "--sensitiveValue"] as const;
+
+/**
+ * Read declarations from the tokens Incur leaves for command parsing. Incur
+ * rejects a malformed token before it reaches later declarations, so this scan
+ * is independent of parse success. A token following a declaration flag counts
+ * as declared even where the command parser would bind it to another option.
+ */
+const declaredSensitiveValues = (
+ command: IncurBuiltinArgumentSplit["command"],
+): readonly string[] => {
+ const values = new Set<string>();
+ for (let index = 0; index < command.length; index += 1) {
+ const token = command[index]!;
+ const flag = FLAGS.find(
+ (candidate) => token === candidate || token.startsWith(`${candidate}=`),
+ );
+ if (flag === undefined) continue;
+ if (token !== flag) values.add(token.slice(flag.length + 1));
+ else if (index + 1 < command.length) {
+ values.add(command[index + 1]!);
+ index += 1;
+ }
+ }
+ values.delete("");
+ return [...values];
+};
+
+type ServeOptions = NonNullable<Parameters<CliInstance["serve"]>[1]>;
+
+/**
+ * Incur rejects an output value in its builtin pass, before command resolution
+ * and outside any middleware, then renders the message it built. Report that
+ * same first rejection here so the whole message follows the declarations,
+ * as parser failures do; the code and Incur's rendering stay unchanged. It
+ * precedes command resolution, so declarations apply whichever command follows.
+ */
+const reportDeclaredOutputRejection = (
+ arguments_: readonly string[],
+ outputValues: IncurBuiltinArgumentSplit["outputValues"],
+ values: readonly string[],
+ options: ServeOptions,
+): boolean => {
+ const rejection = outputValues
+ .map(({ flag, index }) => cliOutputValueRejection(flag, arguments_[index]!))
+ .find((message) => message !== undefined);
+ if (rejection === undefined) return false;
+ const error = {
+ code: "UNKNOWN",
+ message: redactExplicitText(rejection, values),
+ };
+ // Incur has not seen --format or --json yet, so only a TTY selects prose.
+ const output =
+ process.stdout.isTTY === true
+ ? `Error: ${error.message}`
+ : Formatter.format(error, "toon");
+ (options.stdout ?? ((text: string) => process.stdout.write(text)))(
+ output.endsWith("\n") ? output : `${output}\n`,
+ );
+ (options.exit ?? ((code: number) => process.exit(code)))(1);
+ return true;
+};
+
+/** Keep the thrown type, code and exit status; exclude declared literals from text. */
+const withoutDeclaredText = (
+ error: unknown,
+ values: readonly string[],
+): unknown => {
+ const text = (value: string): string => redactExplicitText(value, values);
+ if (!(error instanceof Error)) {
+ const description = String(error);
+ return text(description) === description ? error : text(description);
+ }
+ const message = text(error.message);
+ if (error instanceof Errors.ValidationError) {
+ // Paths and expectations name the command's own schema.
+ const fieldErrors = error.fieldErrors.map((field) => ({
+ ...field,
+ received: text(field.received),
+ message: text(field.message),
+ }));
+ return message === error.message &&
+ fieldErrors.every(
+ (field, index) =>
+ field.received === error.fieldErrors[index]!.received &&
+ field.message === error.fieldErrors[index]!.message,
+ )
+ ? error
+ : new Errors.ValidationError({ message, fieldErrors });
+ }
+ if (error instanceof Errors.IncurError) {
+ const hint = error.hint === undefined ? undefined : text(error.hint);
+ return message === error.message && hint === error.hint
+ ? error
+ : new Errors.IncurError({
+ code: error.code,
+ message,
+ ...(hint === undefined ? {} : { hint }),
+ retryable: error.retryable,
+ ...(error.exitCode === undefined ? {} : { exitCode: error.exitCode }),
+ });
+ }
+ if (message === error.message) return error;
+ return error instanceof Errors.ParseError
+ ? new Errors.ParseError({ message })
+ : new Error(message);
+};
+
+/**
+ * Apply `--sensitive-value` declarations to diagnostics produced before the
+ * command's own service sees them: rejected output values and the parse,
+ * validation and thrown failures of every command that accepts the option.
+ * Diagnostic text is redacted whole; codes, keys and rendering stay intact.
+ * Returns the serve step; command results keep their own redaction owners.
+ */
+export const excludeDeclaredSensitiveArguments = (
+ cli: CliInstance,
+): ((
+ arguments_: readonly string[],
+ options: ServeOptions,
+ serve: (arguments_: string[], options: ServeOptions) => Promise<void>,
+) => Promise<void>) => {
+ const declarations = new AsyncLocalStorage<readonly string[]>();
+ const excludeFromFailures: MiddlewareHandler = async (_context, next) => {
+ const values = declarations.getStore();
+ if (values === undefined) return next();
+ try {
+ await next();
+ } catch (error) {
+ throw withoutDeclaredText(error, values);
+ }
+ };
+ visitRegisteredCommands(cli, (command) => {
+ if (
+ command.options instanceof z.ZodObject &&
+ Object.hasOwn(command.options.shape, OPTION)
+ )
+ // Outermost, so later command middleware failures are covered as well
+ // as the parsing and run that Incur executes inside the chain.
+ command.middleware = [excludeFromFailures, ...(command.middleware ?? [])];
+ });
+ return async (arguments_, options, serve) => {
+ const split = splitIncurBuiltinArguments(arguments_);
+ const values = declaredSensitiveValues(split.command);
+ if (values.length === 0) return serve([...arguments_], options);
+ if (
+ reportDeclaredOutputRejection(
+ arguments_,
+ split.outputValues,
+ values,
+ options,
+ )
+ )
+ return;
+ return declarations.run(values, () => serve([...arguments_], options));
+ };
+};
diff --git a/src/cli/webNetworkCaptureCommands.ts b/src/cli/webNetworkCaptureCommands.ts
index 7d3f14042..5a3d82b96 100644
--- a/src/cli/webNetworkCaptureCommands.ts
+++ b/src/cli/webNetworkCaptureCommands.ts
@@ -15,6 +15,7 @@ import {
deliverCliAnalysisEvidence,
} from "./analysisEvidenceDelivery.js";
import { absoluteCallerPath } from "../filesystem/callerPath.js";
+import { explicitSensitiveValueOptions } from "./explicitSensitiveArguments.js";
/** Expose offline historical capture inspection with the same selection contract as MCP. */
export const registerWebNetworkCaptureCommands = (
@@ -54,12 +55,7 @@ export const registerWebNetworkCaptureCommands = (
.array(cliIntegerArgument(0))
.optional()
.describe("Zero-based producer ordinals; repeat to select several"),
- sensitiveValue: z
- .array(z.string().min(1))
- .default([])
- .describe(
- "Literal string values explicitly marked sensitive; repeat as needed",
- ),
+ ...explicitSensitiveValueOptions,
captureTimeoutMs:
inspectWebNetworkCaptureInputSchema.shape.capture_timeout_ms,
}),
diff --git a/src/cliOutput.ts b/src/cliOutput.ts
index 226d0be5d..d505d85c3 100644
--- a/src/cliOutput.ts
+++ b/src/cliOutput.ts
@@ -17,6 +17,82 @@ const ROOT_UPDATE_OUTPUT_FLAGS = new Set([
"--token-count",
]);
+/** Valueless flags Incur removes from every position before command parsing. */
+const INCUR_BUILTIN_FLAGS = new Set([
+ "--full-output",
+ "--llms",
+ "--llms-full",
+ "--mcp",
+ "--help",
+ "-h",
+ "--update",
+ // Incur's internal update-check flag.
+ "--incur-update-check",
+ "--schema",
+ "--json",
+ "--token-count",
+]);
+
+/**
+ * Incur's message when its builtin pass rejects this spaced value of a valued
+ * output flag, or undefined when Incur accepts it.
+ */
+export const cliOutputValueRejection = (
+ flag: string,
+ value: string,
+): string | undefined => {
+ if (flag === "--format")
+ return INCUR_OUTPUT_FORMATS.has(value)
+ ? undefined
+ : `Invalid format: "${value}". Expected one of: ${[...INCUR_OUTPUT_FORMATS].join(", ")}`;
+ if (
+ (flag === "--token-limit" || flag === "--token-offset") &&
+ (!Number.isFinite(Number(value)) || value.trim() === "")
+ )
+ return `Invalid value for ${flag}: "${value}"`;
+ return undefined;
+};
+
+/** Command tokens and output-flag values as Incur's builtin pass assigns them. */
+export interface IncurBuiltinArgumentSplit {
+ /** Tokens left for command resolution and command option parsing. */
+ readonly command: readonly string[];
+ /** Positions of nonempty values consumed by valued output flags. */
+ readonly outputValues: readonly {
+ readonly flag: string;
+ readonly index: number;
+ }[];
+}
+
+/**
+ * Mirror Incur's builtin pass over normalized arguments without stopping at a
+ * rejected value, so callers can still see every later token. REA configures
+ * neither a config flag nor global options, which Incur would also remove.
+ */
+export const splitIncurBuiltinArguments = (
+ arguments_: readonly string[],
+): IncurBuiltinArgumentSplit => {
+ const command: string[] = [];
+ const outputValues: { readonly flag: string; readonly index: number }[] = [];
+ for (let index = 0; index < arguments_.length; index += 1) {
+ const argument = arguments_[index]!;
+ const next = arguments_[index + 1];
+ if (
+ INCUR_BUILTIN_FLAGS.has(argument) ||
+ // A following value belongs to a command-local `--version` option.
+ (argument === "--version" && (next === undefined || next.startsWith("-")))
+ )
+ continue;
+ if (VALUED_OUTPUT_FLAGS.has(argument) && next) {
+ outputValues.push({ flag: argument, index: index + 1 });
+ index += 1;
+ continue;
+ }
+ command.push(argument);
+ }
+ return { command, outputValues };
+};
+
/**
* Route the root update alias and split `--flag=value` output forms. Incur reads these
* flags only in spaced form, so `--format=json` otherwise reaches the command
@@ -115,7 +191,8 @@ export const parseCliOutputArguments = (
if (value) {
// Incur stops parsing at an invalid format before applying any later
// output controls. Let it report that malformed flag itself.
- if (!INCUR_OUTPUT_FORMATS.has(value)) return parsed(true);
+ if (cliOutputValueRejection(argument, value) !== undefined)
+ return parsed(true);
format = value;
index += 1;
} else missingValue ??= argument;
@@ -131,9 +208,9 @@ export const parseCliOutputArguments = (
if (argument === "--token-limit" || argument === "--token-offset") {
const value = arguments_[index + 1];
if (value) {
- const numericValue = Number(value);
- if (!Number.isFinite(numericValue) || value.trim() === "")
+ if (cliOutputValueRejection(argument, value) !== undefined)
return parsed(true);
+ const numericValue = Number(value);
if (argument === "--token-limit") tokenLimit = numericValue;
else tokenOffset = numericValue;
index += 1;
diff --git a/tests/boundary/cli/explicitSensitiveArgumentsCli.test.ts b/tests/boundary/cli/explicitSensitiveArgumentsCli.test.ts
new file mode 100644
index 000000000..cd3432761
--- /dev/null
+++ b/tests/boundary/cli/explicitSensitiveArgumentsCli.test.ts
@@ -0,0 +1,271 @@
+import { describe, expect } from "vitest";
+
+import { cliTest, type CliResult } from "../../support/cli/cliFixture.js";
+
+const LITERAL = "SYNTHETIC_CAPTURE_LITERAL_83A4";
+const CAPTURE = ["inspect-web-network-capture", "/nonexistent/capture.har"];
+const DECLARED = [...CAPTURE, "har", "--sensitive-value", LITERAL];
+
+const expectExcluded = (
+ result: CliResult,
+ literals: readonly string[] = [LITERAL],
+): void => {
+ expect(result.exitCode).toBe(1);
+ for (const literal of literals) {
+ expect(result.stdout).not.toContain(literal);
+ expect(result.stderr).not.toContain(literal);
+ }
+};
+
+describe("CLI --sensitive-value parser diagnostics", () => {
+ cliTest.for([
+ {
+ name: "negated unknown flag",
+ arguments: [...DECLARED, `--no-unknown-option=${LITERAL}`],
+ message: "Unknown flag: --no-unknown-option=[REDACTED]",
+ },
+ {
+ name: "unknown flag name",
+ arguments: [...DECLARED, `--${LITERAL}`],
+ message: "Unknown flag: --[REDACTED]",
+ },
+ {
+ name: "declaration after the rejected token",
+ arguments: [
+ ...CAPTURE,
+ "har",
+ `--no-${LITERAL}`,
+ `--sensitive-value=${LITERAL}`,
+ ],
+ message: "Unknown flag: --no-[REDACTED]",
+ },
+ {
+ name: "camel-case declaration",
+ arguments: [
+ ...CAPTURE,
+ "har",
+ `--sensitiveValue=${LITERAL}`,
+ `--no-${LITERAL}`,
+ ],
+ message: "Unknown flag: --no-[REDACTED]",
+ },
+ {
+ // Incur removes builtin output flags before reading the declared value.
+ name: "builtin flag before the declared value",
+ arguments: [
+ ...CAPTURE,
+ "har",
+ "--sensitive-value",
+ "--json",
+ LITERAL,
+ `--no-${LITERAL}`,
+ ],
+ message: "Unknown flag: --no-[REDACTED]",
+ },
+ ])(
+ "excludes declarations from a JSON $name rejection",
+ async ({ arguments: arguments_, message }, { cli }) => {
+ const result = await cli.run({ arguments: [...arguments_, "--json"] });
+
+ expectExcluded(result);
+ expect(JSON.parse(result.stdout)).toEqual({ code: "UNKNOWN", message });
+ },
+ );
+
+ cliTest(
+ "redacts fixed parser text but keeps JSON keys and codes",
+ async ({ cli }) => {
+ const result = await cli.run({
+ arguments: [
+ ...CAPTURE,
+ "har",
+ ...["flag", "code", "UNKNOWN"].flatMap((literal) => [
+ "--sensitive-value",
+ literal,
+ ]),
+ "--no-x",
+ "--json",
+ ],
+ });
+
+ expect(result.exitCode).toBe(1);
+ expect(JSON.parse(result.stdout)).toEqual({
+ code: "UNKNOWN",
+ message: "Unknown [REDACTED]: --no-x",
+ });
+ },
+ );
+
+ cliTest(
+ "excludes declarations from validation text while keeping field errors",
+ async ({ cli }) => {
+ const result = await cli.run({
+ arguments: [
+ ...CAPTURE,
+ "bogus",
+ "--sensitive-value",
+ "mitmproxy",
+ "--json",
+ ],
+ });
+
+ expectExcluded(result, ["mitmproxy"]);
+ expect(JSON.parse(result.stdout)).toMatchObject({
+ code: "VALIDATION_ERROR",
+ message: expect.stringContaining('"har"|"[REDACTED]"|"saz"'),
+ fieldErrors: [
+ expect.objectContaining({ code: "invalid_value", path: "format" }),
+ ],
+ });
+ },
+ );
+
+ cliTest(
+ "retains undeclared tokens and declared values that the parser accepts",
+ async ({ cli }) => {
+ const undeclared = await cli.run({
+ arguments: [...CAPTURE, "har", `--no-${LITERAL}`, "--json"],
+ });
+ expect(undeclared.exitCode).toBe(1);
+ expect(JSON.parse(undeclared.stdout)).toEqual({
+ code: "UNKNOWN",
+ message: `Unknown flag: --no-${LITERAL}`,
+ });
+
+ // An accepted output value is honored, so the service failure is JSON.
+ const accepted = await cli.run({
+ arguments: [
+ ...CAPTURE,
+ "har",
+ "--sensitive-value",
+ "json",
+ "--format",
+ "json",
+ ],
+ });
+ expect(accepted.exitCode).toBe(1);
+ expect(JSON.parse(accepted.stdout)).toMatchObject({
+ code: "invalid_request",
+ });
+ },
+ );
+});
+
+describe("CLI --sensitive-value output-value diagnostics", () => {
+ cliTest.for([
+ {
+ name: "a spaced --format value",
+ arguments: [...DECLARED, "--format", LITERAL],
+ message: 'Invalid format: \\"[REDACTED]\\"',
+ },
+ {
+ name: "an equals-form --format value",
+ arguments: [...DECLARED, `--format=${LITERAL}`],
+ message: 'Invalid format: \\"[REDACTED]\\"',
+ },
+ {
+ name: "a --token-limit value",
+ arguments: [...DECLARED, "--token-limit", LITERAL],
+ message: 'Invalid value for --token-limit: \\"[REDACTED]\\"',
+ },
+ {
+ name: "a partially declared --token-offset value",
+ arguments: [...DECLARED, "--token-offset", `1${LITERAL}`],
+ message: 'Invalid value for --token-offset: \\"1[REDACTED]\\"',
+ },
+ ])(
+ "keeps rejecting $name without the declaration",
+ async ({ arguments: arguments_, message }, { cli }) => {
+ const result = await cli.run({ arguments: arguments_ });
+
+ expectExcluded(result);
+ expect(result.stdout).toContain(`code: UNKNOWN\nmessage: "${message}`);
+ },
+ );
+
+ cliTest(
+ "rejects an output value that would be accepted once declarations are removed",
+ async ({ cli }) => {
+ const declared = ["X", "[REDACTED]", "…"];
+ const result = await cli.run({
+ arguments: [
+ ...CAPTURE,
+ "har",
+ ...declared.flatMap((literal) => ["--sensitive-value", literal]),
+ "--token-limit",
+ "12X",
+ ],
+ });
+
+ expectExcluded(result, declared);
+ expect(result.stdout).toContain("Invalid value for --token-limit:");
+ },
+ );
+
+ cliTest.for([
+ {
+ name: "flag-name and value",
+ declared: ["token"],
+ arguments: ["--token-limit", "token"],
+ message: 'Invalid value for --[REDACTED]-limit: \\"[REDACTED]\\"',
+ },
+ {
+ name: "overlapping",
+ declared: ["tok", "token"],
+ arguments: ["--token-offset", "token1"],
+ message: 'Invalid value for --[REDACTED]-offset: \\"[REDACTED]1\\"',
+ },
+ {
+ name: "fixed-text",
+ declared: ["Invalid", "Expected"],
+ arguments: ["--format", "bogus"],
+ message:
+ '[REDACTED] format: \\"bogus\\". [REDACTED] one of: toon, json, yaml, md, jsonl',
+ },
+ {
+ // Codes and keys identify the contract, not caller text.
+ name: "code and key",
+ declared: ["UNKNOWN", "code", "message"],
+ arguments: ["--format", "bogus"],
+ message:
+ 'Invalid format: \\"bogus\\". Expected one of: toon, json, yaml, md, jsonl',
+ },
+ ])(
+ "redacts the whole rejected output message for $name declarations",
+ async ({ declared, arguments: arguments_, message }, { cli }) => {
+ const result = await cli.run({
+ arguments: [
+ ...CAPTURE,
+ "har",
+ ...declared.flatMap((literal) => ["--sensitive-value", literal]),
+ ...arguments_,
+ ],
+ });
+
+ expect(result.exitCode).toBe(1);
+ expect(result.stdout).toBe(`code: UNKNOWN\nmessage: "${message}"\n`);
+ },
+ );
+
+ cliTest.for([
+ ["--format", "bogus"],
+ ["--token-limit=x"],
+ ["--token-offset", " "],
+ ])(
+ "renders %s rejections exactly as Incur does without declarations",
+ async (arguments_, { cli }) => {
+ const command = [...CAPTURE, "har", ...arguments_];
+ const incur = await cli.run({ arguments: command });
+ const declared = await cli.run({
+ arguments: [...command, "--sensitive-value", "unused"],
+ });
+
+ expect(incur.exitCode).toBe(1);
+ expect(declared).toMatchObject({
+ exitCode: incur.exitCode,
+ stdout: incur.stdout,
+ stderr: incur.stderr,
+ });
+ },
+ );
+});