Policies Api Attach Rule

Policies Api Attach Rule
Attach a Rule to a Policy

Appends the Rule at sequence max+1. 409 RULE_ALREADY_ATTACHED when already attached, 409 RULE_RETIRED for a retired Built-in Rule. Requires the ADMIN or SECURITY_OPERATOR role.

Request
URI
POST
https://{api_host}/api/v1/policies/{id}/rules
COPY
Path Parameters
integer
id
Required  

Policy id

id example
3

Request Body

The Rule to attach.

AttachRuleRequest of type(s) application/json
Required  

Show optional properties

{
    "ruleId": 0
}
{
    "ruleId": 31
}
integer As int64 As int64
ruleId
Required  

Identifier of the rule to attach, placed after the Policy's last rule. A rule that does not exist is 404 RULE_NOT_FOUND; one already attached is 409 RULE_ALREADY_ATTACHED; a retired Built-in Rule cannot be newly attached; a Policy holds at most 500 rules (POLICY_RULE_LIMIT_EXCEEDED)

Authentication
This operation uses the following authentication methods.
Responses
201

201 Created successful response envelope. The created attachment

Returns PolicyRuleDto of type(s) application/json
{
    "policyId": 3,
    "ruleId": 31,
    "ruleName": "Require MFA for SSH",
    "ruleType": "MFA",
    "action": "MFA_REQUIRED",
    "ruleRank": "CUSTOM_LOCAL",
    "isBuiltIn": false,
    "isEnabled": true,
    "description": "Asks the Production Operators for a second factor",
    "matchData": "{\"user_group_ids\":[1]}",
    "revision": 1,
    "updatedAt": "2026-01-12T08:00:00Z",
    "sequence": 3
}
integer As int64 As int64
policyId
Required  

Identifier of the Policy the rule is attached to

integer As int64 As int64
ruleId
Required  

Identifier of the attached rule

string
ruleName
Required  

Current name of the attached rule

string
ruleType
Required  

Rule type code of the attached rule: PATH_FILE_CMD, HASH, PUBLISHER_SIGNING, MFA, ANTI_TAMPER or VIB_REPUTATION in this release; further codes are added by new releases; an empty string when the Rule cannot be resolved

string
action
Required  

Default verdict of a Rule. MFA_REQUIRED is accepted only for ruleType MFA (any other type is refused with 400 INVALID_RULE_ACTION).

  • ALLOW: The operation is permitted
  • BLOCK: The operation is aborted with -EPERM
  • AUDIT: The operation is logged and alerted, and execution is permitted
  • MFA_REQUIRED: Triggers an interactive TOTP challenge through PAM; accepted only for ruleType MFA
Enumeration: ALLOW, BLOCK, AUDIT, MFA_REQUIRED
string
ruleRank
Required  

Evaluation rank: CUSTOM_LOCAL (custom rules) first, then CUSTOM_GLOBAL (SHA-256 rules created from the file catalog), then VIRTUAL_PATCHING, then DEFAULT_ATTACK. It decides the order rules are sent to the agent, ahead of Policy stack rank and sequence.

  • UNSPECIFIED: Built-in Rules from a Rule Pack whose vendor rank is unset
  • CUSTOM_LOCAL: Custom rules created on the Rules page; the default for a Custom Rule and the highest priority. Rule ids 1 to 999,999
  • CUSTOM_GLOBAL: Custom SHA-256 rules created from the file catalog, evaluated after CUSTOM_LOCAL. Rule ids 1,000,000 to 9,999,999
  • VIRTUAL_PATCHING: Built-in Rules from a Rule Pack, evaluated after CUSTOM_GLOBAL. Rule ids 10,000,000 to 99,999,999
  • DEFAULT_ATTACK: Built-in Rules from a Rule Pack, evaluated last. Rule ids 100,000,000 to 999,999,999
Enumeration: UNSPECIFIED, CUSTOM_LOCAL, CUSTOM_GLOBAL, VIRTUAL_PATCHING, DEFAULT_ATTACK
boolean
isBuiltIn
Required  

True for a Built-in Rule installed from a Rule Pack; its matchData is then not returned

boolean
isEnabled
Required  

Current enabled state of the attached rule (always true for a Built-in Rule). A disabled rule stays attached but is not compiled, so the next Policy publish leaves it out; GET /api/v1/policies/{id}/pending-changes tells whether the published snapshot still carries it

string
description
Optional

Description of the attached rule. Null when it has none

string
matchData
Optional

JSON-encoded rule match criteria. Null for built-in system rules.

integer As int32 As int32
revision
Required  

Current revision of the Rule

string As date-time As date-time
updatedAt
Required  

When the Rule was last modified

integer As int32 As int32
sequence
Required  

Position of the rule within the Policy, starting at 1; the Publish compiler orders a Policy's rules by it and the agent stops at the first match, so it is not cosmetic. Attaching a rule gives it the highest sequence plus 1; reorder and sync renumber from 1 in the order given


400

400 Bad Request: INVALID_RULE_ID, MALFORMED_REQUEST or POLICY_RULE_LIMIT_EXCEEDED. POLICY_RULE_LIMIT_EXCEEDED when the Policy already has 500 Rules attached

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


401

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


403

403 Forbidden: FORBIDDEN or CSRF_ERROR. CSRF_ERROR when the X-XSRF-TOKEN header is missing or wrong on a POST, PUT, PATCH or DELETE (only POST /api/v1/auth/login is exempt, and a request without a valid session gets 401 UNAUTHENTICATED instead); PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt); LICENSE_REQUIRED or LICENSE_EXPIRED while the license pool is restricted (no license, or expired past grace) (exempt: every route under /api/v1/auth, GET /api/v1/user/preferences, GET /api/v1/licensing/summary and POST /api/v1/licensing/licenses)

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


404

404 Not Found: POLICY_NOT_FOUND or RULE_NOT_FOUND

Returns ApiErrorResponse of type(s) application/json
"ApiErrorResponse Object"
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


409

409 Conflict: RULE_ALREADY_ATTACHED or RULE_RETIRED

Returns ApiErrorResponse of type(s) application/json
"ApiErrorResponse Object"
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    curl -X POST -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"ruleId":"integer"}' https://{api_host}/api/v1/policies/{id}/rules