Configuring authentication

Pentrova supports six authentication modes. Every mode can be combined with a login flow that establishes the credential, so even complex OAuth exchanges can be modelled without requiring Pentrova to hold long-lived secrets. This guide covers each mode and the configuration surface you will use most often.

Bearer tokens#

The simplest mode. Supply a token and Pentrova adds it to every request the agents make. Tokens can be rotated through a short-lived login flow that fetches a fresh token before each scan run.

auth:
  mode: "bearer"
  token_source:
    login_flow: "refresh-token"
    header: "Authorization"
    prefix: "Bearer "

API keys#

API key auth works for any header or query parameter name. Declare the location and Pentrova handles placement on every request.

auth:
  mode: "apikey"
  location: "header"
  name: "X-API-Key"
  value_source: "env:PENTROVA_TEST_API_KEY"

Basic auth#

Standard HTTP basic. Pentrova stores the credentials encrypted in your workspace and only decrypts them inside the agent sandbox.

auth:
  mode: "basic"
  username_source: "env:TEST_USER"
  password_source: "env:TEST_PASS"

#

Pentrova accepts an access token (with optional refresh token plus token URL) and applies it as a bearer credential. Pentrova does not drive the authorization code dance or device flow itself — those run upstream at your identity provider, and you supply the resulting access token to Pentrova. Refresh is handled by Pentrova when a refresh token and token URL are configured.

auth:
  mode: "oauth2"
  access_token_source: "env:OAUTH_ACCESS_TOKEN"
  refresh_token_source: "env:OAUTH_REFRESH_TOKEN"
  token_url: "https://idp.example.com/oauth/token"
  client_id_source: "env:CLIENT_ID"

Custom#

For anything that does not fit the standard modes — multi-step login flows, signed request headers, rotating session cookies — use a custom login flow. You describe the flow as a sequence of requests Pentrova replays before every pentest.

auth:
  mode: "custom"
  login_flow: "sso-step-up"

The login flow itself is a separate object where each step can extract values from a response and inject them into later requests.

Mutual TLS#

For services that authenticate on the transport layer, supply a client certificate and key. Pentrova uses the certificate for every agent request against the target.

auth:
  mode: "mtls"
  cert_source: "secret:client-cert"
  key_source: "secret:client-key"
  ca_bundle_source: "secret:issuer-ca"

Rotating roles#

For authorisation matrix testing, declare multiple auth profiles on a single target. Each profile represents a role. The matrix module replays requests across every profile and flags responses that leak data between roles.

auth_profiles:
  - name: "admin"
    mode: "bearer"
    token_source: "login:admin"
  - name: "member"
    mode: "bearer"
    token_source: "login:member"
  - name: "guest"
    mode: "bearer"
    token_source: "login:guest"