Skip to content

Authorization & Scope

Every Klyrek package that makes a network request is expected to call AuthorizationScope.check() (or is_authorized()) first. This is the mechanism behind Klyrek's "authorized assessments only" principle: a scan can only ever touch hosts the operator has explicitly declared, so a typo'd target, a redirect to a third-party domain, or a misconfigured crawl can't silently reach out-of-scope infrastructure.

from klyrek_core.scope import AuthorizationScope

scope = AuthorizationScope(authorized_hosts=["shop.sandbox.klyrek.com", "*.sandbox.klyrek.com"])
scope.is_authorized("https://api.sandbox.klyrek.com/api/")   # True  (matches the wildcard)
scope.is_authorized("https://evil.example.com/")             # False

Patterns support fnmatch-style wildcards, e.g. *.target.com.

It's enforced at the HTTP client level, not just at the crawler

klyrek-http's KlyrekHTTPClient checks scope on every request it makes — including requests your own code issues directly through the client, not just the ones the crawler's frontier queue generates. Critically, it also checks every redirect hop via an httpx event hook, not just the URL you originally requested. If an authorized host redirects to infrastructure you didn't declare, the request is refused before it ever reaches that host — not logged after the fact.

What this means in practice

  • klyrek-cli's run_scan() builds authorized_hosts from the target URL's own hostname plus a wildcard for its subdomains ([hostname, f"*.{hostname}"]), plus anything you pass via --include-host / extra_hosts.
  • A link discovered mid-crawl to a host outside that list is dropped before it's ever fetched — it never becomes a recorded Endpoint, it's not logged as "found but skipped," it's simply never requested.
  • This is why the sandbox's three subdomains need --include-host "*.sandbox.klyrek.com" to all be reachable from one scan starting at shop.sandbox.klyrek.com — admin. and api. are siblings of shop., not descendants, so the automatic subdomain wildcard doesn't cover them.

No separate scope file

There's no scope.yaml or config file to maintain — the URL you pass to klyrek crawl is the authorized target, and --include-host (repeatable) is how you explicitly widen that. Nothing in Klyrek auto-widens scope on your behalf; that's a decision only the operator makes.