Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -545,3 +545,12 @@ published by hand by the owner.
skipped, so it must refuse them; a journey without blocks still prints version 1 byte for byte as before.
- **Not exported to agent-browser**, which runs every line.

## Read-only runs

- **The guard enforces it, a journey doesn't declare it.** `NetworkGuardOptions.ReadOnly` refuses on the request's
method in `Fetch.requestPaused`, where the page cannot get around it; a journey marked as read-only could still
write by mistake. The TS runner does the same in `page.route`.
- **Writes are judged after the allow list**, so a refused third-party beacon stays a reported request and only a
write to an allowed host fails the step. A page that writes on its own (telemetry) needs `WritableUrls`.
- **`BlockedRequest.RefusedWrite` is `null` for allow-list refusals**, so existing `BlockedRequest` equality is
unchanged.
2 changes: 2 additions & 0 deletions docs/cli/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@ cdp run site/journeys/*.journey --base-url ./site --artifacts .artifacts/journey
| `-a, --allow` | another host pattern the run may reach (repeatable) |
| `--feature` | a feature flag that is on (repeatable), for `feature` blocks |
| `--build-type`, `--env` | the build type and the environment's name, for `build-type:` and `env:` conditions |
| `--read-only` | refuse every request that is not GET, HEAD or OPTIONS, so the run cannot change a live site; see [safety](../journeys/safety.md#read-only-runs) |
| `--writable` | a URL glob a read-only run may write to anyway (repeatable), such as a telemetry endpoint |
| `--file-root` | the folder `file://` URLs may point into, when the base URL is not a folder |
| `--artifacts` | the folder `screenshot` and `network har stop` write into; off unless given |
| `--timeout` | seconds an action waits for its element (default 5) |
Expand Down
16 changes: 16 additions & 0 deletions docs/journeys/safety.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,22 @@ pixel does not break a journey.

`JourneyOptions.GuardNetwork = false` turns the list off, and lets `open` go anywhere.

## Read-only runs

A run against a live site should not change it. With `JourneyOptions.ReadOnly` (the CLI's `--read-only`, `readOnly` in
`@nullean/journeys`) every request whose method is not `GET`, `HEAD` or `OPTIONS` is refused before it leaves the
browser: form posts, `fetch`, `XMLHttpRequest` and `sendBeacon` alike. The step that caused it fails:

```text
Blocked POST https://shop.test/api/basket: this run is read-only, so only GET, HEAD and OPTIONS requests are sent
(JourneyOptions.WritableUrls, or --writable on the CLI, allows a URL).
```

A page often writes on its own, for telemetry. `WritableUrls` (`--writable`, `writableUrls`) lists URL globs a
read-only run may write to anyway: `**` is anything, `*` anything but `/`, as in `wait --url`. Requests the allow list
already refuses stay refused and are reported, not failed, as before. A write is judged only after the allow list lets
it through, so a third-party beacon is a refused request and not a failed step.

## Files

`file://` URLs stay inside one folder: the base URL's folder, or `JourneyOptions.FileRoot` (the CLI's `--file-root`).
Expand Down
24 changes: 20 additions & 4 deletions js/journeys/src/run.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import type { BrowserContext, Locator, Page } from 'playwright-core';
import { joinLine } from './commandline.ts';
import type { Command, Journey, Step, Target } from './model.ts';
import { isSecretReference, requirementMet } from './parse.ts';
import { describeTarget, runExpect } from './expect.ts';
import { describeTarget, runExpect, urlGlob } from './expect.ts';
import type { PlaywrightExpect } from './expect.ts';

export interface RunOptions {
Expand All @@ -23,6 +23,13 @@ export interface RunOptions {
buildType?: string;
/** The environment's name (`prod`, `edge`), for `env:` conditions. */
env?: string;
/**
* Refuse every request that is not GET, HEAD or OPTIONS, so a run against a live site cannot change it. A refused
* write fails the step that caused it.
*/
readOnly?: boolean;
/** URL globs (`**` anything, `*` anything but `/`) a read-only run may write to anyway, such as a telemetry endpoint. */
writableUrls?: string[];
/** Resolves `$env:NAME`; the process environment by default. */
secrets?: (name: string) => string | undefined;
/** Where `screenshot` writes. Without it, screenshot steps are skipped with a warning. */
Expand Down Expand Up @@ -160,6 +167,8 @@ export class JourneyRun {
private actionDocuments = 0;
private readonly blockedNavigations: string[] = [];
private readonly skippedBlocks = new Set<number>();
private readonly blockedWrites: string[] = [];
private readonly writable: RegExp[];
private readonly consoleLog: string[] = [];
private readonly errorLog: string[] = [];
private readonly warned = new Set<string>();
Expand All @@ -184,6 +193,7 @@ export class JourneyRun {
else if (base.protocol === 'file:') fileRoot = dirname(decodeURIComponent(base.pathname.endsWith('/') ? base.pathname + 'x' : base.pathname));
}
this.allow = new AllowList(hosts, fileRoot);
this.writable = (options.writableUrls ?? []).map(urlGlob);
}

/** Starts a run: the network guard, and the recordings the journey's steps need. */
Expand Down Expand Up @@ -214,7 +224,13 @@ export class JourneyRun {
} catch {
return route.fallback();
}
if (url.protocol === 'data:' || url.protocol === 'blob:' || url.protocol === 'about:' || this.allow.refusal(url) === undefined) return route.fallback();
if (url.protocol === 'data:' || url.protocol === 'blob:' || url.protocol === 'about:') return route.fallback();
if (this.allow.refusal(url) === undefined) {
const method = request.method().toUpperCase();
if (!this.options.readOnly || method === 'GET' || method === 'HEAD' || method === 'OPTIONS' || this.writable.some((g) => g.test(url.href))) return route.fallback();
this.blockedWrites.push(`Blocked ${method} ${request.url()}: this run is read-only, so only GET, HEAD and OPTIONS requests are sent (RunOptions.writableUrls, or --writable on the CLI, allows a URL).`);
return route.abort('blockedbyclient');
}
if (request.isNavigationRequest()) this.blockedNavigations.push(`The page navigated to ${request.url()}, which is refused: ${this.allow.refusal(url)}.`);
return route.abort('blockedbyclient');
};
Expand Down Expand Up @@ -270,10 +286,10 @@ export class JourneyRun {
output = await this.run(step.command, step);
// A navigation starts from the page it lands on.
if (step.command.type === 'open' || step.command.type === 'history') this.actionDocuments = this.documents;
const refused = this.blockedNavigations.splice(0);
const refused = [...this.blockedNavigations.splice(0), ...this.blockedWrites.splice(0)];
if (refused.length > 0) throw new StepError(refused[0]);
} catch (e) {
const refused = this.blockedNavigations.splice(0);
const refused = [...this.blockedNavigations.splice(0), ...this.blockedWrites.splice(0)];
const message = refused[0] ?? (e instanceof Error ? e.message : String(e));
throw new StepError(this.secrets.redact(message));
}
Expand Down
86 changes: 86 additions & 0 deletions js/journeys/test/readonly.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
// A read-only run refuses every write before it leaves the browser, and fails the step that made it. Skips when
// Chrome is missing; CDP_BROWSER_REQUIRED=1 makes that a failure.

import assert from 'node:assert/strict';
import { createServer } from 'node:http';
import type { AddressInfo } from 'node:net';
import { after, before, test } from 'node:test';
import type { Browser } from 'playwright-core';
import { parseJourney, runJourney } from '../src/index.ts';
import { launchChrome } from './site.ts';

const page = `<!doctype html><title>Writes</title><link rel="icon" href="data:,">
<button onclick="fetch('/write', {method: 'POST', body: 'x'})">Save with fetch</button>
<button onclick="fetch('/telemetry', {method: 'POST', body: 'x'})">Send telemetry</button>
<form method="post" action="/form"><button>Save with form</button></form>
<a href="/next">Next page</a>`;

let browser: Browser | undefined;
let skip: string | false = false;
let origin = '';
let writes = 0;
let stop = () => {};

before(async () => {
const server = createServer((req, res) => {
if (req.method !== 'GET') writes++;
const next = req.url === '/next';
res.writeHead(200, { 'content-type': 'text/html' }).end(next ? '<title>Next</title><h1>Next</h1>' : req.method === 'GET' ? page : '<title>Saved</title>');
});
await new Promise<void>((done) => server.listen(0, '127.0.0.1', done));
origin = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
stop = () => server.close();
({ browser, skip } = await launchChrome());
});

after(async () => {
await browser?.close();
stop();
});

async function run(text: string, options: { readOnly?: boolean; writableUrls?: string[] } = { readOnly: true }) {
writes = 0;
const p = await (await browser!.newContext()).newPage();
const result = await runJourney(p, parseJourney(text, 'read-only.journey'), { baseUrl: origin + '/', actionTimeout: 3000, warn: () => {}, ...options });
await new Promise((r) => setTimeout(r, 100));
return result;
}

test('a fetch POST fails the step and never reaches the server', async (t) => {
if (skip) return t.skip(skip);
const result = await run('open /\nfind role button click --name "Save with fetch"\nwait 300\nget title');
assert.ok(result.failure, 'the run should fail');
assert.match(result.failure.message, /^Blocked POST http:\/\/127\.0\.0\.1:\d+\/write: this run is read-only/);
assert.equal(writes, 0);
});

test('a form POST fails the step and never reaches the server', async (t) => {
if (skip) return t.skip(skip);
const result = await run('open /\nfind role button click --name "Save with form"\nget title');
assert.match(result.failure?.message ?? '', /^Blocked POST .*\/form: this run is read-only/);
assert.equal(writes, 0);
});

test('reads still work', async (t) => {
if (skip) return t.skip(skip);
const result = await run('open /\nfind role link click --name "Next page"\nwait --url **/next\nget title');
assert.equal(result.failure, undefined);
assert.equal(writes, 0);
});

test('a writable URL lets its write through, and no other', async (t) => {
if (skip) return t.skip(skip);
const ok = await run('open /\nfind role button click --name "Send telemetry"\nwait 300\nget title', { readOnly: true, writableUrls: ['**/telemetry'] });
assert.equal(ok.failure, undefined);
assert.equal(writes, 1);
const refused = await run('open /\nfind role button click --name "Save with fetch"\nwait 300\nget title', { readOnly: true, writableUrls: ['**/telemetry'] });
assert.ok(refused.failure);
assert.equal(writes, 0);
});

test('without readOnly the write goes through', async (t) => {
if (skip) return t.skip(skip);
const result = await run('open /\nfind role button click --name "Save with fetch"\nwait 300\nget title', {});
assert.equal(result.failure, undefined);
assert.equal(writes, 1);
});
6 changes: 5 additions & 1 deletion src/Nullean.Cdp.Cli/CdpCli.cs
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,9 @@ public async Task<int> RunAsync(
string? artifacts = null,
IReadOnlyList<string>? features = null,
string? buildType = null,
string? env = null
string? env = null,
bool readOnly = false,
IReadOnlyList<string>? writable = null
)
{
var (ok, root) = ParseBase(baseUrl);
Expand All @@ -114,6 +116,8 @@ public async Task<int> RunAsync(
Features = new HashSet<string>(features ?? [], StringComparer.Ordinal),
BuildType = buildType,
Env = env,
ReadOnly = readOnly,
WritableUrls = writable ?? [],
FileRoot = fileRoot is null ? null : Path.GetFullPath(fileRoot),
ArtifactsDirectory = artifacts is null ? null : Path.GetFullPath(artifacts),
Secrets = environment,
Expand Down
6 changes: 5 additions & 1 deletion src/Nullean.Cdp.Cli/Program.cs
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ internal sealed class CdpCommands
/// <param name="feature">A feature flag that is on (repeatable), for 'feature' blocks.</param>
/// <param name="buildType">The build type, for build-type: conditions.</param>
/// <param name="env">The environment's name, for env: conditions.</param>
/// <param name="readOnly">Refuse every request that is not GET, HEAD or OPTIONS, so the run cannot change a live site.</param>
/// <param name="writable">URL glob a read-only run may write to anyway (repeatable): ** anything, * anything but /.</param>
/// <param name="headed">Show the browser window.</param>
/// <param name="json">Print JSON; everything under a "page" key came from the page.</param>
/// <param name="maxOutput">Characters per checkpoint before it is cut (0 for no limit).</param>
Expand All @@ -39,12 +41,14 @@ public static Task<int> Run(
string[]? feature = null,
string? buildType = null,
string? env = null,
bool readOnly = false,
string[]? writable = null,
bool headed = false,
bool json = false,
int maxOutput = CdpCli.DefaultMaxOutput,
double? timeout = null,
CancellationToken cancellationToken = default
) => Cli().RunAsync(files, baseUrl, allow ?? [], fileRoot, headed, json, maxOutput, timeout, cancellationToken, artifacts, feature, buildType, env);
) => Cli().RunAsync(files, baseUrl, allow ?? [], fileRoot, headed, json, maxOutput, timeout, cancellationToken, artifacts, feature, buildType, env, readOnly, writable);

/// <summary>Parse journeys without running them, and report every error with its line.</summary>
/// <param name="files">Journey files.</param>
Expand Down
28 changes: 26 additions & 2 deletions src/Nullean.Cdp.Journeys/JourneyRunner.cs
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,24 @@ public sealed class JourneyOptions
/// <summary>What <c>feature</c> blocks and <c>@requires</c> conditions are judged against.</summary>
public JourneyContext Context => new(Features, BuildType, Env);

/// <summary>
/// Refuse every request that is not a read (anything but GET, HEAD and OPTIONS), so a run against a live site cannot
/// change it. A refused write fails the step that caused it. Not tied to <see cref="GuardNetwork"/>.
/// </summary>
public bool ReadOnly { get; init; }

/// <summary>
/// URL globs (<see cref="Page.UrlGlob"/>: <c>**</c> anything, <c>*</c> anything but <c>/</c>) a read-only run may write
/// to anyway, such as a telemetry endpoint.
/// </summary>
public IReadOnlyList<string> WritableUrls { get; init; } = [];

internal NetworkGuardOptions GuardOptions()
{
var writable = WritableUrls.Select(Page.UrlGlob).ToArray();
return new NetworkGuardOptions { ReadOnly = ReadOnly, AllowWrites = writable.Length == 0 ? null : uri => writable.Any(g => g.IsMatch(uri.AbsoluteUri)) };
}

internal JourneyAllowList AllowList(Journey journey)
{
var hosts = journey.AllowedHosts.Concat(AllowedHosts);
Expand Down Expand Up @@ -125,8 +143,8 @@ public static async Task<JourneyResult> RunAsync(Journey journey, Page page, Jou
var checkpoints = new List<Checkpoint>();
var blocked = new List<BlockedRequest>();
// Without the guard, a guard that allows everything is still started when a step needs one (credentials).
await using var guard = options.GuardNetwork || journey.Steps.Any(s => s.Command is SetCommand { Setting: "credentials" })
? await page.GuardNetworkAsync(options.GuardNetwork ? run.AllowList.Allows : _ => true, cancellationToken).ConfigureAwait(false)
await using var guard = options.GuardNetwork || options.ReadOnly || journey.Steps.Any(s => s.Command is SetCommand { Setting: "credentials" })
? await page.GuardNetworkAsync(options.GuardNetwork ? run.AllowList.Allows : _ => true, options.GuardOptions(), cancellationToken).ConfigureAwait(false)
: null;
run.Guard = guard;
// The network is recorded only for journeys that read it.
Expand Down Expand Up @@ -204,6 +222,12 @@ private sealed record Run(Journey Journey, Page Page, JourneyOptions Options, Jo
string? failure = null;
foreach (var request in guard.TakeBlocked())
{
if (request.RefusedWrite is { } method)
{
failure ??= $"Blocked {method} {request.Url}: this run is read-only, so only GET, HEAD and OPTIONS requests are sent (JourneyOptions.WritableUrls, or --writable on the CLI, allows a URL).";
continue;
}

if (!request.IsNavigation)
{
blocked.Add(request);
Expand Down
Loading
Loading