Rules

List all rules

Request

Definition

GET /api/v1/rules

Headers

• Authorization required

  Authentication token with privileges to view the resource.

  Bearer {token}

Query string parameters

Parameter	Type	Required	Description
paginate	boolean	Yes	If the result must be paginated.
page	integer	Yes if paginate is true	Page index.
page_size	integer	Yes if paginate is true	Number of items displayed per page.
id	string	No	Filters results whose ID matches the entered string.
id_list	array<string>	No	Filters results whose id matches any of the list items.
kind	string	No	Filters results whose kind matches the entered string.
pattern	string	No	Filters results where the pattern matches the entered string.
rq_host	string	No	Filters results where the Host matches the entered string.
rq_host_list	array<string>	No	Filters results whose Host matches any of the entered Hosts list.
rq_host_search	string	No	Filters results whose Host matches all or part of the entered string.
target	string	No	Filters results whose target matches the entered string.
target_list	array<string>	No	Filters results whose target matches any of the targets in the entered list.
target_search	string	No	Filters results whose target matches all or part of the entered string.
action	string	No	Filters results related to the action entered.
action_list	array<string>	No	Filters the results related to the list of actions entered.
not_action_list	array<string>	No	Filters the results whose action does not match any of the actions in the list entered.
network_only	boolean	No	If true, filters the network rules.
alert_id	string	No	Filters the results related to the alert whose ID was entered.
alert_id_list	array<string>	No	Filters the results related to the alerts (indicated by their ID) in the inserted list.
attack_code	string	No	Filters the results related to the attack code entered.
attack_code_list	array<string>	No	Filters the results related to the entered attack code list.
timestamp	integer	No	Filters the results related to the timestamp entered.
timestamp_start	integer	No	Filters results created after the date entered.
timestamp_end	integer	No	Filters results created before the date entered.
username	string	No	Filters the results whose username of the person who created the rule matches the string entered.
username_list	array<string>	No	Filters the results where the username of the rule matches one of the items in the list.
username_search	string	No	Filters results where the username of the person who created the rule matches all or part of the specified string.

Response

Status codes

Status code	Message
200	"List of rules"
400	"Error with pagination fields"
403	"Forbidden"

Body

Attributes

• data.rules.action string

  Action defined in the rule.

• data.rules.attack_category string

  Attack category.

• data.rules.attack_code string

  Code identifying the type of attack.

• data.rules.attack_name string

  Type of attack.

• data.rules.case_sensitive boolean

  Indicates whether the rule match should be case sensitive.

• data.rules.id string

  Rule ID.

• data.rules.alert_id string

  Identification code of the alert to which the rule refers.

• data.rules.deleted boolean

  Indicates whether the rule has been deleted.

• data.rules.rq_host string

  Host header indicated in request.

• data.rules.target string

  Field of the request on which the rule should act.

• data.rules.timestamp integer

  Date and time in UNIX format (in microseconds) when the rule was created.

• data.rules.username string

  Username of who created rule.

• data.rules.description string

  Rule description.

• data.rules.duration integer

  Rule duration.

• data.rules.enabled boolean

  Indicates whether the rule is enabled.

• data.rules.expression object

  Object specifying the matching directives of the rule.

• data.rules.kind string

  Rule type.

• data.rules.loaded string

  Indicates if the rule has been loaded on firewall.

• data.rules.matching_method string

  Indicates how the expression value should be compared with the target.

• data.rules.network_only boolean

  If true, it defines a network rule.

• data.rules.pattern string

  Pattern blocked by a rule if associated to an alert.

• data.rules.priority string

  Priority with which the rule is activated in relation to the others.

• data.rules.rq_host string

  Header Host associated with the rule.

• data.rules.spec_values object

  Specification of the context of the rule if associated with an alert.

• data.rules.start_time integer

  In the case of a network rule, date and time the rule was activated in UNIX timestamp format (microseconds).

Example

{
"data": {
    "rules": [
    {
        "action": "deny",
        "alert_id": null,
        "attack_category": null,
        "attack_code": null,
        "attack_name": null,
        "case_sensitive": true,
        "deleted": false,
        "description": null,
        "duration": null,
        "enabled": true,
        "expression": {
        "type": "values",
        "values": [
            "A=0"
        ]
        },
        "id": "CxxQnxxx£Cx=",
        "kind": "negative",
        "loaded": "off",
        "matching_method": "full",
        "network_only": false,
        "pattern": null,
        "priority": "1",
        "rq_host": "www.xxxxxxxxx-xxx.it",
        "spec_values": {
        "path": "any",
        "request:Host": [
            "www.xxxxxxxx-xxx.it"
        ]
        },
        "start_time": null,
        "target": "parameter_key",
        "timestamp": 10,
        "username": "admin"
    }
    ]
},
"message": "List of rules",
"pagination": {
    "first": 1,
    "last": 1,
    "page": 0,
    "total_count": 1,
    "total_pages": 1
},
"status": "ok"
}

List a specific rule

Request

Definition

GET /api/v1/rules/{rule_id}

Header

• Authorization required

  Authentication token with privileges to view the resource.

  Bearer {token}

Response

Status codes

Status code	Message
200	"Rule retrieved."
400	"Error retrieving rule"
400	"Error with pagination fields"
403	"Forbidden"

Body

{
  "data": {
    "rule": {
      "action": "deny",
      "alert_id": null,
      "attack_category": null,
      "attack_code": null,
      "attack_name": null,
      "case_sensitive": true,
      "deleted": false,
      "description": null,
      "duration": null,
      "enabled": true,
      "expression": {
        "type": "values",
        "values": [
          "A=0"
        ]
      },
      "id": "CxxQnxxx£Cx=",
      "kind": "negative",
      "loaded": "off",
      "matching_method": "full",
      "network_only": false,
      "pattern": null,
      "priority": "1",
      "rq_host": "www.pluribus-one.it",
      "spec_values": {
        "path": "any",
        "request:Host": [
          "www.pluribus-one.it"
        ]
      },
      "start_time": null,
      "target": "parameter_key",
      "timestamp": 10,
      "username": "admin"
    }
  },
  "message": "Rule retrieved",
  "status": "ok"
}

Create new rule

Request

Definition

POST /api/v1/rules

Header

• Authorization required

  Authentication token with privileges to view the resource.

  Bearer {token}

• Content-Type required

  application/json

Request body

{
  "rules": [
    {
      "action": "deny",
      "description": "Negative rule",
      "enabled": true,
      "expression": {
        "type": "values",
        "values": [
          "A=0"
        ]
      },
      "kind": "negative",
      "matching_method": "substring",
      "priority": "100",
      "rq_host": "www.xxxxxxx-xxx.it",
      "spec_values": {
        "path": "any",
        "request:Host": [
          "www.xxxxxxxxx-xxx.it"
        ]
      },
      "target": "parameter_key"
    }
  ]
}

Response

Status codes

Status code	Message
200	"Rules created"
400	"Error creating rules"
403	"Forbidden"

Body

{
  "data": {
    "rule_ids": {
      "new_rule_ids": [
        "x2TjxxxiJ2xxxVE0Ykkxxxxrvm0iVxxxJmS0fkxxxT+4g704DxxxxxYEGxxxxPxY"
      ],
      "upd_rule_ids": []
    }
  },
  "message": "Rules created",
  "status": "ok"
}

Update a specific rule

Request

Definition

PUT /api/v1/rules/{rule_id}

Header

• Authorization required

  Authentication token with privileges to view the resource.

  Bearer {token}

• Content-Type required

  application/json

Request body

{
  "attrs": {
    "action": "do_nothing",
    "description": "New description",
    "duration": 500,
    "enabled": "false",
    "priority": "1000",
    "start_time": 1669038092678996
  }
}

Response

Status codes

Status code	Message
200	"Rules updated"
400	"Error updating the rule"
403	"Forbidden"

Body

{
  "data": {
    "rule_ids": [
      "x2TjxxxiJ2xxxVE0Ykkxxxxrvm0iVxxxJmS0fkxxxT+4g704DxxxxxYEGxxxxPxY"
    ]
  },
  "message": "Rules updated",
  "status": "ok"
}

Delete multiple rules

Request

Definition

DELETE /api/v1/rules

Header

• Authorization required

  Authentication token with privileges to view the resource.

  Bearer {token}

• Content-Type required

  application/json

Request body

{
  "rule_ids": [
    "x2TjxxxiJ2xxxVE0Ykkxxxxrvm0iVxxxJmS0fkxxxT+4g704DxxxxxYEGxxxxPxY"
  ]
}

Response

Status codes

Status code	Message
200	"Rules deleted"
400	"Error deleting rules."
403	"Forbidden"

Body

{
  "data": {
    "rule_ids": [
      "x2TjxxxiJ2xxxVE0Ykkxxxxrvm0iVxxxJmS0fkxxxT+4g704DxxxxxYEGxxxxPxY"
    ]
  },
  "message": "Rules deleted",
  "status": "ok"
}