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.mdindex 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:** booleandiff --git a/src/config/mcp-options.ts b/src/config/mcp-options.tsindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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', () => {