IPS - RESTful API

Updated by Client-Security on Apr 20, 2016

IPS-API

The IPS-API is a RESTful api. IPS or Intrusion Prevention Service will require you to have a server and account in the CenturyLink Platform.

Supported Managed Operating Systems

Current supported operating systems can be found here Operating System Support

Authentication

In order to use the IPS-API you must retrieve a bearer token from CLC. This will be used during each of the calls. For more, see the CLC Authentication documentation.

Headers

To interact with the IPS-API you will need to provide in the headers two fields

Header Value
Content-Type application/json
Authorization Bearer (CLC Bearer Token)

Install

Installs an IPS agent on the designated host.

URL

Structure

POST https://api.client-security.ctl.io/ips/api/app/

{
    "hostName":"serverName",
    "accountAlias":"CLC Account Alias"
}
Content Properties
Name Type Description REQ.
accountAlias String Short code for a particular account Yes
hostName String The name of the server that the destination should be set for. Yes
Example
{
    "hostName":"VA1CLCDTEST04",
    "accountAlias":"CLCD"
}

Uninstall

Uninstalls an IPS agent from a designated host.

URL

Structure

DELETE https://api.client-security.ctl.io/ips/api/app/

{
    "hostName":"serverName",
    "accountAlias":"CLC Account Alias"
}
Content Properties
Name Type Description REQ.
accountAlias String Short code for a particular account Yes
hostName String The name of the server that the destination should be set for. Yes
Example
{
    "hostName":"VA1CLCDTEST04",
    "accountAlias":"CLCD"
}

Notification Destination

Configuration Process via our API

The calls below will perform all of the operations for configuring, retrieving, updating, and deleting a notification destination. Calls to this operation must include a token acquired from the authentication endpoint. See the Login API for information on acquiring this token.

Note: If you have any questions, or would like assistance from us in setting up your notifications, please email us at [email protected] We're happy to help at anytime!

URL

Structure
Create and Update

PUT https://api.client-security.ctl.io/ips/api/notifications/{accountAlias}/{serverName}

{
    "url":{some URL},
    "typeCode":{endpoint type}
}
Retrieve

GET https://api.client-security.ctl.io/ips/api/notifications/{accountAlias}/{serverName}

Delete

DELETE https://api.client-security.ctl.io/ips/api/notifications/{accountAlias}/{serverName}

Request

URI Parameters
Name Type Description REQ.
accountAlias String Short code for a particular account Yes
serverName String The name of the server that the destination should be set for. Yes
Content Properties
Name Type Description REQ.
notificationDestinations array List of Notification Destinations Yes
Notification Destination Definition
Name Type Description REQ.
url String The URL endpoint for WEBHOOK or SLACK notification. No
typeCode String This is the type of destination. Yes
sysLogSettings SysLogSettings This contains all of the options for SYSLOG No
emailAddress String This object will contain options for an EMAIL notification No

TypeCode currently consists of: SYSLOG, EMAIL, and WEBHOOK

Note: If you have any questions, or would like assistance from us in setting up your notifications, please email us at [email protected] We're happy to help at anytime!

SysLogSettings Definition
Name Type Description REQ.
ipAddress String The IP address of customers syslog server Yes
udpPort Integer The port the syslog is listening on Yes
facility Integer This is an Integer, 16-23, for descriptions see below. Yes

Facility is to set the type of program logging messages. The options are 16-23 for descriptions follow the link: https://en.wikipedia.org/wiki/Syslog

Example

PUT http://api.client-security.ctl.io/ips/api/notification/ALIAS/VA1ALIASMYSVR01

{
    "url": "http://my.slack.webhook",
    "typeCode": "SLACK"
},
{
    "url": "http://my.generic.webhook",
    "typeCode": "WEBHOOK"
},
{
    "typeCode": "SYSLOG",
    "sysLogSettings":
        {
            "ipAddress": "12345",
            "udpPort": "8081",
            "facility": "16"
        }
},
{
    "typeCode": "EMAIL",
    "emailAddress": "[email protected]"
}

The following key-value pairs are sent to the notification destination when an event is triggered. If you are using the generic "WEBHOOK" type for your notifications the following will be sent in json format.

Response Object
Name Type Description
packetSize int Size of the packet which triggered the event
rank int Name of the DPI filter which triggered the event
driverTime Long Epoch time the Agent driver recorded at the time of the event
startTime Date Start time of the event if repeated multiple times
endTime Date End time of the event if repeated multiple times
action String Resulting action of the triggered event
data String Any captured packet data in Base64 encoded format
destinationIP String Destination IP Address
destinationMAC String Destination MAC Address
destinationPort String Destination Port
direction String Direction of the event
eventOrigin String Origin of the event
flags String Data packet flags
flow String Flow of the packet the log was recorded for in relation to the connection direction
hostName String HostTransport Name of the computer where the event was triggered
iface String Name of the physical network interface where the event was triggered
protocol String Protocol of the connection
reason String Name of the DPI filter which triggered the event
sourceIP String Source IP Address
sourceMAC String Source MAC Address
sourcePort String Source Port
tags String Name of any event tags assigned to this event
severity String Severity

Note: If you have any questions, or would like assistance from us in setting up your notifications, please email us at [email protected] We're happy to help at anytime!

Syslog Firewall Rules
  • Add the following rules to the Firewall that the Syslog server sits behind if located in another location

    • dsm01.client-security.ctl.io 514/udp

    • dsm02.client-security.ctl.io 514/udp

Customer Support

Can’t find what you need?
Give us a call.

1.888.638.6771

M – F, 8am to 6pm