Skip to content

Chrome DevTools for coding agents

feat: add --file-navigations flag to reject file: URL navigations (#2853)

J0xh-Sec54cae57bcfae
diff --git a/docs/configuration.md b/docs/configuration.md
index 05e8596b..822b9729 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -209,6 +209,11 @@ The Chrome DevTools MCP server supports the following configuration option:
- **Type:** boolean
- **Default:** `true`
+- **`--fileNavigations`/ `--file-navigations`**
+ Set to false to disallow navigating to file: URLs. When disabled, new_page, navigate_page and the slim navigate tool reject file: URLs, including view-source: URLs that target them. This restricts navigations the server performs. It is not a filesystem sandbox: it does not affect pages the browser already had open when the server connected, and the browser can reach the filesystem by other means. Use OS sandboxing for full filesystem confinement.
+ - **Type:** boolean
+ - **Default:** `true`
+
- **`--sourceMaps`/ `--source-maps`**
Whether to enable source maps in DevTools. Use --no-source-maps to disable.
- **Type:** boolean
diff --git a/src/config/mcp-options.ts b/src/config/mcp-options.ts
index dfe2d91d..3fe27886 100644
--- a/src/config/mcp-options.ts
+++ b/src/config/mcp-options.ts
@@ -131,6 +131,12 @@ export const mcpOptions = {
describe:
'Set to false to disable JavaScript execution. When disabled, evaluation tools (evaluate_script and slim evaluate) are disabled, the initScript parameter in navigate_page is turned off, and navigating to javascript:, data:, or vbscript: URLs is disallowed.',
},
+ fileNavigations: {
+ type: 'boolean',
+ default: true,
+ describe:
+ 'Set to false to disallow navigating to file: URLs. When disabled, new_page, navigate_page and the slim navigate tool reject file: URLs, including view-source: URLs that target them. This restricts navigations the server performs. It is not a filesystem sandbox: it does not affect pages the browser already had open when the server connected, and the browser can reach the filesystem by other means. Use OS sandboxing for full filesystem confinement.',
+ },
sourceMaps: {
type: 'boolean',
default: true,
diff --git a/src/telemetry/flag_usage_metrics.json b/src/telemetry/flag_usage_metrics.json
index 793cd997..948b7d94 100644
--- a/src/telemetry/flag_usage_metrics.json
+++ b/src/telemetry/flag_usage_metrics.json
@@ -457,5 +457,13 @@
{
"name": "devtools_comments",
"flagType": "boolean"
+ },
+ {
+ "name": "file_navigations_present",
+ "flagType": "boolean"
+ },
+ {
+ "name": "file_navigations",
+ "flagType": "boolean"
}
]
diff --git a/src/tools/pages.ts b/src/tools/pages.ts
index 50fdcc63..ec84c510 100644
--- a/src/tools/pages.ts
+++ b/src/tools/pages.ts
@@ -131,6 +131,7 @@ export const newPage = defineTool((args: ParsedArguments) => {
validateUrl(request.params.url, {
javascriptEvaluation: args?.javascriptEvaluation,
categoryExtensions: args?.categoryExtensions,
+ fileNavigations: args?.fileNavigations,
});
const page = await context.newPage(
@@ -211,6 +212,7 @@ export const navigatePage = definePageTool((args: ParsedArguments) => {
validateUrl(request.params.url, {
javascriptEvaluation: args?.javascriptEvaluation,
categoryExtensions: args?.categoryExtensions,
+ fileNavigations: args?.fileNavigations,
});
}
diff --git a/src/tools/slim/tools.ts b/src/tools/slim/tools.ts
index ed17ca38..6cab8652 100644
--- a/src/tools/slim/tools.ts
+++ b/src/tools/slim/tools.ts
@@ -55,6 +55,7 @@ export const navigate = definePageTool((args: ParsedArguments) => {
validateUrl(request.params.url, {
javascriptEvaluation: args?.javascriptEvaluation,
categoryExtensions: args?.categoryExtensions,
+ fileNavigations: args?.fileNavigations,
});
const page = request.page;
diff --git a/src/utils/url.ts b/src/utils/url.ts
index acdc7667..602c6c00 100644
--- a/src/utils/url.ts
+++ b/src/utils/url.ts
@@ -52,6 +52,7 @@ export function isLocalhost(url?: string): boolean {
export interface ValidateUrlOptions {
javascriptEvaluation: boolean | undefined;
categoryExtensions: boolean | undefined;
+ fileNavigations: boolean | undefined;
}
export interface IsAllowedUrlOptions {
@@ -139,17 +140,41 @@ export function findUnenforceablePattern(
return undefined;
}
+/**
+ * Reports whether a URL ultimately targets the `file:` scheme.
+ *
+ * `view-source:` wraps another URL and Chrome resolves the inner target, so
+ * `view-source:file:///etc/passwd` reads the file just as `file:///etc/passwd`
+ * does. The inner URL is re-parsed rather than string-matched so that an
+ * uppercase inner scheme (`view-source:FILE:///etc/passwd`) is normalised.
+ *
+ * @param url The already-parsed URL to inspect.
+ * @returns true if the URL, after unwrapping any `view-source:` prefixes, uses `file:`.
+ */
+function targetsFileScheme(url: URL): boolean {
+ let current = url;
+ // Bounded in case of a pathologically nested `view-source:` chain.
+ for (let i = 0; i < 5 && current.protocol === 'view-source:'; i++) {
+ try {
+ current = new URL(current.pathname);
+ } catch {
+ return false;
+ }
+ }
+ return current.protocol === 'file:';
+}
+
/**
* Validates a URL string by parsing it with `new URL` and checking for disallowed protocols and restricted schemes.
*
* @param url The URL string to validate.
- * @param options Options object containing javascriptEvaluation and categoryExtensions.
+ * @param options Options object containing javascriptEvaluation, categoryExtensions and fileNavigations.
* @returns The parsed URL.
* @throws Error if the URL does not parse with `new URL`, or if JavaScript evaluation is disabled and a disallowed URL is passed,
- * or if navigating to a restricted scheme.
+ * or if file navigations are disabled and a `file:` URL is passed, or if navigating to a restricted scheme.
*/
export function validateUrl(url: string, options: ValidateUrlOptions): URL {
- const {javascriptEvaluation, categoryExtensions} = options;
+ const {javascriptEvaluation, categoryExtensions, fileNavigations} = options;
let parsed: URL;
try {
@@ -169,6 +194,12 @@ export function validateUrl(url: string, options: ValidateUrlOptions): URL {
);
}
+ if (fileNavigations === false && targetsFileScheme(parsed)) {
+ throw new Error(
+ `Navigating to file: URLs is not allowed when --file-navigations is disabled.`,
+ );
+ }
+
if (!isAllowedUrl(url, {categoryExtensions})) {
if (parsed.protocol === 'chrome-extension:') {
throw new Error(
diff --git a/tests/cli.test.ts b/tests/cli.test.ts
index 14a4e3ad..9d0b589e 100644
--- a/tests/cli.test.ts
+++ b/tests/cli.test.ts
@@ -42,6 +42,7 @@ describe('cli args parsing', () => {
performanceCrux: true,
usageStatistics: true,
javascriptEvaluation: true,
+ fileNavigations: true,
redactNetworkHeaders: false,
allowUnrestrictedPaths: false,
filesystemRoot: DEFAULT_FILESYSTEM_ROOT,
@@ -386,6 +387,24 @@ describe('cli args parsing', () => {
assert.strictEqual(disabledArgs.javascriptEvaluation, false);
});
+ it('parses file navigations flag', async () => {
+ // Test default (should be true).
+ const defaultArgs = parseConfig(['main.js'], {});
+ assert.strictEqual(defaultArgs.fileNavigations, true);
+
+ // Test enabling it
+ const enabledArgs = parseConfig(['--file-navigations']);
+ assert.strictEqual(enabledArgs.fileNavigations, true);
+
+ // Test disabling it
+ const disabledArgs = parseConfig(['--no-file-navigations']);
+ assert.strictEqual(disabledArgs.fileNavigations, false);
+
+ // The camelCase form is equivalent.
+ const camelCaseArgs = parseConfig(['--fileNavigations=false']);
+ assert.strictEqual(camelCaseArgs.fileNavigations, false);
+ });
+
it('respects env variable', async () => {
// Test default (should be true).
const defaultArgs = parseConfig(['main.js'], {
diff --git a/tests/tools/pages.test.ts b/tests/tools/pages.test.ts
index d98ebe7a..2ddb4110 100644
--- a/tests/tools/pages.test.ts
+++ b/tests/tools/pages.test.ts
@@ -293,6 +293,42 @@ describe('pages', () => {
);
});
});
+ it('throws when navigating to a file URL and fileNavigations is false', async () => {
+ await withMcpContext(async (response, context) => {
+ const disabledArgs = new ConfigParser(
+ '1.0.0',
+ ['node', 'script.js', '--no-file-navigations'],
+ {CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true'},
+ ).parse();
+ const tool = newPage(disabledArgs);
+ await assert.rejects(
+ async () => {
+ await tool.handler(
+ {params: {url: 'file:///etc/passwd'}},
+ response,
+ context,
+ );
+ },
+ {
+ message:
+ 'Navigating to file: URLs is not allowed when --file-navigations is disabled.',
+ },
+ );
+ await assert.rejects(
+ async () => {
+ await tool.handler(
+ {params: {url: 'view-source:file:///etc/passwd'}},
+ response,
+ context,
+ );
+ },
+ {
+ message:
+ 'Navigating to file: URLs is not allowed when --file-navigations is disabled.',
+ },
+ );
+ });
+ });
it('throws when URL does not parse with new URL', async () => {
await withMcpContext(async (response, context, args) => {
const tool = newPage(args);
@@ -859,6 +895,37 @@ describe('pages', () => {
});
});
+ it('throws when navigating to a file URL and fileNavigations is false', async () => {
+ await withMcpContext(async (response, context) => {
+ const disabledArgs = new ConfigParser(
+ '1.0.0',
+ ['node', 'script.js', '--no-file-navigations'],
+ {CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true'},
+ ).parse();
+ await assert.rejects(
+ async () => {
+ await navigatePage(disabledArgs).handler(
+ {
+ params: {url: 'file:///etc/passwd'},
+ page: context.getSelectedMcpPage(),
+ },
+ response,
+ context,
+ );
+ },
+ {
+ message:
+ 'Navigating to file: URLs is not allowed when --file-navigations is disabled.',
+ },
+ );
+ // The page must not have left about:blank.
+ assert.strictEqual(
+ context.getSelectedMcpPage().pptrPage.url(),
+ 'about:blank',
+ );
+ });
+ });
+
it('throws an error if the page was closed not by the MCP server', async () => {
await withMcpContext(async (response, context, args) => {
const page = await context.newPage();
diff --git a/tests/tools/slim/tools.test.ts b/tests/tools/slim/tools.test.ts
index a7d1e6f2..21f96b70 100644
--- a/tests/tools/slim/tools.test.ts
+++ b/tests/tools/slim/tools.test.ts
@@ -138,6 +138,31 @@ describe('slim', () => {
sinon.assert.notCalled(page.pptrPage.goto);
});
+ it('disallows file URLs when fileNavigations is false', async () => {
+ const {page, context, response} = createHandlerMocks();
+ const disabledArgs = new ConfigParser(
+ '1.0.0',
+ ['node', 'script.js', '--slim', '--no-file-navigations'],
+ {CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: 'true'},
+ ).parse();
+ const tool = navigate(disabledArgs);
+ await assert.rejects(
+ async () => {
+ await tool.handler(
+ {params: {url: 'file:///etc/passwd'}, page},
+ response,
+ context,
+ );
+ },
+ {
+ message:
+ 'Navigating to file: URLs is not allowed when --file-navigations is disabled.',
+ },
+ );
+
+ sinon.assert.notCalled(page.pptrPage.goto);
+ });
+
it('rejects chrome: and chrome-untrusted: URLs', async () => {
const {page, context, response, args} = createHandlerMocks();
const tool = navigate(args);
diff --git a/tests/utils/url.test.ts b/tests/utils/url.test.ts
index eb442ecd..db4ba599 100644
--- a/tests/utils/url.test.ts
+++ b/tests/utils/url.test.ts
@@ -96,6 +96,7 @@ describe('isLocalhost', () => {
const defaultOptions = {
javascriptEvaluation: undefined,
categoryExtensions: undefined,
+ fileNavigations: undefined,
};
describe('validateUrl', () => {
@@ -143,6 +144,7 @@ describe('validateUrl', () => {
validateUrl('javascript:alert(1)', {
javascriptEvaluation: true,
categoryExtensions: undefined,
+ fileNavigations: undefined,
}).protocol,
'javascript:',
);
@@ -154,6 +156,7 @@ describe('validateUrl', () => {
validateUrl('data:text/html,<div>test</div>', {
javascriptEvaluation: true,
categoryExtensions: undefined,
+ fileNavigations: undefined,
}).protocol,
'data:',
);
@@ -165,6 +168,7 @@ describe('validateUrl', () => {
validateUrl('vbscript:msgbox(1)', {
javascriptEvaluation: true,
categoryExtensions: undefined,
+ fileNavigations: undefined,
}).protocol,
'vbscript:',
);
@@ -176,6 +180,7 @@ describe('validateUrl', () => {
validateUrl('javascript:alert(1)', {
javascriptEvaluation: false,
categoryExtensions: undefined,
+ fileNavigations: undefined,
}),
/Navigating to javascript: URLs is not allowed when JavaScript evaluation is disabled\./,
);
@@ -184,6 +189,7 @@ describe('validateUrl', () => {
validateUrl('JAVASCRIPT:alert(1)', {
javascriptEvaluation: false,
categoryExtensions: undefined,
+ fileNavigations: undefined,
}),
/Navigating to javascript: URLs is not allowed when JavaScript evaluation is disabled\./,
);
@@ -192,6 +198,7 @@ describe('validateUrl', () => {
validateUrl('javascript:void(0)', {
javascriptEvaluation: false,
categoryExtensions: undefined,
+ fileNavigations: undefined,
}),
/Navigating to javascript: URLs is not allowed when JavaScript evaluation is disabled\./,
);
@@ -200,6 +207,7 @@ describe('validateUrl', () => {
validateUrl('data:text/html,<div>test</div>', {
javascriptEvaluation: false,
categoryExtensions: undefined,
+ fileNavigations: undefined,
}),
/Navigating to data: URLs is not allowed when JavaScript evaluation is disabled\./,
);
@@ -208,6 +216,7 @@ describe('validateUrl', () => {
validateUrl('DATA:text/html,<div>test</div>', {
javascriptEvaluation: false,
categoryExtensions: undefined,
+ fileNavigations: undefined,
}),
/Navigating to data: URLs is not allowed when JavaScript evaluation is disabled\./,
);
@@ -216,6 +225,7 @@ describe('validateUrl', () => {
validateUrl('vbscript:msgbox(1)', {
javascriptEvaluation: false,
categoryExtensions: undefined,
+ fileNavigations: undefined,
}),
/Navigating to vbscript: URLs is not allowed when JavaScript evaluation is disabled\./,
);
@@ -224,6 +234,7 @@ describe('validateUrl', () => {
validateUrl('VBSCRIPT:msgbox(1)', {
javascriptEvaluation: false,
categoryExtensions: undefined,
+ fileNavigations: undefined,
}),
/Navigating to vbscript: URLs is not allowed when JavaScript evaluation is disabled\./,
);
@@ -285,6 +296,7 @@ describe('validateUrl', () => {
validateUrl('chrome-extension://abcdef/popup.html', {
javascriptEvaluation: undefined,
categoryExtensions: false,
+ fileNavigations: undefined,
}),
/Navigating to chrome-extension: URLs is not allowed without --categoryExtensions\./,
);
@@ -292,10 +304,128 @@ describe('validateUrl', () => {
validateUrl('chrome-extension://abcdef/popup.html', {
javascriptEvaluation: undefined,
categoryExtensions: true,
+ fileNavigations: undefined,
}).href,
'chrome-extension://abcdef/popup.html',
);
});
+
+ it('should allow file URLs when fileNavigations is true or omitted', () => {
+ assert.strictEqual(
+ validateUrl('file:///tmp/example.txt', defaultOptions).protocol,
+ 'file:',
+ );
+ assert.strictEqual(
+ validateUrl('file:///tmp/example.txt', {
+ javascriptEvaluation: undefined,
+ categoryExtensions: undefined,
+ fileNavigations: true,
+ }).href,
+ 'file:///tmp/example.txt',
+ );
+ });
+
+ it('should reject file URLs when fileNavigations is false', () => {
+ const noFileNavigations = {
+ javascriptEvaluation: undefined,
+ categoryExtensions: undefined,
+ fileNavigations: false,
+ };
+ assert.throws(
+ () => validateUrl('file:///tmp/example.txt', noFileNavigations),
+ /Navigating to file: URLs is not allowed when --file-navigations is disabled\./,
+ );
+ assert.throws(
+ () => validateUrl('file:///etc/passwd', noFileNavigations),
+ /Navigating to file: URLs is not allowed when --file-navigations is disabled\./,
+ );
+ // The host form resolves to the same scheme and is rejected too.
+ assert.throws(
+ () => validateUrl('file://localhost/tmp/example.txt', noFileNavigations),
+ /Navigating to file: URLs is not allowed when --file-navigations is disabled\./,
+ );
+ });
+
+ it('should reject view-source URLs that target a file URL when fileNavigations is false', () => {
+ const noFileNavigations = {
+ javascriptEvaluation: undefined,
+ categoryExtensions: undefined,
+ fileNavigations: false,
+ };
+ // `view-source:` wraps the inner URL and Chrome resolves it, so this reads
+ // the file just as a bare `file:` URL would.
+ assert.throws(
+ () => validateUrl('view-source:file:///etc/passwd', noFileNavigations),
+ /Navigating to file: URLs is not allowed when --file-navigations is disabled\./,
+ );
+ // An uppercase inner scheme normalises to `file:` when re-parsed.
+ assert.throws(
+ () => validateUrl('view-source:FILE:///etc/passwd', noFileNavigations),
+ /Navigating to file: URLs is not allowed when --file-navigations is disabled\./,
+ );
+ // An uppercase outer scheme normalises too.
+ assert.throws(
+ () => validateUrl('VIEW-SOURCE:file:///etc/passwd', noFileNavigations),
+ /Navigating to file: URLs is not allowed when --file-navigations is disabled\./,
+ );
+ // Nested wrapping unwraps to the same target.
+ assert.throws(
+ () =>
+ validateUrl(
+ 'view-source:view-source:file:///etc/passwd',
+ noFileNavigations,
+ ),
+ /Navigating to file: URLs is not allowed when --file-navigations is disabled\./,
+ );
+ });
+
+ it('should not reject view-source URLs that target other schemes', () => {
+ const noFileNavigations = {
+ javascriptEvaluation: undefined,
+ categoryExtensions: undefined,
+ fileNavigations: false,
+ };
+ assert.strictEqual(
+ validateUrl('view-source:http://example.com', noFileNavigations).protocol,
+ 'view-source:',
+ );
+ assert.strictEqual(
+ validateUrl('view-source:https://example.com', noFileNavigations)
+ .protocol,
+ 'view-source:',
+ );
+ });
+
+ it('should allow view-source of a file URL when fileNavigations is true', () => {
+ assert.strictEqual(
+ validateUrl('view-source:file:///etc/passwd', {
+ javascriptEvaluation: undefined,
+ categoryExtensions: undefined,
+ fileNavigations: true,
+ }).protocol,
+ 'view-source:',
+ );
+ });
+
+ it('should only reject file URLs when fileNavigations is false', () => {
+ const noFileNavigations = {
+ javascriptEvaluation: undefined,
+ categoryExtensions: undefined,
+ fileNavigations: false,
+ };
+ assert.strictEqual(
+ validateUrl('https://example.com', noFileNavigations).href,
+ 'https://example.com/',
+ );
+ assert.strictEqual(
+ validateUrl('about:blank', noFileNavigations).href,
+ 'about:blank',
+ );
+ assert.strictEqual(
+ validateUrl('data:text/html,<div>test</div>', noFileNavigations).protocol,
+ 'data:',
+ );
+ });
});
describe('isAllowedUrl', () => {