Enforcement

Policy engine

Policies answer one question — may this agent reach this endpoint at all? Default-deny, * as the only wildcard, and a specificity score that makes overlapping rules resolve predictably.

Default-deny#

A dispatch is forwarded only if a policy explicitly allows it. No matching policy is a denial, not a fallthrough.

{
  "error": "No policy allows intake-agent -> https://evil.example.com/exfil",
  "status": "BLOCKED_BY_POLICY",
  "transferLogId": "clx8m2p4k0003abcd",
  "policyId": null
}

403, recorded as dispatch.blocked_by_policy, nothing delivered.

The consequence worth internalising: a stolen key on a fresh account is worth nothing. It authenticates, and then it can reach precisely zero endpoints. Every route an attacker could use is a route you deliberately opened, which also means every route is on a list you can audit.

policyId: null distinguishes the two denial reasons — null means nothing matched, a populated id means a policy matched and its action was BLOCK.

Anatomy of a policy#

curl -sS -X POST "$ARCUS_URL/v1/admin/policies" \
  -H "Authorization: Bearer <clerk-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "senderAgentId": "intake-agent",
    "targetEndpoint": "https://api.internal.example.com/webhook/*",
    "action": "ALLOW",
    "dlpEnabled": true
  }'

Wildcards#

* is the only wildcard. It is not a glob and not a regex: it matches any run of characters, including /.

There is deliberately no regex support. A policy language you can misread is a policy language that will eventually allow something you did not intend, and a target pattern is exactly the place where "I thought that anchored" becomes an exfiltration route.

Overlap resolution#

When several enabled policies match, Arcus picks the most specific one by score:

Highest score wins. The ranking is deliberate: an exact sender outranks any target pattern (sender identity is the stronger statement), a literal target outranks a wildcard, and among two literal patterns the longer — more specific — one wins.

Worked example#

Four policies exist:

A dispatch from intake-agent:

The pattern this enables is the useful one: allow broadly, then carve out exceptions with longer, more specific BLOCK policies. D beats C without you having to think about ordering, because specificity does the work.

The three actions#

ALLOW#

Proceed to DLP and guardrails. Surviving those, the dispatch is queued and delivered.

BLOCK#

Refuse with 403 BLOCKED_BY_POLICY and the matching policyId. The payload is never scanned and never delivered.

Use an explicit BLOCK when you want the reason recorded as a deliberate rule rather than as an absence. policyId in the response and in your audit chain then names the exact rule, which is a much better answer to "why was this refused" than "nothing allowed it".

REQUIRE_APPROVAL#

The dispatch is held, not refused:

{
  "ok": true,
  "status": "PENDING_APPROVAL",
  "transferLogId": "clx8m2p4k0004abcd",
  "queued": false
}

202, queued: false. The payload is retained and appears in your approval queue. Nothing is delivered until a human approves it, and if nobody does, nothing ever is.

Note what still runs: a held dispatch has already passed threat detection and identity binding. DLP and guardrails are evaluated too, so a REQUIRE_APPROVAL route carrying a credential is refused with 422 rather than queued for someone to approve by mistake.

See Approval workflow for the review and release path.

Per-route DLP#

Each policy carries dlpEnabled, taken from the winning policy for that dispatch. This is how a route is legitimately exempted from payload scanning.

The honest use case: a route whose entire purpose is moving credential-shaped material — a secret-rotation callback, an internal vault sync. DLP would refuse it correctly and constantly.

{
  "senderAgentId": "rotation-worker",
  "targetEndpoint": "https://vault.internal.example.com/rotate",
  "action": "ALLOW",
  "dlpEnabled": false
}

Turning DLP off does not turn off guardrails, threat detection, identity binding or the audit chain. It disables exactly one gate on exactly the routes that policy wins.

Recommended shapes#

Start closed, open one route. Your first policy should be one sender to one endpoint. The default-deny floor is already the safest configuration you will ever have; every policy you write moves away from it, so each should be deliberate.

One agent, one purpose. billing-agent reaching only payment endpoints and support-agent reaching only ticketing endpoints means a compromise of one is contained to that blast radius. Split by capability, not by convenience.

Environment-specific hosts. https://api.staging.example.com/* and https://api.example.com/* as separate policies — so a staging agent that picks up a production URL is refused rather than obeyed.

A deliberate BLOCK for known-bad shapes. An explicit rule against */admin/* reads better in an audit than the absence of an allow, and it survives someone later widening an allow rule.

[
  { "senderAgentId": "intake-agent",  "targetEndpoint": "https://api.example.com/webhook/*", "action": "ALLOW" },
  { "senderAgentId": "intake-agent",  "targetEndpoint": "https://api.example.com/admin/*",   "action": "BLOCK" },
  { "senderAgentId": "billing-agent", "targetEndpoint": "https://payments.example.com/charge", "action": "REQUIRE_APPROVAL" },
  { "senderAgentId": "*",             "targetEndpoint": "*",                                  "action": "BLOCK" }
]

That last catch-all is redundant — default-deny already refuses — but it makes the intent explicit in the policy list, and it makes every denial name a rule instead of an absence.

Managing policies#

Creating appends policy.created to your audit chain; deleting appends policy.deleted. Both carry the actor. A change to your enforcement rules is itself a governance event, sealed in the same chain as the decisions it affects — so "the policy was different at the time" is a verifiable claim rather than an assertion.

Custom policies require the policy.custom capability (Pro and above). On Free the default-deny floor and all five gates still apply — what Free lacks is the ability to author fine-grained rules of your own. See Pricing & plans.

Testing a policy set#

The cheapest way to check a policy does what you think is to send the dispatch you expect to be refused, and read the reason:

# Should be blocked — a route you did not open
curl -sS -o /dev/null -w '%{http_code}\n' -X POST "$ARCUS_URL/v1/dispatch" \
  -H "Authorization: Bearer $ARCUS_KEY" -H "Content-Type: application/json" \
  -d '{"target":"https://api.example.com/admin/users","from":"intake-agent","message":"probe"}'
# 403

# Should be allowed
curl -sS -o /dev/null -w '%{http_code}\n' -X POST "$ARCUS_URL/v1/dispatch" \
  -H "Authorization: Bearer $ARCUS_KEY" -H "Content-Type: application/json" \
  -d '{"target":"https://api.example.com/webhook/triage","from":"intake-agent","message":"probe"}'
# 202

Both attempts are recorded, which is the point: your audit chain ends up containing the proof that the denial path works, not just the success path.