Webtrax docs

Configuration (webtrax.yml)

The webtrax.yml file, every key it accepts, and the defaults. webtrax init writes a commented one.

webtrax check reads webtrax.yml from the current directory (or --config <file>). Every key is optional; options on the command line win. Unknown keys are an error, so a typo does not silently do nothing.

version: 1
target: https://your-site.example/

scope:
  include: []            # path prefixes to crawl (* is a wildcard); empty means the whole site
  exclude: []            # path prefixes never to crawl (still checked as links)
  check_external: true   # check links to other sites (they are never crawled)
  respect_robots: true   # honour robots.txt
  allow_private: false   # allow private network targets (automatic for localhost)

limits:
  max_pages: 300
  max_depth: 10
  concurrency: 4
  per_host_rps: 2        # requests per second to each host
  time_budget_s: 600

suites:
  links: { enabled: true }
  security: { enabled: true }
  seo: { enabled: true }
  a11y: { enabled: false }         # browser suite, needs Chromium
  performance: { enabled: false }  # browser suite, needs Chromium

fail_on: high            # critical, high, medium, low, info or none
reports: [html, md]      # html, md, json, sarif, junit
ignore: []               # rule ids to leave out, e.g. [seo.noindex] on staging

Keys

Key Type Default Meaning
version 1 1 File format version.
target URL none The site to check when no URL is given. A bare host gets https://.
scope.include list all Crawl only paths starting with one of these (* matches anything).
scope.exclude list none Never crawl these paths; links to them are still checked once.
scope.check_external bool true Check links to other sites for reachability.
scope.respect_robots bool true Honour robots.txt Disallow and Crawl-delay.
scope.allow_private bool false Allow private, loopback and link-local addresses. Cloud metadata addresses are always refused.
limits.max_pages int 300 Pages to crawl.
limits.max_depth int 10 Link depth from the start page.
limits.concurrency int 4 Parallel requests.
limits.per_host_rps number 2 Requests per second to each host. A longer Crawl-delay wins.
limits.time_budget_s int 600 Stop after this long and report what was found.
suites.<links|security|seo>.enabled bool true Turn a suite off.
suites.<a11y|performance>.enabled bool false Turn a browser suite on (or use --browser).
fail_on severity high Exit 1 at this severity or worse; none never fails.
reports list [html, md] Report files written to the run directory: html, md, json, sarif, junit.
ignore list of rule ids none Rules to leave out of reports and the exit code (they stay in run.ndjson). Unknown ids are an error.