Policies API¶

The Policies API provides CRUD operations for policy rules that govern agent behavior. Policies define the rules that the policy engine (INV-002) evaluates against every connector operation. Each policy specifies a rule type, connector scope, action pattern, risk threshold, and optional approval channel for escalation.

All endpoints are scoped to the authenticated user's organization via Row-Level Security.

List Policies¶

Retrieves all policy rules for the authenticated user's organization, optionally filtered by agent.

Method: GET
Path: /v1/policies
Required Role: Any authenticated user

Query Parameters¶

Parameter	Type	Required	Description
`agent_id`	`UUID`	No	Filter policies by agent.

Response¶

{
  "policies": [
    {
      "id": "p1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "org_id": "org-uuid",
      "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "block-host-containment",
      "rule_type": "deny",
      "connector": "crowdstrike",
      "action_pattern": "hosts:contain",
      "risk_threshold": 80,
      "approval_channel": "slack:#soc-approvals",
      "created_by": "user-uuid",
      "created_at": "2026-03-20T09:00:00Z",
      "updated_at": "2026-03-20T09:00:00Z"
    }
  ],
  "total": 1
}

Example¶

curl -X GET "https://api.arxsec.io/v1/policies?agent_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {token}"

Create Policy¶

Creates a new policy rule for an agent.

Method: POST
Path: /v1/policies
Required Role: admin

Request Body¶

Field	Type	Required	Description
`agent_id`	`UUID`	Yes	The agent this policy applies to.
`name`	`string`	Yes	Human-readable policy name.
`rule_type`	`string`	Yes	Rule type: `permit`, `deny`, or `escalate`.
`connector`	`string`	Yes	Connector type this rule applies to (e.g., `crowdstrike`).
`action_pattern`	`string`	Yes	Operation pattern to match (e.g., `hosts:contain`, `detections:*`).
`risk_threshold`	`integer`	No	Risk score threshold (0--100) that triggers the rule.
`approval_channel`	`string`	No	Notification channel for escalation (e.g., `slack:#soc-approvals`).

Example¶

curl -X POST "https://api.arxsec.io/v1/policies" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "escalate-host-containment",
    "rule_type": "escalate",
    "connector": "crowdstrike",
    "action_pattern": "hosts:contain",
    "risk_threshold": 70,
    "approval_channel": "slack:#soc-approvals"
  }'

Response¶

Returns the created policy object with HTTP status 201 Created. The creation is audit-logged with the rule type and action pattern.

Update Policy¶

Updates an existing policy rule.

Method: PATCH
Path: /v1/policies/{policy_id}
Required Role: admin

Path Parameters¶

Parameter	Type	Description
`policy_id`	`UUID`	The policy's unique identifier.

Request Body¶

All fields are optional. Only provided fields are updated.

Field	Type	Description
`name`	`string`	Updated policy name.
`rule_type`	`string`	Updated rule type.
`connector`	`string`	Updated connector scope.
`action_pattern`	`string`	Updated action pattern.
`risk_threshold`	`integer`	Updated risk threshold.
`approval_channel`	`string`	Updated approval channel.

Example¶

curl -X PATCH "https://api.arxsec.io/v1/policies/p1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "risk_threshold": 60,
    "approval_channel": "teams:#security-ops"
  }'

Response¶

Returns the updated policy object. Returns 400 if no fields are provided. Returns 404 if the policy is not found.

Delete Policy¶

Deletes a policy rule.

Method: DELETE
Path: /v1/policies/{policy_id}
Required Role: admin

Path Parameters¶

Parameter	Type	Description
`policy_id`	`UUID`	The policy's unique identifier.

Example¶

curl -X DELETE "https://api.arxsec.io/v1/policies/p1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer {token}"

Response¶

Returns HTTP status 204 No Content on success. Returns 404 if the policy is not found. The deletion is audit-logged with the policy name.