Rules Api Update Rule

Rules Api Update Rule
Edit a Custom Rule

Edits a Custom Rule's own content. 409 BUILT_IN_RULE_IMMUTABLE for a Built-in Rule. For a file-catalog rule (CUSTOM_GLOBAL) the SHA-256 cannot change: 409 RULE_HASH_LOCKED. A matchData longer than 8192 characters is 400 INVALID_MATCH_DATA. Saving the values the Rule already has (after the name and description are trimmed and matchData is normalized) changes nothing: 200 with the Rule as it is, the same revision, its Policies keep their published state and no RULE_UPDATE audit record is written. Requires the ADMIN or SECURITY_OPERATOR role.

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

Id of the catch-all rule the administrator authored

id example
12

Request Body

The Rule content to save: name, description, matchData and action. A Built-in Rule cannot be edited, and the SHA-256 of a file-catalog Rule cannot change.

UpdateRuleRequest of type(s) application/json
Required  

Show optional properties

{
    "name": "string",
    "matchData": "string",
    "action": "string"
}
{
    "name": "Block Unapproved Scripts",
    "description": "Blocks scripts executed from the temporary directories",
    "matchData": "{\"target_path\":\"/tmp/\",\"match_mode\":\"PREFIX\",\"allowed_ops\":[\"EXECUTE\"],\"is_directory_recursive\":true}",
    "action": "BLOCK"
}
string
name
Required  
Constraints: minLength: 1 maxLength: 255

The new name, validated as on create; the character check is skipped when the trimmed name equals the stored one

string
description
Optional
Constraints: maxLength: 2000

Replaces the description with the same limits as on create; absent or null clears it

string
matchData
Required  
Constraints: maxLength: 8192

Replaces the match criteria, validated for the rule's own type, which cannot be changed; at most 8192 characters (INVALID_MATCH_DATA when longer or invalid). For PATH_FILE_CMD, target_path and process_path must be absolute (start with '/') for match_mode PREFIX; each '|' part of a GLOB must start with '/', '', '?' or '{'; a REGEX must be a valid ECMAScript regular expression. With match_mode EXACT or absent, a value is read as the Agent reads it: a regex when it holds a regex metacharacter, else a glob when it holds '' or '?', else an exact path that must be absolute. argv_pattern and arg_pattern must be valid regular expressions when match_mode is REGEX or they hold a regex metacharacter. 'any' and '*' match anything (INVALID_MATCH_DATA otherwise)

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
Authentication
This operation uses the following authentication methods.
Responses
200

200 OK successful response envelope. The updated Rule

Returns RuleDto of type(s) application/json
{
    "ruleId": 12,
    "name": "Block Unapproved Scripts",
    "description": "Blocks scripts executed from the temporary directories",
    "ruleType": "PATH_FILE_CMD",
    "matchData": "{\"target_path\":\"/tmp/\",\"match_mode\":\"PREFIX\",\"allowed_ops\":[\"EXECUTE\"],\"is_directory_recursive\":true}",
    "action": "BLOCK",
    "ruleRank": "CUSTOM_LOCAL",
    "minAgentVersion": "1.0.0",
    "guid": "00000000-0000-4000-8000-000000000012",
    "isEnabled": true,
    "isBuiltIn": false,
    "revision": 2,
    "createdBy": 1,
    "updatedBy": 2,
    "policyCount": 2,
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T11:00:00Z"
}
integer As int64 As int64
ruleId
Required  

Identifier of the rule, never changed. A Custom Rule gets it from the Console (CUSTOM_LOCAL 1 to 999,999, CUSTOM_GLOBAL 1,000,000 to 9,999,999); a Built-in Rule gets it from its Rule Pack (VIRTUAL_PATCHING 10,000,000 to 99,999,999, DEFAULT_ATTACK and UNSPECIFIED 100,000,000 to 999,999,999)

string
name
Required  

A Custom Rule's name is stored trimmed and differs from every other Rule's name ignoring case

string
description
Optional

Free text; a Custom Rule's text is stored trimmed, at most 2,000 characters, and a whitespace-only text is stored as an empty string. Null when none was given

string
ruleType
Required  

Rule type code, the key of a rule type catalog entry: PATH_FILE_CMD, HASH, PUBLISHER_SIGNING, MFA, ANTI_TAMPER or VIB_REPUTATION in this release; further codes are added by new releases; fixed when the rule is created

string
matchData
Optional

JSON-encoded rule match criteria. Null for built-in system rules to prevent detection evasion.

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
string
minAgentVersion
Required  

Never admin-supplied: stamped from the rule type's catalog baseline or a Rule Pack's metadata

string As uuid As uuid
guid
Required  

Generated once on first insert; read-only, for correlation with the agent's rule header

boolean
isEnabled
Required  

Whether the rule is enabled. A new Custom Rule starts enabled; a Built-in Rule is always enabled and cannot be disabled

boolean
isBuiltIn
Required  

True for a rule installed from a Rule Pack, false for a rule created through the API. A Built-in Rule cannot be edited or deleted

integer As int32 As int32
revision
Required  

Starts at 1 and grows by 1 each time the rule's content or enabled state changes; a Rule Pack update or retirement of a Built-in Rule also advances it

integer As int64 As int64
createdBy
Optional

Identifier of the user who created the rule, or for a Built-in Rule of the administrator who installed its pack. Null when no user is recorded, as for a rule installed by the first-boot system install

integer As int64 As int64
updatedBy
Optional

Identifier of the user who last changed the rule (edit, enable or disable, Rule Pack update or retirement). Null when no user is recorded

integer As int64 As int64
policyCount
Required  

Number of Policies the Rule is attached to

string As date-time As date-time
createdAt
Required  

When the rule was created, as an ISO 8601 date-time with offset; never changes

string As date-time As date-time
updatedAt
Required  

When the rule was last updated, as an ISO 8601 date-time with offset


400

400 Bad Request: INVALID_RULE_NAME, DUPLICATE_RULE_NAME, INVALID_RULE_ACTION, INVALID_MATCH_DATA, UNKNOWN_USER_GROUP or MALFORMED_REQUEST

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: 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: BUILT_IN_RULE_IMMUTABLE or RULE_HASH_LOCKED

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 PUT -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{"name":"string","matchData":"string","action":"string"}' https://{api_host}/api/v1/rules/{id}