Skip to main content

REST APIs 25.1.0

Showing Rule ID in Syslog

For large customers handling 10K+ messages per second, including rule IDs in the Syslog events will substantially increase the volume of recorded data.

New Feature: Added the organization-level feature flag rule_info_exposure_to_syslog (disabled by default) in release 25.1.0. This flag controls whether rule ID information is included in syslog messages.

Adding the Rule ID to Syslog Events

To add the rule IDs to the syslog events, the API optional_features_put was changed by adding the new property rule_info_exposure_to_syslog:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "oneOf": [
      {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "enabled"
        ],
        "properties": {
          "name": {
            "description": "Name of the feature",
            "type": "string",
            "enum": [
              "ip_forwarding_firewall_setting",
              "ui_analytics",
              "illumination_classic",
              "ransomware_readiness_dashboard",
              "per_rule_flow_log_setting",
              "lightning_default",
              "collector_scanner_filters",
              "corporate_ips_groups",
              "labels_editing_warning_for_enforcement_mode",
              "label_based_network_detection",
              "cloudsecure_enabled",
              "windows_outbound_process_enforcement",
              "rule_based_label_mapping",
              "core_insights",
              "rule_info_exposure_to_syslog"
            ]
  ==============================================

To enable this feature flag, set the firewall_settings.enable_all_rule_hit_count_enabled option. This will instruct the VEN to send the rule IDs and the traffic flow payload to the PCE.

PUT /api/v2/orgs/:org_id/optional_features
payload
[  
    {    
        name: "rule_info_exposure_to_syslog",    
        enabled: true  
    }
[
Enabling the Rule Data

Before implementing the property rule_info_exposure_to_syslog , you must update the firewall settings and set the flag enable_all_rule_hit_count_enabled=true;.

This can be done in several ways: using SQL commands, API, or PCE console.

Setting the flag via the PCE console is explained in Events Administration Guide, Showing Rule ID in Syslog.

To set the flag enable_all_rule_hit_count_enabled via API, use the following command:

curl -u api_${ILO_API_KEY_ID}:${ILO_API_KEY_SECRET} -H "Content-Type: application/json" -X PUT -d '{"rule_hit_count_enabled_scopes": [[]]}' https://${ILO_SERVER}/api/v2/orgs/${ILO_ORG_ID}/sec_policy/draft/firewall_settings
Formatting the Rule Data

The rule data is organized into rule sets to prevent excessive data from logging into Syslog, with an extra field indicating the rule type.

This organization enables the user to combine the rule set href, rule type, and the relevant rule ID to make an API request for rule details.

The prerequisites for implementation are as follows:

  • Syslog logging is managed by the organization-level feature flag set in the firewall_settings.enable_all_rule_hit_count_enabled column.

  • The fields in the syslog_destinations table determine the information that can be logged into Syslog.

An example of a message indicating six allow rules from two different rulesets.

{  
    "rules": [    
        { "rule_set": "/orgs/1/sec_policy/active/rule_sets_123", "rule_ids": [2,3,4] },    
        { "rule_set": "/orgs/1/sec_policy/active/rule_sets_789", "rule_ids": [12,13,14]}  
    ],  
    "rule_type": "allow"
}

An example of a deny rule

{  
    "rules": [    
        { "rule_set": "/orgs/1/sec_policy/active/rule_sets/123", "rule_ids": [5,6,7] },    
        { "rule_set": "/orgs/1/sec_policy/active/rule_sets/789", "rule_ids": [122,133]}  
    ],  
    "rule_type": "deny"
}

An example in JSON format of a record for a single potentially blocked syslog event

{  
    "tdms":30004,  
    "ddms":30004,  
    "un":"root",  
    "src_ip":"192.200.33.4",  
    "dst_ip":"192.200.33.3",  
    "class":"U",  
    "proto":6,  
    "dst_port":7777,  
    "count":1,  
    "dir":"O",  
    "org_id":1,  
    "timestamp":"2024-11-05T16:10:42Z",  
    "state":"C",  
    "pd_qualifier":2,  
    "pd":1,  
    "rules": [    
        { "rule_set": "/orgs/1/sec_policy/active/rule_sets/123", "rule_ids": [5,6,7] },    
        { "rule_set": "/orgs/1/sec_policy/active/rule_sets/789", "rule_ids": [122,133]}  ],  
    "rule_type": "deny",  
    "src_hostname":"server1",  
    "src_href":"/orgs/1/workloads/9d436e4f-0c21-4817-9abb-28a5249e5120",  
    "dst_hostname":"client3","dst_href":"/orgs/1/workloads/02af2903-9ea5-4807-a47f-86c5eda8e1fd",  
    "network":"Corporate",  
    "interval_sec":584,  
    "pce_fqdn":  
    "mylab.lab.io",  
    "version":4}