Create User-defined Filter

Registers a new user-defined filter. Detection scenarios can reference the registered filter to reuse its condition expression.

Required Permissions

Available to users with the Admin role or higher. The JSON-serialized condition expression is limited to 65,535 characters. The filter name cannot be in GUID format.

HTTP Request

POST /api/sonar/user-defined-filters
cURL Example
curl -H "Authorization: Bearer <API_KEY>" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
           "name": "Internal maintenance exclusion",
           "description": "Exclude internal traffic during scheduled maintenance",
           "predicate": {
             "type": "AND",
             "args": [
               {
                 "type": "EQ",
                 "args": [
                   { "type": "FIELD", "value": "src_ip" },
                   { "type": "VALUE", "value": "192.0.2.10" }
                 ]
               },
               {
                 "type": "STARTS_WITH",
                 "args": [
                   { "type": "FIELD", "value": "host" },
                   { "type": "VALUE", "value": "intra-" }
                 ]
               }
             ]
           }
         }' \
     https://HOSTNAME/api/sonar/user-defined-filters
Request Parameters
KeyRequiredTypeDescriptionNotes
guidNoStringUser-defined filter GUIDGenerated automatically when omitted. 36-character GUID
nameYesStringFilter nameCannot be in GUID format
descriptionNoStringFilter description
predicateYesString mapCondition expressionTree of node and leaf expression objects

predicate object properties

The condition expression is composed of node expressions and leaf expressions.

  • Common properties
    • type (String, required): Expression type
    • comment (String): Comment for the expression
  • Leaf expression (when type is VALUE or EXPR)
    • value (String|Number): Expression value. VALUE carries a literal used for comparison, while EXPR carries a query expression string
  • Node expression (other type values)
    • args (Array, required): Child expressions

When type is FIELD, set the field name in value. FIELD is used as a leaf operand of comparison nodes.

The supported type values and their child structures are listed below.

CategorytypeChild structure
LeafVALUE, EXPR, FIELDUses value; args is absent
UnaryNOT, IS_NULL, IS_NOT_NULLOne element in args
ComparisonEQ, NEQ, GT, GTE, LT, LTETwo elements in args (left FIELD, right VALUE or expr.)
StringSTARTS_WITH, ENDS_WITH, CONTAINSTwo elements in args
SetINTwo or more elements in args (left FIELD, right VALUE x N)
LogicalAND, ORTwo or more elements in args
Group ref.SUBNET_GROUP, PATTERN_GROUP, ADDRESS_GROUP, PORT_GROUPTwo elements in args (left FIELD, right group identifier)

Success Response

{}

Error Responses

Required argument is missing

HTTP status code 400

{
  "error_code": "null-argument",
  "error_msg": "name should be not null"
}
Filter name is in GUID format

HTTP status code 500

{
  "error_code": "illegal-argument",
  "error_msg": "user-defined filter name cannot be guid format"
}
Filter with the same name already exists

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "udf name exists"
}
Expression type is missing

HTTP status code 500

{
  "error_code": "illegal-argument",
  "error_msg": "type should be not null."
}
Expression children are missing

HTTP status code 500

{
  "error_code": "illegal-argument",
  "error_msg": "args should be not null."
}
Condition expression exceeds 65,535 characters

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "Exceeded maximum character limit: max=65535, actual=70000"
}
Condition expression cannot be serialized

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "cannot jsonize predicate of udf Internal maintenance exclusion"
}
No permission

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "no-permission"
}