Security Management System External Interface Guide...2 Security Management System External Interface Guide Convention Element Italics font Text emphasis, important terms, variables,

Security Management SystemExternal Interface GuideVersion 4.6.0

5998-2911May 2017

Legal and notice information

© Copyright 2017 Trend Micro

Trend Micro makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Trend Micro shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance, or use of this material.

This document contains proprietary information, which is protected by copyright. No part of this document may be photocopied, reproduced, or translated into another language without the prior written consent of Trend Micro. The information is provided “as is” without warranty of any kind and is subject to change without notice. The only warranties for Trend Micro products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. Trend Micro shall not be liable for technical or editorial errors or omissions contained herein.

TippingPoint®, the TippingPoint logo, and Digital Vaccine® are registered trademarks of Trend Micro. Vertica Copyright © 2016 Hewlett Packard Enterprise Development Company LP. All other company and product names may be trademarks of their respective holders. All rights reserved. This document contains confidential information, trade secrets or both, which are the property of Trend Micro. No part of this documentation may be reproduced in any form or by any means or used to make any derivative work (such as translation, transformation, or adaptation) without written permission from Trend Micro or one of its subsidiaries. All other company and product names may be trademarks of their respective holders.

TippingPoint Security Management System External Interface Guide

Security Management System External Interface Guide i

ContentsAbout this guide......................................................................................................................................1

Target audience...................................................................................................................................... 1

Related documentation...........................................................................................................................1

Conventions............................................................................................................................................ 1

Product support...................................................................................................................................... 2

SMS web API........................................................................................................................................... 3

Authentication and authorization............................................................................................................ 3

Errors...................................................................................................................................................... 3

Profile management................................................................................................................................4

Shared settings.................................................................................................................................... 4

Export a profile.....................................................................................................................................5

Import a profile.....................................................................................................................................7

Distribute a profile................................................................................................................................8

Distribute a profile to a segment group............................................................................................ 9

Distribute a profile to a single segment.......................................................................................... 10

Profile distribution XML schema..................................................................................................... 10

Retrieve profile distribution status..................................................................................................... 12

Profile distribution XML schema..................................................................................................... 12

Create a traffic management filter.....................................................................................................14

Retrieve current filter settings............................................................................................................16

Current filter settings XML schema................................................................................................ 16

Current filter settings XML response.............................................................................................. 18

Update filter settings.......................................................................................................................... 23

Update filter settings XML schema.................................................................................................23

Update filter settings XML response...............................................................................................27

ii Security Management System External Interface Guide

Retrieve Digital Vaccine information..................................................................................................28

Reputation management...................................................................................................................... 28

Reputation management best practices............................................................................................ 28

Syntax rules for import files...............................................................................................................29

Import file example..........................................................................................................................30

Import reputation entries....................................................................................................................31

Add reputation entries........................................................................................................................31

Delete reputation entries....................................................................................................................32

Query reputation entries.................................................................................................................... 34

Virtual segment management...............................................................................................................35

Virtual segment response codes....................................................................................................... 35

Virtual segment XML schema............................................................................................................37

Virtual Segment XML elements......................................................................................................... 42

Create a virtual segment................................................................................................................... 46

Update a virtual segment.................................................................................................................. 47

Delete a virtual segments..................................................................................................................48

Retrieve a list of virtual segments..................................................................................................... 49

Remote administration..........................................................................................................................49

Backup the SMS database................................................................................................................49

Retrieve the SMS version..................................................................................................................51

Enterprise Vulnerability Remediation................................................................................................... 51

Vulnerability scan specifications........................................................................................................ 52

Import a vulnerability scan.................................................................................................................53

Convert a vulnerability scan.............................................................................................................. 54

Active response.................................................................................................................................... 55

Active response best practices..........................................................................................................55

Create a response............................................................................................................................. 55

Close a response...............................................................................................................................56

Security Management System External Interface Guide iii

Packet trace..........................................................................................................................................57

Device-based packet trace................................................................................................................ 57

Events-based packet trace................................................................................................................ 58

Set up event-based packet trace....................................................................................................58

Database access.................................................................................................................................. 58

Usage sequence................................................................................................................................ 59

DataDictionary.................................................................................................................................... 59

ACTIONSET table........................................................................................................................... 61

ALERT_TYPE table.........................................................................................................................62

CATEGORY table............................................................................................................................62

DEVICE table.................................................................................................................................. 63

NOTICE_ACTION table...................................................................................................................63

POLICY table...................................................................................................................................64

POLICY_GROUP_LOOKUP table.................................................................................................. 64

PRODUCT_CATEGORY table........................................................................................................ 65

PROFILE table................................................................................................................................ 65

PROFILE_INSTALL_INVENTORY table......................................................................................... 66

QUARANTINE_NETWORK_DEVICES table.................................................................................. 66

SEGMENT table.............................................................................................................................. 66

SEGMENT_GROUP table...............................................................................................................67

SEVERITY table.............................................................................................................................. 67

SIGNATURE table........................................................................................................................... 68

TAXONOMY_MAJOR table.............................................................................................................69

TAXONOMY_MINOR table............................................................................................................. 69

TAXONOMY_PLATFORM table...................................................................................................... 70

TAXONOMY_PROTOCOL table..................................................................................................... 70

THRESHOLD_GROUP_LOOKUP table......................................................................................... 70

THRESHOLD_UNITS table.............................................................................................................71

TPT_DEVICE table..........................................................................................................................71

TPT_PORT table............................................................................................................................. 72

iv Security Management System External Interface Guide

TPT_SEGMENT table..................................................................................................................... 72

VIRTUAL_SEGMENT table.............................................................................................................73

DataDictionary XML response........................................................................................................ 73XML response sample..................................................................................................................75

GetData.............................................................................................................................................. 77

Events Data.....................................................................................................................................78ALERTS table............................................................................................................................... 78DDOS_STATS table......................................................................................................................84FIREWALL_BLOCK_LOG table................................................................................................... 84FIREWALL_TRAFFIC_LOG table.................................................................................................86PORT_TRAFFIC_STATS table..................................................................................................... 87QUARANTINE_HOSTS table....................................................................................................... 88RATELIMIT_STATS table..............................................................................................................89THRESHOLD_STATS table..........................................................................................................89

GetNewestRecord.............................................................................................................................. 90

GetOldestRecord................................................................................................................................91

Schema.............................................................................................................................................. 91

Status................................................................................................................................................. 92

Version................................................................................................................................................92

External database..................................................................................................................................93

Configure the SMS for external access............................................................................................... 93

Configure the SMS for replication........................................................................................................94

Configure the SMS to enable restricted access.................................................................................. 95

ALERTS table – ExternalAccess..........................................................................................................95

Replication – database schema...........................................................................................................96

MIB files for the SMS............................................................................................................................98

SMS MIBs.............................................................................................................................................98

Public MIB files.....................................................................................................................................98

Health monitoring..................................................................................................................................98

Security Management System External Interface Guide 1

About this guideThe Security Management System External Interface Guide provides information required to interact with the SMSusing web API. This guide also provides information about the management information database (MIB)files and object identifiers (OIDs) used by the SMS.

Target audienceThe intended audience includes technicians and maintenance personnel responsible for installing,configuring, and maintaining TippingPoint security systems and associated devices.

Users should be familiar with the following concepts:

• Basic networking

• Network security

• Routing

Related documentationA complete set of documentation for your product is available on the TippingPoint Threat ManagementCenter (TMC) at: https://tmc.tippingpoint.com. The documentation generally includes installation and userguides, command-line interface (CLI) references, safety and compliance information, and release notes.

ConventionsThis information uses the following conventions.

Typefaces

TippingPoint uses the following typographic conventions for structuring information.

Convention Element

Bold font • Key names

• Text typed into a GUI element, such as into a box

• GUI elements that are clicked or selected, such as menu and list items,buttons, and check boxes. Example: Click OK to accept.

https://tmc.tippingpoint.com

2 Security Management System External Interface Guide

Convention Element

Italics font Text emphasis, important terms, variables, and publication titles

Monospace font • File and directory names

• System output

• Code

• Text typed at the command-line

Monospace, italicfont

• Code variables

• Command-line variables

Monospace, boldfont

Emphasis of file and directory names, system output, code, and text typedat the command line

Messages

Messages are special text that is emphasized by font, format, and icons.

Warning! Alerts you to potential danger of bodily harm or other potential harmful consequences.

Caution: Provides information to help minimize risk, for example, when a failure to follow directionscould result in damage to equipment or loss of data.

Note: Provides additional information to explain a concept or complete a task.

Important: Provides significant information or specific instructions.

Tip: Provides helpful hints and shortcuts, such as suggestions about how to perform a task more easily ormore efficiently.

Product supportInformation for you to contact product support is available on the TMC at: https://tmc.tippingpoint.com.

https://tmc.tippingpoint.com/TMC/Support?parentFolderId=support&contentId=Support_Contacts


SMS web APIThe SMS web API provides access to the following set of SMS features:

• Profile management on page 4

• Reputation management on page 28

• Virtual segment management on page 35

• Remote administration on page 49

• Enterprise Vulnerability Remediation on page 51

• Active response on page 55

• Packet trace on page 57

• Database access on page 58

HTTPS or HTTP service to the SMS is required to send API requests to the SMS. By default, HTTPSservice to the SMS is enabled. For more information, see "Server properties" in the Security ManagementSystem User Guide.

Authentication and authorizationThe SMS supports the following authentication methods for the SMS web API:

• Query string parameters encoded in URL: smsuser={username}&smspass={password}

• HTTP Basic authentication: –u {username}:{password} option in cURL

Note: You can customize or replace the default SMS SSL X509 certificate in the SMS Admin workspace.

Web access on the SMS includes access to the SMS through the web client and web API requests.By default, authentication with a valid username and password is required for web access. For moreinformation, see "System preferences" in the Security Management System User Guide.

We recommend that only users with the superuser role have web access for full authorization. For moreinformation, see "Managing user roles" in the Security Management System User Guide.

ErrorsThe SMS web API returns one of the following HTTP status codes if the request is unsuccessful.


Code Description

400 Bad request – Malformed parameter or request.

401 Unauthorized – Missing or incorrect credentials.

404 Not Found – Invalid or nonexistent requested source.

412 Preconditioned Fail – Unexpected error. Check the SMS system log for more information.

500 Internal Server Error – Server-side exception. Check the SMS system log for moreinformation.

Profile managementThe profile management API enables you to export, import, and distribute an SMS profile and to createand update filters. In addition, you can retrieve profile distribution status and data about the Digital Vaccine(DV) on the SMS.

For more information, see the Security Management System User Guide.

Shared settingsProfiles include shared settings, such as action sets, notification contacts, and services.

If the imported profile includes policies or category settings that use a particular action set, the action setis added to the SMS. The SMS does not overwrite an existing action set with the same name. Instead, theSMS renames the new action set by appending a number to the end of the file name, for example, “MyQuarantine_2”.

A notification contact that is used by an action set is also imported and renamed, if necessary.

Existing port definitions for services on the SMS remain the same. If an imported profile includes aservice with a port definition that differs from the existing service on the SMS, the service is added to theSMS service list. Review services any time a profile is imported from a different user or from a differentenvironment.


Export a profileUse the exportProfile method to export a profile to the SMS Web “Exports” directory or to a fullyspecified SMB or NFS server location. Location parameters are required when you export to SMB or NFSremote directories.

Note: Profile packages typically remain unchanged. If you want to change the files within a profile package,update the md5sum in the sms-security-manifest file before importing the profile packageback into the SMS.

Definition

ipsProfileMgmt/exportProfile

Profile export parameters

Parameter Description

exportMethod (optional) Export destination: SMS HTTP server [default], smb, nfs

profileName Name of profile to export.

profileVersion (optional) Version of profile to export; if profileVersion is not specified,the latest version of the profile is used.

SMB location parameters


remoteDirectory Remote SMB directory

remoteFilename (optional) Remote filename (default: "profile_name.pkg")

remoteServer SMB server

userid SMB user ID



password SMB password

domain SMB domain

NFS location parameters


remoteDirectory Remote NFS directory.

remoteFilename (optional) Remote filename (default: "profile_name.pkg")

remoteServer NFS server

Examples

The following example exports the MyProfile profile to the Export directory on the SMS server.

http[s]://<sms_server>/ipsProfileMgmt/exportProfile?profileName=MyProfile&smsuser=<sms_user>&smspass=<password>

The following example exports the Default profile to an SMB server.

http[s]://<sms_server>/ipsProfileMgmt/exportProfile?exportMethod=SMB&profileName=Default&remoteDirectory=MyExportDirectory&remoteServer=MyRemoteServer&userid=guest&password=guestpass&domain=CompanyXDomain

The following example exports the Default profile to an NFS server.

http[s]://<sms_server>/ipsProfileMgmt/exportProfile?exportMethod=NFS&remoteDirectory=savedProfiles&remoteServer=MyExportDirectory&profileName=Default


Import a profileUse the importProfile method to import an exported profile package to the SMS. Check the versiondetails section to see the name of the profile the current profile was imported from and the date of theupdate.

Note: If you change the profile, ensure that you maintain the same format. If you are importing a changedprofile, ensure that you update the md5sum in the sms-security-manifest file in the profilepackage.

Definition

ipsProfileMgmt/importProfile

Parameters


importAction Required. Possible values include the following:

• add: Adds a completely new profile; must have an unusedname or import fails.

• combine_add: Adds new settings and merges non-conflicting changes into an existing profile.

• combine_change: Adds new settings to and overwritesexisting settings of an existing profile with settings of the newprofile.

• replace: Overwrites contents of SMS profile with those ofthe profile being imported; name and UUID remain the same;snapshot of replaced profile occurs and updated profile getsnew version.

targetProfileName The name of the existing profile in the SMS profile inventory.Required for all replace and combine actions.

Note: The profile must exist in the SMS profile inventory. If thespecified profile does not exist or is not specified in therequest, the operation fails, an error is returned, and theaudit log is updated with information. If the specified profile



does exist, the specified importAction is performed, thetarget profile version is updated, and the audit log is updatedwith information.

replacedProfileName The name of the imported profile that will have its contents appliedto the existing profile in the SMS profile inventory. Required for allreplace and combine actions.

Note: The profile must be specified in the request. If the specifiedprofile does not exist or is not specified in the request, theoperation fails, an error is returned, and the audit log isupdated with information.

Examples

Add a new profile:

curl -k -u <sms_user>:<password> -F "file=@</path/to/import.pkg>" "https://<sms_server>/ipsProfileMgmt/importProfile?importAction=add"

Combine with an existing profile and add new settings:

curl -k -u <sms_user>:<password> -F "file=@</path/to/import.pkg>""https://<sms_server>/ipsProfileMgmt/importProfile?importAction=combine_add&targetProfileName=<profile_name_on_sms>&replacedProfileName=<adding_profile_name>"

Combine with an existing profile, adding new and overwriting existing settings:

curl -k -u <sms_user>:<password> -F "file=@</path/to/import.pkg>" "https://<sms_server>/ipsProfileMgmt/importProfile?importAction=combine_change&targetProfileName=<profile_name_on_sms>&replacedProfileName=<adding_overwriting_profile_name>"

Replace the contents of an existing profile:

curl -k -u <sms_user>:<password> -F "file=@</path/to/import.pkg>" "https://<sms_server>/ipsProfileMgmt/importProfile?importAction=replace&targetProfileName=<profile_name_on_sms>&replacedProfileName=<replacing_profile_name>"

Distribute a profileUse the distributeProfile method to initiate a profile distribution to a single segment target or to asegment group.


Definition

ipsProfileMgmt/distributeProfile

Profile distribution parameters


profileName Name of profile on SMS to distribute

profileVersion (optional) Version of profile to distribute (latest version is used if notspecified)

distribPriority (optional) Priority of distribution on IPS: high [default] or low. If priority isnot specified, high priority is used as a default

Segment group target parameter


segmentGroupName Name of segment group that is target of distribution

Single segment target parameters


deviceIpAddr IP Address of device, only required for single segment distributions

segmentName Name of segment receiving distributed profile, only required forsingle segment distributions

Distribute a profile to a segment group

The following example shows the URL format to distribute a profile to a segment group.

http[s]://<sms_server>/ipsProfileMgmt/distributeProfile?profileName=<profile_name>&segmentGroupName=<SegmentGroupName>&smsuser=<sms_user>&smspass=<password>


Distribute a profile to a single segment

The following example shows the URL format to distribute a profile to a single segment.

http[s]://<sms_server>/ipsProfileMgmt/distributeProfile?profileName=<profile_name>&deviceIpAddr=<device_ip_address>&segmentName=<segment_name>&smsuser=<sms_user>&smspass=<password>

Profile distribution XML schema

The profile management API uses the following XML schema for profile distribution requests.

<?xml version="1.0" encoding="utf-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:simpleType name="uuid"> <xs:restriction base="xs:string"> <xs:pattern value="[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f] {4}-[0-9a-f]{12}"/> </xs:restriction> </xs:simpleType> <xs:complexType name="idname"> <xs:choice> <xs:element name="id" type="uuid"/> <xs:element name="name" type="xs:string"/> </xs:choice> </xs:complexType> <xs:element name="distribution"> <xs:complexType> <xs:sequence> <xs:element name="profile" minOccurs="1"maxOccurs="1"> <xs:complexType> <xs:attribute name="id" type="uuid"/> <xs:attribute name="name" type="xs:string"/> <xs:attribute name="version" type="xs:string" use="required"/> </xs:complexType> </xs:element> <xs:element name="priority" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="high"/> <xs:enumeration value="low"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="segmentGroup" type="idname" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="virtualSegment" minOccurs="0" maxOccurs="unbounded"> <xs:complexType>


<xs:sequence> <xs:element name="id" type="uuid"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="device" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:choice> <xs:element name="id" type="uuid"/> <xs:element name="shortID" type="xs:positiveInteger"/> <xs:element name="name" type="xs:string"/> <xs:element name="ipAddress" type="xs:string"/> </xs:choice> <xs:element name="virtualSegment" type="idname" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>

XML elements

The following table describes XML elements in the profile distribution request schema.

Element Value Definition

profile Empty elementwith theseattributes:

• id

• name

• version

IPS profile identified by an id expressed in UUID format,a name string and a version number string

priority String, eitherhigh or low

High or low value indicating the priority for distributingthe profile to the managed IPS devices

segmentGroup String ID string expressed in UUID format or a name string tospecify the group of segments for the profile distribution



virtualSegment String ID string expressed in UUID format to specify a virtualsegment

device/id (device) String Internal ID assigned to the device expressed in UUIDformat

device/shortID Positive integer Internal number assigned to the device

device/name String Name of the device

device/ipAddress

String IP address string of the device

device/virtualSegment

String ID string expressed in UUID format or a name string tospecify a virtual segment on the device

Retrieve profile distribution statusUse the distributionStatus resource to determine the success or failure and the duration of adistribution session in a POST request. The actual percent-complete progress and predicted end-time arenot available.

Definition

ipsProfileMgmt/distributionStatus

Parameters

A profile distribution status request must include at least one Distribution ID. A request can also includeDevice Name, Device ID, Device ShortID and Device IP Address.

Example

http[s]://<sms_server>/ipsProfileMgmt/distributionStatus?<distribution_id>

Profile distribution XML schema

The profile management API uses the following XML schema for profile distribution status requests.

<?xml version="1.0" encoding="utf-8"?>


<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:simpleType name="uuid"> <xs:restriction base="xs:string"> <xs:pattern value="[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f] {4}-[0-9a-f]{4}-[0-9a-f]{12}"/> </xs:restriction> </xs:simpleType> <xs:element name="distributions"> <xs:complexType> <xs:sequence> <xs:element name="distribution" minOccurs="1" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="device" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:choice> <xs:element name="name" type="xs:string"/> <xs:element name="id" type="uuid"/> <xs:element name="shortID" type="xs:positiveInteger"/> <xs:element name="ipAddress" type="xs:string"/> </xs:choice> </xs:complexType> </xs:element> </xs:sequence> <xs:attribute name="id" type="uuid"/> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:schema>

XML elements

The following table describes XML elements in the profile distribution request.


distribution/id

String Internal ID assigned to the distribution session expressed inUUID format

device/id String Internal ID assigned to the device expressed in UUID format

device/shortID

Positive integer Internal number assigned to the device



device/name String Name of the device

device/ipAddress

String IP address string of the device

Create a traffic management filterUse the createTrafficMgmt method to create a traffic management filter.

Definition

ipsProfileMgmt/createTrafficMgmt

Parameters

Note: Parameter names and enumerated values are not case sensitive.

The following parameters are required.


name Name of the traffic management filter. Names must be unique for each profile.

profile Name of the profile that contains the traffic management filter. The profile mustalready exist.

srcAddr Source address for the filter. Valid value can be any or an IP address.

destAddr Destination address for the filter. Valid value can be any or an IP address.

The following parameters are optional. If a parameter is not specified, the default value is used.

Parameter Description Default

direction Direction of filter. Valid values are AtoB, BtoA, orboth.

AtoB


Parameter Description Default

action Action set to use. Valid values are restricted to allow,block, and trust. For rate limiting, use the rate-limitparameter.

block

rate-limit Rate limiting action set to use. The action set mustalready be defined and be set to rate limit.

protocol Protocol to filter. Valid values are ip, ipv6, tcp,tcpv6, udp, udpv6, icmp, and icmpv6.

ip

ipFragments Apply only to IP fragments; valid only when protocol isIP. Valid values are true and false.

false

icmptype ICMP type; valid only when protocol is ICMP. Validvalues are 0-255.

0

icmpcode ICMP code; valid only when protocol is ICMP. Validvalues are 0-255.

0

srcPort Source port to filter on, valid only when protocol isTCP or UDP. Valid values are any or 0-65535.

0, which is all ports

destPort Destination port to filter on; valid only when protocol isTCP or UDP. Valid values are any or 0-65535.

0, which is all ports

position Precedence of filter. Valid values are 0-200. 0, which uses the lowestunused value

comment Comment for filter.

state State of filter. Valid values are enable and disable. enabled

Example

http[s]://<sms_server>/ipsProfileMgmt/createTrafficMgmt?name=<filter_name>&profile=<profile_name>&srcAddr=<ip_address>&destAddr=<ip_address>


Retrieve current filter settingsUse the getFilters method to retrieve current filter settings for particular filters in a profile with anXML file with the profile and filter details.

When the SMS receives a current filter settings service request, it performs the following functions:

1. Validates the filter ID using the DV metadata.

2. Finds the category the filter ID belongs to.

3. Finds the setting of the category from the profile specified by the Profile ID and version.

4. Sets the filter ID in the response XML.

Note: The setting of a given filter might be changed by IPS administrators. The changes are defined in thePOLICY response XML defined by the existing service interface.

Example

http[s]://<sms_server>/ipsProfileMgmt/getFilters

Current filter settings XML schema

The profile management API uses the following XML schema for current filter settings status requests.

<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:simpleType name="uuid"> <xs:restriction base="xs:string"> <xs:pattern value="[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f] {4}-[0-9a-f]{4}-[0-9a-f]{12}"/> </xs:restriction> </xs:simpleType> <xs:element name="getFilters"> <xs:complexType> <xs:sequence> <xs:element name="profile"> <xs:complexType> <xs:attribute name="id" type="uuid"/> <xs:attribute name="name" type="xs:string"/> </xs:complexType> </xs:element> <xs:element name="filter" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="number" type="xs:positiveInteger"minOccurs="0"/> <xs:element name="name" type="xs:string" minOccurs="0"/> <xs:element name="signature-id" type="uuid" minOccurs="0"/> <xs:element name="policy-id" type="uuid" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element>


</xs:sequence> </xs:complexType> </xs:element> </xs:schema>

XML elements

The following table describes XML elements in the current filter setting request.


profile Empty element with theseattributes:

• id

• name

IPS profile identified by ID expressed in UUIDformat and name string

number Integer Internally-assigned unique number for the filter

name String Name of the filter

signature-id String Internally-assigned filter ID expressed in UUIDformat

policy-id string Internally-assigned policy ID expressed inUUID format

The following sample shows an instance of a filter setting request XML:

<?xml version="1.0"?><getFilters> <profile name="Default"/> <filter> <number>3295</number> </filter> <filter> <signature-id>00000001-0001-0001-0001-000000000027</signature-id> </filter> <filter> <policy-id>00000002-0002-0002-0002-000000000051</policy-id> </filter> <filter> <name>0050: IP Options: Unknown Code</name> </filter>


</getFilters>

Current filter settings XML response

The current filter settings response is defined in the following XML schema format:

<?xml version="1.0" encoding="utf-8"?><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:simpleType name="uuid"> <xs:restriction base="xs:string"> <xs:patternvalue="[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"/> </xs:restriction> </xs:simpleType> <xs:element name="filters"> <xs:complexType> <xs:sequence> <xs:element name="profile"> <xs:complexType> <xs:attribute name="name" type="xs:string"/> <xs:attribute name="id" type="xs:string"/> <xs:attribute name="version" type="xs:string"/> </xs:complexType> </xs:element> <xs:element name="filter" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="name" type="xs:string"/> <xs:element name="policy-id" type="uuid"/> <xs:element name="version" type="xs:string"/> <xs:element name="locked" type="xs:boolean"/> <xs:element name="useParent" type="xs:boolean"/> <xs:element name="comment" type="xs:string" minOccurs="0"/> <xs:element name="description" type="xs:string" minOccurs="0"/> <xs:element name="severity" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="Low"/> <xs:enumeration value="Minor"/> <xs:enumeration value="Major"/> <xs:enumeration value="Critical"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="enabled" type="xs:boolean"/> <xs:element name="actionset" minOccurs="0"> <xs:complexType> <xs:attribute name="refid" type="uuid"/> <xs:attribute name="name" type="xs:string"/> </xs:complexType> </xs:element> <xs:element name="control"> <xs:simpleType> <xs:restriction base="xs:string">


<xs:enumeration value="Category"/> <xs:enumeration value="Filter"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="afc" type="xs:boolean"/> <xs:element name="policyGroup" minOccurs="0"> <xs:complexType> <xs:attribute name="refid" type="uuid"/> </xs:complexType> </xs:element> <xs:element name="trigger" minOccurs="0"> <xs:complexType> <xs:attribute name="threshold"> <xs:simpleType> <xs:restriction base="xs:integer"> <xs:minInclusive value="2"/> <xs:maxInclusive value="10000"/> </xs:restriction> </xs:simpleType> </xs:attribute> <xs:attribute name="timeout"> <xs:simpleType> <xs:restriction base="xs:long"> <xs:minInclusive value="0"/> <xs:maxInclusive value="999999"/> </xs:restriction> </xs:simpleType> </xs:attribute> </xs:complexType> </xs:element> <xs:element name="capability" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="enabled" type="xs:boolean"/> <xs:element name="actionset" minOccurs="0"> <xs:complexType> <xs:attribute name="refid" type="uuid"/> <xs:attribute name="name" type="xs:string"/> </xs:complexType> </xs:element> </xs:sequence> <xs:attribute name="name" type="xs:string"/> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element></xs:schema>


XML elements

The following table describes the definitions of current filter setting response XML elements.


profile Empty elementwith theseattributes:

• id

• name

• version

An IPS profile identified by an id expressed in UUID format, aname string and a version number string.

name String The name of the filter.

policy-id String An internally-assigned policy ID expressed in UUID format.

version Integer IPS TOS version that the filter is applicable.

locked Boolean Boolean variable indicating if the filter is locked. A locked filtercannot be remotely changed.

useParent Boolean Boolean variable indicating if the filter actionset setting isinherited from a parent profile.

comment String User comment on the filter.

description String Description of the filter.

severity String taking oneof these values:

• Low

• Minor

• Major

Severity of the filter.



• Critical

enabled Boolean Boolean variable indicating if the filter is enabled or disabled.

actionset Empty elementwith theseattributes:

• refid

• name

An actionset setting defined by a refid expressed in UUIDformat and a name string.

control String taking oneof these values:

• Category

• Filter

Controlling element of the filter actionset setting.

If the filter’s actionset setting is controlled by its categoryaction set setting, then the control is “Category”.

If the filter’s actionset setting is controlled by overridingits default action set setting, then the control is “Filter”.

afc Boolean Boolean variable indicating if the filter is managed by the IPSAdaptive Filter Configuration (AFC).

If a filter is managed by AFC, then the filter is automaticallydisabled when the IPS device is under heavy load and the givenfilter is triggered without an actual filter match.

policyGroup Empty elementwith a refidattribute

An IPS profile group identified by a refid, expressed in UUIDformat. The policyGroup element is never used by a filter.

trigger Empty elementwith theseattributes:

• threshold

• timeout

A filter's trigger frequency detection parameter. The thresholdis used to specify the number of filter triggers. The timeoutis used to specify the time period under which the number oftriggers are being counted (in seconds). The trigger element isused only for scan/sweep filters.



capability Element with aname attributehaving thesechild elements:

• enabled

• actionset

• refid

IPS device-specific filter settings. The name attribute specifiesthe type of device. The enabled and actionset child elementsspecify the filter setting. These child elements have the samedefinition as those defined previously. The refid element mapsto the action set ID for the capability.

The following sample shows an instance of filter current setting response XML:

<?xml version="1.0" encoding="utf-8"?> <filters xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="getFiltersResponse.xsd"> <profile name="name" id="5d8814e0-8a58-11e1-23de-c4ae1e90eacf" version="1.1"/> <filter> <name>7120: TCP: Segment Overlap With Different Data, e.g., Fragroute</name> <policy-id>00000002-0002-0002-0002-000000007120</policy-id> <version>5400+</version> <locked>false</locked> <useParent>true</useParent> <severity>Low</severity> <enabled>false</enabled> <control>Category</control> <afc>true</afc> <capability name="n-series"> <enabled>true</enabled> <actionset name="Block / Notify" refid="a6ae6a71-b685-49fb-a478-b558ea8ade2a"/> </capability> </filter> <filter> <name>3295: HTTP: ShoutCAST DNAS Format String Vulnerability</name> <policy-id>00000002-0002-0002-0002-000000003295</policy-id> <version>5200+</version> <locked>false</locked> <useParent>true</useParent> <severity>Critical</severity> <enabled>false</enabled> <control>Category</control> <afc>true</afc> <capability name="n-series"> <enabled>true</enabled> <actionset name="Block / Notify" refid="a6ae6a71-b685-49fb-a478-b558ea8ade2a"/> </capability> <capability name="model-10"> <enabled>true</enabled> <actionset name="Block / Notify" refid="a6ae6a71-b685-49fb-a478-b558ea8ade2a"/>


</capability> </filter><filter> <name>0027: IP Options: Record Route (RR)</name> <policy-id>00000002-0002-0002-0002-000000000027</policy-id> <version>5200+</version> <locked>false</locked> <useParent>true</useParent> <comment>This is a comment</comment> <severity>Minor</severity> <enabled>true</enabled> <actionset refid="e0a0b14b-934c-11d6-93ca-0002b34b9580" name="Block"/> <control>Filter</control> <afc>true</afc> </filter><filter> <name>0051: IP: Source IP Address Spoofed (Impossible Packet)</name> <policy-id>00000002-0002-0002-0002-000000000051</policy-id> <version>5200+</version> <locked>false</locked> <useParent>true</useParent> <severity>Critical</severity> <enabled>true</enabled> <actionset refid="a6ae6a71-b685-49fb-a478-b558ea8ade2a" name="Block/Notify"/> <control>Category</control> <afc>true</afc> </filter><filter> <name>0050: IP Options: Unknown Code</name> <policy-id>00000002-0002-0002-0002-000000000050</policy-id> <version>5400+</version> <locked>false</locked> <useParent>true</useParent> <severity>Minor</severity> <enabled>false</enabled> <control>Category</control> <afc>true</afc> </filter></filters>

Update filter settingsUse the setFilters method to apply policy changes to selected profiles with an XML file with theprofile and filter details.

Example

https://<sms_server>/ipsProfileMgmt/setFilters

Update filter settings XML schema

The profile management API uses the following XML schema for filter settings change requests.


<?xml version="1.0" encoding="utf-8"?><xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:simpleType name="uuid"> <xs:restriction base="xs:string"><xs:pattern value="[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"/> </xs:restriction> </xs:simpleType> <xs:element name="setFilters"> <xs:complexType> <xs:sequence> <xs:element name="profile"> <xs:complexType> <xs:attribute name="name" type="xs:string"/> <xs:attribute name="id" type="uuid"/> </xs:complexType> </xs:element> <xs:element name="filter" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:choice> <xs:element name="policy-id" type="uuid"/> <xs:element name="signature-id" type="uuid"/> <xs:element name="number" type="xs:positiveInteger"/> <xs:element name="name" type="xs:string"/> </xs:choice> <xs:element name="locked" type="xs:boolean" minOccurs="0"/> <xs:element name="comment" type="xs:string" minOccurs="0"/> <xs:element name="control" minOccurs="0"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="Category"/> <xs:enumeration value="Filter"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="actionset" minOccurs="0"> <xs:complexType> <xs:attribute name="refid" type="uuid"/> <xs:attribute name="name" type="xs:string"/> </xs:complexType> </xs:element> <xs:element name="enabled" type="xs:boolean" minOccurs="0"/> <xs:element name="afc" type="xs:boolean" minOccurs="0"/> <xs:element name="useParent" type="xs:boolean" minOccurs="0"/> <xs:element name="trigger" minOccurs="0"> <xs:complexType> <xs:attribute name="threshold"> <xs:simpleType> <xs:restriction base="xs:integer"> <xs:minInclusive value="2"/> <xs:maxInclusive value="10000"/> </xs:restriction> </xs:simpleType>


</xs:attribute> <xs:attribute name="timeout"> <xs:simpleType> <xs:restriction base="xs:long"> <xs:minInclusive value="0"/> <xs:maxInclusive value="999999"/> </xs:restriction> </xs:simpleType> </xs:attribute> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element></xs:schema>

XML elements

The following table describes the XML elements in the filter settings change request.


actionset Empty element with theseattributes:

• refid

• name

Actionset setting defined by a refid expressed inUUID format or a name string

afc Boolean Boolean variable indicating if the filteris managed by the IPS Adaptive FilterConfiguration (AFC)

If a filter is managed by AFC, then the filter willbe automatically disabled when the IPS deviceis under heavy load and the given filter is beingtriggered without actual filter match

comment String User comment on the filter

control String taking one of these values:

• category

Controlling element of the filter's actionsetsetting. If an actionset is controlled by itscategory actionset, then the control is "Category"



• filter If an actionset is controlled by overriding itsdefault actionset, then the control is "Filter"

enabled Boolean Boolean variable specifying if the filter should beenabled or disabled

filter Empty element

This value is read-only.

Parent element of the following elements

locked Boolean Boolean variable indicating if the filter is locked.A locked filter cannot be remotely changed

number Integer


Unique, internal assigned number for the filter

name String


Name of the filter

policy-id String


Internal ID assigned to the policy, expressed inUUID format

profile Empty element with twoattributes:

• id

• name

These values are read-only.

IPS profile identified by ID, expressed in UUIDformat or name string

signature-id

String


Internal ID assigned to the filter, expressed inUUID format



trigger Empty element with theseattributes:

• threshold

• timeout

A filter's trigger frequency detection parameter.The threshold is used to specify the number offilter triggers. The timeout is used to specify thetime period under which the number of triggersare being counted (in seconds).

The trigger element is used only for scan/sweepfilters.

useParent Boolean Boolean variable indicating if a filter's actionsetsetting is inherited from a parent profile

The following sample shows an instance of update filter request XML:

<setFilters> <profile name="test"/> <filter> <number>7001</number> <actionset name="Block + Notify"/> <trigger threshold="10" timeout="5000"/> </filter> <filter> <number>3295</number> <actionset name="Block + Notify"/> </filter> <filter> <signature-id>00000001-0001-0001-0001-000000000027</signature-id> <enabled>false</enabled> </filter> <filter> <policy-id>00000002-0002-0002-0002-000000000051</policy-id> <comment>this is a comment</comment> </filter> <filter> <name>0050: IP Options: Unknown Code</name> <actionset refid="57ec4769-ca05-4dc5-8e79-a34c182adc48"/> </filter></setFilters>

Update filter settings XML response

For a sample XML response for the update filter settings, see Current filter settings XML response on page18.


Retrieve Digital Vaccine informationUse the dvInfo resource to view the active DV on the SMS and all DVs stored on the SMS.

Definition

ipsProfileMgmt/dvInfo

Parameters


request Required. Possible values include the following:

• active: active DV on the SMS.

• all: a list of all DVs on the SMS.

Examples

The following example retrieves the active DV on the SMS.

http[s]://<sms_server>/ipsProfileMgmt/dvInfo?request=active

The following example retrieves a list of all DVs on the SMS.

http[s]://<sms_server>/ipsProfileMgmt/dvInfo?request=all

Reputation managementThe reputation management API enables you to manage the SMS reputation database by importing, adding,deleting, and querying reputation entries.


Reputation management best practicesMonitor the device distribution queue to identify the appropriate time interval for submitting the reputationmanagement API requests in your environment.

The following factors can affect performance levels:

• The method used for the reputation entries submission – import or add. Use import with a largenumber of entries to reduce the number of distributions.

• The number of files to be imported into the reputation database and the number of entries in each file.


• The number of entries on the SMS. A bigger reputation database takes longer to copy and distribute,resulting in less frequent distributions. For improved performance, limit the entries in the reputationdatabase to 6,000,000.

• The number and type of devices that the SMS manages. Newer models load the entries faster. Ifyou have a large number of devices, increase the interval of entry submission so that the SMS is notoverloaded with frequent distributions.

Syntax rules for import filesThe import file must be in a comma-separated value (CSV) format with each line representing a reputationentry without any blank lines. Comment lines are discarded during import.

Each line is made up of one or more fields separated by commas. Construct your entries using the fields inthe following table.

Field Description Required

Address • The first field on each line must be the IPv4 address, IPv6 address,or DNS name for that entry. The remaining fields on a lineare optional. If present, remaining fields are processed as tagcategory/tag value pairs.

• Only one type of address (IPv4, IPv6, or DNS name) can becontained in a file.

• A DNS entry matches any lookups that contain the specifiedstring. For example, foo.com matches foo.com,www.foo.com, and images.foo.com. To specify an exactDNS entry match, enclose the DNS name in square brackets. Forexample, [foo.com].

• CIDR values are normalized. Any bits outside the portion of theaddress specified by the prefix length are changed to zero. Forexample, 192.168.66.127/24 is stored as 192.168.66.0/24.

Yes

Tag category/tag value pairs

If the reputation entry within the file does not have tags, the importedentry merges with the values of the existing entry. If the reputationentry within the file does have tags, the imported entry merges andoverwrites the values of the existing entry.

• Any tag categories in the file must exist on the SMS prior toimport.

No


Field Description Required

• Tag category/value pairs do not have to be listed in the same orderon each line. The entries in the file do not have to list all the tagcategories or specify the ones shared with other entries in the file.

• Empty pairs of fields are ignored. If a tag category field is empty,an error occurs and the entry is not imported. If a tag value fieldis empty, the corresponding tag category is discarded and the nextfield of the entry is processed; the net result is equivalent to the tagcategory not appearing on that line at all.

• Except for yes/no tag categories, character case is significant in alltag category names and tag values.

• For yes/no tag categories, the text yes, regardless of case, denotesa yes value. Any other text is considered a no value.

• For list categories, the list values must be separated by ~~~.

• A field can be enclosed in double-quotes; this is mandatory whena value contains a comma that should not be treated as a fieldseparator.

• To represent a double-quote character within a quoted value, usetwo double-quotes.

Import file example

For the example in this section, the following tag categories are defined:

• Country (List)

• Approved (Yes/No)

• Comment (Text)

For the Country tag category, the following tag values are defined:

• China

• Mexico

• United States

The following example shows a file with IPv4 reputation entries.

1.2.3.0/24,Country,United States,Approved,yes2.3.0.0/16,Country,Mexico,Approved,no3.4.5.0/24,Approved,yes,Country,China


1.2.3.0/24,Country,United States,Approved,yes,Comment,"This comment, contains a comma"1.2.3.0/24,Country,United States,Approved,yes,Comment,"This comment ""contains"" quotes"2.3.0.0/163.4.5.0/24,,,,

Import reputation entriesUse the import method to upload a file with one or more reputation entries. The SMS can upload one fileat a time, and each file can contain multiple entries.

Tip: Each request results in a distribution and a sync time to the managed devices. For improvedperformance, limit the number of entries in a file to between 1,000 and 10,000.

Definition

repEntries/import

Parameters

Parameter Description Required

type Address type of the reputation entry. Possible values include the following:

• ipv4 (default)

• ipv6

• dns

Only one type is allowed within a file.

No

Example

The following example uses cURL to import a file with reputation entries to the SMS. For information onhow to format the import file, see Syntax rules for import files on page 29.

curl -v -k -F "file=@/path/to/file.csv" "http[s]://<sms_server>/repEntries/import?smsuser=<user_name>&smspass=<password>&type=ipv4"

Note: When you request back-to-back imports with files that have 10 or less reputation entries, the SMSgroups those entries to use the add method instead to reduce the number of distributions.

Add reputation entriesUse the add method to create a reputation entry.


Tip: Each request can result in a distribution and a sync time to the managed devices. For improvedperformance, send requests in bursts up to 1,000 entries in time intervals that allow distributions tocomplete in a timely manner.

Definition

repEntries/add

Parameters


ip IPv4 or IPv6 address of the reputation entry. Yes if no dns

dns DNS address of the reputation entry. Yes if no ip

TagData One or more tag categories and their values. Must be UTF-8 encodedand separated by a comma (,).

Note: Reputation entries with a list tag category can include multiplevalues only when the Allow Multiple Values? check boxis selected from the Edit Tag Category box on the SMS.The list values must be separated by ~~~. For example:MalwareIpType,malwareSource~~~cncHost

No

Example

The following example uses cURL to add an IPv4 reputation entry with tag categories MalwareIpTypeand CreatedDate to the SMS.

curl -v -k "http[s]://<sms_server>/repEntries/add?smsuser=<user_name>&smspass=<password>&ip=1.1.1.1&TagData=MalwareIpType,infectedHost,CreatedDate,”Jan 22, 2014”"

Delete reputation entriesUse the delete method to delete one or more reputation entries.

Tip: Each request can result in a distribution and a sync time to the managed devices. For optimalperformance, delete reputation entries with a file.

Definition

repEntries/delete


Parameters


ip IPv4 or IPv6 address of the reputationentry.

Yes withcriteria=entry

dns DNS address of the reputation entry. Yes withcriteria=entry

criteria Possible values include the following:

• all: deletes all reputation entries,including user-defined and RepDV.

• user: deletes all user-defined entries.

• repdv: deletes all RepDV entries.

• entry: deletes specified entries.

Yes

Examples

The following example uses cURL to delete multiple IPv4 and DNS reputation entries.

curl -v -k "http[s]://<sms_server>/repEntries/delete?smsuser=<user_name>&smspass=<password>&ip=1.1.1.1&ip=1.1.1.2&dns=malware.source1.com&dns=malware.source2.com&criteria=entry"

The following example uses cURL to delete all RepDV entries.

curl -v -k "http[s]://<sms_server>/repEntries/delete?smsuser=<user_name>&smspass=<password>&criteria=repdv"

Delete reputation entries with a file

When you want to delete a large number of reputation entries, use delete with a file.

Parameters



type Address type of the reputation entry. Possible values include thefollowing:

• ipv4 (default)

• ipv6

• dns

Only one type is allowed within a file.

Yes

Example

The following example uses cURL to import a file with reputation entries to delete in the SMS. Forinformation on how to format the import file, see Syntax rules for import files on page 29.

curl -v -k -F "file=@/path/to/file.csv" "http[s]://<sms_server>/repEntries/delete?smsuser=<user_name>&smspass=<password>&type=dns"

Query reputation entriesUse the query method to search the reputation database for one or more reputation entries. You canspecify up to 10,000 entries in a single request.

The SMS returns all matching entries in the query in UTF-8 encoding. The returned entries are orderedfrom lowest to highest address, regardless of the order in which they are specified in the query. Each entry isterminated by a newline character.

Definition

repEntries/query

Parameters


ip IPv4 or IPv6 address of the reputation entry. Yes if no dns

dns DNS address of the reputation entry. Yes if no ip


Example

The following example uses cURL to query multiple ipv4 addresses.

curl -v -k "http[s]://<sms_server>/repEntries/query?smsuser=<smsusername>&smspass=<smspassword>&ip=1.1.1.1&ip=1.1.1.2"

The preceding query generates the following response:

1.1.1.1,AtaHost,myata.device.com,MalwareIpType,infectedHost1.1.1.2,AtaHost,myata.device.com,ThreatScore,28,MalwareIpType,cncHost~~~infectedHost

Virtual segment managementThe virtual segment management API enables you to create, update, and delete virtual segments. Inaddition, you can retrieve a list of virtual segments for SMS-managed devices.


Special notes

• Virtual segments can be created that do not initially contain any physical segments.

• IPS devices with virtual segments that were configured locally on an IPS device and then added to theSMS are merged to the global virtual segment listing.

• A virtual segment must contain at least one VLAN ID, source IP, or destination IP traffic definition.

Note: A named resource is an individual resource, typically created to be included in a named resource group.You cannot create a named resource using the SMS web API. Any named resource in the file mustexist on the SMS.

Virtual segment response codesThe following table describes the available web API response codes and their corresponding HTTPresponse codes.

Web API response code HTTP response code Description

0 200 Successful completion

100 401 Authentication error

200 400 Missing parameter error


Web API response code HTTP response code Description

205 400 Operation error

300 400 Input XML file error

305 500 Output result file error

310 400 Validation error

320 400 Resource error

500 500 Unexpected error

Example responses

Retrieve list of virtual segments

<smsResponse> <service>virtualsegment</service> <operation>get</operation> <resultCode>0</resultCode> <resultDetails> <virtualSegments> <virtualSegment> <name>NamedResourceExample</name> <description></description> <virtualSegPosition positionType="ORDINAL_POSITION"> <ordinalPosition>1</ordinalPosition> </virtualSegPosition> <vlanIdList> <namedVlanGroup>WAN-Group</namedVlanGroup> </vlanIdList> <sourceAddressList> <namedAddrGroup>AccountingDeptsrcAddress</namedAddrGroup> </sourceAddressList> <destinationAddressList> <namedAddrGroup>DMZ</namedAddrGroup> </destinationAddressList> <segmentGroup> <segmentGroupID> <name>Default</name> </segmentGroupID> </segmentGroup> <physicalSegments>


<physicalSegment> <device> <name>IPS_device_name</name> </device> <segmentNameList> <segmentNames>Segment 1-1 (A > B)</segmentNames> <segmentNames>Segment 1-1 (A < B)</segmentNames> <segmentNames>Segment 1-2 (A > B)</segmentNames> <segmentNames>Segment 1-2 (A < B)</segmentNames> </segmentNameList> </physicalSegment> </physicalSegments> </virtualSegment> </virtualSegments> </resultDetails></smsResponse>

Create virtual segment

<smsResponse> <service>virtualsegment</service> <operation>create</operation> <resultCode>0</resultCode> <resultDetails> <deviceResults> <deviceResult> <device> <name>IPS_device_name</name> </device> <success>true</success> </deviceResult> </deviceResults> </resultDetails></smsResponse>

Virtual segment XML schemaThe Virtual Segment Management API uses the following XML schema.

<?xml version="1.0" encoding="UTF-8"?><xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema" > <xs:simpleType name="uuid"> <xs:restriction base="xs:string"> <xs:pattern value="[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f] {4}-[0-9a-f]{4}-[0-9a-f]{12}"/> </xs:restriction></xs:simpleType><xs:simpleType name="vs_name"> <xs:restriction base="xs:string"> <xs:maxLength value="127"/> </xs:restriction>


</xs:simpleType><xs:simpleType name="vlan_Constraint"> <xs:restriction base="xs:int"> <xs:minInclusive value="0"/> <xs:maxInclusive value="4095"/> </xs:restriction></xs:simpleType><xs:simpleType name="vs_description"> <xs:restriction base="xs:string"> <xs:maxLength value="250"/> </xs:restriction></xs:simpleType> <xs:simpleType name="positionType"> <xs:restriction base="xs:string"> <xs:annotation> <xs:documentation>Placement of the object in the list, first, last, or somewhere in between</xs:documentation> </xs:annotation> <xs:enumeration value="FIRST" /> <xs:enumeration value="LAST" /> <xs:enumeration value="ORDINAL_POSITION" /> </xs:restriction></xs:simpleType><xs:complexType name="messageList"> <xs:sequence> <xs:element type="xs:string" name="message" minOccurs="1" maxOccurs="unbounded"/> </xs:sequence></xs:complexType> <xs:complexType name="deviceResult"> <xs:all> <xs:element name="device" type="deviceType"/> <xs:element name="success" type="xs:boolean"/> <xs:element name="messages" type="messageList" minOccurs="0" maxOccurs="1"/> </xs:all></xs:complexType><xs:complexType name="deviceResultList"> <xs:sequence> <xs:element type="deviceResult" name="deviceResult" minOccurs="1" maxOccurs="unbounded"/> </xs:sequence></xs:complexType><xs:complexType name="rangeType"> <xs:all> <xs:annotation> <xs:documentation>Range (i.e. 5 - 90)</xs:documentation> </xs:annotation> <xs:element type="vlan_Constraint" name="start"/> <xs:element type="vlan_Constraint" name="end"/> </xs:all>


</xs:complexType> <xs:complexType name="idName"> <xs:choice> <xs:element name="id" type="xs:string"/> <xs:element name="name" type="xs:string"/> </xs:choice></xs:complexType><xs:complexType name="cidrListType"> <xs:sequence> <xs:element type="xs:string" name="cidr" maxOccurs="unbounded"> <xs:annotation> <xs:documentation>1 or more repetitions:1 or more repetitions:</xs:documentation> </xs:annotation> </xs:element> </xs:sequence></xs:complexType><xs:element name="virtualSegment" type="virtualSegmentType" nillable="false" /> <xs:element name="virtualSegmentList" type="virtualSegmentListType" nillable="false"/> <xs:complexType name="segmentGroupType"> <xs:sequence> <xs:element type="segmentGroupIDType" name="segmentGroupID"/> </xs:sequence> </xs:complexType> <xs:complexType name="sourceAddressListType"> <xs:choice> <xs:annotation> <xs:documentation>You have a CHOICE of the next 2 items at this level</xs:documentation> </xs:annotation> <xs:element type="cidrListType" name="cidrList"> </xs:element> <xs:element type="xs:string" name="namedAddrGroup"> </xs:element> </xs:choice></xs:complexType><xs:complexType name="vlanIdListType"> <xs:sequence> <xs:annotation> <xs:documentation>VLAN can either be a 1 named resource or a list of integer/ranges</xs:documentation> </xs:annotation> <xs:choice> <xs:element type="vlanListType" name="vlanList" > </xs:element> <xs:element type="xs:string" name="namedVlanGroup"> </xs:element> </xs:choice> </xs:sequence></xs:complexType>


<xs:complexType name="virtualSegmentType" > <xs:annotation> <xs:documentation>Definition of the virtual segment</xs:documentation> <xs:documentation>Any optional fields should be omitted, no empty elements</xs:documentation> <xs:documentation>Required: Name, segmentGroup, one, two or all of: [vlanIdList,sourceAddressList, destinationAddressList]</xs:documentation> <xs:documentation>Optional: description, and physicalSegments. If physicalSegments is not provided no devices will be updated with the virtual segment</xs:documentation> </xs:annotation> <xs:all> <xs:element type="vs_name" name="name" /> <xs:element type="vs_description" name="description" nillable="false" minOccurs="0"/> <xs:element type="virtualSegPositionType" name="virtualSegPosition"/> <xs:element type="vlanIdListType" name="vlanIdList" nillable="false" minOccurs="0"> </xs:element> <xs:element type="sourceAddressListType" name="sourceAddressList" nillable="false" minOccurs="0"> </xs:element> <xs:element type="destinationAddressListType" name="destinationAddressList" nillable="false" minOccurs="0"> </xs:element> <xs:element type="segmentGroupType" name="segmentGroup" /> <xs:element type="physicalSegmentsType" name="physicalSegments" nillable="false" minOccurs="0"> </xs:element> </xs:all> </xs:complexType> <xs:complexType name="virtualSegmentListType"> <xs:sequence> <xs:element type="virtualSegmentType" name="virtualSegment" nillable="false" minOccurs="1" maxOccurs="unbounded"> </xs:element> </xs:sequence> </xs:complexType> <xs:complexType name="destinationAddressListType"> <xs:choice> <xs:annotation> <xs:documentation>You have a CHOICE of the next 2 items at this level</xs:documentation> </xs:annotation> <xs:element type="cidrListType" name="cidrList"> </xs:element> <xs:element type="xs:string" name="namedAddrGroup"> </xs:element> </xs:choice> </xs:complexType> <xs:complexType name="segmentGroupIDType"> <xs:choice> <xs:annotation>


<xs:documentation>You have a CHOICE of the next 2 items at this level</xs:documentation> </xs:annotation> <xs:element type="xs:string" name="id"> </xs:element> <xs:element type="xs:string" name="name"/> </xs:choice> </xs:complexType> <xs:complexType name="virtualSegPositionType"> <xs:sequence> <xs:element nillable="true" type="xs:positiveInteger" minOccurs="0" name="ordinalPosition"> </xs:element> </xs:sequence> <xs:attribute type="positionType" name="positionType"/> </xs:complexType> <xs:complexType name="deviceType"> <xs:choice> <xs:annotation> <xs:documentation>You have a CHOICE of the next 4 items at this level</xs:documentation> </xs:annotation> <xs:element type="uuid" name="id"/> <xs:element type="xs:positiveInteger" name="shortID"/> <xs:element type="xs:string" name="name"/> <xs:element type="xs:string" name="ipAddress"/> </xs:choice> </xs:complexType> <xs:complexType name="segmentNameListType"> <xs:sequence> <xs:element type="xs:string" name="segmentNames" minOccurs="1" maxOccurs="unbounded"> <xs:annotation> <xs:documentation>1 or more device segment names</xs:documentation> </xs:annotation> </xs:element> </xs:sequence> </xs:complexType> <xs:complexType name="vlanIdRangeType" > <xs:choice> <xs:element name="vlanID" type="vlan_Constraint"/> <xs:element name="vlanRange" type="rangeType"/> </xs:choice> </xs:complexType> <xs:complexType name="vlanListType" > <xs:sequence> <xs:element name="vlan" type="vlanIdRangeType" minOccurs="1" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <xs:complexType name="physicalSegmentsType"> <xs:sequence> <xs:annotation>


<xs:documentation>1 or more repetitions:</xs:documentation> </xs:annotation> <xs:element type="deviceSegmentsType" name="physicalSegment" maxOccurs="unbounded"> </xs:element> </xs:sequence> </xs:complexType> <xs:complexType name="deviceSegmentsType"> <xs:sequence> <xs:element type="deviceType" name="device"/> <xs:element type="segmentNameListType" name="segmentNameList"/> </xs:sequence> </xs:complexType></xs:schema>

Virtual Segment XML elementsThe following table describes the elements in the Virtual Segment Management XML schema.


name String Name of the virtual segment

description (optional) String Description for the virtualsegment

virtualSegPosition Indicates where in the listvirtual segment is placed. Youdefine the priority order fora virtual segment so that anyoverlapping definitions areresolved. Attempting to definean overlapping virtual segmenton a device which does notallow it will produce an error.

virtualSegPosition/positionType

ORDINAL_POSITION,FIRST, LAST

Attribute; must be one of thethree values

virtualSegPosition/ordinalPosition

Positive Integer Must be providedwhen positionType isORDINAL_POSITION



vlanIdList (optional) Used to assign a list of VLANIDs, and/or VLAN ranges ora named object referencing anamed VLAN group

vlanIdList/vlanList Used when assigning a list ofVLAN IDs and/or VLANranges to the virtual segment

vlanIdList/vlanList/vlan Single element for either aVLAN ID or VLAN range

vlanIdList/vlanList/vlan/vlanID

Integer (1 to 4094) VLAN ID

vlanIdList/vlanList/vlan/vlanID/vlanRange

Element containing a VLANrange

vlanIdList/vlanList/vlan/vlanID/vlanRange/start

Integer (1 to 4094) VLAN ID start of the range

vlanIdList/vlanList/vlan/vlanID/vlanRange/end

Integer (1 to 4094) VLAN ID end of the range

vlanIdList/namedVlanGroup String Named VLAN group identifier

sourceAddressList (optional) Used to assign a list of IPaddresses and/or IP addressblocks or a named objectreferencing a named addressgroup for the source address

sourceAddressList/cidrList Used when providing a list ofIP addresses and/or IP addressblocks



sourceAddressList/cidrList/cidr

IP address or IP address block

sourceAddressList/namedAddrGroup

String Named address group identifier

destinationAddressList(optional)

Used to assign a list of IPaddresses, and/or IP addressblocks or a named objectreferencing a named addressgroup for the destinationaddress

destinationAddressList/cidrList

Used when providing a list ofIP addresses and/or IP addressblocks

destinationAddressList/cidrList/cidr

IP address or IP address block

destinationAddressList/namedAddrGroup

String Named address group identifier

segmentGroup Used when assigning a virtualsegment to a segment group

segmentGroup/segmentGroupID Identifier element for thesegment group

segmentGroup/segmentGroupID/name

String Name of the segment group

segmentGroup/segmentGroupID/id

String ID of the segment group



physicalSegments (optional) Used for assigning the virtualsegment to one or moresegments on one or moredevices

physicalSegments/physicalSegment

Identifies the device and thesegments to assign the virtualsegment to

physicalSegments/physicalSegment/device

Identifies the device

physicalSegments/physicalSegment/device/uuid

String UUID of the device

physicalSegments/physicalSegment/device/shortID

Positive integer Short ID of the device

physicalSegments/physicalSegment/device/name

String Name of the device

physicalSegments/physicalSegment/device/ipAddress

String IP Address of the device

physicalSegments/physicalSegment/segmentNameList

Element containing a list of thesegment names

physicalSegments/physicalSegment/segmentNameList/segmentNames

String Name of the segment


Create a virtual segmentUse the create method to create a virtual segment with a file.

Definition

virtualsegment/create

Examples

The following example uses cURL to create a virtual segment.

curl -v -k -F "[email protected]""http[s]://<sms_server>/virtualsegment/create?smsuser=<user_name>&smspass=<password>"

Create a virtual segment (any VLAN, any destination, and a specific source IP address)

<virtualSegment> <name>AnyExample</name> <description></description> <virtualSegPosition positionType="FIRST"> </virtualSegPosition> <sourceAddressList> <cidrList> <cidr>1.1.1.133</cidr> </cidrList> </sourceAddressList> <segmentGroup> <segmentGroupID> <name>Default</name> </segmentGroupID> </segmentGroup> </virtualSegment>

Create a virtual segment (named resource):

For the sample XML that you can use to adjust the virtual segment position, see Update a virtual segment onpage 47.

Note: Any named resources that appear in the file must exist on the SMS.

<virtualSegment> <name>NamedResourceExample</name> <description></description> <virtualSegPosition positionType="LAST"> </virtualSegPosition> <vlanIdList> <namedVlanGroup>WAN-Group</namedVlanGroup> </vlanIdList> <sourceAddressList> <namedAddrGroup>AccountingDeptsrcAddress</namedAddrGroup>


</sourceAddressList> <destinationAddressList> <namedAddrGroup>DMZ</namedAddrGroup> </destinationAddressList> <segmentGroup> <segmentGroupID> <name>Default</name> </segmentGroupID> </segmentGroup> <physicalSegments> <physicalSegment> <device> <name>IPS_device_name</name> </device> <segmentNameList> <segmentNames>Segment 1-1 (A > B)</segmentNames> <segmentNames>Segment 1-1 (A < B)</segmentNames> <segmentNames>Segment 1-2 (A > B)</segmentNames> <segmentNames>Segment 1-2 (A < B)</segmentNames> </segmentNameList> </physicalSegment> </physicalSegments> </virtualSegment>

Update a virtual segmentUse the update method to update a virtual segment with a file.

Definition

virtualsegment/update

Parameters


vs The name of the virtual segment to be updated on the device and on the SMS.

Example

The following example uses cURL to update a virtual segment named NamedResourceExample.

curl -v -k -F "[email protected]""http[s]://<sms_server>/virtualsegment/update?smsuser=<user_name>&smspass=<password>&vs=NamedResourceExample"


The following sample XML shows how you can update a virtual segment by adjusting the virtual segmentposition.

Note: Any named resources that appear in the file must exist on the SMS.

<virtualSegment> <name>NamedResourceExample</name> <description></description> <virtualSegPosition positionType="ORDINAL_POSITION"> <ordinalPosition>3</ordinalPosition> </virtualSegPosition> <vlanIdList> <namedVlanGroup>WAN-Group</namedVlanGroup> </vlanIdList> <sourceAddressList> <namedAddrGroup>AccountingDeptsrcAddress</namedAddrGroup> </sourceAddressList> <destinationAddressList> <namedAddrGroup>DMZ</namedAddrGroup> </destinationAddressList> <segmentGroup> <segmentGroupID> <name>Default</name> </segmentGroupID> </segmentGroup> <physicalSegments> <physicalSegment> <device> <name>IPS_device_name</name> </device> <segmentNameList> <segmentNames>Segment 1-1 (A > B)</segmentNames> <segmentNames>Segment 1-1 (A < B)</segmentNames> <segmentNames>Segment 1-2 (A > B)</segmentNames> <segmentNames>Segment 1-2 (A < B)</segmentNames> </segmentNameList> </physicalSegment> </physicalSegments> </virtualSegment>

Delete a virtual segmentsUse the delete method to delete a virtual segment.


Parameters


vs The name of the virtual segment to be deleted from the device and from the SMS.

Example

The following example uses cURL to delete a virtual segment named namedResourceExample.

curl -v -k "http[s]://<sms_server>/virtualsegment/delete?smsuser=<user_name>&smspass=<password>&vs=NamedResourceExample"

Retrieve a list of virtual segmentsUse the get method to retrieve a list of all of the virtual segments on the SMS in XML format. In addition,the request returns the device NAME from the DEVICE table. For more information, see DEVICE tableon page 63

Note: Use the following links to download the XML schema from the SMS: https://<sms_ip_or_hostname>/xsds/VirtualSegment.xsd or https://<sms_ip_or_hostname>/xsds/sms/response/xsd.

Definition

virtualsegment/get

Example

The following example uses cURL to get a list of the virtual segments.

curl -v -k "http[s]://<sms_server>/virtualsegment/get?smsuser=<user_name>&smspass=<password>"

Remote administrationThe remote administration API enables you to backup the SMS database and retrieve SMS software versioninformation.

Backup the SMS databaseUse the backup resource to create a backup of the SMS database.

Definition

smsAdmin/backup

https://customer_sms/xsds/VirtualSegment.xsd

https://customer_sms/xsds/VirtualSegment.xsd

https://customer_sms/xsds/smsresponse.xsd


Parameters


type Destination type: smb, nfs, scp, sftp, sms (stored locally on theSMS—only one backup allowed at a time)

location Destination path for backup file; does not apply for destination typesms

username Type-specific username; used for destination types smb, scp andsftp

password Type-specific password; used for destination types: smb, scp andsftp

domain Type-specific domain; only used for destination type smb

tos Number of most recent TOS packages to include (default value = 0)

dv Number of most recent DV packages to include (default value = 1)

events Include events data (boolean—default value false)

notify Send email notification when backup has completed or failed (boolean—default value true)

timestamp Use timestamp to build backup file name (boolean—default valuetrue)

encryptionPass Encrypt backup using supplied password (default null—do notencrypt)

smsuser SMS username to use for the backup operation



smspass SMS password

Back up locally to SMS (with defaults)

The following example shows the URL format you use when backing up locally to the SMS. The exampleomits optional parameters to accept default values.

http[s]://<sms_server>/smsAdmin/backup?type=sms

Back up with SCP (with some defaults)

The following example shows the URL format you use when creating a backup with SCP. The examplespecifies some parameters and omits others to accept default values.

http[s]://<sms_server>/smsAdmin/backup?type=<scp>&location=<//203.0.113.0/home/usr/backups/>&username=<scp_user>&password=<scp_pwd>&timestampName=<true>

Back up to SMS Server (with no defaults)

The following example shows the URL format to use when you backup to an SMB server, and specifiessample values for all parameters.

http[s]://<sms_server>/smsAdmin/backup?type=<smb>&location=<//198.51.100.100/backups/sms.bak>&username=<smb_user>&password=<smb_pwd>&domain=<dom00>&tos=<1>&dv=<1>&events=<false>&notify=<false>&timestampName=<true>

Retrieve the SMS versionUse the info resource to retrieve the SMS software version. The request returns a version number.

Example

http[s]://<sms_server>/smsAdmin/info?request=version&smsuser=<sms_user>&smspass=<password>

Enterprise Vulnerability RemediationThe Enterprise Vulnerability Remediation (eVR) API enables you import vulnerability scans to the SMS.After you import a vulnerability scan, use the SMS client to:

• View vulnerabilities (listed by CVE) that have been discovered in your network; view which assetsare impacted by those vulnerabilities; and view which DV filters can defend those assets from thediscovered vulnerabilities.


• Select a profile to quickly highlight DV filters that can protect your assets from the discoveredvulnerabilities.

• Flag CVEs for follow-up.

• Track policy changes.

• Adjust profiles to protect your assets.

After you import a vulnerability scan, you can view the scan on the SMS (select Profiles > VulnerabilityScans).


Vulnerability scan specificationsVulnerability scans must be in a native, comma-separated value (CSV) format before they can be used onthe SMS. If you use a supported vulnerability management product, custom converters are available forQualys®, Rapid7 Nexpose®, and Tenable™ Nessus®.

CSV file specifications

Note the following CSV file specifications (and sequence) for the native SMS-Standard format before youimport a vulnerability scan:

• The first line in the CSV file must be the column headers for each of the columns.

• Each row after the header must contain the same number of columns that are in the header.

• Each column must be delimited with a comma.

• The value within each column must be wrapped in double quotes; however, embedded double quotesare not permitted ("This is "invalid" data").

• Each row in a CSV file must be less than 65536 bytes.

Vulnerability scan specifications

The minimum data required for a native SMS-Standard vulnerability scan is:

• IP Address - (host IP addresses) The maximum number of host IP address and vulnerabilitycombinations that you can import on the SMS is 10 million. When the SMS reaches the maximum limit,it displays an error message, and you must delete vulnerability scans on the SMS client before you canimport a new scan using the eVR API.

• CVE IDs - CVE must be in the format CVE-YYYY-NNNN where YYYY is a 4 digit year and NNNNis a sequence number.

• Severity - Vulnerabilities are assigned a severity levels to define the urgency associated with remediatingeach vulnerability. Rankings are based on a variety of industry standards including CVE.


For more information about the native, SMS-Standard fields in the CSV file format on the SMS, selectProfiles > Vulnerabilty Scans > Import > more.

Import a vulnerability scanUse the import method to import a vulnerability scan file that is in native SMS-Standard format.

Definition

vulnscanner/import

Parameters


vendor Name of the vulnerability management vendor. Use the SMS-Standard value with the import method.

For other values, see Convert a vulnerability scan on page 54.

Yes

product Product name associated with the vulnerability scanner, and can beany value.

Yes

version Version of the vulnerability scanning file format, and can be anyvalue.

Yes

runtime Scan start time and end time, and can be a single date or a daterange. When entering a date range, you must use a forward slash(/) to separate the scan start and scan end dates.

The date format must be yyyy-MM-dd'T'HH:mm:ss.SSS'Z.

Yes

Example

The following example uses cURL to import a vulnerability scan to the SMS in the native SMS-Standardformat.

curl -v -k -F "[email protected]""http[s]://<sms_server>/vulnscanner/import?<smsuser>=<sms_username>&smspass=<sms_password>&vendor=SMS-Standard&product=Vulnscanner&version=1.0&runtime=2014-01-20T13:01:15.255Z/2014-01-20T13:22:14.333Z"


Convert a vulnerability scanUse the convert method to convert a vulnerability scan file that is not in native SMS-Standard format toimport to the SMS.

Definition

vulnscanner/convert

Parameters


vendor Name of the vulnerability management vendor. Possible valuesinclude the following:

• Nexpose

• Qualys-CSV

• Nessus

Yes

product Product name associated with the vulnerability scanner, and canbe any value.

Yes

version Version of the vulnerability scanning file format, and can be anyvalue.

Yes

runtime Scan start time and end time, and can be a single date or a daterange. When entering a date range, you must use a forward slash(/) to separate the scan start and scan end dates.

The date format must be yyyy-MM-dd'T'HH:mm:ss.SSS'Z.

Yes

Examples

The following example uses cURL to import a vulnerability scan to the SMS in the Nexpose format.

curl -v -k -F "[email protected]" "http[s]://<sms_server>/vulnscanner/convert?smsuser=<sms_username>&smspass=<sms_password>&vendor=Nexpose&product=Nexpose&version=1.0&runtime=2014-01-20T13:01:15.255Z/2014-01-20T13:22:14.333Z"

The following example uses cURL to import a vulnerability scan to the SMS in the Qualys-CSV format.


curl -v -k -F "[email protected]" "http[s]://<sms_server>/vulnscanner/convert?smsuser=<sms_username>&smspass=<sms_password>&vendor=Qualys-CSV&product=Qualys&version=1.0&runtime=2014-01-20T13:01:15.255Z/2014-01-20T13:22:14.333Z"

The following example uses cURL to import a vulnerability scan to the SMS in the Nessus format.

curl -v -k -F "[email protected]" "http[s]:<sms_server>/vulnscanner/convert?smsuser=<sms_username>&smspass=<sms_password>&vendor=Nessus&product=Nessus-Sample&version=1.0&runtime=2014-01-20T13:01:15.255Z/2014-01-20T13:22:14.333Z"

Active responseUse the active response API to create and close a response.

By default, no policies can be externally triggered. To enable external triggering, configure the activeresponse policy to allow an SNMP trap or web service to invoke the policy. For more information, see theSecurity Management System User Guide.

Active response best practicesCreate a user and policies specifically for this interface to organize which policies are involved with calls thathappen externally.

Create a responseUse the quarantine method to quarantine an IP address.

Definition

quarantine/quarantine

Parameters


ip IP address for the target host. Required to create or close a response.

id Response History ID that is displayed in the Response History table. Toclose a response, either IP or ID must be specified.



policy Specific Active Response Policy to implement. The policy name is casesensitive and must match an existing SMS Active Response policy name.The Allow an SNMP Trap or Web Service call to invoke this Policyinitiation setting must be enabled for this policy. This argument is notnecessary to close a response and, if provided, is ignored.

timeout Optional argument to specify the duration of response. The specifiedvalue overrides the default already in the policy. If no parameter isspecified, the timeout value from the policy is used. This argument isnot necessary to close a response and, if provided, is ignored.

Example

http[s]://<sms_server>/quarantine/quarantine?ip=<target_ip>&policy=<policy_name>&timeout=<minutes_to_quarantine>&smsuser=<user_name>&smspass=<password>

Close a responseUse the unquarantine method to unquarantine an IP address.

Definition

quarantine/unquarantine

Parameters


ip IP address for the target host. Required to create or close a response.

id Response History ID that is displayed in the Response History table. Toclose a response, either IP or ID must be specified.



policy Specific Active Response Policy to implement. The policy name is casesensitive and must match an existing SMS Active Response policy name.The Allow an SNMP Trap or Web Service call to invoke this Policyinitiation setting must be enabled for this policy. This argument is notnecessary to close a response and, if provided, is ignored.

timeout Optional argument to specify the duration of response. The specifiedvalue overrides the default already in the policy. If no parameter isspecified, the timeout value from the policy is used. This argument isnot necessary to close a response and, if provided, is ignored.

Example

http[s]://<sms_server>/quarantine/unquarantine?ip=<target_ip>&smsuser=<user_name>&smspass=<password>

Packet traceThe SMS Packet Trace feature compiles information about packets that have triggered a filter. Packet traceencapsulates the information according to requirements set for the filter in the SMS.

Packet trace options are configured for an action set, and an action set is specified for each filter. Filters aredistributed to devices according to profiles. If a filter uses an action set for which packet trace logging isenabled, then you can view the compiled and stored packet trace information for events that triggered thefilter.

The SMS saves packet trace information to a PCAP file. Two retrieval options are available for a packettrace:

• Device-based packet trace on page 57

• Events-based packet trace on page 58

Device-based packet traceDevice-based packet trace compiles PCAP information for a particular device from the SMS database. Thefollowing example shows the URI format to obtain a device-based packet trace. The deviceId in theexample is the SHORT_ID for the device. For more information, see DEVICE table on page 63.

http[s]://<sms_server>/pcaps/getByDevice?deviceId=<SHORT_ID>


Events-based packet traceTo obtain all the PCAP information from the SMS for a group of events, you must know the event IDs.

Event IDs are included in data sent to a remote syslog server. For information about configuring and usingRemote Syslog, see the Security Management System User Guide, and refer to the current SMS Deployment Noteavailable from the TMC.

Set up event-based packet trace

1. Set up a remote syslog server.

2. Add all the event IDs to a file as a comma separated list (new line breaks are also allowed).

3. Use cURL to upload the file to the Web server.

The following example demonstrates a POST request to upload the file using cURL:

curl -k -v -F "file=@<filepath/to/eventidfile.txt>""https://<sms_server>/pcaps/getByEventIds?smsuser=<user_name>&smspass=<password>"

The result outputs to STDOUT and can be redirected to a file with a '>' operator.

Database accessUse the SMS web API to access various data, including the SMS data dictionary, table, database schema,status of the web services support, and the version of the SMS web API.

Definition

dbAccess/tptDBServlet

Parameters


method Possible values include the following:

• DataDictionary: Data dictionary information related toprofiles, devices, segments, and virtual segments.

• GetData: Data from the specified table.

• GetOldestRecord: The oldest record of the specifiedtable.

Yes



• GetNewestRecord: The newest record of the specifiedtable.

• Schema: Database schema.

• Status: Status of the SMS web API support.

• Version: Version of the SMS web API.

Usage sequenceFollow this sequence when accessing the SMS database:

1. Use the Schema method to retrieve the schema definition. Apply the returned data to user-defineddatabase.

2. Use the DataDictionary method to retrieve supporting data. Apply the returned data to database.You may repeat this step as needed, such as to create new profiles and activate new DVs.

3. Continuously use the GetData method, and import the event data into the database.

DataDictionaryUse the DataDictionary resource to obtain SMS data dictionary information. For more informationabout the XML response to a DataDictionary request, see DataDictionary XML response on page73.

Definition

dbAcess/tptDBServlet?method=DataDictionary

Parameters


format Possible values include the following:

• sql(default)

• csv

• xml

No



mode Possible values include the following:

• insert(default) – use with sql format.

• update

• replace– use with MySQL.

No

table If you do not specify a table, all tables areincluded. Possible values include the following:

• ACTIONSET – see ACTIONSET table onpage 61.

• ALERT_TYPE – see ALERT_TYPE tableon page 62.

• DEVICE – see DEVICE table on page63.

• POLICY – see POLICY table on page64.

• PRODUCT_CATEGORY – seePRODUCT_CATEGORY table on page65.

• PROFILE – see PROFILE table on page65.

• PROFILE_INSTALL_INVENTORY –see PROFILE_INSTALL_INVENTORYtable on page 66.

• QUARANTINE_NETWORK_DEVICES– seeQUARANTINE_NETWORK_DEVICEStable on page 66.

• SEGMENT – see SEGMENT table on page66.

• SEGMENT_GROUP – seeSEGMENT_GROUP table on page 67.

No



• SEVERITY – see SEVERITY table onpage 67.

• SIGNATURE – see SIGNATURE table onpage 68.

• TAXONOMY_MAJOR – seeTAXONOMY_MAJOR table on page69.

• TAXONOMY_MINOR – seeTAXONOMY_MINOR table on page69.

• TAXONOMY_PLATFORM – seeTAXONOMY_PLATFORM table on page70.

• TAXONOMY_PROTOCOL – seeTAXONOMY_PROTOCOL table on page70.

• THRESHOLD_UNITS – seeTHRESHOLD_UNITS table on page71.

• VIRTUAL_SEGMENT – seeVIRTUAL_SEGMENT table on page73.

Example

http[s]://<sms_server>/dbAccess/tptDBServlet?method=DataDictionary&format=sql

ACTIONSET table

An ACTIONSET record is one defined by the user and applied to a POLICY. The ACTIONSET hasa descriptive name that can help determine the action that is taken when a POLICY is triggered. ForRATELIMIT ACTIONSETs, the RATE column has a value specifying the RATE to be applied. This tableis not expected to grow by many entries. It is a relatively small table.


Column Description

ID Unique identifier for the record entry; use this column to join fromother tables

NAME Descriptive name for the ACTIONSET

RATE RATELIMIT value applied to this ACTIONSET

FLOW_CONTROL Traffic flow indicator (ALLOW, DENY, TRUST, and RATE)

ALERT_TYPE table

A simple table that gives descriptive names for ALERTS. The table should not grow, but may have newtypes added in future releases.

Column Description

ID Unique identifier for this record

NAME Descriptive name for the entry

CATEGORY table

The CATEGORY table maintains the names used for SIGNATURE categories. The SIGNATUREtable contains a number that is joined to the ID field in this CATEGORY table. The NAME field is thedescriptive text for the CATEGORY.

Column Description


NAME Descriptive name for the CATEGORY


DEVICE table

This table contains a record for each of the devices being managed. This table is not expected to grow bymany entries. It is a relatively small table.

Column Description

ID Unique identifier for the table entry

SHORT_ID Lookup identifier for the table entry

NAME Descriptive name for the device provided during device installation

MODEL String that represents the model of the device

SERIAL_NUMBER Alpha-numeric TippingPoint serial number

IP_ADDRESS IP address for the management port for the device

LOCATION Descriptive location text entered during device installation

DV_VERSION Current version of the Digital Vaccine installed on the device; if thedevice is a Core Controller, this field is null

OS_VERSION Current version of the TOS installed on the device

DEVICE_GROUP Name of the group to which the device belongs

MANAGED Boolean to show if the device is currently managed by the SMS

NOTICE_ACTION table

A simple table that gives descriptive names for ALERTS. The table should not grow, but may have newtypes added in future releases.


Column Description


NAME Descriptive name for the entry

POLICY table

The POLICY table holds objects that are setup to determine what actions to take and behavior to havefor a SIGNATURE trigger. This table is expected to grow based on the number of changes made to thePROFILE table entries. It is a relatively small table.

Column Description


PROFILE_ID Identifier of the PROFILE object that contained this POLICY

SIGNATURE_ID Identifier of the SIGNATURE this object is defining in a POLICY

ACTIONSET_ID Identifier for the ACTIONSET applied to this object

DISPLAYNAME Descriptive name for the POLICY, which is usually the same asthe SIGNATURE referenced by SIGNATURE_ID; however,THRESHOLDS allow you to name the POLICY

MULTIPART_GROUP_ID Identifier for SMS policy group

POLICY_GROUP_LOOKUP table

This table holds the mapping information for policy group information in SMS and in device. This table isused to find the policy information from the event/statistic that comes from the device.

Example


Select * from DDOS_STATS DS, POLICY_GROUP_LOOKUP PGL, POLICY POLwhere DS.DEV_GROUP_ID = PGL.DEV_GROUP_ID and PGL.SMS_GROUP_ID =POL.MULTIPART_GROUP_ID;

Column Description

DEV_GROUP_ID Identifier for the POLICY group in device

SMS_GROUP_ID Identifier of the PROFILE group in SMS

PRODUCT_CATEGORY table

The PRODUCT_CATEGORY table maintains the names used for SIGNATURE categories. TheSIGNATURE table contains a number that is joined to the ID field in this PRODUCT_CATEGORY table.The NAME field is the descriptive text for the PRODUCT_CATEGORY.

Column Description


NAME Descriptive name for the PRODUCT_CATEGORY

PROFILE table

The PROFILE table is a container for your POLICY entries. You are able to name the PROFILE, makechanges to the POLICY objects, and then distribute to a segment group. Table size depends on the numberof PROFILEs you create in the SMS. It is a relatively small table.

Column Description


VERSION Current version of the PROFILE

NAME Descriptive name of the PROFILE


Column Description

DESCRIPTION Description of the PROFILE

PROFILE_INSTALL_INVENTORY table

The PROFILE_INSTALL_INVENTORY table is a container for items associated with PROFILE entries.Table size depends on the number of PROFILEs you create in the SMS. It is a relatively small table.

Column Description

VIRTUAL_SEGMENT_ID Lookup identifier for the virtual segment where the profile wasdistributed

PROFILE_ID Lookup identifier for the profile details

PROFILE_VERSION Profile version

DISTRIBUTE_ID Lookup identifier for the distribution details

COMPLETE_TIME Time the profile distribution completed; this value is in millisecondssince Jan. 1, 1970 00:00:00 GMT

QUARANTINE_NETWORK_DEVICES table

The QUARANTINE_NETWORK_DEVICES table contains the defined quarantine switches.

Column Description

NAME Descriptive name for the network device switch type

IP_ADDRESS IP address for the switch

SEGMENT table

A SEGMENT record represents a physical SEGMENT on a DEVICE. It is a relatively small table and isonly expected to grow when new devices are added to your network.


Column Description

ID Unique identifier for this record entry

DEVICE_ID DEVICE to which this SEGMENT belongs

NAME Descriptive name

IP_ADDRESS OBSOLETE IP Address that may be given to this SEGMENT

This value was used in Discovery services, which have been removedfrom the product

SLOT_INDEX Internal chassis slot number; this number is always 3 for physicalsegments and 0 for virtual segments

SEGMENT_INDEX For physical segments, the physical segment number; for virtualsegments, this number is 0

SEGMENT_GROUP table

A SEGMENT_GROUP record represents a group of physical SEGMENTS. It is a relatively small table andis only expected to grow when new devices are added to your network.

Column Description

ID Unique identifier for this entry

NAME Descriptive name for the SEGMENT GROUP provided during groupcreation

SEVERITY table

The SEVERITY table is a static table used to provide descriptive text for SEVERITY fields.


Column Description


NAME Name given to the SEVERITY

SIGNATURE table

The SIGNATURE table details the currently active Digital Vaccine package on the SMS for use withdevices. The table grows as new Digital Vaccines are released, downloaded, and activated.

Column Description


NUMBER Integer number used to reference this SIGNATURE; The number isassigned by TippingPoint.

SEVERITY_ID Identifier for the SEVERITY of this SIGNATURE. Join toSEVERITY.ID to obtain a descriptive name of the SEVERITY.

NAME Name given to the SIGNATURE by TippingPoint

CLASS Descriptive classification for the SIGNATURE

PRODUCT_CATEGORY_ID Category ID from PRODUCT_CATEGORY table, provided byTippingPoint

PROTOCOL Well-known PROTOCOL of which this SIGNATURE is part

TAXONOMY_ID TAXONOMY classification

CVE_ID Comma-separated list of CVE IDs that can be used to link to the CVEdatabase

See: http://www.cve.mitre.org/

http://www.cve.mitre.org/


Column Description

BUGTRAQ_ID Comma-separated list of BugTraq IDs that can be used to link to theBugTraq database

See: http://www.securityfocus.com

DESCRIPTION Descriptive text detailing this SIGNATURE. This text is informativeinformation provided by TippingPoint

MESSAGE Message that can be filled in with ALERTS.MESSAGE_PARMS valuesto create a dynamic message for this SIGNATURE

TAXONOMY_MAJOR table

The TAXONOMY_MAJOR table details the TippingPoint signature taxonomy major classifications. See theTippingPoint Event Taxonomy document for Taxonomy specifics.

Column Description


NAME Short name for the TAXONOMY_MAJOR entry

DESCRIPTION Descriptive text for the TAXONOMY_MAJOR entry

TAXONOMY_MINOR table

The TAXONOMY_MINOR table details the TippingPoint signature taxonomy minor classifications.

Column Description


MAJOR_ID Identifier of the major classification ID to which this minorclassification relates

http://www.securityfocus.com


Column Description

DESCRIPTION Descriptive text for the TAXONOMY_MINOR entry

TAXONOMY_PLATFORM table

The TAXONOMY_PLATFORM table details the TippingPoint signature platforms.

Column Description


DESCRIPTION Descriptive text for the TAXONOMY_PLATFORM entry

TAXONOMY_PROTOCOL table

The TAXONOMY_PROTOCOL table details the TippingPoint signature protocols.

Column Description


DESCRIPTION Descriptive text for the TAXONOMY_PROTOCOL entry

THRESHOLD_GROUP_LOOKUP table

This table holds the mapping information for threshold policy group information in SMS and in device.This table is used to find the policy information from the event/statistic that comes from the device.

Example

select * from THRESHOLD_GROUP_LOOKUP TGL, POLICY POL, THRESHOLD_STATS TSwhere TGL.SMS_GROUP_ID = POL.MULTIPART_GROUP_ID and TGL.DEV_GROUP_ID =TS.DEV_GROUP_ID;


Column Description

DEV_GROUP_ID Identifier for the POLICY group in device

SMS_GROUP_ID Identifier for the POLICY group on SMS

THRESHOLD_UNITS table

The THRESHOLD_UNITS table defines the UNITS in which THRESHOLDS can be specified. Thistable is not expected to grow and has very few records.

Column Description


NAME Descriptive name for this UNIT entry

TPT_DEVICE table

An IPS entry. This table contains a record for each of the IPS's being managed.

Column Description


SHORT_ID Unique identifier for the table entry in integer format

DISPLAY_NAME A descriptive name for the device provided by the end user duringdevice installation

DEVICE_MODEL A string that represents the IPS model

IP_ADDRESS The IP address for the management port of this IPS

LOCATION A descriptive location text entered by the user during device installation


TPT_PORT table

A TPT_PORT record represents a physical PORT on a DEVICE. It is a relatively small table and is onlyexpected to grow when new IPS devices are added to your network.

Column Description


DISPLAY_NAME A descriptive name for the port

TPT_SEGMENT table

A SEGMENT record represents a physical SEGMENT on a DEVICE. It is a relatively small table and isonly expected to grow when new IPS devices are added to your network.

Column Description


DEVICE_ID The DEVICE which this SEGMENT belongs to

DEVICE_SHORT_ID The short ID of DEVICE which this SEGMENT belongs to

DISPLAY_NAME A descriptive name entered by the end user

IP_ADDRESS OBSOLETE IP Address that may be given to this SEGMENT. Thisvalue was used in Discovery services which have been removed fromthe product

SEGMENT_SLOT The internal chassis slot number. This number is always 3 for physicalsegments and 0 for virtual segments

SEGMENT_INDEX For physical segments, the physical segment number. For virtualsegments, this number is 0


VIRTUAL_SEGMENT table

A VIRTUAL_SEGMENT record represents a virtual physical SEGMENT on a DEVICE. It is a relativelysmall table and is only expected to grow when new devices are added to your network.

Column Description


DEVICE_ID DEVICE to which this SEGMENT belongs

SEGMENT_GROUP_ID SEGMENT GROUP to which this SEGMENT belongs

NAME Descriptive name

DataDictionary XML response

When the SMS receives a valid, authenticated request using DataDictionary method, it can return anXML response. Specific response content depends on data you specify in the request. The following tablelists the database tables that can be called by an external system, and describes the type of data included inthe response.

Table name Response

PROFILE_INSTALL_INVENTORY Lists virtual segments that are enabled by IPSadministrators. Each entry contains the following data:VIRTUAL_SEGMENT_ID

PROFILE_ID

PROFILE_VERSION

DISTRIBUTE_ID

COMPLETE_TIME

See PROFILE_INSTALL_INVENTORY table on page66 for more information.

DEVICE Lists the IPS devices. Each entry contains the following data:

ID


Table name Response

SHORT_ID

NAME

MODEL

SERIAL_NUMBER

IP_ADDRESS

LOCATION

DV_VERSION

OS_VERSION

DEVICE_GROUP

MANAGED

See DEVICE table on page 63 for more information.

SEGMENT Lists physical segments that are enabled by IPSadministrators. Each entry contains the following data:

ID

DEVICE_ID

NAME

IP_ADDRESS

SLOT_INDEX

SEGMENT_INDEX

See SEGMENT table on page 66 for more information.

VIRTUAL_SEGMENT Lists virtual segments that are defined by IPS administrators.Each entry in the list contains the following data:

ID

DEVICE_ID

SEGMENT_GROUP_ID

NAME

See VIRTUAL_SEGMENT table on page 73 for moreinformation.


XML response sample

The following is a sample XML response to a PROFILE_INSTALL_INVENTORYtable request. This sample response includes information for the ten profile entries in thePROFILE_INSTALL_INVENTORY table.

Note that, while the response is formatted in XML, for historical reasons it was not designed to conform tothe common practice of schema-based XML.

<?xml version="1.0" ?> <resultset> <table name="PROFILE_INSTALL_INVENTORY"> <column name="VIRTUAL_SEGMENT_ID"type="Integer"/> <column name="PROFILE_ID"type="String"/> <column name="PROFILE_VERSION"type="String"/> <column name="DISTRIBUTE_ID"type="String"/> <column name="COMPLETE_TIME"type="Long"/> <data> <r> <c>0</c> <c>8d577840-e7f1-11e1-7c4f-6eddc2a345a7</c> <c>85.4109</c> <c>96c829e0-e87a-11e1-7c4f-6eddc2a345a7</c> <c>1345218057347</c> </r> <r> <c>1</c> <c>8d577840-e7f1-11e1-7c4f-6eddc2a345a7</c> <c>85.4109</c> <c>96c829e0-e87a-11e1-7c4f-6eddc2a345a7</c> <c>1345218023621</c> </r> <r> <c>10</c> <c>8d577840-e7f1-11e1-7c4f-6eddc2a345a7</c> <c>85.4109</c> <c>96c829e0-e87a-11e1-7c4f-6eddc2a345a7</c> <c>1345218023621</c> </r> <r> <c>11</c> <c>8d577840-e7f1-11e1-7c4f-6eddc2a345a7</c> <c>85.4109</c> <c>96c829e0-e87a-11e1-7c4f-6eddc2a345a7</c> <c>1345218023621</c> </r> <r> <c>10</c> <c>8d577840-e7f1-11e1-7c4f-6eddc2a345a7</c> <c>85.4109</c> <c>96c829e0-e87a-11e1-7c4f-6eddc2a345a7</c> <c>1345218023621</c>


</r> <r> <c>11</c> <c>8d577840-e7f1-11e1-7c4f-6eddc2a345a7</c> <c>85.4109</c> <c>96c829e0-e87a-11e1-7c4f-6eddc2a345a7</c> <c>1345218023621</c> </r> <r> <c>12</c> <c>8d577840-e7f1-11e1-7c4f-6eddc2a345a7</c> <c>85.4109</c> <c>96c829e0-e87a-11e1-7c4f-6eddc2a345a7</c> <c>1345218023621</c> </r> <r> <c>2</c> <c>8d577840-e7f1-11e1-7c4f-6eddc2a345a7</c> <c>85.4109</c> <c>96c829e0-e87a-11e1-7c4f-6eddc2a345a7</c> <c>1345218023621</c> </r> <r> <c>20</c> <c>8d577840-e7f1-11e1-7c4f-6eddc2a345a7</c> <c>85.4109</c> <c>96c829e0-e87a-11e1-7c4f-6eddc2a345a7</c> <c>1345218023621</c> </r> <r> <c>21</c> <c>8d577840-e7f1-11e1-7c4f-6eddc2a345a7</c> <c>85.4109</c> <c>96c829e0-e87a-11e1-7c4f-6eddc2a345a7</c> <c>1345218023621</c> </r> <r> <c>30</c> <c>8d577840-e7f1-11e1-7c4f-6eddc2a345a7</c> <c>85.4109</c> <c>96c829e0-e87a-11e1-7c4f-6eddc2a345a7</c> <c>1345218023621</c> </r> <r> <c>31</c> <c>8d577840-e7f1-11e1-7c4f-6eddc2a345a7</c> <c>85.4109</c> <c>96c829e0-e87a-11e1-7c4f-6eddc2a345a7</c> <c>1345218023621</c> </r> </data> </table></resultset>Security Management System (SMS) External Interfaces


GetDataUse the GetData method to request data from specific tables and specify parameters and format.

Definition

dbAccess/tptDBServlet?method=GetData

Parameters


begin_time Type integer. Time is expressed as the number ofmilliseconds since 01-01-1970 00:00:00 GMT.

Yes

end_time Type integer. Time is expressed as the number ofmilliseconds since 01-01-1970 00:00:00 GMT.

Yes

format Possible values include the following:

• csv (default)

• sql

• xml

No

limit Type integer. This is the maximum number ofvalues returned. By default, all values are returned.

No

table Possible values include the following:

• ALERTS

• DDOS_STATS

• QUARANTINE_HOSTS

• RATELIMIT_STATS

• THRESHOLD_STATS

Yes


Example

The following example gets data from the ALERTS table with begin and end times in csv format.

http[s]://<sms_server>/dbAccess/tptDBServlet?method=GetData&table=ALERTS&begin_time=1&end_time=1162252800000&format=csv

Events Data

The following dynamic Events Data tables are used with the GetData variable:

• ALERTS table on page 78

• DDOS_STATS table on page 84

• QUARANTINE_HOSTS table on page 88

• RATELIMIT_STATS table on page 89

• THRESHOLD_STATS table on page 89

ALERTS table

The ALERTS table contains information pertaining to the event that caused a POLICY to trigger. When anACTIONSET is applied to a POLICY and it has a Management Console notification selected, it is put inthe ALERTS table.

The primary key, a unique key, is a four column index, DEVICE_ID, ALERT_TYPE_ID,SEQUENCE_NUM, and END_TIME.

The table is expected to have a continuous growth pattern and contain millions of records. The data isretrieved by using the method=GetData&table=ALERTS parameter.

The following table lists the table columns:

Column Description

SEQUENCE_NUM Part of the ALERTS table unique index; it is a reference to aparticular logs row entry counter.

The ALERT_TYPE column defines the log being referenced.

Note: This sequence number is not reliable as far as countingon it behaving as an ever increasing sequential number.It can be reset on the device and repeated for newevents.


Column Description

DEVICE_ID Identifier for the DEVICE entry that sent the notification; it isthe second part of the ALERTS table unique index.

A foreign key to the DEVICE table was left off for thepurpose of performance and due to the possibility that aDEVICE entry may not have been yet stored in the DEVICEtable for this external database.

ALERT_TYPE_ID The TYPE column is the third and final primary keyconstraint on the ALERTS table.

This field can be joined to the ALERT_TYPE table for adescriptive name for this column.

POLICY_ID Identifier used to map this alert to a POLICY table entry.

SIGNATURE_ID Identifier used to map this alert to a SIGNATURE table entry.

BEGIN_TIME Time at which the event was first started or previously logged.This value is in milliseconds elapsed since Jan. 1, 1970 00:00:00GMT.

When using notification aggregation, this value and theEND_TIME typically are off by the number of minutesspecified in the aggregation setting. The difference betweenBEGIN_TIME and END_TIME may be larger if a lot of timepasses between attack events. When aggregation is turned off,the BEGIN_TIME usually is the same as the END_TIME.

END_TIME Time at which the notification was logged and sent to theManagement Console. This value is in milliseconds elapsedsince Jan. 1, 1970 00:00:00 GMT.


Column Description

Subtracting BEGIN_TIME from END_TIME can determinethe length of an attack if aggregation is being used. Thedifference between BEGIN_TIME and END_TIME mightbe unexpectedly large if a lot of time passes between attackevents.

Note: This is the column used when comparing withBEGIN_TIME and END_TIME fields in theGetData method.

HIT_COUNT Counter displaying the number of times the event triggeredbefore the notification was sent to the Management Console.

SRC_IP_ADDR Source IP of the packet causing the notification. Numericvalue of an IPv4 address, or the low-order 64 bits for an IPv6address if SRC_IP_ADDR_HIGH is not NULL.

SRC_IP_ADDR_HIGH Source IP of the packet causing the notification. Numericvalue of high-order 64 bits for an IPv6 address.

SRC_PORT Source port of the packet causing the notification.

DST_IP_ADDR Destination IP of the packet causing the notification. Numericvalue of an IPv4 address, or the low-order 64 bits for an IPv6address if DST_IP_ADDR_HIGH is not NULL.

DST_IP_ADDR_HIGH Destination IP of the packet causing the notification. Numericvalue of high-order 64 bits for an IPv6 address.

DST_PORT Destination port of the packet causing the notification.

VIRTUAL_SEGMENT_INDEX Identifier for which device segment this alert was seen on.

PHYSICAL_PORT_IN Device port on which the event was detected.


Column Description

VLAN_TAG VLAN identifier contained in the event.

SEVERITY SEVERITY of the event. Usually corresponds to theSIGNATURE.SEVERITY column, joined by theSIGNATURE_ID column. A foreign key constraint to theSEVERITY table has been applied here.

PACKET_TRACE Indicates if a packet trace is available on the device.

DEVICE_TRACE_BUCKET Part of the device packet trace identifier.

DEVICE_TRACE_BEGIN_SEQ Part of the device packet trace identifier.

DEVICE_TRACE_END_SEQ Part of the device packet trace identifier.

MESSAGE_PARMS Variable list of message parameters. This value can betokenized and combined with the SIGNATURE.MESSAGEdata to display a dynamic ALERT message.

Join SIGNATURE_ID with SIGNATURE.ID to retrieve theSIGNATURE.MESSAGE data. The MESSAGE_PARMSstring is a delimited string, the delimiter is the “|” character.The SIGNATURE.MESSAGE string contains place holdersfor these strings, the place holders are %1, %2, ..., %n. Thetokenized MESSAGE_PARMS replaces the %n values basedon there location in the string.

Example

MESSAGE_PARMS=Austin|TexasSIGNATURE.MESSAGE=%1 is in %2.

The preceding parameters and message generates thefollowing message:

Austin is in Texas.

QUARANTINE_ACTION Quarantine action taken, either Added or Removed; used onlyin quarantine logs.


Column Description

FLOW_CONTROL Action taken by the action set: Permit, Rate Limit, or Trust.

ACTION_SET_UUID Action set UUID; used only in rate limit logs.

ACTION_SET_NAME Rate limit action; used only in rate limit logs.

RATE_LIMIT_RATE Rate for rate limit logs; a numerical value followed by a unit.The unit can be Kbps or Mbps.

CLIENT_IP_ADDR Long value of the Client IP address (Capture AdditionalEvent Information must be enabled).

CLIENT_IP_ADDR_HIGH Long value of the Client IP address (Capture AdditionalEvent Information must be enabled). For IPV6 only.

XFF_IP_ADDR Long value of the X-Forwarded-For IP address (CaptureAdditional Event Information must be enabled).

XFF_IP_ADDR_HIGH Long value of the X-Forwarded-For IP address (CaptureAdditional Event Information must be enabled). For IPV6only.

TCIP_IP_ADDR Long value of the True-Client-IP address (CaptureAdditional Event Information must be enabled).

TCIP_IP_ADDR_HIGH Long value of the True-Client-IP address (CaptureAdditional Event Information must be enabled). For IPV6only.

URI_METHOD Method of the URI.

URI_HOST Host of the URI.

URI_STRING URI string.


Column Description

SRC_USER_NAME User name on the source machine.

User ID IP Correlation must be configured on the SMS toretrieve this information. User ID IP Correlation is a featurethat enables the SMS to collect user authentication datadirectly and continuously from an Identity Agent device.

SRC_DOMAIN Name of the source domain.


SRC_MACHINE Name of the source machine.


DST_USER_NAME User name on the destination machine.


DST_DOMAIN Name of the destination domain.


DST_MACHINE Name of the destination machine.



DDOS_STATS table

When using advanced DDOS policies, this data is accumulated from the DEVICE.

If you are using advanced DDOS, this table is expected to have a continuous growth pattern and containmillions of records.

The data is retrieved by using the method=GetData&table=DDOS_STATS parameter.

Column Description

POLICY_ID Identifier of the POLICY that was created to produce this DDOSdata

STAT_TIME Time the data was collected; this time is stored in millisecondssince Jan. 1, 1970 00:00:00 GMT

REJECT_SYNS Number of rejected SYN requests for the stat period

PROXIED_CXNS Number of proxied connections for the stat period

CPS_CXNS Number of Connections Per Second over stat period

BLOCKED_CPS_CXNS Number of blocked CPS in stat period

CFLOOD_CXNS Number of Connection Flood connections in stat period

BLOCKED_CFLOOD_CXNS Number of blocked Connection Flood connections in stat period

FIREWALL_BLOCK_LOG table

The FIREWALL_BLOCK_LOG table contains information pertaining to logs where traffic has beenpermitted by firewall rules that have logging enabled, including packets that were permitted by the contentfiltering configuration.

Column Description

SEQUENCE_NUM This field is a reference to a particular logs row entry counter


Column Description

TPT_DEVICE_SHORT_ID This is the identifier for the DEVICE entry that sent the notification

TIME The time in which the event was first started. When using notificationaggregation, this value and the TIME_END typically are off bythe number of minutes specified in the aggregation setting. Whenaggregation is turned off, the BEGIN_TIME usually is the same as theTIME_END. This value is in milliseconds since Jan. 1, 1970 00:00:00GMT.

TIME_END The time in which the notification was sent to the ManagementConsole. Subtracting BEGIN_TIME from TIME_END can determinethe length of an attack if aggregation is being used. This value is inmilliseconds since Jan. 1, 1970 00:00:00 GMT

HIT_COUNT The number of times the firewall rule was applied

SRC_IP_ADDR Source IP of the packet causing the notification

SRC_PORT Source port of the packet causing the notification

DST_IP_ADDR Destination IP of the packet causing the notification

DST_PORT Destination port of the packet causing the notification

RULE_ID Unique identifier for rule to monitor traffic between security zones

PROTOCOL_NAME The packet type

PROTOCOL_NUMBER The number associated with the protocol in the filter

PROTOCOL_TYPE The protocol that was used to respond to the event

IN_ZONE_UUID The security zone from which the attack originated


Column Description

OUT_ZONE_UUID The security zone from which the attack was targeted

PHYSICAL_PORT_IN The device port on which the attack was detected

VLAN The local VLAN that was targeted

CATEGORY The type of traffic filter that was activated

SESSION_DURATION The duration of the attack

URL The URL that was associated with the attack, if applicable

URLINFO Additional information relevant to the URL

SEVERITY The severity of the attack

FIREWALL_TRAFFIC_LOG table

The FIREWALL_TRAFFIC_LOG table contains information pertaining to logs where traffic has beenpermitted by firewall rules that have logging enabled, including packets that were permitted by the contentfiltering configuration.

Column Description

SEQUENCE_NUM This field is a reference to a particular logs row entry counter

TPT_DEVICE_SHORT_ID This is the identifier for the DEVICE entry that sent the notification

TIME_END The time in which the notification was sent to the ManagementConsole. Subtracting BEGIN_TIME from TIME_END can determinethe length of an attack if aggregation is being used. This value is inmilliseconds since Jan. 1, 1970 00:00:00 GMT


Column Description

SRC_IP_ADDR Source IP of the packet causing the notification

SRC_PORT Source port of the packet causing the notification

DST_IP_ADDR Destination IP of the packet causing the notification

DST_PORT Destination port of the packet causing the notification

RULE_ID Unique identifier for rule to monitor traffic between security zones

PROTOCOL_NAME The packet type

PROTOCOL_NUMBER The number associated with the protocol in the filter

IN_ZONE_UUID The security zone from which the attack originated

OUT_ZONE_UUID The security zone from which the attack was targeted

CATEGORY The type of traffic filter that was activated

SESSION_DURATION The duration of the attack

URL The URL that was associated with the attack, if applicable

XFER_BYTES The number of bytes transferred for this event

MESSAGE A dynamic ALERT message

PORT_TRAFFIC_STATS table

This table contains information of traffic going through each port of IPS.


Column Description

DEVICE_ID Identifier for the DEVICE entry that sent the notification

PORT_ID Identifier for the PORT entry that the traffic going through

SMS_TIME SMS time in which the statistics get captured

DEVICE_TIME Device SMS time in which the statistics get captured

IN_OCTETS Device SMS time in which the statistics get captured

OUT_OCTETS Total traffic going out the port

QUARANTINE_HOSTS table

The QUARANTINE_HOSTS table is where quarantine actions for devices and SMS actions are tracked.

The data is retrieved by using the method=GetData&table=QUARANTINE_HOSTS parameter.

Column Description


QUARANTINED_IP IP address of the quarantined host

QUARANTINED_MAC MAC address of the quarantined host

POLICY_NAME Descriptive name for the policy that triggered the host quarantine

STATE Current state of the host - UNQUARANTINED, QUARANTINED,INITIAL, or ERROR

AUTHORITY Source of the quarantine state for the host


Column Description

CREATE_TIME Time the initial quarantine state was set

LAST_UPDATE Time of the last quarantine state change

RATELIMIT_STATS table

When using RATELIMIT ACTIONSETs, this data is accumulated from the DEVICE.

If you are using RATELIMIT ACTIONSETs, this table is expected to have a continuous growth patternand contain millions of records.

The data is retrieved by using the method=GetData&table=RATELIMIT_STATS parameter.

Column Description

ACTIONSET_ID Identifier of the ACTIONSET table entry for this record

STAT_TIME Time this stat was recorded; the time is milliseconds since Jan. 1, 197000:00:00 GMT

DEVICE_ID Identifier for the DEVICE

RATE RATE in kbps

VALUE Number of Bytes

THRESHOLD_STATS table

When using THRESHOLD policies, this data is accumulated from the DEVICE.

If you are using THRESHOLDs, this table is expected to have a continuousgrowth pattern and contain millions of records. The data is retrieved by using themethod=GetData&table=THRESHOLD_STATS parameter.


Column Description

POLICY_ID Identifier of the POLICY that was created to produce thisTHRESHOLD data

STAT_TIME Time the data was collected; time is stored in milliseconds since Jan. 1,1970 00:00:00 GMT

VALUE Stat value for the MEAS_UNIT at collection time

MEAS_UNIT Identifier can be used to join with the THRESHOLD_UNITS tableand obtain a descriptive name for the unit

GetNewestRecordUse the GetNewestRecord method to retrieve the newest record of the specified table.

Definition

/dbAccess/tptDBServlet?method=GetNewestRecord

Parameters



• ALERTS

• DDOS_STATS


• RATELIMIT_STATS

• THRESHOLD_STATS

Example

The following example retrieves the newest record of the ALERTS table.

http[s]://<sms_server>/dbAccess/tptDBServlet?method=GetNewestRecord&table=ALERTS


GetOldestRecordUse the GetOldestRecord method to retrieve the oldest record of the specified table.

Definition

/dbAccess/tptDBServlet?method=GetOldestRecord

Parameters



• ALERTS

• DDOS_STATS


• RATELIMIT_STATS

• THRESHOLD_STATS

Example

The following example retrieves the oldest record of the ALERTS table.

http[s]://<sms_server>/dbAccess/tptDBServlet?method=GetOldestRecord&table=ALERTS

SchemaUse the Schema resource to obtain SMS database schema information.

The SMS returns the schema information in Oracle 8i or MySQL 4.0 compliant data definition language(DDL) statements.

Definition

dbAccess/tptDBServlet?method=Schema


Parameters


database Only valid for sql format. Possible values include the following:

• MySQL (default)

• Oracle

Example

http[s]://<sms_server>/dbAccess/tptDBServlet?method=Schema

StatusThe Status resource returns OK if the SMS web API support is enabled and running and Not Found ifthe SMS web API support is not enabled.

Example

http[s]://<sms_server>/dbAccess/tptDBServlet?method=Status

VersionThe Version resource returns the version number of the SMS web API.

Example

http[s]://<sms_server>/dbAccess/tptDBServlet?method=Version


External databaseThe SMS supports the following database options:

• External access - direct access to the database

• External replication - remote replication of the database

The external database can be used for customized reporting. For custom reports, you can access the SMSdatabase directly or replicate the SMS to your external server. If you require data that the SMS reports donot routinely provide, you can set up an SMS External Database with a reporting tool of your choice.

External Replication provides a copy of the database that can be edited, backed up, or used for offloadingreport functions.

Note: The data that you access remotely is read-only and cannot be changed.

External access

Setting up the Access service allows an external database tool to access data in the SMS. You must configurethe SMS for external access before you configure your external application. You must reboot the SMS toenable or disable this service.

External replication

Setting up the replication service allows an external database server to replicate data from the SMS. Youmust reboot the SMS to enable or disable this service.

Configure the SMS for external accessThis service opens a MariaDB read-only database for any third-party access or reporting tool. The read-onlydatabase name is ExternalAccess.

Note: Running complex report against SMS server may slow down the SMS response time significantly.

1. In the SMS, go to Admin > Database.

2. On the External Database Settings panel, click Edit.

3. In the Edit External Database Settings wizard, select External Access Settings.

4. Select Enable external database access to enable the service. (To disable the service, clear the checkbox.)

5. Provide the following:

• Username – Provide the user name for an account with sufficient rights to read all the desired datafrom the SMS database.


• Password – Provide the password for the user account. Retype the password in the ConfirmPassword field.

6. If you changed the external access settings, click Reboot to restart the SMS server and initialize theservice.

Note: Follow your company’s server downtime policies, including notification to SMS clients of apending reboot. Before you reboot the SMS, gracefully stop other client connections to the server.

7. Click OK.

If you verification fails or you encounter issues, check the following items:

◦ Make sure that the username and password on the database are the same as the ones you set up onthe SMS client.

◦ Make sure to reboot the SMS before you try to access the database.

Configure the SMS for replicationThis service allows an external database server to replicate data from the SMS. Using an external databasefor data replication allows you to offload report processing to an external server which can provideperformance gains to your existing system. Reboot the SMS to completely enable or disable this service.

Before you begin, make sure that your replication system has sufficient disk space to accommodate thedatabase and any increase in size due to additional data or reporting.



3. In the Edit External Database Settings wizard, select External Replication Settings.

Note: To configure external database replication, you must create an SMS database snapshot, and thencopy the snapshot to the target replication system and import it into a MariaDB database before theSMS server can replicate its data to the target system.

4. Select Enable external database replication to enable the service. (To disable the service, clear thecheck box.)


• Username – Provide the user name for an account with sufficient rights to read all the desired datafrom the SMS database.

• Password – Provide the password for the user account. Retype the password in the ConfirmPassword field.

6. If you changed the replication settings, click Reboot to restart the SMS server and initialize the service.


Note: Follow your company’s server downtime policies, including notification to SMS clients of apending reboot. Before you reboot the SMS, gracefully stop other client connections to the server.

7. Click Create Snapshot, and select Include Events in Snapshot if you want the snapshot to includeevent data.

Note: The snapshot is saved locally on the SMS server. You must copy the snapshot to the targetreplication system and import it into a new or existing MariaDB database before the SMS server canreplicate its data to the target system.

8. Click OK.

Note: External database replication and the SMS High Availability (HA) features both leverage thesame functionality in the underlying MariaDB database. The SMS database does not support replicationto multiple destinations; therefore, we do not recommend using SMS HA and external databasereplication at the same time.

Configure the SMS to enable restricted accessThis service allows access to the external database to be restricted to a set of IP addresses.



3. In the Edit External Database Settings wizard, select Access Restrictions.

4. Select Enable restricted access to enable the service. (To disable the service, clear the check box.)


• Named IP Address Group – To restrict a set of IP addresses, click the arrow, and either select aNamed IP Address Group or create a new one.

6. Click OK.

ALERTS table – ExternalAccessThe database name for external access is ExternalAccess. With a few exceptions, the schema for theExternal Database Access ALERTS table is the same as Web API schema for the ALERT_TYPE table. SeeALERTS table on page 78.

The following table includes the exceptions.


Column Description

DEVICE_ID type change. Unique identifier for the device in the format ofinteger, which is much faster when used in a query.

SRC_IP_ADDR_2 New field. Introduced for IPv6 support. Represents thehigher 64 bit for the IPv6 source addresses. For IPv4 address,this field has a NULL value.

DST_IP_ADDR_2 New field. Introduced for IPv6 support. Represents thehigher 64 bit for the IPv6 destination addresses. For IPv4address, this field has a NULL value.

Replication – database schemaA list of tables created when you dump the snapshot file to the replicated database server. Some of thetables are for internal use only. The rest of tables are divided into two categories like Web Service API -Data Dictionary and Events Data. The tables are very similar with Web Server API with minor differences.

The following section detail the tables:

• DataDictionary on page 59

• Events Data on page 78

DataDictionary

See the following sections for more information on the tables in the database:

ACTIONSET table on page 61

CATEGORY table on page 62

NOTICE_ACTION table on page 63

POLICY table on page 64

POLICY_GROUP_LOOKUP table on page 64

PROFILE table on page 65

SEVERITY table on page 67

SIGNATURE table on page 68

TAXONOMY_MAJOR table on page 69


TAXONOMY_MINOR table on page 69

TAXONOMY_PLATFORM table on page 70

TAXONOMY_PROTOCOL table on page 70

THRESHOLD_GROUP_LOOKUP table on page 70

THRESHOLD_UNITS table on page 71

TPT_DEVICE table on page 71

TPT_SEGMENT table on page 72

TPT_PORT table on page 72

VIRTUAL_SEGMENT table on page 73

Events Data

See the following sections for more information on the tables in the database:

ALERTS table on page 78

DDOS_STATS table on page 84

PORT_TRAFFIC_STATS table on page 87

RATELIMIT_STATS table on page 89

THRESHOLD_STATS table on page 89

FIREWALL_TRAFFIC_LOG table on page 86

FIREWALL_BLOCK_LOG table on page 84


MIB files for the SMSA management information base (MIB) is a type of database that is used to manage devices in acommunications network. Database entries are addressed through object identifiers (OIDs). MIB files aredescriptions of network objects that can be managed using the Simple Network Management Protocol(SNMP). The format of the MIB is defined as part of the SNMP.

This information includes the following topics:

SMS MIBs on page 98

Public MIB files on page 98

Health monitoring on page 98

SMS MIBsYou can download TippingPoint SMS MIB files from the TMC at https://tmc.tippingpoint.com. On the TMCwebsite, navigate to the Documentation area for this product release, and then select SMS MIBS.

The compressed file contains two MIB files:

• TPT-SMSMIBS defines monitoring functions

• TPT-SMS-TRAP-MIB defines the SMS traps

For more information about these MIBs, refer to the TippingPoint Operating System MIB Guide, available on theTMC.

Public MIB filesPublicly available UCD-SNMP-MIB and UCD-DISKIO-MIB definitions can be used to query SMS healthvalues. These files can be downloaded from the following locations:

• http://net-snmp.sourceforge.net/docs/mibs/

• http://net-snmp.sourceforge.net/docs/mibs/UCD-SNMP-MIB.txt

• http://net-snmp.sourceforge.net/docs/mibs/UCD-DISKIO-MIB.txt

Note that only the SMS Health Section OIDs listed in Health monitoring on page 98 are supported.

Health monitoringThe following table lists the OIDs that are used to graph and display values in the SMS Health section ofthe SMS client.

https://tmc.tippingpoint.com

http://net-snmp.sourceforge.net/docs/mibs/

http://net-snmp.sourceforge.net/docs/mibs/UCD-SNMP-MIB.txt

http://net-snmp.sourceforge.net/docs/mibs/UCD-DISKIO-MIB.txt


Section Description OID

CPU_USER 1.3.6.1.4.1.2021.11.50.0

CPU_SYS 1.3.6.1.4.1.2021.11.52.0

CPU

CPU_IDLE 1.3.6.1.4.1.2021.11.53.0

FS_DSKPATH 1.3.6.1.4.1.2021.9.1.2

FS_DEVPATH 1.3.6.1.4.1.2021.9.1.3

FS_TOTAL 1.3.6.1.4.1.2021.9.1.6

FS_AVAIL 1.3.6.1.4.1.2021.9.1.7

FS_USED 1.3.6.1.4.1.2021.9.1.8

FS_PERCENT 1.3.6.1.4.1.2021.9.1.9

Filesystem

FS_IPERCENT 1.3.6.1.4.1.2021.9.1.10

HighAvailability

HA 1.3.6.1.4.1.2021.8.1.101.34

SWAP_TOTAL 1.3.6.1.4.1.2021.4.3.0

SWAP_AVAIL 1.3.6.1.4.1.2021.4.4.0

REALMEM_TOTAL 1.3.6.1.4.1.2021.4.5.0

Memory

REALMEM_AVAIL 1.3.6.1.4.1.2021.4.6.0



ETHO_RX_BYTES 1.3.6.1.4.1.2021.8.1.101.1

ETHO_RX_PACKETS 1.3.6.1.4.1.2021.8.1.101.2

ETHO_RX_ERRORS 1.3.6.1.4.1.2021.8.1.101.3

ETHO_RX_DROPPED 1.3.6.1.4.1.2021.8.1.101.4

ETHO_RX_FIFO_ERRORS 1.3.6.1.4.1.2021.8.1.101.5

ETHO_RX_FRAME_ERRORS 1.3.6.1.4.1.2021.8.1.101.6

ETHO_RX_COMPRESSED 1.3.6.1.4.1.2021.8.1.101.7

ETHO_TX_BYTES 1.3.6.1.4.1.2021.8.1.101.8

ETHO_TX_PACKETS 1.3.6.1.4.1.2021.8.1.101.9

ETHO_TX_ERRORS 1.3.6.1.4.1.2021.8.1.101.10

ETHO_TX_DROPPED 1.3.6.1.4.1.2021.8.1.101.11

ETHO_TX_FIFO_ERRORS 1.3.6.1.4.1.2021.8.1.101.12

ETHO_TX_CARRIER_ERRORS 1.3.6.1.4.1.2021.8.1.101.13

ETHO_TX_COMPRESSED 1.3.6.1.4.1.2021.8.1.101.14

ETHO_MULTICAST 1.3.6.1.4.1.2021.8.1.101.15

NetworkTraffic

ETHO_COLLISIONS 1.3.6.1.4.1.2021.8.1.101.16



ETH1_RX_BYTES 1.3.6.1.4.1.2021.8.1.101.17

ETH1_RX_PACKETS 1.3.6.1.4.1.2021.8.1.101.18

ETH1_RX_ERRORS 1.3.6.1.4.1.2021.8.1.101.19

ETH1_RX_DROPPED 1.3.6.1.4.1.2021.8.1.101.20

ETH1_RX_FIFO_ERRORS 1.3.6.1.4.1.2021.8.1.101.21

ETH1_RX_FRAME_ERRORS 1.3.6.1.4.1.2021.8.1.101.22

ETH1_RX_COMPRESSED 1.3.6.1.4.1.2021.8.1.101.23

ETH1_TX_BYTES 1.3.6.1.4.1.2021.8.1.101.24

ETH1_TX_PACKETS 1.3.6.1.4.1.2021.8.1.101.25

ETH1_TX_ERRORS 1.3.6.1.4.1.2021.8.1.101.26

ETH1_TX_DROPPED 1.3.6.1.4.1.2021.8.1.101.27

ETH1_TX_FIFO_ERRORS 1.3.6.1.4.1.2021.8.1.101.28

ETH1_TX_CARRIER_ERRORS 1.3.6.1.4.1.2021.8.1.101.29

ETH1_TX_COMPRESSED 1.3.6.1.4.1.2021.8.1.101.30

ETH1_MULTICAST 1.3.6.1.4.1.2021.8.1.101.31

ETH1_COLLISIONS 1.3.6.1.4.1.2021.8.1.101.32



Temperature TEMPERATURE 1.3.6.1.4.1.2021.8.1.101.33

Documents

Security Management System External Interface Guide...2 Security Management System External Interface Guide Convention Element Italics font Text emphasis, important terms, variables,