Engagement & control

Declare Rules of Engagement, decide in-run approvals, watch window warnings, and stop a pentest with cancel or the kill switch — fail-closed by default.

Why engagement exists

Creating a pentest and attaching assets only records inventory. Agents are not allowed to touch that inventory until you declare an active Rules of Engagement (RoE). Rank is fail-closed: without an active RoE the orchestrator will not start (no_active_roe). Saving a draft version does not authorize a run.

The web app is the same control plane as the Engagement API and the Python SDK. This page describes what you authorize and how control behaves. Exact payloads and method names are in those references and in the Rules of Engagement recipe.

Declare RoE

A RoE is a versioned, machine-readable authorization. At least one of allowed CIDRs or allowed domains must be non-empty, and every pentest asset must fall inside that allow-list. Deny-lists always win. Rank also merges a global deny-list you cannot edit.

Typical fields you set:

• Allow / deny — allowed_cidrs, allowed_domains, denied_cidrs, denied_domains.
• Time windows — start / end as HH:MM, days, and an IANA timezone. No windows means 24/7. A window whose end is earlier than start crosses midnight.
• Approval classes — requires_approval_for (shell, script, destructive, exploit, scope_expansion, low_scope_confidence). auto_approve may skip waiting for listed classes except scope_expansion.
• authorization_ref — required. Ticket, memo or contract id (max 255 characters).
• escalation_contacts — required, non-empty. Each contact has type (email, slack or webhook) and value.

Activation fails if any asset sits outside the allow-list, or if a public IPv4 allow CIDR is wider than /16 (IPv6 /32). Private ranges are exempt from that floor.

Kill vs cancel

Cancel and kill are different operations. Do not treat them as the same button.

Pending approvals

Restricted actions pause until someone approves or denies them. Widening the RoE of a running pentest is scope_expansion and is never auto-approved. Tightening (narrower allow-lists, extra denies, extra forbidden techniques) does not need that gate.

List pending items and decide them from the same engagement surface, or from GET /pentests/{id}/approvals and POST …/approvals/{id}/decide.

Window warnings

If the RoE declares time_windows, the live stream emits window warnings as the close time approaches (thresholds at 60 / 30 / 5 minutes). When the window is closed, the orchestrator stops fail-closed — it does not keep working “just a bit longer.”

Where to go next