SecurityCenterâ€™s JSON API - Tenable Network Security

Tenable Network Security, Inc. • 7063 Columbia Gateway Drive, Suite 100, Columbia, MD 21046 • 410.872.0555 • [email protected] • www.tenable.com

Copyright © 2002-2012 Tenable Network Security, Inc. Tenable Network Security, Nessus and ProfessionalFeed are registered trademarks of Tenable Network Security, Inc. Tenable, the Tenable logo, the Nessus logo, and/or other Tenable products referenced herein are trademarks of Tenable Network Security, Inc., and may be registered in certain jurisdictions. All other product names, company names, marks, logos, and symbols may be the trademarks of their respective owners.

SSeeccuurriittyyCCeenntteerr 44..44 AAPPII

May 10, 2012

(Revision 1)

Copyright © 2002-2012 Tenable Network Security, Inc.

2

TTaabbllee ooff CCoonntteennttss

Introduction ............................................................................................................................... 3

Standards and Conventions ....................................................................................................... 3 About the API ............................................................................................................................. 3

API Usage.. ................................................................................................................................ 4

API Commands/Responses ....................................................................................................... 4 alert::init ................................................................................................................................. 4 asset::add .............................................................................................................................10 asset::init ..............................................................................................................................12 asset::edit .............................................................................................................................14 asset::getIPs .........................................................................................................................16 auth::login .............................................................................................................................16 auth::logout ...........................................................................................................................20 credential::edit ......................................................................................................................20 credential::init .......................................................................................................................21 events::query ........................................................................................................................23 plugin::getDetails ..................................................................................................................27 plugin::getPage .....................................................................................................................28 plugin::init .............................................................................................................................29 repository::init .......................................................................................................................30 role::init .................................................................................................................................32 scanResult::init .....................................................................................................................34 scanResult::download ...........................................................................................................35 system::init ...........................................................................................................................35 ticket::init ..............................................................................................................................38 user::init ................................................................................................................................41 vuln::init ................................................................................................................................46 vuln::getIP ............................................................................................................................50 vuln::query ............................................................................................................................51 zone::init ...............................................................................................................................58

Error Codes ..............................................................................................................................59

About Tenable Network Security .............................................................................................62

Appendix 1: Sample Vuln Query Perl Script ...........................................................................63

Sample Output ..........................................................................................................................65

Appendix 2: Sample Host Detail Python Script ......................................................................66

Sample Output ..........................................................................................................................68

Appendix 3: Sample Credential Update Python Script ..........................................................69

Sample Output ..........................................................................................................................72


3

INTRODUCTION

This document describes Tenable Network Security’s SecurityCenter 4.4 API. Please email

any comments and suggestions to [email protected].

This document covers basic usage of the SecurityCenter 4.4 API including basic API input,

output and error codes. In addition, several sample scripts are provided in the appendices

to provide a better understanding of how the API could be used in a real-world scenario.

Please note that whenever Tenable extends the protocol or implementation, we may not be

able to maintain backward compatibility, thus some APIs may change without warning.

Therefore, this document comes with NO GUARANTEE OF FUTURE COMPATIBILITY. If you

want to use this API in a professional environment, please contact Tenable to determine

what partnership options can be established to assist your organization.

A basic understanding of SecurityCenter administration, JSON objects and one or more

programming languages, such as C, Perl, PHP, Python and Ruby, that are capable of

handling the JSON formatted text is assumed.

STANDARDS AND CONVENTIONS

Throughout the documentation, filenames, daemons and executables are indicated with a bold font such as gunzip, httpd and /etc/passwd.

Command line options and keywords are also indicated with the courier bold font.

Command line examples may or may not include the command line prompt and output text

from the results of the command. Command line examples will display the command being

run in courier bold to indicate what the user typed while the sample output generated by

the system will be indicated in courier (not bold). Following is an example running of the

Unix pwd command:

# pwd

/opt/sc4/daemons

#

Important notes and considerations are highlighted with this symbol and grey text

boxes.

Tips, examples, and best practices are highlighted with this symbol and white on

blue text.

ABOUT THE API

The SecurityCenter 4.4 API receives and responds to properly formatted JSON objects via

HTTP POST and GET requests. The API is not meant to be a replacement for the

SecurityCenter UI, but to supplement the UI functionality.

Please feel free to post any comments, suggestions, or example scripts to the

SecurityCenter Discussions Forum.

mailto:[email protected]

https://discussions.nessus.org/community/apis


4

API USAGE

The API utilizes JSON (JavaScript Object Notation), a lightweight data-interchange format

that can interface with a large number of programming languages such as C, Perl, PHP,

Python and Ruby. See http://json.org/ for more information on working with JSON.

API COMMANDS/RESPONSES

All HTTP requests can be sent to the request.php interface at the following URL:

https://<ip or hostname>/request.php

Required parameters:

> module – A string containing the name of the procedure to be invoked

> action – Standard actions are: init(), add(), edit(), delete(), share() other actions may

be defined depending on the function

> request_id – The request identifier is used to match the response with its request

token – A session token that must be included with all requests following the login

> input – The arguments passed to the module as a JSON object, using standard URL

encoding

The following tables contain the common API requests including the required JSON input

and the subsequent output along with error response(s). Available API actions are specified

using “Module::Action” format (e.g., asset::init). In cases where there is no input/output

the field is left blank. This is the case with the “input” field on the majority of the “init”

functions.

Most of the commands make use of a login token that can be obtained using the

“auth::login” function described in more detail below. This function not only returns a token

but will also set a cookie named “TNS_SESSIONID” containing the sessionID for that

particular host. Both must be supplied with every request otherwise you will receive a “not

authenticated” message for subsequent attempts.

Unless otherwise indicated most time values return an integer which is the timestamp in

seconds since the Epoch (1970-01-01T00:00:00Z ISO 8601).

alert::init Returns a list of all alerts and their metadata.

Input Output

alerts = [

{

id = <num>

ownerID = <num>

modifiedTime = <num>

createdTime = <num>

name = <string>

description = <string>

queryID = <num>

http://json.org/


5

triggerName = <string>

triggerOperator = <string>

triggerValue = <num>

lastTriggered = <num>

lastEvaluated = <num>

executeOnEveryTrigger = <string> “true”

| “false”

didTriggerLastEvaluation = <string>

“true” | “false”

status = <num>

actions = [

{

id = <num>

type = <string> “email” |

“notification” | “scan” | “syslog” |

“ticket”

objectID = <num>

status = <num>

users = [

{ id = <num> }…

]

type “email”

subject = <string>

message = <string>

addresses = [

{ email = <string> }…

]

includeResults = <string> “true” |

“false”

type “notification”

message = <string>

type “syslog”

host = <string>

port = <num>

message = <string>

severity = <string> “Critical” |

“Warning” | “Notice”

type “ticket”

assigneeID = <num>

name = <string>


notes = <string>

}…

]

scheduleFrequency = <string>

scheduleDefinition = <string>

}…

]


6

users = [

{

id = <num>

parentID = <num>

roleID = <num>

status = <num> 0 (active)

username = <string>

firstname = <string>

lastname = <string>

title = <string>

email = <string>

address = <string>

city = <string>

state = <string>

country = <string>

phone = <string>

fax = <string>

lastLogin = <num>

authType = <string> “ldap” | “legacy” |

“tns”

fingerprint = <string>

locked = <string> “true” | “false”

}…

]

roles = [

{

id = <num>

name = <string>


visibility = <string> “organizational” |

“application”

}…

]

templateScans = [

{

id = <num>

name = <string>


type = <string> “full” | “policy” | “none”

}…

]

assets = [

// All assets of session user + defining

assets of all users

{

id = <num>

name = <string>



“user”

ownerID = <num>

type = <string> “dnsname” | “dynamic”


7

| “static” | “watchlist”

context = <string> “” | “ticketing”


group = <string>

assetDataFields = [

{

fieldName = <string>

fieldValue = <string>

}…

]

}…

]

repositories = [

{

id = <num>

name = <string>


type = <string>”Local” | “Offline” |

“Remote”

ipRange = <string>

ipCount = <num>

vulnCount = <num>

remoteID = <num>

remoteIP = <string>

running = <string> “true” | “false”

enableTrending = <string> “true” |

“false”

downloadFormat = <string> “v1” | “v2”

lastSyncTime = <num>

lastVulnUpdate = <num>

createdTime = <num>


lastGenerateNessusTime = <num>

runningNessus = <string> “true” | “false”

}…

]

policies = [

{

id = <num>

name = <string>

type = <string> “custom” | “family” |

“plugin”



visibility = <string> “application” |

“organizational” | “user”

group = <string>

status = <num> 0 (active) | 128

(inactive audit file)

}…

]

auditFiles = [


8

{

id = <num>

creatorID = <num>

name = <string>


version = <string>

type = <string> “as/400” | “cisco” |

“database” | “unix” | “windows” |

“windowsfiles”

status = <num> 0 (unparsed) | 1

(parsed) | 2 (parsing)

filename = <string>

orginalFilename = <string>

createdTime = <string>

modifiedTime = <string>


“organizational”

visibility “organizational”

ownerID = <num>

}…

]

families = [

{

id = <num>

name = <string>

type = <string> “active” | “compliance” |

“custom” | “customPassive” | “passive”

count = <num>

}…

]

types = [

<string>…

]

lces = [

{

id = <num>

name = <string>


version = <string>

silos = [

{

id = <num>

file = <string>

startDate = <string> (Format:

Mmm dd, yyyy)

endDate = <string> (Format:

Mmm dd, yyyy)

records = <num>

}…

]

}…


9

]

queries = [

{

id = <num>

creatorID = <num>

ownerID = <num>

name = <string>


tool = <string> "iplist" | "listdata" |

"listmailclients" | "listos" | "listservices" |

"listsoftware" | "listsshservers" |

"listwebclients" | "listwebservers" |

"listvuln" | "sumasset" | "sumclassa" |

"sumclassb" | "sumclassc" | "sumcve" |

"sumdate" | "sumdnsname" | "sumevent"

| "sumevent2" | "sumfamily" | "sumiava"

| "sumid" | "sumip" | "summsbulletin" |

"sumport" | "sumprotocol" | "sumsensor"

| "sumtime" | "sumtype" | "sumuser" |

"sumseverity" | "syslog" | "timedist" |

"trend" | "vulndetails" | "vulnipsummary"

| "vulnipdetail"

type = <string> “alert” | “lce” | “ticket” |

“user” | “vuln”


“user”

group = <string>

context = <string> “” | “alerting”

browseColumns = <string>

browseSortColumn = <string>

browseSortDirection = <string> “ASC” |

“DESC”

createdTime = <num>


status = <num> 0 (active) | 2 (inactive

repository) &| 4 (inactive asset) &| 8

(inactive policy) &| 64 (inactive LCE) &|

128 (inactive audit file) &| 512 (inactive

user) &| 4096 (inactive role)

filters = [

{

filterName = <string>

operator = <string>

value = <string>

}…

]

visibility “user”, user is owner

users = [

{ id = <num> }…

]

}…


10

]

Notes:

> Schedule definition “monthly1” specifies a date while schedule definition “monthly2”

specifies a day of the month, e.g. “first monday …” or “second Sunday …”.

> Entries returned in users[] only consist of “active” users.

> See events::query and vuln::query for more detail on query tool values.

asset::add Adds a new asset list. Available asset list types include: static, dynamic, upload,

uploadmultiple, and staticvulnfilter.

Input Output


| “static” | “upload” | “uploadmultiple” |

“staticeventfilter” | “staticvulnfilter” |

“watchlist” | “watchlisteventfilter” |

“watchlistupload”

ownerID = <num> (default session

user id)

type not “uploadmultiple”

name = <string>

description = <string> (default “”)


“user”

context = <string> (default “”)

group = <string> (default “”)

assetDataFields = [

{

fieldName = <string> (default “”

if fieldValue not empty)

fieldValue = <string> (default “”

if fieldName not empty)

}…

] (optional)

type “dynamic”

rules = {

operator = <string> “all” | “any”

children = [

{

type = <string> “clause” |

“group

child type “clause”

filterName = <string> "dns" |

"firstseen" | "mac" | "os" | "ip"

assets = [ {

id = <num>



name = <string>



“user”

group = <string>

creatorID = <num>

ownerID = <num>



createdTime = <num>

ipCount = [

{

repositoryID = <num>

ipCount = <num>

}…

]

assetDataFields = [

{



}…

]

users = [

{ id = <num> }…

]

type “dynamic”

rules = {

operator = <string>

type = <string> “group”


11

| "lastseen" | "netbioshost" |

"netbiosworkgroup" | "pluginid"

| "plugintext" | "port" |

"severity" | "sshv1" | "sshv2" |

"tcpport" | "udpport"

value = <string>

operator = <string> "contains"

| "eq" | "lt" | "lte" | "ne" | "gt"

| "gte" | "regex"

pluginIDConstraint = <num>

(optional)

child type “group”

(attributes of “rules”,

aggregate)

}

]

}

type “dnsname”

definedDNSNames = <string>

type “static” | “watchlist”

definedIPs = <string>

type “staticeventfilter” |

“staticvulnfilter” |

“watchlisteventfilter”

filters = [

{


value = <string>

operator = <string>

}…

]


“watchlisteventfilter”

tool = “sumip”

sourceType = <string>"archive" | "lce"

(default "lce")

startOffset = <num> (default 0)

endOffset = <num> (default

2,147,483,647)


“watchlisteventfilter”, sourceType

"lce"

view = <string>

lceID = <num>

type “staticvulnfilter”

children = [

{

operator = <string>

type = <string> “group |

“clause”

type “clause”


value = <string>


}…

]

}



type “dnsname”


12

tool = <string>”iplist” | "listmailclients"

| "listos" | "listsshservers" |

"listservices" | "listsoftware" |

"listwebclients" | "listwebservers"

(forced to “iplist” with appropriate

filters)

sourceType = "cumulative" |

"individual" | "patched" (default "")

startOffset = <num> (optional)

endOffset = <num> (optional)

sortField = <string> (optional, must

accompany sortDir)

sortDir = <string> “ASC” | “DESC”

(optional, must accompany sortField)

type “staticvulnfilter”, sourceType

"individual"

view = <string>

scanID = <num>

Notes:

> More than one entry can be returned in assets[] for type “upload”.

asset::init Returns a list of all existing asset objects and their metadata. This command is available to

an organizational user with ownership of one or more assets.

Input Output

assets = [


assets of all users

{

id = <num>



name = <string>



“user”

group = <string>

creatorID = <num>

ownerID = <num>



createdTime = <num>

ipCount = [

{


ipCount = <num>

}…


13

]

assetDataFields = [

{



}…

]


users = [

// Users with whom I shared this asset

{ id = <num> }…

]

type “dynamic”

rules = {

operator = <string>


children = [

{

operator = <string>


“clause”

type “clause”


value = <string>


}…

]

}



type “dnsname”


}

]

users = [

{

id = <num>

parentID = <num>

username = <string>


lastname = <string>

roleID = <num>

}…

]

roles = [

{

id = <num>


14

name = <string>




}…

]

templates = [

{

id = <num>

name = <string>


rules = {

operator = <string>


children = [

{

operator = <string>


“clause”

type “clause”


value = <string>


}…

]

}

}…

]

repositories = [

{

id = <num>

name = <string>




“Remote”

}…

]

Notes:


asset::edit Edit an existing asset list by ID. This command is available to an organizational user with

ownership of the selected asset.

Input Output

id = <num>

name = <string>

assets = [ {


15


| “static” | “watchlist” (must match

existing data)

ownerID = <num> (optional, default no

change)



“user”

context = <string> (default “”)


assetDataFields = [

{

fieldName = <string> (default “”

if fieldValue not empty)

fieldValue = <string> (default “”

if fieldName not empty)

}…

] (optional)

users = [

{ id = <num> }…

]

type “dynamic”

rules = {

operator = <string> “all” | “any”

children = [

{

type = <string> “clause” |

“group

child type “clause”

filterName = <string> "dns" |

"firstseen" | "mac" | "os" | "ip"

| "lastseen" | "netbioshost" |

"netbiosworkgroup" | "pluginid"

| "plugintext" | "port" |

"severity" | "sshv1" | "sshv2" |


value = <string>

operator = <string> "contains"

| "eq" | "lt" | "lte" | "ne" | "gt"

| "gte" | "regex"


(optional)

child type “group”

(attributes of “rules”,

aggregate)

}

]

}

id = <num>



name = <string>



“user”

group = <string>

creatorID = <num>

ownerID = <num>



createdTime = <num>

ipCount = [

{


ipCount = <num>

}…

]

assetDataFields = [

{



}…

]

users = [

{ id = <num> }…

]

type “dynamic”

rules = {

operator = <string>


children = [

{

operator = <string>


“clause”

type “clause”


value = <string>


}…

]

}



type “dnsname”



16

type “dnsname”




}… ]

Notes:

asset::getIPs Returns IPs associated with the posted repository ID. This command is available to an

organizational user with ownership of the selected asset.

Input Output

id = <num>

ipsOnly = <num> 0 (false) | 1 (true)

(nonnegative, default 0)

viewableIPs = [

{


repositoryName = <string>

ipList = <string>

}…

]

id = <num>

Notes:

Explicitly setting ipsOnly to true will remove all hostname elements from the pipe-

delimited elements in the ipList[] entries (the entries in ipList[] are delimited on “\n”).

auth::login Authenticates a user and returns metadata associated with the submitted credentials.

Input Output

username = <string>

password = <string>

sessionID = <num>

token = <num>

user = { // authentication password

id = <num>

username = <string>

password = <string> “” | “SET”

orgID = <num>


“tns”

fingerprint = <string> “” | “SET”

mustChangePassword = <string> “true” |

“false”

lastLogin = <num>

lastLoginIP = <string>

failedLogins = <num>


askAboutCert = <string> “true” | “false”


17

roleID = <num>

status = <num> 0 (active) | 1 (deleted)


lastname = <string>

title = <string>

email = <string>

address = <string>

city = <string>

state = <string>

country = <string>

phone = <string>

fax = <string>

displayName = <string>

role = {

id = <num>

creatorID = <num>

name = <string>


createdTime = <num>


permManageApp = <string> “true” |

“false”

permManageUsers = <string> “true” |

“false”

permManageRoles = <string> “true” |

“false”

permManageImages = <string> “true” |

“false”

permManageBlackoutWindows =

<string> “true” | “false”

permCreateOrgAssets = <string> “true” |

“false”

permCreateOrgCredentials = <string>


permCreateOrgPolicies = <string> “true”

| “false”

permCreateOrgQueries = <string> “true”

| “false”

permEditOrgAssets = <string> “true” |

“false”

permEditOrgCredentials = <string>


permEditOrgPolicies = <string> “true” |

“false”

permEditOrgQueries = <string> “true” |

“false”

permCreateTickets = <string> “true” |

“false”

permCreateAlerts = <string> “true” |

“false”

permCreateAuditFiles = <string> “true” |

“false”


18

permCreatePolicies = <string> “true” |

“false”

permPurgeTickets = <string> “true” |

“false”

permPurgeScanResults = <string> “true”

| “false”

permPurgeReportResults = <string>


permShareAssets = <string> “true” |

“false”

permShareCredentials = <string> “true”

| “false”

permShareDashboards = <string> “true”

| “false”

permSharePolicies = <string> “true” |

“false”

permShareQueries = <string> “true” |

“false”

permUpdatePlugins = <string> “true” |

“false”

permUploadNessusResults = <string>


permViewOrgLogs = <string> “true” |

“false”

permViewRawLogsData = <string> “true”

| “false”

permViewLCEData = <string> “true” |

“false”

permViewVulnData = <string> “true” |

“false”

permCreateAcceptRiskRules = <string>


permCreateRecastRiskRules = <string>


permScan = <string> “full” | “policy” |

“none”



Session user is not an administrator

ownerID = <num>

}


parentID = <num>

}

organization = {

id = <num>

name = <string>


zoneSelection = <string> “true” | “false”

restrictedIPs = <string>


19

}

preferences = {

userID = <num>

prefTimeZone = <string>

prefPluginUpdateNotification = <string>


prefNewObjectNotification = <string> “true”

| “false”

prefChangedObjectNotification = <string>


prefRemovedObjectNotification = <string>


gmtOffset = <num>


prefLowVulnColor = <string>

prefMediumVulnColor = <string>

prefHighVulnColor = <string>

prefCriticalVulnColor = <string>

prefScanStartNotification = “true” | “false”

prefScanCompletionNotification = “true” |

“false”

prefScanErrorNotification = “true” | “false”

prefReportStartNotification = “true” | “false”

prefReportCompletionNotification = “true” |

“false”

prefReportErrorNotification = “true” | “false”

prefTicketAssignmentEmail = “true” | “false”

prefTicketStatusNotification = “true” |

“false”

prefTicketEditNotification = “true” | “false”

prefZoneEditNotification = “true” | “false”

prefRoleEditNotification = “true” | “false”

prefRepositoryAddNotification = “true” |

“false”

prefRepositoryRemoveNotification = “true” |

“false”

prefNessusScannerNotification = “true” |

“false”

prefAlertTriggerNotification = “true” | “false”

prefOrgRestrictIPNotification = “true” |

“false”

prefOrgZoneSelectEditNotification = “true” |

“false”

prefUserEditNotification = “true” | “false”

prefPVSLCEEditNotification = “true” | “false”

}

version = <string>

buildID = <string>

releaseID = <string>


20

Notes:

> parentID is intentionally not returned here

> orgID on return will be “0” for an admin user

> token must be used for all subsequent requests for the duration of the session

auth::logout Logs the user with the specified token out.

Input Output

token = <num>

Notes:

credential::edit Edits credential metadata.

Input Output

id = <num>

name = <string>




“user”

type = <string> “kerberos” | “snmp” |

“ssh” | “windows”

users = [

{

id = <num>

}…

] (optional)

type “kerberos”

ip = <string>

port = <num>

protocol = <string>

realm = <string>

type “snmp”

communityString = <string>

type “ssh”

username = <string>

password = <string> (Supplied if

publicKey and privateKey are not

credential = {

id = <num>

creatorID = <num>

type = <string> “windows” | “snmp” | “ssh”

| “kerberos”

group = <string>

name = <string>




createdTime = <num>


users = [

// empty if visibility “application”

{ id = <num> }…

]

visibility “organizational” | “user"

ownerID = <num>

type “kerberos”

ip = <string>

port = <num>

protocol = <string>

realm = <string>

type “snmp”


21

empty)

publicKey = <string> (Supplied with

privateKey if password was removed or

is empty. Cannot be empty string)

privateKey = <string> (Supplied with

publicKey if password was removed or

is empty. Cannot be empty string)

passphrase = <string> (optional)

privilegeEscalation = <string> “Cisco

‘enable’” | “dzdo” | “none” | “pbrun” |

“su” | “su+sudo” | “sudo” (default “”)

type “ssh”, privilegeEscalation

“none"

escalationUsername = <string> “”

esclationPassword = <string> “”

type “ssh”, privilegeEscalation

“Cisco ‘enable’” | “dzdo” | “pbrun”

| “su” | “sudo”

escalationUsername = <string> “”

escalationPassword = <string>

(optional)

type “ssh”, “su+sudo”

escalationUsername = <string>

escalationPassword = <string>

(optional)

type “windows”

username = <string>

password = <string>

domain = <string> (default “”)


type “ssh”

username = <string>


publicKey = <string>

privateKey = <string>

passphrase = <string> “” | “SET”

privilegeEscalation = <string>


escalationPassword = <string> “” | “SET”

type “windows”

username = <string>


domain = <string>

}

Notes:

> For all credential types, all passwords and passphrases will add or replace the existing

data if supplied. If these fields are empty when supplied, they will remove the existing

data for their field.

> For all credential types, all passwords and passphrases will not be modified under the

conditions that (1) they are not supplied and (2) the privilege escalation field has not

been changed to warrant this behavior. The latter applies to escalationPassword only.

credential::init Displays user and credential metadata.

Input Output

credentials = [

{

id = <num>


22

creatorID = <num>

type = <string> “windows” | “snmp” |

“ssh” | “kerberos”

group = <string>

name = <string>




createdTime = <num>


users = [

// empty if visibility “application”

{ id = <num> }…

]


ownerID = <num>

type “kerberos”

ip = <string>

port = <num>

protocol = <string>

realm = <string>

type “snmp”


type “ssh”

username = <string>


publicKey = <string>

privateKey = <string>

passphrase = <string> “” | “SET”

privilegeEscalation = <string>


escalationPassword = <string> “” | “SET”

type “windows”

username = <string>


domain = <string>

}…

]

users = [

{

id = <num>

username = <string>


lastname = <string>

parentID = <num>

roleID = <num>

}…


23

]

roles = [

{

id = <num>

name = <string>




}…

]

Notes:

events::query Query event (LCE) data based upon the specified parameters.

Input Output

tool = <string> "listdata" | "sumasset"

| "sumclassa" | "sumclassb" |

"sumclassc" | "sumdate" | "sumevent" |

"sumevent2" | "sumip" | "sumport" |

"sumprotocol" | "sumsensor" |

"sumtime" | "sumtype" | "sumuser" |

"syslog" | "timedist"

startOffset = <num> (Lower bound to

returned record set, default 0)

endOffset = <num> (Upper bound to

returned record set, default 100)

sortField = <string> (optional, must

accompany sortDir)


(optional, default “ASC”)

sourceType = <string> “archive” | “lce”

file = <string> (default “”)

filters = [

{

filterName = <string> "assetID" |

"connectionDirection" |

"correlated" | "destAssetID" |

"destip" | "detailedEventName" |

"dipfile" | "dport" | "endtime" |

"eventName" | "ip" | "fip" |

"lceIDs" | "maxEvents" | "mipfile"

| "outputAssets" | "port" |

"protocol" | "repositoryIDs" |

"sensor" | "showEarliest" |

"sourceAssetID" | "sourceip" |

"sport" | "sipfile" | "starttime" |

"text" | "timeframe" | "user"

totalRecords = <num>

returnedRecords = <num>

startOffset = <num>

endOffset = <num>

startTime = <num>

endTime = <num>

matchingDataElementCount = <num>

tool “listdata”

results = [

{

event = <string>

type = <string>

protocol = <num>

source ip = <string>

destination ip = <string>

destination port = <num>

sensor = <string>

va/ids = <num>

time = <num>

number of vulns = <num>

}…

]

tool “sumasset”

results = [

{

assetID = <num>

count = <num>

}…

]


24

value = <string>

operator = <string> “=” | ”<=” |

”>=”

}…

] (optional)

sourceType "archive"

view = <string>

lceID = <num>

tool “sumclassa”

results = [

{

class-a = <string>

count = <num>

}…

]

tool “sumclassb”

results = [

{

class-b = <string>

count = <num>

}…

]

tool “sumclassc”

results = [

{

class-c = <string>

count = <num>

}…

]

tool “sumdate”

results = [

{

date = <string>

24-hour plot = <num>

time block start = <num>

time block stop = <num>

count = <num>

}…

]

tool “sumevent”

results = [

{

event = <string>

file = <string>


24-hour plot = <string>

count = <num>

}…

]

tool “sumevent2”

results = [

{

event = <string>

file = <string>



25


count = <num>

}…

]

tool “sumip”

results = [

{

lce id = <num>

address = <string>

count = <num>

}…

]

tool “sumport”

results = [

{

port = <num>

count = <num>

}…

]

tool “sumprotocol”

results = [

{

protocol = <num>

count = <num>

}…

]

tool “sumsensor”

results = [

{

sensor = <string>

count = <num>

}…

]

tool “sumtime”

results = [

{

time block start = <num>

time block stop = <num>

count = <num>

}…

]

tool “sumtype”

results = [

{

type = <string>



26

count = <num>

}…

]

tool “sumuser”

results = [

{

user = <string>


count = <num>

}…

]

tool “syslog”

results = [

{

type = <string>

sensor = <string>

message = <string>

time = <num>

}…

]

Notes:

> These requests have intrinsic, “high” query priorities.

> A default timeframe of 24 hours will be applied if a timeframe filter is not provided.

> Events with sourceType “archive” filter by default on all LCEs currently accessible by

the session user, unless LCE filter(s) are provided.

Tool List

listdata = List of Events

sumasset = Asset Summary

sumclassa = Class A Summary

sumclassb = Class B Summary

sumclassc = Class C Summary

sumdate = Summarize matching events by date

sumevent = Normalized Event Summary

sumevent2 = Detail Event Summary (Original Event Name)

sumip = IP Summary

sumport = Port Summary

sumprotocol = Protocols Summary

sumsensor = Sensor Summary

sumtime = Event Trend by time frame

sumtype = Type Summary

sumuser = User Summary

syslog = Raw Syslog Events

Filter List

assetID = <num> (single ID right now)

connectionDirection = <string> "inbound" | "internal" | "outbound"

correlated = <string> “true” | ”false” (default “false”)


27

date = <string>

destAssetID = <num> (single ID right now)

destip = <string> (comma-separated list of single ips, ranges, CIDRS)

detailedEventName = <string>

dipfile = <string>

dport = <string> (comma-separated list of single ports or ranges between 0 and 65535.

Ranges are delimited on a dash, “- “. Operators “<=” and “>=” require a single port

specification)

endtime = <num>

eventName = <string>

ip = <string> (comma -separated list of single ips, ranges, CIDRS)

fip = <string>

lceIDs = <string> (comma-separated list of integer IDs)

maxEvents = <num>

mipfile = <string>

numEvents = <num>

outputAssets = <string> (comma-separated list of integer IDs)

port = <string> (comma-separated list of single ports or ranges between 0 and 65535.


specification)

protocol = <string> "icmp" | "tcp" | "udp" | "unknown" | [0..] (any string in the value set

or an integer)

repositoryIDs = <string> (comma-separated list of integer IDs)

sensor = <string>

showEarliest = <string>

silo = <string>

sourceAssetID = <num> (single ID right now )

sourceip = <string> (comma -separated list of single ips, ranges, CIDRS)

sport = <string> (comma-separated list of single ports or ranges between 0 and 65535.


specification)

sipfile = <string>

starttime = <num>

text = <string>

timeframe = <string> “all” | “any” | “custom” | [0..] [“d” | “h” | “m”] (specific timeframe

uses any nonnegative integer, then a unit. Valid units are “d” for days, “h” for hours”,

and “m” for months)

type = <string>

user = <string>

plugin::getDetails Returns metadata specific to the Plugin ID.

Input Output

pluginID = <num> id = <num>

name = <string>


familyID = <num>


“custom” | “passive”


28

copyright = <string>

version = <string>

sourceFile = <string>

source = <string>

dependencies = <string>

requiredPorts = <string>

requiredUDPPorts = <string>

cpe = <string>

srcPort = <num>

dstPort = <num>

protocol = <num>

riskFactor = <string>

solution = <string>

seeAlso = <string>

synopsis = <string>

checkType = <string>

exploitEase = <string>

exploitAvailable = <string> “” | “true” | “false”

exploitFrameworks = <string>

cvssVector = <string>

cvssVectorBF = <num>

baseScore = <string>

temporalScore = <string>

stigSeverity = <string> “I” | “II” | null

pluginPubDate = <num>

pluginModDate = <num>

vulnPubDate = <num>

patchPubDate = <num>


md5 = <string>

family = <string>

xrefs = <string>

Notes:

Example Request:

POSTDATA

=token=1872564972&module=plugin&action=getDetails&request_id=1&input={"pluginI

D":"20811"}

plugin::getPage Search all plugins based on the filter criteria specified

Input Output

size = <num> (nonnegative, default

“100”)

offset = <num> (nonnegative, default

0)

type = <string> “all” | “notPassive” |

“active” | “compliance” | “custom” |

lastUpdates = {

active = {

updateRunning = <string> “true | “false”

pluginsStale = <string> “true” | “false”

updateTime = <num>

}


29

“passive” (default “all”)

sortField = <string> “modifiedTime” |

“id” | “name” | “family” | “type” (default

“modifiedTime”)

sortDirection = <string> “ASC” | “DESC”

(default “DESC”)

filterField = <string> “id” | “name” |

“description” | “type” | “version” |

“copyright” | “sourceFile” | “family” |

“exploitAvailable” | “xrefs:XXX” (default

“”. If filterField begins with “xrefs:”,

then XXX must be any valid XRefs type.)

filterString = <string> (default “”. If

filterField is “type”, then this value must

be “active”, “passive”, “compliance”, or

“custom”)

since = <num> (timestamp in seconds

since the Epoch, default 0)

custom = {

updateTime = <num>

}

passive = {



updateTime = <num>

}

}

plugins = [

{

id = <num>

name = <string>

familyID = <num>


version = <string>

sourceFile =<string>



md5 = <string>


family = <string>

xrefs = <string>

}…

]

pluginCount = <num> // -1 if active or

passive updates running

Notes:

> All sorts on plugin “family”, “name”, “type”, and “modifiedTime” will have a secondary

ascending sort on plugin “id”.

> Default sort (if no sortField is provided) will be on modified time descending, then

pluginID ascending.

Example Request:

POSTDATA

=token=1872564972&module=plugin&action=getPage&request_id=1&input={"sortDirecti

on":"DESC","filterField":"id","type":"all","sortField":"modifiedTime","filterString":"10180"}

plugin::init

Input Output

size = <num> (nonnegative, default

“100”)

offset = <num> (nonnegative, default

0)

type = <string> “all” | “notPassive” |

“active” | “compliance” | “custom” |

“passive” (default “all”)

sortField = <string> “modifiedTime” |

lastUpdates = {

active = {



updateTime = <num>

}

custom = {

updateTime = <num>


30

“id” | “name” | “family” | “type” (default

“modifiedTime”)

sortDirection = <string> “ASC” |

“DESC” (default “DESC”)

filterField = <string> “id” | “name” |

“description” | “type” | “version” |

“copyright” | “sourceFile” | “family” |

“exploitAvailable” | “xrefs:XXX” (default

“”. If filterField begins with “xrefs:”,

then XXX must be any valid XRefs

type.)

filterString = <string> (default “”. If

filterField is “type”, then this value must

be “active”, “passive”, “compliance”, or

“custom”)

since = <num> (timestamp in seconds

since the Epoch, default 0)

}

passive = {



updateTime = <num>

}

}

plugins = [

{

id = <num>

name = <string>

familyID = <num>


version = <string>

sourceFile =<string>



md5 = <string>


family = <string>

xrefs = <string>

}…

]

pluginCount = <num> // -1 if active or

passive updates running

Active and passive updates not running

active = <num>

compliance = <num>

custom = <num> // if custom plugins exist

passive = <num>

Notes:

> All sorts on plugin “family”, “name”, “type”, and “modifiedTime” will have a secondary

ascending sort on plugin “id”.

> Default sort (if no sortField is provided) will be on modified time descending, then

pluginID ascending.

> Restrictions on cvebid are now specified through “xrefs” filters.

repository::init Displays all repositories with their associated metadata.

Input Output

repositories = [

{

id = <num>

name = <string>




31

“Remote”

ipRange = <string>

ipCount = <num>

vulnCount = <num>

remoteID = <num>

remoteIP = <string>



“false”




createdTime = <num>




organizations = [

{

id = <num>

userAssign = <string> "all" |

"orghead" | "partial"

}...

]

correlation = [

{ id = <num> }…

]

nessusScheduleType = <string> “never”

| “daily” | “weekly” | “monthly1” |

“monthly2”

nessusScheduleDefinition = <string>

vulnCount = <num>

repositories type “Remote”

remoteScheduleType = <string> “never”

| “daily” | “weekly” | “monthly1” |

“monthly2”

remoteScheduleDefinition = <string>

}…

]

organizations = [

{

id = <num>

name = <string>


}…

]

lces = [

{

id = <num>

name = <string>


ip = <string>


32

managedRanges = <string> | null

version = <string>

status = <num> 1 (working) | 2 (closed)

| 16 (failure) | 32 (auth failure) | 64

(invalid) | 2048 (LCE daemon down) |

4096 (Query daemon down)

createdTime = <num>


organizations = [

{ id = <num> }…

]

}…

]

licensedIPs = <num>

activeIPs = <num>

Notes:

> Schedule definition “monthly1” specifies a date while schedule definition “monthly2”

specifies a day of the month. e.g. “first monday …” or “second Sunday …”

> The LCE statuses given represent nonexclusive status bits (i.e. they can be

combined).

role::init Displays user roles with their associated metadata.

Input Output

roles = [

{

id = <num>

creatorID = <num>

name = <string>


createdTime = <num>



“false”


“false”


“false”


“false”




“false”




| “false”


34

organizationCounts = [

{

id = <num>

userCount = <num>

}…

]




ownerID = <num>

}…

]

organizations = [

{

id = <num>

name = <string>


}…

]

users = [

{

id = <num>

parentID = <num>

username = <string>


lastname = <string>

roleID = <string>

}…

]

Notes:

> Organizations list is only populated if the session user is an administrator.

> Users list is only populated if the session user is not an administrator.


scanResult::init Displays individual scan job information for the past 30 days.

Input Output

scanResults = [

{

downloadFormat = <string>

initiatorID = <num>


status = <string> completed | blocked |

partial

details = <string>

totalIPs = <num>


35


name = <string>

errorDetails = <string>

importErrorDetails = <string>

finishTime = <num>

downloadAvailable = <string> “true” |

“false”

startTime = <num>

scannedIPs = <num>

id = <num>


importStatus = <string>

}…

]

Notes:

scanResult::download Downloads a compressed individual scan result file.

Input Output

scanResultID = <num>

downloadType = <string> “v1” | “v2”

'content-disposition': 'attachment;

filename=<id>.zip'

Notes:

> SecurityCenter versions prior to 4.4 supported a download type of either “nessus” (v1

format) or “nsr”.

> scanResultID is the id returned by the scanResult::init call above

system::init Displays system information such as version and build.

Input Output

version = <string>

buildID = <string>

releaseID = <string>

uuid = <string>

logo = <string>

sessionTimeout = <num>

licenseStatus = <string> “Exceeded” |

“Expired” | “Invalid” | “Locked” | “Valid” |

“Stale”

mode = <string> “” | “LCE” | “SC”

ACAS = <string> “true” | “false”

freshInstall = <string> “yes” | “no”

headerText = <string>

timezones = [


36

{

name = <string>

gmtOffset = <string>

}…

]

Configuration fingerprint is set for server

sessionID = <num>

token = <num>

user = { // authentication cert

id = <num>

username = <string>


orgID = <num>


“tns”

fingerprint = <string> “” | “SET”

mustChangePassword = <string> “true” |

“false”

lastLogin = <num>




askAboutCert = <string> “true” | “false”

roleID = <num>



lastname = <string>

title = <string>

email = <string>

address = <string>

city = <string>

state = <string>

country = <string>

phone = <string>

fax = <string>

displayName = <string>

role = {

id = <num>

creatorID = <num>

name = <string>


createdTime = <num>



“false”


“false”


“false”


“false”


38


“false”






“none”




ownerID = <num>

}


parentID = <num>

Server SSL CLIENT M SERIAL is set

certSerial = <string>

}

organization = {

id = <num>

name = <string>


zoneSelection = <string> “true” | “false”

restrictedIPs = <string>

}

Notes:

> This call does not require an auth token, and will return an error if one is provided.

> The mode will be the empty string before any license is used.

ticket::init Displays tickets and associated metadata.

Input Output

users = [

{

id = <num>

parentID = <num>

roleID = <num>

status = <num> 0 (active)

username = <string>


lastname = <string>

title = <string>

email = <string>

address = <string>

city = <string>


39

state = <string>

country = <string>

phone = <string>

fax = <string>

lastLogin = <num>


“tns”



}…

]

queries = [

{

id = <num>

name = <string>















| "vulnipdetail"




“user”

group = <string>


ownerID = <num>

Non Descendants Ticket Queries &

No Context Queries

creatorID = <num>




“DESC”

createdTime = <num>








40

filters = [

{


operator = <string>

value = <string>

}…

]


users = [

{ id = <num> }…

]

}…

]

tickets = [

{

id = <num>

name = <string>


status = <string> “assigned” |

“closed” | “duplicate” | “feedback” |

“na” | “resolved”

classification = <string> “Accept Risk”

| “Bad Credentials” | “Compromised

System” | “Configuration” | “Disable” |

“External Probe” | “False Positive” |

“Firewall” | “IDS” | “Information” |

“Investigation Needed” | “Other” |

“Patch” | “Re-scan Request” | “Recast

Risk” | “Schedule” | “System Probe” |

“Unauthorized Software” |

“Unauthorized System” |

“Unauthorized User” | “Virus Incident”

notes = <string>

assignedTime = <num>


closedTime = <num>

creatorID = <num>

ownerID = <num>

createdTime = <num>

assigneeID = <num>

resolvedTime = <num>

queries = [

{ id = <num> }…

]

}…

]

Notes:




41

user::init Display all user metadata from the queried system.

Input Output

users = [

{

id = <num>

roleID = <num>


username = <string>


lastname = <string>

title = <string>

email = <string>

address = <string>

city = <string>

state = <string>

country = <string>

phone = <string>

fax = <string>

lastLogin = <num>


“tns”






parentID = <num>

mustChangePassword = <string> “true”

| “false”


lces = [

{ id = <num> }…

]

repositories = [

{ id = <num> }…

]

credentials = [

// Shared BY editing user to this user

{ id = <num> }…

]

assets = {

isAccessible = [

// Shared BY editing user to this

user

{ id = <num> }…

]


42

User is not session user

definesUser = [

// Assets that define this user

{ id = <num> }…

]

}

policies = [

{ id = <num> }…

]

queries = [

// Shared BY editing user to this user

{ id = <num> }…

]

activeScans = <num> 0

scheduledScans = <num> 0

reports = <num> 0

openTickets = <num> 0

totalTickets = <num> 0

}…

]

roles = [

{

id = <num>

creatorID = <num>

name = <string>


createdTime = <num>



“false”


“false”


“false”


“false”




“false”




| “false”


| “false”


“false”




“false”


43


“false”


“false”


“false”


“false”


“false”


“false”


| “false”




“false”


| “false”


| “false”


“false”


“false”


“false”




“false”


| “false”


“false”


“false”






“none”




ownerID = <num>

}…

]

ldapConfig = {


44

LDAPHost = <string>

LDAPPort = <num>

LDAPUseTLS = <string> “yes” | “no”

LDAPdn = <string>

LDAPUsername = <string>

LDAPPassword = <string “” | “SET”

LDAPAttrUsername = <string>

LDAPAttrEmail = <string>

LDAPAttrName = <string>

LDAPAttrPhone = <string>

LDAPSearchString = <string>

LDAPLowercase = <string> “true” | “false”

]


repositories = [

{

id = <num>

name = <string>



“Remote”

ipRange = <string>

ipCount = <num>

vulnCount = <num>

remoteID = <num>

remoteIP = <string>



“false”




createdTime = <num>




}…

]

queries = [ // All of editing user

{

id = <num>

ownerID = <num>

name = <string>










45







| "vulnipdetail"




“user”

group = <string>

}…

]

credentials = [

// All of editing user

{

id = <num>

name = <string>






group = <string>


ownerID = <num>

}…

]

assets = [


assets of all users + assets of decendants

{

id = <num>

name = <string>



“user”

ownerID = <num>



group = <string>

assetDataFields = [

{



}…

]

visibility “organizational” or asset

belongs to session user


46

context = <string> “”


}…

]

Notes:

> Only the administrator role will be present in roles[] if the session user is an

administrator, otherwise all “application” visible roles as well as roles visible in the

organizational context will be present.

> In users[], only contact, parent, role, status, last login, auth type, fingerprint, and

locked information is provided for users NOT below the logged-in user in the hierarchy

for an organizational context. If the session user an administrator, then only this

information will be returned for all users regardless, and these users will be the

application administrators.

> repositories[] and assets[] are populated with info for the session user.


vuln::init Displays all available vulnerabilities from the remote system.

Input Output

queries = [

{

id = <num>

creatorID = <num>

ownerID = <num>

name = <string>















| "vulnipdetail"




“user”

group = <string>

context = <string> “” | “alerting”



47



“DESC”

createdTime = <num>







filters = [

{


operator = <string>

value = <string>

}…

]


users = [

{ id = <num> }…

]

}…

]

repositories = [

{

id = <num>

name = <string>




“Remote”

}…

]

assets = [


assets of all users

{

id = <num>

name = <string>



“user”

ownerID = <num>





group = <string>

assetDataFields = [

{



48


}…

]

}…

]

users = [

{

id = <num>

parentID = <num>

username = <string>


lastname = <string>

roleID = <num>

}

]

policies = [

{

id = <num>

name = <string>

type = <string> “custom” | “family” |

“plugin”





group = <string>

status = <num> 0 (active) | 128

(inactive audit file)

}…

]

auditFiles = [

{

id = <num>

name = <string>


modifiedTime = <string>

type = <string> “as/400” | “cisco” |

“database” | “unix” | “windows” |

“windowsfiles”



visibility “application”

filename = <string>

orginalFilename = <string>

}…

]

families = [

{

id = <num>

name = <string>



49

“custom” | “customPassive” | “passive”

count = <num>

}…

]

styleFamilies = [

{

id = <num>

name = <string>


}…

]

creds = [

{

id = <num>

name = <string>






group = <string>


ownerID = <num>

}…

]

prefs = [

{

modulePrefID = <num>

userID = <num>

module = <string> “lce” | “vuln”














| "vulnipdetail"

columns = <string>

chart = <string>

sortColumn = <string>

sortDirection = <string> “ASC” | “DESC”

filters = [

{



50

operator = <string>

value = <string>

}…

]

columns = [

name = <string>

]

}…

]

zones = [

{

id = <num>

name = <string>


ipList = <string>

createdTime = <num>


scanners = [

{ id = <num> }…

]

}…

]

ipInfoLinks = [

{

name = <string>

link = <string>

}…

]

Notes:

> The zones[] element may contain entries if zone selection is enabled for the

organizational context.



vuln::getIP Displays host detailed information for an IP address.

Input Output

ip = <string>

repositories = [

{

id = <num>

}…

]

links = [

{

name = <string>

link = <string>

}…

]

records = [

{

ip = <num>



51

score = <num>

total = <num>

severityInfo = <num>

severityLow = <num>

severityMedium = <num>

severityHigh = <num>

severityCritical = <num>

macAddress = <string>

netbiosName = <string>

dnsName = <string>

severityAll = <string>

os = <string>

hasPassive = <string> “Yes” | “No”

hasCompliance = <string> “Yes” | “No”

lastScan = <num>

}…

]

Notes:

> The repositories[] element defaults to all repositories for the session user if no ids are

provided.

vuln::query Query vulnerability data based on the specified parameters.

Input Output

tool = <string> "iplist" | "listmailclients"

| "listos" | "listservices" | "listsoftware"

| "listsshservers" | "listvuln" |


"sumasset" | "sumclassa" | "sumclassb"

| "sumclassc" | "sumcve" |

"sumdnsname" | "sumfamily" |

"sumiava" | "sumid" | "sumip" |

"summsbulletin" | "sumport" |

"sumprotocol" | "sumseverity" |

"vulndetails" | "vulnipdetail" |

"vulnipsummary"

startOffset = <num> (optional, lower

bound to returned record set. Must be

explicitly supplied for tools “vulndetails”

and “listvuln”)

endOffset = <num> (optional, upper

bound to returned record set. Must be

explicitly supplied for tools “vulndetails”

and “listvuln”)

sortField = <string> (optional, can be

any valid field returned in the results

entry for the corresponding tool. Must

totalRecords = <num>

returnedRecords = <num>

startOffset = <num>

endOffset = <num>

matchingDataElementCount = <num>

tool “iplist”

results = [

<string>…

]

tool “listmailclients” | “listos” |

“listservices” | “listsoftware” |

“listsshservers” | “listwebclients” |

“listwebservers”

results = [

{

name = <string>

detectionMethod = <string>

count = <num>

}…

]


52

accompany sortDir)


(optional, default “ASC”)

sourceType = <string> "cumulative" |

"individual" | "patched"

filters = [

{


"acceptRiskStatus" | "assetID" |

"auditFileID" | "baseCVSSScore" |

"cveID" | "dnsName" |

"exploitAvailable" | "familyID" |

"firstSeen" | "iavaID" | "ip" |

"lastMitigated" | "lastSeen" |

"mitigatedStatus" | "msbulletinID"

| "outputAssets" | "pluginID" |

"pluginName" | "pluginText" |

"pluginType" | "policyID" | "port" |

"protocol" | "recastRiskStatus" |

"repositoryIDs" | "severity" |


value = <string>

operator = <string> “=” | ”>=” |

”<=” | “!=”

}…

] (optional)

sourceType “cumulative”

tool |= “trend” (i.e. tool value set may

also include “trend”)

sourceType "individual"

view = <string>

dateDirectory = <string>

scanID = <num>

tool “listvuln”

results = [

{

pluginID = <num>


severity = <num> 0 (info) | 1 (low) |

2 (medium) | 3 (high) | 4 (critical)

ip = <string>

port = <num>

protocol = <num>

name = <string>

familyID = <string>

dnsName = <string>



}…

]

tool “sumasset”

results = [

{

assetID = <num>

score = <num>

total = <string>


severityLow = <num>




}…

]

tool “sumclassa” | “sumclassb” |

“sumclassc”

results = [

{

ip = <string>


score = <num>

total = <num>


severityLow = <num>




}…

]

tool “sumcve”

results = [

{

cveID = <num>


53

severity = <num> 0 (info) | 1 (low) | 2

(medium) | 3 (high) | 4 (critical)

total = <num>

}…

]

tool “sumdnsname”

results = [

{

dnsName = <string>


score = <num>

total = <num>


severityLow = <num>




}…

]

tool “sumfamily”

results = [

{

familyID = <string>

score = <num>

total = <num>


severityLow = <num>




}…

]

tool “sumiava”

results = [

{

iavaID = <string>



total = <num>

}…

]

tool “sumid”

results = [

{

pluginID = <num>

name = <string>

family ID= <num>



54


total = <num>

}…

]

tool “sumip”

results = [

{

ip = <string>


score = <num>

total = <num>


severityLow = <num>






dnsName = <string>

}…

]

tool “summsbulletin”

results = [

{

msbulletinID = <string>



total = <num>

}…

]

tool “sumport”

results = [

{

port = <string>

score = <num>

total = <num>


severityLow = <num>




}…

]

tool “sumprotocol”

results = [

{

protocol = <num>

score = <num>


55

total = <num>


severityLow = <num>




}…

]

tool “sumseverity”

results = [

{



count = <num>

}…

]

tool “trend”

results = [

{

date = <num>

score = <num>

total = <num>


severityLow = <num>




}…

]

tool “vulndetails”

results = [

{

pluginID = <num>




hasBeenMitigated = <num> 0 (false) | 1

(true)

acceptRisk = <num>

recastRisk = <num>

ip = <string>

port = <num>

protocol = <num>

pluginName = <string>

familyID = <num>

firstSeen = <num>

lastSeen = <num>

exploitAvailable = <string> “true” |

“false”


56

exploitFrameworks = <string>

pluginText = <string>

dnsName = <string>



}…

]

tool “vulnipdetail”

results = [

{

pluginID = <num>

total = <num>



name = <string>

familyID = <num>

pluginDescription = <string>

hosts = [

{


iplist = [

{

ip = <string>



dsnName = <string>

}…

]

}…

]

}…

]

tool “vulnipsummary”

results = [

{

pluginID = <num>

total = <num>



name = <string>

familyID = <num>

pluginDescription = <string>

hosts = [

{


iplist = <string>

}…

]

}…

]


57

Notes:

Tool List

iplist = IP Address List

listmailclients = Mail Clients List

listos = Operating Systems List

listservices = Service Banners List

listsoftware = Software List

listsshservers = SSH Versions List

listvuln = Vulnerabilities List

listwebclients = Web Client Versions List

listwebservers = Web Server Versions List

sumasset = Asset Summary

sumclassa = Class A Summary

sumclassb = Class B Summary

sumclassc = Class C Summary

sumcve = CVE Summary

sumdnsname = DNS Name Summary

sumfamily = Plugin Family Summary

sumiava = IAVA Summary

sumid = Plugin ID Summary

sumip = IP Summary

summsbulletin = MS Bulletin Summary

sumport = Port Summary

sumprotocol = Protocols Summary

sumseverity = Severity Summary

trend = Vulnerability Severity Trend

vulndetails = Vulnerabilities Detail

vulnipdetail = Vulnerability IPs Detail

vulnipsummary = Vulnerability IPs Summary

Filter List

acceptedRisk = <string> “true” | “false”

acceptRiskStatus = <string> “accepted” | “all”

assetID = <num> (single ID right now)

auditFileID = <num> (audit file ID)

baseCVSSScore = <string> [number][“-“][number] (dash-delimited integer range)

cveID = <string> (comma-separated list of IDs)

dnsName = <string> (comma -separated list of single DNS names)

exploitAvailable = <string> “true” | “false”

familyID = <num> (plugin family ID)

firstSeen = <num> (valid Unix timestamp of discovery)

iavaID = <string>

ip = <string> (comma -separated list of single ips, ranges, CIDRS)

lastMitigated = <num> (valid Unix timestamp of last mitigation)

lastSeen = <num> (valid Unix timestamp of last observation)

mitigatedStatus = <string> “never” | “previously”

msbulletinID = <string> (comma-separated list of IDs)

outputAssets = <string> (comma-separated list of integer IDs)

pluginID = <string> (comma-separated list of single integer IDs or ranges between 0 and

16777216. Ranges are delimited on a dash, “- “. Operators “<=” and “>=” require a

single ID specification)


58

pluginName = <string>

pluginText = <string>

pluginType = <string> comma-separated list of the following set: “active” | “passive” |

“compliance”

policyID = <num> policy ID

port = <string> (comma-separated list of single ports or ranges between 0 and 65535.


specification)

protocol = <num> (comma-separated list of single integers or ranges. Ranges are

delimited on a dash, “- “. Operators “<=” and “>=” require a single ID specification)

recastRisk = <string> “true” | “false”

recastRiskStatus = <string> “notRecast” | “recast”

repositoryIDs = <string> (comma-separated list of integer IDs)

severity = <string> (comma-separated list of single integers or ranges for the following

set: 0 (info) | 1 (low) | 2 (medium) | 3 (high) | 4 (critical). Ranges are delimited on a

dash, “- “. )

tcpport = <string> (comma-separated list of single ports or ranges between 0 and

65535. Ranges are delimited on a dash, “- “. Operators “<=” and “>=” require a single

port specification)

udpport = <string> (comma-separated list of single ports or ranges between 0 and

65535. Ranges are delimited on a dash, “- “. Operators “<=” and “>=” require a single

port specification)

wasMitigated = <string> “true” | “false”

zone::init Display all available scan zones and scanner status.

Input Output

zones = [

{

id = <num>

name = <string>


ipList = <string>

createdTime = <num>


scanners = [

{ id = <num> }…

]

organizations = [

{ orgID = <num> }…

]

}…

]

scanners = [

{

id = <num>

name = <string>


status = <num> 1 (working) | 2 (closed)


59

| 4 (timeout) | 8 (certificate error) | 16

(failure) | 32 (auth failure) | 64 (invalid)

| 128 (reloading) | 256 (out of date) |

512 (results available) | 1024 (updating

plugins) | 8192 (calculating) | 16384

(disabled) | 32768 (old)

}…

]

organizations = [

{

id = <num>

name = <string>


}…

]

Notes:

> Scanners returned are Nessus scanners.

> Scanners containing a status bit of “old” have a web server older than v3.0.0.

> The Scanner statuses given represent nonexclusive status bits (i.e. they can be

combined).

ERROR CODES

Description Code

RESPONSE_UNKNOWN -1

RESPONSE_OK 0

RESPONSE_WARNING 65536

RESPONSE_NO_MODULE 10

RESPONSE_NO_ACTION 11

RESPONSE_BAD_TOKEN 12

RESPONSE_BAD_JSON 13

RESPONSE_CONFIGURATION_ERROR 60

RESPONSE_NOT_CONFIGURED 61

RESPONSE_UNAVAILABLE 62


60

RESPONSE_DENIED 63

RESPONSE_DISABLED 64

RESPONSE_EXPIRED 65

RESPONSE_REREGISTER 66

RESPONSE_CONNECTION_ERROR 67

RESPONSE_STOPPED 68

RESPONSE_KILLED 69

RESPONSE_CANTFORK 70

RESPONSE_FILE_READ_ERROR 101

RESPONSE_FILE_WRITE_ERROR 102

RESPONSE_FILE_FORMAT_ERROR 103

RESPONSE_MISSING_FILE 104

RESPONSE_FILE_OPEN_ERROR 105

RESPONSE_FILESYSTEM_ERROR 106

RESPONSE_UPLOAD_ERROR 107

RESPONSE_FILE_COPY_ERROR 108

RESPONSE_UNEXPECTED_DATA 141

RESPONSE_MISSING_REQUIRED_INPUT 142

RESPONSE_INVALID_FILTER 143

RESPONSE_NAME_EXISTS 144

RESPONSE_DATA_DOES_NOT_EXIST 145


61

RESPONSE_INVALID_DATA 146

RESPONSE_NOT_FOUND 147

RESPONSE_EXISTS 148

RESPONSE_INVALID_CREDENTIALS 161

RESPONSE_INVALID_USER_OBJECT 162

RESPONSE_NO_PERMISSION 163

RESPONSE_LDAP_ERROR 171

RESPONSE_DATABASE_SETUP_FAILURE 201

RESPONSE_DATABASE_ERROR 202


62

ABOUT TENABLE NETWORK SECURITY

Tenable Network Security, the leader in Unified Security Monitoring, is the source of the

Nessus vulnerability scanner and the creator of enterprise-class, agentless solutions for the

continuous monitoring of vulnerabilities, configuration weaknesses, data leakage, log

management, and compromise detection to help ensure network security and FDCC, FISMA,

SANS CAG, and PCI compliance. Tenable’s award-winning products are utilized by many

Global 2000 organizations and Government agencies to proactively minimize network risk.

For more information, please visit http://www.tenable.com/.

Tenable Network Security, Inc.

7063 Columbia Gateway Drive

Suite 100

Columbia, MD 21046

410.872.0555 www.tenable.com

http://www.tenable.com/

http://www.tenable.com/


63

APPENDIX 1: SAMPLE VULN QUERY PERL SCRIPT

Following is a sample script that authenticates to SecurityCenter 4.4 and queries the

number of vulnerabilities by severity in the cumulative database.

Use CPAN to obtain the following prerequisite Perl modules (if not already

installed):

> Crypt::SSLeay

> URI::Escape

> Data::Dump

> LWP::UserAgent

> HTTP::Cookies

> JSON

#!/usr/bin/perl

use strict;

use warnings;

use JSON; # JSON encoding and decoding with to_json and

from_json

use URI::Escape; # URI encoding with uri_escape

use LWP::UserAgent; # High-level HTTP API

use HTTP::Cookies; # Used to store session cookie

use Data::Dump qw( dump );

my $username='org1';

my $password='password';

my $server='127.0.0.1';

# Construct input as a Perl data structure.

my $input = {

username => $username, # This is the username

password => $password, # This is the password

request_id => 1 # int

};

# Convert the input object from Perl hash to JSON string, and URI encode

it.

my $encoded = to_json($input); # Serialize object to string.

my $escaped = uri_escape($encoded); # URI encode the string.

# Create a UserAgent object with a cookie jar

my $cookies = HTTP::Cookies->new(

'file' => '/tmp/cookies.lwp',

# where to read/write cookies

'autosave' => 1,

# save it to disk when done

'ignore_discard' => 1

);

my $ua = LWP::UserAgent->new;

http://search.cpan.org/


64

$ua->agent("MyApp/0.1 " . $ua->agent);

$ua->cookie_jar($cookies);

# Create a request

my $req = new HTTP::Request POST => 'https://'.$server.'/request.php';

$req->content_type('application/x-www-form-urlencoded');

$req->content('module=auth&action=login&request_id=1&input='.$escaped);

# Pass request to the user agent and get a response back

my $response = $ua->request($req);

# Check the outcome of the response

if ($response->is_success) {

#print $response->content."\n";

my $responsetext = $response->content; # Get result as JSON text.

my $response = from_json($responsetext); # Parse text to a Perl

hash.

# Dump the response hash

#print STDERR "The response is " . dump( $response ) . "\n";

if ($response->{error_code} ne 0) {

print "Error: ".$response->{error_code}." ".$response->{error_msg};

} else {

my $token=dump( $response->{response}{token} );

print "Session Token: ".$token."\n";

# Construct input as a Perl data structure.

my $input = { tool => "sumseverity", sourceType => "cumulative"

};

# Convert the input object from Perl hash to JSON string, and URI

encode it.

my $encoded = to_json($input); # Serialize object to string.

my $escaped = uri_escape($encoded); # URI encode the string.

# create a request

$req-

>content('module=vuln&action=query&input='.$escaped.'&request_id=1&

token='.$token);

$response = $ua->request($req);

$responsetext = $response->content; # Get result as JSON

text.

$response = from_json($responsetext); # Parse text to a Perl

hash.

print dump( $response->{response}{results} ) . "\n";

# Logout and remove the cookie

$req-

>content('module=auth&action=logout&request_id=1&token='.$token);

$cookies->clear;

}

} else {

print "Request failed!!\n";

print $response->status_line."\n";

}


65

SAMPLE OUTPUT

Session Token: 101843183

The response is [

{ count => 1, severity => 3 },



{ count => 2142, severity => 0 },

]


66

APPENDIX 2: SAMPLE HOST DETAIL PYTHON SCRIPT

Following is a sample script that authenticates to SecurityCenter 4 and returns host details

for the specified IP address.

This Python script requires Python version 2.6 or greater along with the package

httplib2 from http://code.google.com/p/httplib2.

#!/usr/bin/python26

# Simple python script to demonstrate the SC4 API

# Returns host detail info for IP addr

#

# Requires: Python 2.6+ and httplib2 from

http://code.google.com/p/httplib2

# Adjust the Python path to your working environment

import sys

if sys.version_info[0:3] < (2, 6):

print 'This script does not work with this version of

Python (%d.%d.%d)' % sys.version_info[0:3]

print 'Python 2.6 or later includes a json module,

otherwise you need to install simplejson'

sys.exit()

import httplib2, urllib, json, pprint, time

def usage():

print "Usage: sc4-getIP.py <IP Addr> "

print "IE: sc4-getIP.py 192.168.111.1"

sys.exit(1)

if len(sys.argv) != 2:

usage()

ip = sys.argv[1]

user = 'org1'

passwd = 'password'

url = 'https://localhost/request.php'

def SendRequest(url, headers, data):

http = httplib2.Http(disable_ssl_certificate_validation=True)

response, content = http.request(url, 'POST', headers=headers,

body=urllib.urlencode(data))

if 'set-cookie' in response:

headers['Cookie'] = response['set-cookie']

#print response.status, response.reason

return response, content

headers = {"Content-type": "application/x-www-form-urlencoded"}

# Construct input data structure.

input = {'password': passwd,



67

'username': user}

# Convert python object to JSON

inputjson = json.dumps(input)

data = {"request_id": "1",

"module": "auth",

"action": "login",

"input": inputjson}

# Send Request

response, content = SendRequest(url, headers, data)

# Decode JSON to python data structure

result = json.loads(content)

#print json.dumps(result)

#print "Keys:",result['response'].keys()

if result["error_code"] == 0:

print "SC4 Login Successful"

token = result['response']['token']

print "Session Token:",token

# Query

input = {"ip": ip};



"module": "vuln",

"action": "getIP",

"input": inputjson,

"token": token}


results = json.loads(content)

#pprint.pprint(results['response']['records'])

if len(results['response']['records']) != 0:

for result in results['response']['records']:

print "IP Addr:",result['ip']

print "Last Scanned:",time.ctime(int(result['lastScan']))

print "DNS:",result['dnsName']

print "MAC Address:",result['macAddress']

print "NetBIOS:",result['netbiosName']

print "OS:",result['os'].rstrip('\\n')

print "Repository ID:",result['repositoryID']

print "Repository Name:",result['repositoryName']

print "Score:",result['score']

print "Critical Vulns:",result['severityCritical']

print "High Vulns:",result['severityHigh']

print "Medium Vulns:",result['severityMedium']

print "Low Vulns:",result['severityLow']

else:

print "IP " + ip + " not found"

# Logout

data = {"module": "auth", "action": "logout", "token": token}



68

else:

print("Error " + str(result["error_code"]) + ": %s" %

(result["error_msg"]))

SAMPLE OUTPUT

SC4 Login Successful


IP Addr: 192.168.111.1

Last Scanned: Tue Jul 20 12:22:02 2010

DNS: host.target.tenablesecurity.com

MAC Address:

NetBIOS: WORKGROUP\host

OS: Microsoft Windows Server 2003 Service Pack 2

Repository ID: 1

Repository Name: Rep1

Score: 1324

Critical Vulns: 0

High Vulns: 107

Medium Vulns: 40

Low Vulns: 134


69

APPENDIX 3: SAMPLE CREDENTIAL UPDATE PYTHON

SCRIPT

Following is a sample script that authenticates to SecurityCenter 4, enumerates and updates

the chosen Windows/SSH password.

This Python script requires Python 2.6 and greater along with the package

httplib2 from http://code.google.com/p/httplib2.

#!/usr/bin/python

# Simple python script to demonstrate the SC4 API

# Enumerates existing ssh and windows credentials and replaces

# the password of the chosen id

#

# Requires: Python 2.6+ and httplib2 from


# Adjust the Python path to your working environment

import sys

if sys.version_info[0:3] < (2, 6):

print 'This script does not work with this version of

Python (%d.%d.%d)' % sys.version_info[0:3]

print 'Python 2.6 or later includes a json module, otherwise

you need to install simplejson'

sys.exit()

import httplib2, urllib, json, pprint, getpass, string, time

def usage():

print "Usage: python26 credentials.py or ./credentials.py"

sys.exit(1)

if len(sys.argv) != 1:

usage()

user = 'orghead'

passwd = 'password'

url = 'https://localhost/sc4/request.php'

def SendRequest(url, headers, data):

http = httplib2.Http(disable_ssl_certificate_validation=True)

response, content = http.request(url, 'POST', headers=headers,

body=urllib.urlencode(data))

if 'set-cookie' in response:

headers['Cookie'] = response['set-cookie']

return response, content

headers = {"Content-type": "application/x-www-form-urlencoded"}

input = {'password': passwd,

'username': user}



70

# Convert input to JSON



"module": "auth",

"action": "login",

"input": inputjson}

# Send Login Request


# Decode JSON to python data structure

result = json.loads(content)

if result["error_code"] == 0:

print "SC4 Login Successful"

token = result['response']['token']

print "Session Token:",token

# Query existing Credentials


"module": "credential",

"action": "init",

"token": token}


resultd = json.loads(content)

print "\nAvailable System Credentials:"

print "ID\t\tName\t\tUsername\tType\t\tModifiedTime"

ids = []

for result in resultd['response']['credentials']:

fmt = '{0:16}{1:16}{2:16}{3:16}{4:16}'

print fmt.format(result['id'], result['name'],

result['username'],result['type'],

time.ctime(int(result['modifiedTime'])))

ids.append(result['id'])

# Grab the user input

print("Press Control-C to exit\n")

number = 1

while number != -1:

strin = raw_input("Enter the numeric credential ID to modify: ")

if strin in ids:

print "The credential list contains ID#",strin

number = -1

else:

print strin + " is not a valid ID, please try again"

strpw = getpass.getpass('Enter the new password:')

# The code below can be used in case you want to display the password

# raw_input('Press ENTER to show the password..')

# print strpw

# raw_input('Press ENTER to exit..')

# Match the hash - windows or ssh credential

for result in resultd['response']['credentials']:


71

if result['id'] == strin:

if result['type'] == 'windows':

# Update the credential

input = {"type":result['type'],

"id":result['id'],

"name":result['name'],

"visibility":result['visibility'],

"password":strpw,

"username":result['username'],

"domain":result['domain'],

"description":result['description'],

"group":result['group']}

elif result['type'] == 'ssh':

# These values may or may not be null

if result['passphrase'] is not None:

pp = result['passphrase']

else:

pp = ""

if result['privilegeEscalation'] is not None:

pe = result['privilegeEscalation']

else:

pe = ""

if result['privateKey'] is not None:

prikey = result['privateKey']

else:

prikey = ""

if result['publicKey'] is not None:

pubkey = result['publicKey']

else:

pubkey = ""

if result['escalationUsername'] is not None:

eu = result['escalationUsername']

else:

eu = ""

if result['escalationPassword'] is not None:

ep = result['escalationPassword']

else:

ep = ""

input = {"type":result['type'],

"id":result['id'],

"name":result['name'],

"visibility":result['visibility'],

"password":strpw,

"username":result['username'],

"description":result['description'],

"group":result['group'],

"passphrase":pp,

"privilegeEscalation":pe,

"privateKey":prikey,

"publicKey":pubkey,

"escalationUsername":eu,

"escalationPassword":ep}

else:

print "Unsupported credential."




72

"module": "credential",

"action": "edit",

"input": inputjson,

"token": token}

# Send the updated credential data to the server


resultu = json.loads(content)

if resultu["error_code"] == 0:

print "Password updated successfully!"

else:

print("Error " + str(resultu['error_code']) + ": %s" %

(resultu['error_msg']))

SAMPLE OUTPUT

SC4 Login Successful


Available System Credentials:

ID Name Username Type ModifiedTime

1000001 sa admin windows Fri Nov 12 14:08:13

2010

1000002 qu admin windows Fri Nov 12 13:58:41

2010

1000003 am admin windows Tue Nov 9 10:06:44

2010

1000005 pal paul ssh Fri Nov 12 13:04:04

2010

1000006 lce root ssh Fri Nov 12 14:12:04

2010

Press Control-C to exit

Enter the numeric credential ID to modify: 1000003

The credential list contains ID# 1000003

Enter the new password:

Password updated successfully!

SecurityCenterâ€™s JSON API - Tenable Network Security

Documents

Transcript of SecurityCenterâ€™s JSON API - Tenable Network Security