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
48 changes: 38 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,43 @@

HCL-driven browser-automation CLI for [go-webengine/engine](https://github.com/go-webengine/engine): click/fill-form/assert test scenarios, for driving a rendered page's own `LiveDocument` (`Focus`/`Type`/`Click`/`Submit`) from a declarative scenario file instead of hand-written Go.

Status: in progress. This repository currently holds the scenario format
(`hclscenario`), a `driver` package that executes a parsed scenario
against a real `engine.LiveDocument` (click/fill/assert/submit, plus the
pinned-page identity check), and a `webtest validate <file>` CLI command
(parse-only). The `run` CLI subcommand and the session/dry-run-by-default/
audit-log/bounds/anti-bot guardrails are tracked separately and not
implemented yet — `driver.Run`'s own `doSubmit` parameter is the one
escape hatch those guardrails will gate.
## Usage

```sh
webtest validate scenario.hcl # parse + schema-check only, no render
webtest run scenario.hcl # render + drive; every submit step is a DRY RUN (no request)
webtest run scenario.hcl --submit # submit steps perform the real request
```

`run`'s guardrails:

- **Dry-run by default.** A `submit` step always computes and reports
what it WOULD send (method, URL, body); only `--submit` makes it real.
- **Pinned-page check**, built into `driver.Run` itself: before the first
step runs, the rendered page's own URL and every `pin.selectors` entry
must already match, or the run refuses with a named diff.
- **Session persistence.** Cookies the real HTTP client actually received
(e.g. from a prior `run --submit` that logged in) are kept in a 0600
file under the user's own config dir (`--cookie-file` to override) —
never in an argument, environment variable, or log line. A file found
with any other permission is treated as corrupted, not silently
trusted.
- **Append-only audit log** (`--audit-log` to override), one JSON line
per submit step — timestamp, URL, method, body, and whether it was a
dry run — 0600, rotated past 10 MiB.
- **Bounds.** `--timeout` (default 30s) covers the whole render + every
step; `--max-steps` (default 200) refuses an oversized scenario before
rendering anything.
- **Anti-bot detection that stops, never evades**: a small, named set of
markers for well-known CAPTCHA providers and Cloudflare's own
interstitial — found on the page, `run` refuses outright rather than
attempting to continue. A heuristic, not exhaustive; check a target
site's own terms of service before automating it regardless.

The `run` subcommand does not perform a login on its own behalf — "the
user logs in themselves" (a scenario's own `submit` step against a real
login form, run once with `--submit`); the resulting session cookie is
then reused by later `run` invocations against the same host.

## Scenario format

Expand Down Expand Up @@ -51,8 +80,7 @@ scenario "login" {
present, or the run refuses with a named diff rather than acting against
an unexpected page.
- `step "submit"` always computes a dry-run preview (method, URL, body) by
default; only the CLI's own `--submit` flag (once the CLI exists) makes
it a real request.
default; only `run`'s own `--submit` flag makes it a real request.
- Every attribute value is an HCL expression and may call a function from
a small, fixed, reviewed allowlist (`hclscenario.Functions`) — currently
`upper`/`lower`/`trim`/`join`. The allowlist is deliberately NOT cty's
Expand Down
41 changes: 41 additions & 0 deletions cmd/webtest/antibot.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
// Copyright (c) the go-webengine/webtest authors.
// SPDX-License-Identifier: BSD-3-Clause

package main

import "strings"

// antiBotMarkers is a small, named set of strings that show up on a real
// CAPTCHA/anti-bot challenge page from a well-known provider, or on
// Cloudflare's own interstitial — deliberately a HEURISTIC, not an
// exhaustive detector: go-wasmcontainers' own guardrail is "detect and
// STOP, never evade," so a false negative (a challenge this doesn't
// recognize) just means the scenario proceeds and then fails its own
// pin/assert steps normally — safe either way. A false POSITIVE (stopping
// on an ordinary page that merely mentions one of these words, e.g. in a
// footer) is the safer failure direction for a tool whose whole point is
// never to route around a real challenge.
var antiBotMarkers = []string{
"recaptcha",
"hcaptcha",
"are you a robot",
"just a moment", // Cloudflare's own interstitial title
"attention required", // Cloudflare's own block-page title
"cf-challenge",
"distil_r_captcha",
"perimeterx",
"datadome",
}

// detectAntiBot scans title+html (the rendered page's own <title> and raw
// decoded source) for any marker, case-insensitively, returning the first
// one found.
func detectAntiBot(title, html string) (marker string, found bool) {
haystack := strings.ToLower(title + " " + html)
for _, m := range antiBotMarkers {
if strings.Contains(haystack, m) {
return m, true
}
}
return "", false
}
26 changes: 26 additions & 0 deletions cmd/webtest/antibot_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
// Copyright (c) the go-webengine/webtest authors.
// SPDX-License-Identifier: BSD-3-Clause

package main

import "testing"

func TestDetectAntiBotFindsRecaptcha(t *testing.T) {
marker, found := detectAntiBot("Verify you are human", `<div class="g-recaptcha"></div>`)
if !found || marker != "recaptcha" {
t.Fatalf("detectAntiBot = (%q, %v), want (recaptcha, true)", marker, found)
}
}

func TestDetectAntiBotFindsCloudflareInterstitial(t *testing.T) {
marker, found := detectAntiBot("Just a moment...", `<p>Checking your browser</p>`)
if !found || marker != "just a moment" {
t.Fatalf("detectAntiBot = (%q, %v), want (just a moment, true)", marker, found)
}
}

func TestDetectAntiBotOrdinaryPage(t *testing.T) {
if marker, found := detectAntiBot("Sign in", `<form><input name="email"></form>`); found {
t.Fatalf("detectAntiBot on an ordinary login page = (%q, true), want false", marker)
}
}
56 changes: 56 additions & 0 deletions cmd/webtest/auditlog.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
// Copyright (c) the go-webengine/webtest authors.
// SPDX-License-Identifier: BSD-3-Clause

package main

import (
"encoding/json"
"os"
"path/filepath"
"time"
)

// maxAuditLogBytes bounds the audit log file size: past this, the
// current file is rotated (renamed to a .1 suffix, overwriting any
// previous one) rather than left to grow without bound — this tool's
// own "every new capability needs its own bound" convention, inherited
// from go-webengine/engine's.
const maxAuditLogBytes = 10 << 20

// auditEntry is one line of the append-only audit log — go-wasmcontainers'
// own guardrail: "an append-only log of what was sent (time, URL, fields,
// response status)". DryRun is recorded explicitly so the log itself
// shows which entries were ever a REAL request, not just a preview.
type auditEntry struct {
Time time.Time `json:"time"`
URL string `json:"url"`
Method string `json:"method"`
Body string `json:"body,omitempty"`
DryRun bool `json:"dry_run"`
}

// appendAuditLog appends entry as one JSON line to path (0600, created if
// missing), rotating first if the file has already grown past
// maxAuditLogBytes.
func appendAuditLog(path string, entry auditEntry) error {
if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
return err
}
if info, err := os.Stat(path); err == nil && info.Size() > maxAuditLogBytes {
if err := os.Rename(path, path+".1"); err != nil {
return err
}
}
f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600)
if err != nil {
return err
}
defer f.Close()
data, err := json.Marshal(entry)
if err != nil {
return err
}
data = append(data, '\n')
_, err = f.Write(data)
return err
}
79 changes: 79 additions & 0 deletions cmd/webtest/auditlog_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
// Copyright (c) the go-webengine/webtest authors.
// SPDX-License-Identifier: BSD-3-Clause

package main

import (
"bufio"
"encoding/json"
"os"
"path/filepath"
"strings"
"testing"
"time"
)

func TestAppendAuditLogCreatesAndAppends(t *testing.T) {
path := filepath.Join(t.TempDir(), "audit.log")
e1 := auditEntry{Time: time.Now(), URL: "https://x/a", Method: "POST", Body: "a=1", DryRun: true}
e2 := auditEntry{Time: time.Now(), URL: "https://x/b", Method: "GET", DryRun: false}
if err := appendAuditLog(path, e1); err != nil {
t.Fatalf("append 1: %v", err)
}
if err := appendAuditLog(path, e2); err != nil {
t.Fatalf("append 2: %v", err)
}
info, err := os.Stat(path)
if err != nil {
t.Fatal(err)
}
if mode := info.Mode().Perm(); mode != 0o600 {
t.Fatalf("audit log mode = %#o, want 0600", mode)
}

f, err := os.Open(path)
if err != nil {
t.Fatal(err)
}
defer f.Close()
sc := bufio.NewScanner(f)
var lines []string
for sc.Scan() {
lines = append(lines, sc.Text())
}
if len(lines) != 2 {
t.Fatalf("audit log has %d lines, want 2", len(lines))
}
var got auditEntry
if err := json.Unmarshal([]byte(lines[0]), &got); err != nil {
t.Fatalf("line 1 is not valid JSON: %v", err)
}
if got.URL != "https://x/a" || !got.DryRun {
t.Fatalf("line 1 = %+v", got)
}
}

func TestAppendAuditLogRotatesWhenTooLarge(t *testing.T) {
path := filepath.Join(t.TempDir(), "audit.log")
big := strings.Repeat("x", maxAuditLogBytes+1)
if err := os.WriteFile(path, []byte(big), 0o600); err != nil {
t.Fatal(err)
}
if err := appendAuditLog(path, auditEntry{URL: "https://x/after-rotation"}); err != nil {
t.Fatalf("append after exceeding the size bound: %v", err)
}
rotated := path + ".1"
if _, err := os.Stat(rotated); err != nil {
t.Fatalf("rotated file %s: %v, want it to exist", rotated, err)
}
data, err := os.ReadFile(path)
if err != nil {
t.Fatal(err)
}
if !strings.Contains(string(data), "after-rotation") {
t.Fatalf("new log file = %q, want it to contain the post-rotation entry, not the old giant content", data)
}
if len(data) > len(big) {
t.Fatalf("new log file is %d bytes, want it SMALLER than the pre-rotation file (%d) — rotation must have moved the old content out", len(data), len(big))
}
}
1 change: 1 addition & 0 deletions cmd/webtest/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -32,5 +32,6 @@ func RootCmd() *cobra.Command {
SilenceUsage: true,
}
cmd.AddCommand(newValidateCmd())
cmd.AddCommand(newRunCmd())
return cmd
}
Loading
Loading