Home  Prev  cOS Core 15.00.01 REST API Guide  Next

Chapter 5: Blacklist Control

This section describes the usage of the cOS Core REST API to change and list the contents of a configuration's blacklist. This section will not describe how the blacklist feature itself functions but only how the REST API is used to interact with it. A full description of the blacklist can be found in the separate cOS Core Administration Guide in the section titled Blacklisting Hosts and Networks.

The REST API allows an external computer to perform the following management operations on a cOS Core configuration:

Note that the API can only delete blacklist entries that were first added by the API. Entries created by configured cOS Core features, such as IDP and threshold rules, cannot be altered by the API.

However, when retrieving a list of blacklist entries using the API, all entries are returned, including those not added by the API. It is possible when retrieving a list of entries to use a filter so that only the entries of a certain type are retrieved and doing this is described later in this section.

The typical use case for adding and deleting blacklist entries is when a separate network component identifies an IP address as the source of a threat and needs to have a Clavister Next Generation Firewall drop connections initiated by that address.

Visibility of REST API Changes for the cOS Core Administrator

Any changes made to the blacklist using the REST API are visible to the administrator when the blacklist is listed in a management interface such as the Web Interface (WebUI) or CLI.

In addition, a cOS Core user with administrator privileges has the ability to delete blacklist entries that were added using the REST API. However, the API cannot delete entries not created through the API.

5.1. Adding a New Blacklist Entry

To add a blacklist entry, the action received by cOS Core should be an HTTP POST to the URI: 

/api/oper/blacklist

The action can have the following parameters:

  • host - The single source IPv4 address to be blacklisted. (Required.) This must be a single IP address, not a range or network.

  • service - The service associated with the entry. The value specified should be the name of a Service object defined in the cOS Core configuration. A "400 Bad Request" message is returned if it is not a valid service name. (Optional with an default value of all_services.)

  • ttl - The time-to-live in the blacklist in seconds. (Optional with a default value of 300 seconds.)

  • rule_name - The rule name associated with the entry. This arbitrary text data which can be used to store some value meaningful to the API client. It has no meaning for cOS Core but will be stored in the blacklist and appear in a listing of entries. (Optional with an empty default value.)

  • close_established - Close any established connections that originate from this IP address. (Optional.) If specified, this must have a value of yes or no. If not specified, the default value is no.

  • description - A textual description for the entry. (Optional with an empty default value.)

For example, to blacklist the IPv4 address 203.0.113.5, send a POST to the following URI: 

/api/oper/blacklist

The POST body should, at minimum, contain a string in the following form: 

host=203.0.113.5

By default, this adds a blacklist entry with the service set to all_services. If, for example, the blacklist entry is only to apply to HTTP and HTTPS traffic then the http-all service would be specified as an additional parameters in the POST body: 

host=203.0.113.5&service=http-all

The JSON reply sent by cOS Core will confirm that the entry has been added and specify all the parameter values used. It will have the following form: 

{
  "error": false,
  "blacklist_entry": {
    "host": "203.0.113.5",
    "service": "http-all",
    "ttl": "300",
    "rule_name": "-",
    "description": "-"
  }
}
Home  Prev   Next