Repository REST Reference

/repository

Methods
GET

Gets the list of Repositories.

NOTE: The field 'transfer' will only be returned if the type is "remote", running is "true", and the field is requested

Fields Parameter
 Expand

The fields parameter should be specified along the query string, and it takes the syntax

    ?fields=<field>,.

NOTE: 'typeFields' returns type-specific parameters inside of a 'typeFields." If requested, typeFields returns as follows:

dataFormat "mobile": mobileSchedule, preferences, scanner, mdm, mdmType, deviceCount, status, errorDetails
dataFormat "IPv6" | "IPv4": nessusSchedule, correlation, ipRange, ipCount, runningNessus, lastGenerateNessusTime, lastTrendUpdate, trendingDays, trendWithRaw

Allowed Fields

*id
**name
**description
type
dataFormat
vulnCount
remoteID
remoteIP
running
downloadFormat
lastSyncTime
lastVulnUpdate
createdTime
modifiedTime
transfer
typeFields 
remoteSchedule

Session User role "1" (Administrator)

organizations

Legend

* = always comes back

** = comes back if fields list not specified on GET all
Request Parameters
 Expand

Parameters must be passed in as query string (as opposed to JSON) in the format of: /repository?type=All&...

{
	"type" : <string> "All" | "Local" | "Remote" | "Offline" DEFAULT "All",
}
Expand Parameters

mdm (only applies to Mobile repositories. 'typeFields' must be requested)

Example Response
 Expand
{
	"type" : "regular",
	"response" : [
		{
			"id" : "37",
			"name" : "ag repo1",
			"description" : "Copied from QA"
		},
		{
			"id" : "38",
			"name" : "jm ipv4",
			"description" : "copied from QA"
		},
		{
			"id" : "39",
			"name" : "ipv6 rep",
			"description" : "Copied from QA (name changed)"
		},
		{
			"id" : "43",
			"name" : "Test Local mobile Repository",
			"description" : "DevForm test of mobile repository post"
		},
		{
			"id" : "44",
			"name" : "Test w\/pluginPrefs",
			"description" : ""
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1423767348
}

POST

Adds a Repository.

Request Parameters
 Expand

NOTE: The downloadFormat version number doesn't necessarily correlate directly to the version number for 'mobile' Repositories. As it is defaulted to the correct value, this parameter should not be passed.
TODO: We should validate schedule types not useful for Repositories (template, dependent, etc)

{
	"name" : <string>,
	"description" : <string> DEFAULT "",
	"dataFormat" : <string> "IPv4" | "IPv6" | "mobile",
	"type" : <string> "Local" | "Remote" | "Offline",
	"downloadFormat" : <string> "v2" DEFAULT "v2" (see Note),
	"organizations" : [
        {
            "id" : <number>,
            "groupAssign" : <string> "all" | "fullAccess" | "partial" | "" DEFAULT ""
        }...
	] OPTIONAL,
	...
}
dataFormat "IPv4" | "IPv6"
...
	"ipRange" : <string> (valid IP format based on IP version),
	"trendingDays" : <number> (Positive integer no greater than "365"),
	"trendWithRaw" : <string> "false" | "true",
	"nessusSchedule" : {
		"type" : <string> "dependent" | "ical" | "never" | "rollover" | "template" DEFAULT "never"
 
		type "ical"
		-----------
		"start" : <string> (This value takes the iCal format),
		"repeatRule" : <string> (This value takes the repeat rule format)
	}
 
	type "Local"
	------------
	"correlation" : [
		{
			"id" : <number>
		}...
	] DEFAULT [],
...

dataFormat "mobile"

NOTE #1: For Front-end, the valid preference names and types may be retrieved by looking at the editor block from  /mdm/<id>::GET. For Back-end, the idMapper.php file is utilized.
NOTE #2: 'preferences' are handled in the same manner as preferences for plugins. Particularly, if the preference name passed does not exist, the entry is ignored.

...
	"mdm" : {
		"id" : <string>
	}
	type "Local"
	------------
	"scanner" : {
		"id" : <number>
	},
	"mobileSchedule" : {
		"type" : "type" : <string> "dependent" | "ical" | "never" | "rollover" | "template" DEFAULT "never"


		type "ical"
		-----------
		"start" : <string> (This value takes the iCal format),
		"repeatRule" : <string> (This value takes the repeat rule format)
	},
	"preferences" : [
		<string:name>:<string:value>...
	] DEFAULT []
...

type "Remote"

...
	"remoteID" : <number>,
	"remoteIP" : <string> (valid remote SC IP),
	"remoteSchedule" : {
        "type" : "type" : <string> "dependent" | "ical" | "never" | "rollover" | "template" DEFAULT "never"
 
 
        type "ical"
        -----------
        "start" : <string> (This value takes the iCal format),
        "repeatRule" : <string> (This value takes the repeat rule format)
	}
...
Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"id" : "37",
		"name" : "ag repo1",
		"description" : "Copied",
		"type" : "Local",
		"dataFormat" : "IPv4",
		"remoteID" : null,
		"remoteIP" : null,
		"running" : "false",
		"downloadFormat" : "v2",
		"lastSyncTime" : "0",
		"createdTime" : "1422396357",
		"modifiedTime" : "1422396357",
		"organizations" : [
			{
				"id" : "8",
				"groupAssign" : "fullAccess",
				"name" : "Org",
				"description" : "Testing for Policies with New Schema"
			}
		],
		"typeFields" : {
			"lastVulnUpdate" : 1423718403,
			"vulnCount" : 0,
			"nessusSchedule" : {
				"type" : "never",
				"start" : "",
				"repeatRule" : ""
			},
			"correlation" : [],
			"ipRange" : "192.168.0.0\/24",
			"ipCount" : "0",
			"runningNessus" : "false",
			"lastGenerateNessusTime" : "0",
			"trendingDays" : "0",
			"trendWithRaw" : "true"
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1423767366
}

/repository/{id}

Methods
GET

Gets the Repository associated with {id}.

NOTE: The field 'transfer' will only be returned if the type is "remote", running is "true", and the field is requested

Fields Parameter
 Expand

The fields parameter should be specified along the query string, and it takes the syntax

    ?fields=<field>,...

NOTE: 'typeFields' returns type-specific parameters inside of a 'typeFields." If requested, typeFields returns as follows:

dataFormat "mobile": mobileSchedule, preferences, scanner, mdm, mdmType, deviceCount, status, errorDetails
dataFormat "IPv6" | "IPv4": nessusSchedule, correlation, ipRange, ipCount, runningNessus, lastGenerateNessusTime, lastTrendUpdate, trendingDays, trendWithRaw

Allowed Fields

*id
**name
**description
type
dataFormat
vulnCount
remoteID
remoteIP
running
downloadFormat
lastSyncTime
lastVulnUpdate
createdTime
modifiedTime
transfer
typeFields 
remoteSchedule

Session User role "1" (Administrator)

organizations

Legend

* = always comes back

** = comes back if fields list not specified on GET all
Request Parameters

None

Expand Parameters

mdm (only applies to Mobile repositories. 'typeFields' must be requested)

Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"id" : "37",
		"name" : "ag repo1",
		"description" : "Copied",
		"type" : "Local",
		"dataFormat" : "IPv4",
		"remoteID" : null,
		"remoteIP" : null,
		"running" : "false",
		"downloadFormat" : "v2",
		"lastSyncTime" : "0",
		"createdTime" : "1422396357",
		"modifiedTime" : "1422396357",
		"organizations" : [
			{
				"id" : "8",
				"groupAssign" : "fullAccess",
				"name" : "Org",
				"description" : "Testing for Policies with New Schema"
			}
		],
		"typeFields" : {
			"lastVulnUpdate" : 1423718403,
			"vulnCount" : 0,
			"nessusSchedule" : {
				"type" : "never",
				"start" : "",
				"repeatRule" : ""
			},
			"correlation" : [],
			"ipRange" : "192.168.0.0\/24",
			"ipCount" : "0",
			"runningNessus" : "false",
			"lastGenerateNessusTime" : "0",
			"trendingDays" : "0",
			"trendWithRaw" : "true"
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1423767366
}

PATCH

Edits the Repository associated with {id}, changing only the passed in fields.

NOTE: Parameters 'type', 'dataFormat', and 'mdm' may not be modified on PATCH.

Request Parameters

(All fields are optional)

Example Response

DELETE

Deletes the Repository associated with {id}, depending on access and permissions.

Request Parameters

None

Example Response
 Expand
{
	"type" : "regular",
	"response" : "",
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1401911117
}

/repository/{id}/acceptRiskRule

Methods

GET

Gets the list of Accept Risk Rules in the Repository associated with {id}, unless filters are provided.

Fields Parameter
 Expand

The fields parameter should be specified along the query string, and it takes the syntax

    ?fields=<field>,...

Allowed Fields

*id
**repository
**organization
**user
**plugin
**hostType
**hostValue
**port
**protocol
**expires
**status
comments
createdTime
modifiedTime

Legend

* = always comes back
** = comes back if fields list not specified on GET all

Filters
 Expand
pluginID=<number> | <string> "all" DEFAULT "all" (i.e. all Plugins)
port=<number> | <string> "all" DEFAULT "all" (i.e. all Ports)

Session User is role "1" (administrator)

organizationIDs=<number>,... | <string> "all" DEFAULT "all" (i.e. all Organizations)

Session User is not role "1" (administrator)

organizationIDs=<number>,... | <string> "all" DEFAULT :sessionOrgID:
Example Response
 Expand
 {
	"type" : "regular",
	"response" : [
		{
			"id" : "3",
			"hostType" : "all",
			"hostValue" : "",
			"port" : "any",
			"protocol" : "any",
			"expires" : "-1",
			"status" : "0",
			"repository" : {
				"id" : "17",
				"name" : "New Fields Repo",
				"description" : ""
			},
			"organization" : {
				"id" : "8",
				"name" : "Org",
				"description" : "Testing for Policies with New Schema"
			},
			"user" : {
				"id" : "1",
				"username" : "head",
				"firstname" : "Security Manager",
				"lastname" : ""
			},
			"plugin" : {
				"id" : "0",
				"name" : "Open Port",
				"description" : ""
			}
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1410275054
}

/repository/{id}/recastRiskRule

Methods

GET

Gets the list of Recast Risk Rules in the Repository associated with {id}, unless filters are provided.

Fields Parameter
 Expand

The fields parameter should be specified along the query string, and it takes the syntax

    ?fields=<field>,...

Allowed Fields

*id
**repository
**organization
**user
**plugin
**newSeverity
**hostType
**hostValue
**port
**protocol
**order
**status
comments
createdTime
modifiedTime

Legend

* = always comes back
** = comes back if fields list not specified on GET all

Filters
 Expand
pluginID=<number> | <string> "all" DEFAULT "all" (i.e. all Plugins)
port=<number> | <string> "all" DEFAULT "all" (i.e. all Ports)

Session User is role "1" (administrator)

organizationIDs=<number>,... | <string> "all" DEFAULT "all" (i.e. all Organizations)

Session User is not role "1" (administrator)

organizationIDs=<number>,... | <string> "all" DEFAULT :sessionOrgID:
Example Response
 Expand
{
	"type" : "regular",
	"response" : [
		{
			"id" : "1",
			"newSeverity" : "0",
			"hostType" : "all",
			"hostValue" : "",
			"port" : "any",
			"protocol" : "any",
			"order" : "1",
			"status" : "0",
			"repository" : {
				"id" : "18",
				"name" : "New Rep 1",
				"description" : ""
			},
			"organization" : {
				"id" : "8",
				"name" : "Org",
				"description" : "Testing for Policies with New Schema"
			},
			"user" : {
				"id" : "1",
				"username" : "head",
				"firstname" : "Security Manager",
				"lastname" : ""
			},
			"plugin" : {
				"id" : "0",
				"name" : "Open Port",
				"description" : ""
			}
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1410281615
}

/repository/{id}/assetIntersections

GET

Gets the ip intersections of an Asset.
NOTE: The number of assets should be limited. Intersecting large numbers of assets may be cause long delays, so pagination should be used in F/E

Request Parameters
 Expand

Parameters must be passed in as query string (as opposed to JSON) in the format of: /assetIntersections?ip="1.1.1.1"&dnsName="foo"

{
	"ip" : <string> (valid IP),
	"dnsName" : <string> OPTIONAL
}
Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"assets" : []
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1409924685
}

/repository/{id}/import

The /repository/import resource.

POST

Starts an on-demand, import for the Repository associated with {id}. The data is specified by a previously uploaded, gzipped tarball of Repository data obtained using /repository/{id}/export.

NOTE: The file field should contain the value of the same parameter passed back on */file/upload::POST*.

Request Parameters
 Expand
{
	"file" : <string>
}
Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"objectID" : "100",
		"objectType" : "importRepository",
		"type" : "now",
		"ownerID" : "1"
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1402950576
}

/repository/{id}/export

The /repository/export resource.

GET

Exports the Repository associated with {id} as a gzipped tar file.

Request Parameters

None

Example Response

None given. The response will be a gzipped file containing a tarball of the Repository files.

The tarball will contain the following contents:

  • A Hostname.txt file corresponding to the SecurityCenter from which the repository was exported. This value is populated by the hostname field from the SC License Configuration.
  • The license.key file of the SecurityCenter from which the repository was exported.
  • An sc.version.txt file with the version, data format, and mdm type on consecutive lines, respectively.
  • The binary files corresponding to the Repository's current data.
  • A VDB directory containing binary files for the Repository's trending data (if applicable).

/repository/{id}/sync

The /repository/sync resource.

POST

Starts an on-demand synchronization of local data for the remote Repository associated with {id}.

Request Parameters

None

Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"objectID" : "107",
		"objectType" : "repositorySynchronizationClient",
		"type" : "now",
		"definition" : {
			"action" : "download",
			"token" : "1039771703"
		},
		"ownerID" : "1"
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1402947699
}

/repository/{id}/generateNessus

The /repository/generateNessus resource.

POST

Starts an on-demand process to generate a gzipped Nessus V2 file of the Repository associated with {id}. This command is required prior to calling /repository/{id}/download.

Request Parameters

None

Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"id" : "109"
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1402942558
}

/repository/{id}/updateMobileData

The /repository/updateMobileData resource.

POST

Starts an on-demand process to update the mobile data for the Repository associated with {id}. This is considered a mobile scan process by SecurityCenter.

Request Parameters

None

Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"id" : "156"
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1402942558
}

/repository/{id}/ipInfo

GET

Gets the IP Info for the Repository associated with {id}.

Fields Parameter
 Expand

The fields parameter should be specified along the query string, and it takes the syntax

    ?fields=<field>,...

Allowed Fields

*ip
*repositoryID
repository
score
total
severityInfo
severityLow
severityMedium
severityHigh
severityCritical
macAddress
policyName
pluginSet
netbiosName
dnsName
osCPE
biosGUID
tpmID
mcafeeGUID
lastAuthRun
lastUnauthRun
severityAll
os
hasPassive
hasCompliance
lastScan
links

Legend

* = always comes back

Request Parameters
 Expand

Parameters must be passed in as query string (as opposed to JSON) in the format of: /ipInfo?ip="1.1.1.1"&dnsName="foo"

{
	"ip" : <string> (valid ip address),
	"dnsName" : <string> OPTIONAL
}
Example Response
 Expand
{
	"type" : "regular",
	"response" : {
		"ip" : "192.168.1.145",
		"repositoryID" : "2",
		"score" : "2130",
		"total" : "322",
		"severityInfo" : "110",
		"severityLow" : "7",
		"severityMedium" : "41",
		"severityHigh" : "152",
		"severityCritical" : "12",
		"macAddress" : "00:00:00:00:00:00",
		"policyName" : "",
		"pluginSet" : "",
		"netbiosName" : "TARGET\\WIN7X64",
		"dnsName" : "target.domain.com",
		"osCPE" : "cpe:\/o:microsoft:windows_7: :gold:x64-ultimate",
		"biosGUID" : "",
		"tpmID" : "",
		"mcafeeGUID" : "",
		"lastAuthRun" : "",
		"lastUnauthRun" : "",
		"severityAll" : "12,152,41,7,110",
		"os" : "Microsoft Windows 7 Ultimate",
		"hasPassive" : "No",
		"hasCompliance" : "No",
		"lastScan" : "1408294249",
		"links" : [
			{
				"name" : "SANS",
				"link" : "https : \/\/isc.sans.edu\/ipinfo.html?ip=192.168.1.145"
			},
			{
				"name" : "ARIN",
				"link" : "http : \/\/whois.arin.net\/rest\/ip\/192.168.1.145"
			}
		],
		"repository" : {
			"id" : "2",
			"name" : "Rep2",
			"description" : ""
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1409855674
}

/repository/{id}/download

The /repository/download resource.

POST

Deletes the Repository associated with {id}.

NOTE: The /repository/{id}/generateNessus command should be used to generate a snapshot of the repository for download. An error code of 163 (RESPONSE_NO_PERMISSIONS) will occur if no file has ever been generated, while a stale snapshot will silently produce 0 (SUCCESS).

Request Parameters
 Expand
{
	"format" : <string> "v2" DEFAULT "v2"
} 
Example Response

None given. The response will be a gzipped file containing the Repository encoded in the Nessus V2 format.

/repository/authorize

POST

Authorizes communication with the remote machine associated with the provided host ip.

Request Parameters
 Expand
{
	"host" : <string>,
	"username" : <string>,
	"password" : <string>
} 
Example Response
 Expand
{
	"type" : "regular",
	"response" : "",
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1402939540
}

/repository/fetchRemote

The /repository/download resource.

GET

Gets a list of Repositories at the specified location.

NOTE: The /sshKey/installRemoteKey command may need to be used to gain access to the list of repositories at the remote host if it has not been done so previously. An error code of 63 (RESPONSE_DENIED) will indicate if such a request is required.

Request Parameters
 Expand

Parameters must be passed in as query string (as opposed to JSON) in the format of: /repository/fetchRemote/?host=172.26.X.X

{
	"host" : <string>
} 
Example Response
 Expand
{
	"type" : "regular",
	"response" : [
		{
			"id" : "1",
			"name" : "qarep_ipv4",
			"description" : "",
			"type" : "Local",
			"dataFormat" : "IPv4",
			"vulnCount" : 13352,
			"remoteID" : null,
			"remoteIP" : null,
			"running" : "false",
			"enableTrending" : "true",
			"downloadFormat" : "v2",
			"lastSyncTime" : "0",
			"lastVulnUpdate" : 1402938930,
			"createdTime" : "1357331461",
			"modifiedTime" : "1357569012",
			"organizations" : [
				{
					"id" : "1",
					"groupAssign" : "all"
				},
				{
					"id" : "2",
					"groupAssign" : "all"
				}
			],
			"correlation" : [],
			"ipRange" : "192.168.1.145\/22,192.168.1.145-192.168.1.146,192.168.1.146\/22",
			"ipCount" : "80",
			"runningNessus" : "false",
			"lastGenerateNessusTime" : "1402272018",
			"size" : 41586909
		},
		{
			"id" : "2",
			"name" : "qarep_pvs_ipv4_3601",
			"description" : "",
			"type" : "Local",
			"dataFormat" : "IPv4",
			"vulnCount" : 0,
			"remoteID" : null,
			"remoteIP" : null,
			"running" : "false",
			"enableTrending" : "true",
			"downloadFormat" : "v2",
			"lastSyncTime" : "0",
			"lastVulnUpdate" : 1402892411,
			"createdTime" : "1357568971",
			"modifiedTime" : "1357744461",
			"organizations" : [
				{
					"id" : "1",
					"groupAssign" : "partial"
				}
			],
			"correlation" : [],
			"ipRange" : "192.168.0.0\/24",
			"ipCount" : "0",
			"runningNessus" : "false",
			"lastGenerateNessusTime" : "1402533002",
			"size" : 0
		},
		{
			"id" : "3",
			"name" : "qarep_pvs_ipv4",
			"description" : "",
			"type" : "Local",
			"dataFormat" : "IPv4",
			"vulnCount" : 0,
			"remoteID" : null,
			"remoteIP" : null,
			"running" : "false",
			"enableTrending" : "true",
			"downloadFormat" : "v2",
			"lastSyncTime" : "0",
			"lastVulnUpdate" : 1402938928,
			"createdTime" : "1357592482",
			"modifiedTime" : "1392317291",
			"organizations" : [
				{
					"id" : "1",
					"groupAssign" : "all"
				},
				{
					"id" : "2",
					"groupAssign" : "all"
				}
			],
			"correlation" : [],
			"ipRange" : "192.168.0.0\/24",
			"ipCount" : "0",
			"runningNessus" : "false",
			"lastGenerateNessusTime" : "1402891203",
			"size" : 40
		},
		{
			"id" : "4",
			"name" : "qarep_lce",
			"description" : "",
			"type" : "Local",
			"dataFormat" : "IPv4",
			"vulnCount" : 4350,
			"remoteID" : null,
			"remoteIP" : null,
			"running" : "false",
			"enableTrending" : "false",
			"downloadFormat" : "v1",
			"lastSyncTime" : "0",
			"lastVulnUpdate" : 1402939008,
			"createdTime" : "1357744413",
			"modifiedTime" : "1357744413",
			"organizations" : [
				{
					"id" : "1",
					"groupAssign" : "partial"
				},
				{
					"id" : "2",
					"groupAssign" : "all"
				}
			],
			"correlation" : [],
			"ipRange" : "192.168.0.0\/24",
			"ipCount" : "20",
			"runningNessus" : "false",
			"lastGenerateNessusTime" : "0",
			"size" : 1413684
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1402939540
}

Expand Items: details, shares

  • details

    • Show specific details (such as vulnerability count, nessus schedule information, etc.)
  • shares

    • Show the organizations granted access to the Repository.