Detection Rules

API for managing detection rules including CRUD operations for security policies, compliance metadata, and rule configurations.

Create Detection Rule

post

Creates a new detection rule with the specified configuration including name, severity, query, and compliance metadata. The rule will be validated and persisted if all required fields are provided correctly.

Header parameters

x-xdr-auth-idstringRequired

api_key_id authentication identifier

Example: 123

Body

Request body for creating a detection rule

namestring · max: 255Required

Unique rule name

Example: GCP BigQuery Table not encrypted with CMEKPattern: \S

descriptionstring · max: 2000Optional

Detailed rule description

Example: This policy identifies GCP BigQuery tables...

classstringOptional

Rule class - Must be 'config' (CSPM)

Example: configPattern: \S

typestringOptional

Rule type - Must be 'DETECTION' (can be inferred if not provided)

Example: DETECTION

asset_typesstring[] · min: 1 · max: 1Required

Array with single asset type identifier (exactly one required)

Example: ["gcp-bigquery-dataset"]

severitystringRequired

Rule severity (low, medium, high, critical, informational)

Example: highPattern: \S

labelsstring[] · max: 50Optional

Custom labels (max 50, each max 100 chars)

Example: ["Custom Rule","Security"]

enabledbooleanOptional

Rule enabled status (default: true)

Example: true

Responses

201

Rule successfully created

application/json

Response for rule operations

idstringOptional

Unique rule identifier

Example: c053f2b7-a106-4550-9f9e-6272e5a45a04

namestringOptional

Rule name

Example: GCP BigQuery Table not encrypted with CMEK

descriptionstringOptional

Rule description

Example: This policy identifies GCP BigQuery tables...

rule_classstringOptional

Rule class

Example: config

typestringOptional

Rule type

Example: DETECTION

providersstring[]Optional

Cloud providers (derived from asset_types)

Example: ["gcp"]

asset_typesstring[]Optional

Array of asset type identifiers

Example: ["gcp-bigquery-dataset"]

severitystringOptional

Rule severity

Example: high

labelsstring[]Optional

Custom labels

Example: ["Custom Rule","Encryption"]

enabledbooleanOptional

Rule enabled status

Example: true

system_defaultbooleanOptional

System default rule indicator

created_bystringOptional

Creator identifier

Example: [e-mail]

created_oninteger · int64Optional

Creation timestamp (epoch milliseconds)

Example: 1733452350456

last_modified_bystringOptional

Last modifier

Example: [e-mail]

last_modified_oninteger · int64Optional

Last modification timestamp (epoch milliseconds)

Example: 1733452350456

deletedbooleanOptional

Deletion status

Example: true

deleted_atinteger · int64Optional

Deletion timestamp (epoch milliseconds)

Example: 1733552350456

deleted_bystringOptional

User who deleted the rule

Example: [e-mail]

400

Bad Request - Invalid parameters

application/json

401

Unauthorized

403

Forbidden

409

Conflict - Rule with same name already exists

application/json

429

Too Many Requests

500

Internal Server Error

application/json

502

Bad Gateway

503

Service Unavailable

post/public_api/v1/rule

POST /public_api/v1/rule HTTP/1.1
Host: api-cortex.paloaltonetworks.com
x-xdr-auth-id: text
Content-Type: application/json
Accept: */*
Content-Length: 657

{
  "name": "AWS S3 Bucket with Public Access",
  "description": "Identifies S3 buckets that allow public access",
  "rule_class": "config",
  "asset_types": [
    "aws-s3-bucket"
  ],
  "severity": "high",
  "query": {
    "xql": "dataset = cloud_resource_inventory | filter cloud_provider = \"AWS\" and asset_type = \"AWS::S3::Bucket\" | filter json_extract(config, \"$.acl.grants[*].grantee.uri\") contains \"AllUsers\" | fields asset_id, asset_name, cloud_account_id, region"
  },
  "metadata": {
    "issue": {
      "recommendation": "Remove public access from the S3 bucket by updating the bucket ACL..."
    }
  },
  "compliance_metadata": [
    {
      "control_id": "CIS-AWS-2.1.5"
    }
  ],
  "labels": [
    "S3",
    "Public Access"
  ],
  "enabled": true
}

{
  "id": "c053f2b7-a106-4550-9f9e-6272e5a45a04",
  "name": "GCP BigQuery Table not encrypted with CMEK",
  "description": "This policy identifies GCP BigQuery tables that are not encrypted with Customer Managed Encryption Keys (CMEK)",
  "rule_class": "config",
  "type": "DETECTION",
  "providers": [
    "gcp"
  ],
  "asset_types": [
    "gcp-bigquery-dataset"
  ],
  "severity": "high",
  "query": {
    "xql": "dataset = cloud_resource_inventory | filter cloud_provider = \"GCP\" and asset_type = \"GCP::BigQuery::Table\" | filter json_extract(config, \"$.encryptionConfiguration.kmsKeyName\") = null | fields asset_id, asset_name, cloud_account_id, region"
  },
  "metadata": {
    "issue": {
      "recommendation": "To configure a Customer-managed encryption key (CMEK) for BigQuery Table, follow the steps..."
    }
  },
  "compliance_metadata": [
    {
      "standard_name": "Health Insurance Portability and Accountability Act",
      "control_id": "164.312(a)(2)(iv)",
      "control_name": "Encryption and Decryption"
    },
    {
      "standard_name": "Payment Card Industry Data Security Standard",
      "control_id": "3.5.1",
      "control_name": "Protect encryption keys"
    }
  ],
  "labels": [
    "Custom Rule",
    "Encryption"
  ],
  "enabled": true,
  "system_default": false,
  "created_by": "[e-mail]",
  "created_on": 1733452350456,
  "last_modified_by": "[e-mail]",
  "last_modified_on": 1733452350456
}

Get Detection Rules

post

Searches for detection rules based on filter criteria with support for pagination and sorting. Returns a list of rules matching the specified filters.

Header parameters

x-xdr-auth-idstringRequired

api_key_id authentication identifier

Example: 123

Body

Request body for querying detection rules

search_frominteger · int32Optional

Offset index for pagination

search_tointeger · int32 · max: 1000Optional

Ending index for pagination. The default is 100, and it can be up to 1000. For example, when search_from is 10 and search_to is 100, the API retrieves results from index 10 through 100.

Default: 100Example: 100

Responses

200

OK

application/json

Response containing a list of detection rules with metadata

400

Bad Request

application/json

401

Unauthorized

403

Forbidden

404

Not Found

application/json

429

Too many requests

500

Internal Server Error

application/json

502

Bad Gateway

503

Service Unavailable

post/public_api/v1/rule/search

POST /public_api/v1/rule/search HTTP/1.1
Host: api-cortex.paloaltonetworks.com
x-xdr-auth-id: text
Content-Type: application/json
Accept: */*
Content-Length: 375

{
  "filter": {
    "OR": [
      {
        "SEARCH_FIELD": "id",
        "SEARCH_TYPE": "EQ",
        "SEARCH_VALUE": "4f900112-eb70-490e-a867-63a31769a786"
      },
      {
        "SEARCH_FIELD": "id",
        "SEARCH_TYPE": "EQ",
        "SEARCH_VALUE": "1236bf26-18d5-4393-885d-e828115f5836"
      },
      {
        "SEARCH_FIELD": "id",
        "SEARCH_TYPE": "EQ",
        "SEARCH_VALUE": "e928a48c-c734-4d89-895f-24220616c2ef"
      }
    ]
  },
  "search_from": 0,
  "search_to": 50,
  "sort": [
    {
      "FIELD": "name",
      "ORDER": "ASC"
    }
  ]
}

{
  "data": [
    {
      "id": "19403de7-0b16-476f-97c1-2e15ffcb9ab4",
      "name": "Authorization bypass risk due to a publicly exposed Azure Virtual Machine with an unauthorized Docker API access vulnerability (Docker, CVE-2024-41110)",
      "description": "Publicly exposed Azure Virtual Machines with unauthorized Docker API access (CVE-2024-41110) pose a significant authorization bypass risk, enabling attackers to execute arbitrary commands and escalate privileges.",
      "class": "config",
      "module": "CSPM",
      "asset_types": [
        "azure-vm"
      ],
      "severity": "critical",
      "enabled": true,
      "system_default": true,
      "provider": "azure",
      "type": "config",
      "compliance_metadata": [
        {
          "standard_name": "CIS Microsoft Azure Foundations Benchmark",
          "control_id": "7.1",
          "control_name": "Ensure that 'OS and Data' disks are encrypted with CMK"
        }
      ],
      "labels": [
        "Cloud Security"
      ],
      "created_by": "John Doe",
      "created_on": 1756934040224,
      "last_modified_by": "Cortex System Admin",
      "last_modified_on": 1756934040224
    }
  ],
  "metadata": {
    "filter_count": 1213,
    "total_count": 1213
  }
}

Get Rule By Id

get

Retrieves a specific detection rule by its unique identifier. Returns the complete rule configuration including query, compliance metadata, and labels.

Path parameters

idstringRequired

Unique identifier of the detection rule to retrieve

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Header parameters

x-xdr-auth-idstringRequired

api_key_id authentication identifier

Example: 123

Responses

200

Rule successfully retrieved

application/json

Response for rule operations

idstringOptional

Unique rule identifier

Example: c053f2b7-a106-4550-9f9e-6272e5a45a04

namestringOptional

Rule name

Example: GCP BigQuery Table not encrypted with CMEK

descriptionstringOptional

Rule description

Example: This policy identifies GCP BigQuery tables...

rule_classstringOptional

Rule class

Example: config

typestringOptional

Rule type

Example: DETECTION

providersstring[]Optional

Cloud providers (derived from asset_types)

Example: ["gcp"]

asset_typesstring[]Optional

Array of asset type identifiers

Example: ["gcp-bigquery-dataset"]

severitystringOptional

Rule severity

Example: high

labelsstring[]Optional

Custom labels

Example: ["Custom Rule","Encryption"]

enabledbooleanOptional

Rule enabled status

Example: true

system_defaultbooleanOptional

System default rule indicator

created_bystringOptional

Creator identifier

Example: [e-mail]

created_oninteger · int64Optional

Creation timestamp (epoch milliseconds)

Example: 1733452350456

last_modified_bystringOptional

Last modifier

Example: [e-mail]

last_modified_oninteger · int64Optional

Last modification timestamp (epoch milliseconds)

Example: 1733452350456

deletedbooleanOptional

Deletion status

Example: true

deleted_atinteger · int64Optional

Deletion timestamp (epoch milliseconds)

Example: 1733552350456

deleted_bystringOptional

User who deleted the rule

Example: [e-mail]

400

Bad Request - Invalid ID format

application/json

401

Unauthorized

403

Forbidden

404

Not Found - Rule does not exist

application/json

429

Too Many Requests

500

Internal Server Error

application/json

502

Bad Gateway

503

Service Unavailable

get/public_api/v1/rule/{id}

GET /public_api/v1/rule/{id} HTTP/1.1
Host: api-cortex.paloaltonetworks.com
x-xdr-auth-id: text
Accept: */*

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "AWS S3 Bucket with Public Access",
  "description": "Identifies S3 buckets that allow public access",
  "rule_class": "config",
  "type": "DETECTION",
  "providers": [
    "aws"
  ],
  "asset_types": [
    "aws-s3-bucket"
  ],
  "severity": "high",
  "query": {
    "xql": "dataset = cloud_resource_inventory | filter cloud_provider = \"AWS\" and asset_type = \"AWS::S3::Bucket\" | filter json_extract(config, \"$.acl.grants[*].grantee.uri\") contains \"AllUsers\" | fields asset_id, asset_name, cloud_account_id, region"
  },
  "metadata": {
    "issue": {
      "recommendation": "Remove public access from the S3 bucket by updating the bucket ACL..."
    }
  },
  "compliance_metadata": [
    {
      "standard_name": "CIS Amazon Web Services Foundations Benchmark",
      "control_id": "2.1.5",
      "control_name": "Ensure S3 buckets are configured with Block public access"
    }
  ],
  "labels": [
    "S3",
    "Public Access"
  ],
  "enabled": true,
  "system_default": false,
  "created_by": "[e-mail]",
  "created_on": 1733452350456,
  "last_modified_by": "[e-mail]",
  "last_modified_on": 1733452350456
}

Delete Detection Rule

delete

Permanently deletes a detection rule by its unique identifier. This action cannot be undone. Only custom rules can be deleted; system default rules cannot be removed.

Path parameters

idstringRequired

Unique identifier of the detection rule to delete

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Header parameters

x-xdr-auth-idstringRequired

api_key_id authentication identifier

Example: 123

Responses

204

Rule successfully deleted (no content)

No content

400

Bad Request - Invalid ID format

application/json

401

Unauthorized

403

Forbidden

404

Not Found - Rule does not exist

application/json

429

Too Many Requests

500

Internal Server Error

application/json

502

Bad Gateway

503

Service Unavailable

delete/public_api/v1/rule/{id}

DELETE /public_api/v1/rule/{id} HTTP/1.1
Host: api-cortex.paloaltonetworks.com
x-xdr-auth-id: text
Accept: */*

No content

Update Detection Rule

patch

Updates an existing detection rule with the provided fields. Only the fields included in the request body will be updated. The rule_class field is required for validation.

Path parameters

idstringRequired

Unique identifier of the detection rule to update

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Header parameters

x-xdr-auth-idstringRequired

api_key_id authentication identifier

Example: 123

Body

Request body for updating a detection rule

namestring · max: 255Optional

Rule name (must be unique if changed)

Example: Updated AWS S3 Bucket Rule

descriptionstring · max: 2000Optional

Rule description

Example: Updated description...

rule_classstringRequired

Rule class - Must be 'config' (CSPM)

Example: config

typestringOptional

Rule type - Must be 'DETECTION'

Example: DETECTION

asset_typesstring[] · min: 1 · max: 1Optional

Array with single asset type identifier (exactly one if provided)

Example: ["aws-s3-bucket"]

severitystringOptional

Rule severity (low, medium, high, critical, informational)

Example: high

labelsstring[] · max: 50Optional

Custom labels (max 50, each max 100 chars)

Example: ["Updated","Security"]

enabledbooleanOptional

Rule enabled status

Example: true

Responses

200

Rule successfully updated

application/json

Response for rule operations

idstringOptional

Unique rule identifier

Example: c053f2b7-a106-4550-9f9e-6272e5a45a04

namestringOptional

Rule name

Example: GCP BigQuery Table not encrypted with CMEK

descriptionstringOptional

Rule description

Example: This policy identifies GCP BigQuery tables...

rule_classstringOptional

Rule class

Example: config

typestringOptional

Rule type

Example: DETECTION

providersstring[]Optional

Cloud providers (derived from asset_types)

Example: ["gcp"]

asset_typesstring[]Optional

Array of asset type identifiers

Example: ["gcp-bigquery-dataset"]

severitystringOptional

Rule severity

Example: high

labelsstring[]Optional

Custom labels

Example: ["Custom Rule","Encryption"]

enabledbooleanOptional

Rule enabled status

Example: true

system_defaultbooleanOptional

System default rule indicator

created_bystringOptional

Creator identifier

Example: [e-mail]

created_oninteger · int64Optional

Creation timestamp (epoch milliseconds)

Example: 1733452350456

last_modified_bystringOptional

Last modifier

Example: [e-mail]

last_modified_oninteger · int64Optional

Last modification timestamp (epoch milliseconds)

Example: 1733452350456

deletedbooleanOptional

Deletion status

Example: true

deleted_atinteger · int64Optional

Deletion timestamp (epoch milliseconds)

Example: 1733552350456

deleted_bystringOptional

User who deleted the rule

Example: [e-mail]

400

Bad Request - Invalid parameters

application/json

401

Unauthorized

403

Forbidden

404

Not Found - Rule does not exist

application/json

409

Conflict - Name already exists

application/json

429

Too Many Requests

500

Internal Server Error

application/json

502

Bad Gateway

503

Service Unavailable

patch/public_api/v1/rule/{id}

PATCH /public_api/v1/rule/{id} HTTP/1.1
Host: api-cortex.paloaltonetworks.com
x-xdr-auth-id: text
Content-Type: application/json
Accept: */*
Content-Length: 840

{
  "name": "Updated AWS S3 Bucket Policy",
  "description": "Updated description for S3 bucket policy",
  "rule_class": "config",
  "type": "DETECTION",
  "asset_types": [
    "aws-s3-bucket"
  ],
  "severity": "critical",
  "query": {
    "xql": "dataset = cloud_resource_inventory | filter cloud_provider = \"AWS\" and asset_type = \"AWS::S3::Bucket\" | filter json_extract(config, \"$.acl.grants[*].grantee.uri\") contains \"AllUsers\" | fields asset_id, asset_name, cloud_account_id, region, config"
  },
  "metadata": {
    "issue": {
      "recommendation": "Updated remediation steps:\n1. Login to AWS Console\n2. Navigate to S3\n3. Select the bucket\n4. Go to Permissions tab\n5. Edit Block Public Access settings\n6. Enable all Block Public Access options"
    }
  },
  "compliance_metadata": [
    {
      "control_id": "CIS-AWS-2.1.5"
    },
    {
      "control_id": "NIST-AC-3"
    }
  ],
  "labels": [
    "Updated",
    "S3",
    "Critical"
  ],
  "enabled": true
}

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Updated AWS S3 Bucket Policy",
  "description": "Updated description for S3 bucket policy",
  "rule_class": "config",
  "type": "DETECTION",
  "providers": [
    "aws"
  ],
  "asset_types": [
    "aws-s3-bucket"
  ],
  "severity": "critical",
  "query": {
    "xql": "dataset = cloud_resource_inventory | filter cloud_provider = \"AWS\" and asset_type = \"AWS::S3::Bucket\" | filter json_extract(config, \"$.acl.grants[*].grantee.uri\") contains \"AllUsers\" | fields asset_id, asset_name, cloud_account_id, region"
  },
  "metadata": {
    "issue": {
      "recommendation": "Updated remediation steps..."
    }
  },
  "compliance_metadata": [
    {
      "standard_name": "CIS Amazon Web Services Foundations Benchmark",
      "control_id": "2.1.5",
      "control_name": "Ensure S3 buckets are configured with Block public access"
    }
  ],
  "labels": [
    "Updated",
    "S3",
    "Critical"
  ],
  "enabled": true,
  "system_default": false,
  "created_by": "[e-mail]",
  "created_on": 1733452350456,
  "last_modified_by": "[e-mail]",
  "last_modified_on": 1733552350456
}