My Nexpose API Guide

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 340

Download
Open PDF In Browser	View PDF

Nexpose
API 1.1 and 1.2 Guide
Product version: 6.0

Contents
Contents

Revision history

About this guide

Document conventions

Other documents and Help

User’s guide
The user’s guide helps you to gather and distribute information about your network assets and
vulnerabilities using the application. It covers the following activities:
l

logging onto the Security Console and familiarizing yourself with the interface

managing dynamic discovery

setting up sites and scans

pairing Scan Engines with the Security Console

running scans manually

viewing asset and vulnerability data

creating remediation tickets

using preset and custom report templates

using report formats

reading and interpreting report data

configuring scan templates

configuring other settings that affect scans and report

For technical support
l

Send an e-mail to support@rapid7.com (Enterprise and Express Editions only).

Click the Support link on the Security Console Web interface.

Go to community.rapid7.com.

For technical support

Architecture and functionality
Understanding the Nexpose architecture will help you make to make the best use of the functions
in the API.
Nexpose is a unified vulnerability solution that scans networks to identify the devices running on
them and to test these devices for vulnerabilities and policy compliance. It analyzes the scan data
and processes it for reports. You can use these reports to help you assess your network security
at various levels of detail and remediate any vulnerabilities quickly.
Vulnerability checks identify security weaknesses in all layers of a network computing
environment, including operating systems, databases, applications, and files. Checks can identify
areas in your infrastructure that may be at risk for an attack and verify patch updates and security
compliance measures.
Nexpose consists of two main components: Scan Engines and a Security Console. One or more
Scan Engines (NSEs) search networks to discover devices and the processes running on them,
such as operating systems, programs, and databases. The Scan Engines then test discovered
assets for vulnerabilities, patches, and other security-related factors. A Security Console collects,
analyzes, and stores the scan data, and it generates reports and vulnerability remediation
procedures. Additionally, the console controls the Scan Engines and provides a Web-accessible
user interface for managing all Nexpose functions.
An organization can deploy Scan Engines within its network or outside its firewall. It also can use
Hosted Scanning Engines that are located in Rapid7 data centers.
The simplest configuration consists of a single Scan Engine and the Security Console on one
host.

Sites
A site is a logical group of assets assembled for a scan by a specific, dedicated Scan Engine. The
grouping principle may be something meaningful to you, such as a common geographic location
or a range of IP addresses. Or, you may organize a site for a specific type of scan.
For example, a company sets up Nexpose in a Boston location. The Global Administrator, whose
logon name is corp_admin wants to scan two sets of assets at different times and with different
scanning parameters. So, he sets up two sites:
BOS_Servers includes Web and database servers.
BOS_Workstations includes the workstations.
The Global Administrator is in charge of scanning both sites.

Architecture and functionality

The initial implementation with two sites

For more information about setting up sites an asset groups, see the user’s guide, which you can
download from the Support page of Help.

Distributed Scan Engines
Distributing multiple Scan Engines promotes fault tolerance and improves scanning performance
while conserving bandwidth. It is a best practice to deploy at least one Scan Engine at each
physical location, where it can scan assets locally. This frees up bandwidth for more remote
connections. Also, installing Scan Engines locally, behind firewalls, removes the need for firewall
rule exceptions.

Agentless operation
Nexpose scans exclusively over the network, using common Windows and UNIX network
protocols to gain access to systems. It does not require agent software to be installed on the
assets targeted for scanning. Agentless architecture lowers the total cost of ownership (TCO)
and avoids potential security and stability issues associated with agents.

Distributed Scan Engines

Asset groups
An asset group is a collection of assets, but unlike a site, it is not defined for scanning. An asset
group typically is assigned to a nonadministrative user, who views scan reports about that group
in order to perform any necessary remediation.
Using the example of the Boston company in the Sites section, the Global Administrator, who has
control of the entire deployment, wants to delegate teams for remediating vulnerabilities on the
Web servers, database servers, and workstations. So, he creates three asset groups.
BOS_Web includes the two Web servers. Two nonadministrative users, Jeff and Dave, who
handle Web server maintenance and troubleshooting at the Boston location, have access to this
group.
BOS_DB includes the two database servers. A nonadministrative user, Pete, who is a database
manager, has access to this group.
BOS_WS includes all workstations. A nonadministrative user, Gary, who troubleshoots the
workstations, has access to this group.

Asset groups

The implementation with three asset groups

For more information about setting up sites an asset groups, see the user’s guide, which you can
download from the Support page of Help.

Security Console
Each Scan Engine is controlled by a Security Console, which can be located anywhere on the
network. The console communicates with the engines via encrypted SSL sessions over a defined
Transmission Control Protocol (TCP) port. Engines talk only to the console, they do not talk to
other engines.
In order to manage scans and view results, users log on to the Security Console interface using a
Web browser over HTTPS (secure encrypted HTTP). The only software required for using the
console is a Web browser.

Security Console

User access control
The Security Console requires users to log on with Nexpose credentials. This authentication
occurs over HTTPS, so it is entirely encrypted. The authentication database is stored in an
encrypted format locally on the console server. Passwords are not stored or transmitted in
plaintext.
Upon logging on, a user sees only information to which he or she has been granted access by a
Global Administrator. A given user can have access to one or more entire sites, one or more
assets within a site, or one or more asset groups. The Global Administrator can control access to
sensitive security information by granting fine-grained, “need-to-know” user permissions.

Scanning
A scan includes one or more of the following phases:
Phase

What the Scan Engine does in this phase

Device discovery

Locates active devices on the network.

Service discovery

Determines the types of services running on devices found to be active on
the network.

Access discovery

Scans active devices to determine configurations, including operating
system, hardware, service and installed software.

Vulnerability
assessment

Scans active devices for known vulnerabilities.

Device (asset) discovery
In device discovery, the first phase of a scan, the Scan Engine maps out the network and locates
the active assets.
The Scan Engine can discover devices using ICMP ECHO requests, or by sending TCP packets
to one or more ports in what is effectively a mini port scan. Systems responding to these packets
are marked as active and will be included in subsequent scan phases.
You may wish to disable device discovery when scanning assets in a DMZ or any other area with
strict protection, such as a firewall that drops blocked packets. When you disable device
discovery, the application uses port scan results found in the discovery phase to determine which
hosts are active. If any ports are found to be open on an asset, the application will mark that asset
“alive.”

Scanning

Service Discovery
In the service discovery phase the Scan Engine maps out the network services running on the
active assets.
You can tune service discovery to enable or disable TCP and User Datagram Protocol (UDP)
port scans. You can specify which ports to scan, including default port lists or all possible ports (1–
65,535). Additionally, you can change the method of TCP port scanning to use full connections,
half-open (SYN) scans, or other variations.
Once the application determines a port to be open, it performs a protocol handshake on that port
to verify the type of service running on it. Doing so allows the application to determine if a service
is running, even if it is not on the expected port. For example, an HTTP server may be running on
port 1234, as opposed to the standard HTTP port 80.
Asset inventory
Once the application knows the network layout with active assets and services, it can perform an
asset inventory to determine the configuration of many system components:
l

operating system type and version (for example, Microsoft Windows XP SP2)

system configuration

hardware type (for example, Cisco 2621)

service type and version (for example, Apache 2.0.54)

service configuration

installed software (for example, Mozilla Firefox 1.0.5)

software configuration

Vulnerability assessment
In the vulnerability assessment phase, the application scans active devices for known
vulnerabilities.
Vulnerability checks cover known vulnerabilities in a broad range of products. The Web spidering
feature can discover vulnerabilities caused by Web application developers. The spider can
search a Web site for common programming errors and backup copies of scripts that may divulge
sensitive information.
You can specify certain vulnerabilities or vulnerability types for discovery. The application
includes default scan templates with predefined vulnerability check settings. You also can
custom-define your own vulnerability checks.

Device (asset) discovery

Reporting
You can create reports based on scan data in PDF, HTML, XML, and plain text formats. The
application also can export data to most database systems or to structured file formats, such as
XML, QualysXML, and CSV.
Configuring a report involves several steps:
l

selecting a report template

specifying sites, asset groups, or assets to include in the report

selecting delivery options, such as e-mail to all authorized users

scheduling when to generate the report

You can use built-in report templates, which include predefined settings for level of technical
data, specific information for certain compliance audits, export format, and other features. See
the user’s guide for sample reports and export formats. You also can create custom report
templates.
Report sections
Each report template consists of sections that include specific types of information. When you
create a custom report, you can choose from a list of sections to generate information exactly
according to your needs. Examples of report sections include Discovered System Information,
Discovered Vulnerabilities, Risk Assessment, and Remediation Plan.
See the user’s guide for a complete list of report sections, including descriptions and visual
samples.

Management and diagnostic functions
You can use the logging and system reporting functions to monitor internal activity and
troubleshoot problems. Additionally, you can configure the application to restart and to obtain
required software updates when necessary.

Reporting

Using the API
The API provides programming access to a subset of the full feature set that is available in the
Security Console Web interface. Your range of API access depends on the user privileges
assigned to your logon credentials.
You may access the API using encrypted Hypertext Transfer Protocol over a Secure Socket
Layer connection. The API supports HTTP 1.0 and 1.1 syntax. For data exchange, you may use
the Extensible Markup Language (XML) as defined by the W3C (http://www.w3.org/TR/RECxml).

Working with two API versions
There are currently two versions of APIs: API v1.1 and Extended API v1.2. They are different in
two major ways.
Each version provides a unique set of functions. However, many functions in each of the APIs
support common categories of operation, such as vulnerability management and reporting. See
the list of functions
Each version is validated with a different method. API v1.1 is validated with DTDs, and Extended
API v1.2 is validated with XML schemas.
API v1.1 functions
The API 1.1 is available in Nexpose 4.0 or later and is broken down into the following functional
categories:
l

Session Management on page 30

Site management on page 32

Scan management on page 43

Device (asset) management on page 64

Asset group management on page 65

Vulnerability management on page 70; additional vulnerability management is covered in the
Extended API v1.2

Vulnerability exception management on page 172

User management functions on page 81

General management and diagnostic functions on page 87

Using the API

Note: The API does not support scan template creation.
The requests made to the API 1.1 are validated with DTDs documented in Section I of this guide.
Extended API v1.2 functions
The Extended API 1.2 provides extended functionality available in Nexpose 4.0 or later and. It is
broken down into the following functional categories:
l

Asset group management on page 65

Scan engine management on page 132

Ticket management on page 148

Vulnerability management on page 164

Vulnerability exception management on page 172

Multi-Tenant users on page 188

Silo Profiles on page 207

Silo Management on page 232

Role Management on page 261

Scan Engine Pool Management on page 313

API 1.1 Session Management is required for all functions, including those for API 1.2.
The requests made to the API 1.2 are validated with the XML schemas provided in the package
Extended_API_XMLSchemas_v1.2.zip. You can download all documentation and schemas
from the Support page in Help.

Sending API requests
You access the API through a URL of the form:
https://:/api/api-version/xml

The client connecting to Nexpose must use HTTPS to engage the console. The client must then
log on with valid credentials. Upon successful logon, Nexpose returns a session ID to the
application. Use the session ID for subsequent requests rather than resubmitting the credentials.
The following is a typical login sequence:

Sending API requests

1. Open an HTTPS connection to the Web console, usually on port 3780.
2. Construct a LoginRequest XML request containing valid credentials.
3. Verify that the Content-type HTTP header is set to “text/xml”.
4. For API 1.1 operations, send the XML request to
https://:/api/1.1/xml using HTTP POST Method.
For API 1.2 operations, send the XML request to
https://:/api/1.2/xml using HTTP POST Method.
5. Parse the returned LoginResponse.
6. If the success attribute is set to 1, extract the session-id attribute for use in subsequent
requests.
7. If the success attribute is set to 0, extract the Failure information and report it.
The session-id is subject to timeout from inactivity regardless of how much work Nexpose is
performing. You can specify the timeout period on the Security Console Configuration page of
the Web interface. See the administrator's guide for details.
All subsequent requests must include the appropriate session-id in their respective request XML
structure. This inclusion will allow the API program to perform actions on behalf of the credentials
specified.
If the API request results in a failure, the response XML document will have the success attribute
set to 0 and the Failure element will be returned. The format of the Failure element is as follows:

LoginRequest sample

LoginResponse

LoginResponse sample

Session Management

Logout
Log off from the Security Console, freeing the session and all related resources.
LogoutRequest DTD

LogoutRequest sample

LogoutResponse DTD

LogoutResponse sample

Logout

Site management
SiteListing
Provide a list of all sites the user is authorized to view or manage.
SiteListingRequest DTD

SiteListingRequest sample

SiteListingResponse DTD

SiteListingResponse example

SiteConfig
Provide the configuration of the site, including its associated assets.

Site management

SiteConfigRequest DTD

SiteConfigRequest sample

SiteConfigResponse DTD

SiteConfig

SiteConfigResponse sample

server1.example.com
server2.example.com
server3.example.com
server4.example.com
server5.example.com

user2@example.com

SiteSave
Save changes to a new or existing site.

SiteConfigResponse sample

SiteSaveRequest DTD
Note: Only enter DNS names in the host element. Do not enter an IP address in that element.
Use the range element for IP address ranges. For a single IP address, use the range element
where the from value is the IP address and the to value is empty.

SiteSave

SiteSaveRequest sample

server1.example.com
server2.example.com
server3.example.com
server4.example.com
server5.example.com

user1@example.com

SiteSave

SiteSaveResponse DTD

SiteSaveResponse sample

SiteDelete
Delete the specified site and all associated scan data.
If you have a scan in progress or a paused scan, you cannot delete the site in which that scan was
initiated. If you send SiteDeleteRequest with a paused or in-progress scan, the application will
return an error response. For more information, see Error responses on page 334.
It is a best practice to send SiteScanHistoryRequest first to determine if any scans are paused or
running. See SiteScanHistory on page 39).
To stop a paused or running scan, send ScanStopRequest. See ScanStop on page 51).
When you are certain that no scans are running or paused, send SiteDeleteRequest.
SiteDeleteRequest DTD

SiteDeleteRequest sample

SiteSaveResponse sample

SiteDeleteResponse DTD

SiteDeleteResponse sample

SiteDeviceListing
Provide a list of all of the assets in a site. If no site-id is specified, then this will return all of the
assets for the Scan Engine, grouped by site-id.
SiteDeviceListingRequest DTD

SiteDeviceListingRequest sample

SiteDeviceListingResponse DTD

SiteDeviceListing

SiteDeviceListingResponse sample

SiteScanHistory
Provide a list of all previous scans of the site.
SiteScanHistoryRequest DTD

SiteScanHistoryRequest sample

SiteScanHistory

SiteScanHistoryResponse DTD

SiteScanHistory

SiteScanHistoryResponse sample

SiteScanHistory

Scan management
This section includes management of Scan Engines.

SiteScan
Scan the specified site.
SiteScanRequest DTD

SiteScanRequest sample

SiteScanResponse DTD

Scan management

SiteScanResponse sample

SiteDevicesScan
Scan a specified subset of site assets.
SiteDevicesScanRequest DTD

SiteDevicesScan

SiteDevicesScanRequest sample

SiteDevicesScan

SiteDevicesScanResponse DTD

SiteDevicesScanResponse sample
Without the AdHocSchedule element in the request:

With the AdHocSchedule element in the request:

SiteDevicesScan

Error responses for SiteDevicesScan
If you are a Global Administrator or a user with SuperUser permissions, and your scan conflicts
with a blackout period, you will see one of the following responses:
If you schedule the scan to start in a blackout period:

The requested scan schedule cannot be saved at this
time. Start time is in a blackout period, use force="true" to
force this scan to run.

If your scheduled duration runs into a blackout period:

The requested scan schedule cannot be saved at this
time. Scan duration running into a blackout period, use
force="true" to force this scan to run.

If you are not a Global Administrator or a user with SuperUser permissions, and your scan
conflicts with a blackout period, you will see one of the following responses:
If you schedule the scan to start in a blackout period:

Not authorized to schedule a scan due to start time in
a blackout period.

If your scheduled duration runs into a blackout period:

Not authorized to schedule a scan due to scan duration
running into a blackout period.

SiteDevicesScan

ScanActivity
Provide a list of current scan activities across all Scan Engines managed by the Security
Console.
ScanActivityRequest DTD

ScanActivityRequest sample

ScanActivity

ScanActivityResponse DTD

ScanActivityResponse sample

ScanPause
Pause a running scan.
ScanPauseRequest DTD

ScanPauseRequest sample

ScanActivityResponse sample

ScanPauseResponse DTD

ScanPauseResponse sample

ScanResume
Resume a running scan.
ScanResumeRequest DTD

-->
session-id CDATA #REQUIRED>
scan-id CDATA #REQUIRED>

ScanResumeRequest sample

ScanResumeResponse DTD

ScanResume

ScanResumeResponse sample

ScanStop
Stop a running scan.
ScanStopRequest DTD

ScanStopRequest sample

ScanStopResponse DTD

ScanStopResponse sample

ScanStatus
Check the current status of a scan.

ScanStop

ScanStatusRequest DTD

-->
session-id CDATA #REQUIRED>
scan-id CDATA #REQUIRED>

ScanStatusRequest sample

ScanStatusResponse DTD

ScanStatusResponse sample

ScanStatistics
Get scan statistics, including node and vulnerability breakdowns.

ScanStatistics

ScanStatisticsRequest DTD

ScanStatisticsRequest sample

ScanStatisticsResponse

ScanStatistics

ScanStatisticsResponse sample

ScanStatistics

EngineListing
Provide a list of all Scan Engines managed by the Security Console.

EngineListing

EngineListingRequest DTD

EngineListingRequest sample

EngineListingResponse DTD

EngineListingResponse sample

EngineActivity
Provide a list of current scan activities for a specific Scan Engine.

EngineActivity

EngineActivityRequest DTD

EngineActivityRequest sample

EngineActivityResponse DTD

EngineActivity

EngineActivityResponse sample

EngineActivity

General management and diagnostic functions
ConsoleCommand
Execute an arbitrary console command that is supplied as text via an API parameter. Console
commands are documented in the administrator's guide and in Help. If you use a command that
is not listed in the in administrator's guide, the application will return the XMLResponse.
ConsoleCommandRequest DTD

ConsoleCommandResponse DTD

Tip: Set a higher timeout value for a command that requires a substantial amount of time to
execute and finish. Doing so ensures that the application has sufficient time to respond to the
command.

SystemInformation
Obtain system data, such as total RAM, free RAM, total disk space, free disk space, CPU speed,
number of CPU cores, and other vital information.

General management and diagnostic functions

SystemInformationRequest DTD

SystemInformationRequest sample

SystemInformationResponse DTD

SystemInformation

SystemInformationResponse sample

2
2660
/opt/rapid7/nexpose=32901904
../shared/temp=32901904
Ubuntu Linux 12.04
170376
8177868
45757264
postgresql
PostgreSQL 9.0.13 on x86_64unknown-linux-gnu, compiled by GCC gcc (GCC) 4.1.2 20080704 (Red
Hat 4.1.2-52), 64-bit
Java HotSpot(TM) 64-Bit Server
VM
6263537664
4829077504
3694844920
2568692744
24.0-b56
CN=NeXpose Security Console,
O=Rapid7
5.12.2
1423140440496
1028948869
44
67
118
4950

StartUpdate
Induce the application to retrieve required updates and restart if necessary.

StartUpdate

StartUpdateRequest DTD

StartUpdateResponse DTD
Set a higher timeout value for a command that requires a substantial amount of time to execute
and finish. Doing so ensures that the application has sufficient time to respond to the command.

Restart
Restart the application.
RestartRequest DTD

RestartRequest sample

restart

Restart

RestartResponse
There is no response to RestartRequest. When the application shuts down as part of the restart
process, it terminates any active connections. Therefore, the application cannot issue a response
when it restarts.

SendLog
Output diagnostic information into log files, zip the files, and encrypt the archive with a PGP public
key that is provided as a parameter for the API call. Then, either e-mail this archive to an address
that is specified as an API parameter, or upload the archive using HTTP or HTTPS to a URL that
is specified as an API parameter.
If you do not specify a key, the SendLogRequest uses a default key.
SendLogRequest DTD

SendLogResponse DTD

SendLog

Device (asset) management
DeviceDelete
Delete the specified asset.
DeviceDeleteRequest DTD

DeviceDeleteRequest sample

DeviceDeleteResponse DTD

DeviceDeleteResponse sample

Device (asset) management

Asset group management
AssetGroupListing
Provide a list of all asset groups the user is authorized to view or manage.
AssetGroupListingRequest DTD

AssetGroupListingRequest sample

AssetGroupListingResponse DTD

AssetGroupListingResponse sample

AssetGroupConfig
Provide the configuration of the asset group, including its associated devices.
AssetGroupConfigRequest DTD

AssetGroupConfigRequest sample

AssetGroupConfigResponse

AssetGroupConfigResponse sample

AssetGroupSave
Save changes to a new or existing static asset group.
AssetGroupSaveRequest API

AssetGroupSave

AssetGroupSaveRequest sample

AssetGroupSave

AssetGroupSaveResponse DTD

AssetGroupDeleteRequest sample

AssetGroupDeleteResponse

AssetGroupDelete

AssetGroupDeleteResponse sample

AssetGroupDelete

Vulnerability management
VulnerabilityListing
Provide a list of vulnerabilities that can be checked.
VulnerabilityListingRequest

Vulnerability management

VulnerabilityListingResponse

VulnerabilityDetails
Provide the full details of a vulnerability, including its description, cross-references, and solution.

VulnerabilityDetails

VulnerabilityDetailsRequest

VulnerabilityDetailsResponse

VulnerabilityDetails

Reporting
ReportTemplateListing
Provide a list of all report templates the user can access on the Security Console.
ReportTemplateListing

ReportTemplateListingResponse

ReportTemplateConfig
Retrieve the configuration for a report template.

Reporting

ReportTemplateConfigRequest

session-id CDATA #REQUIRED>
retrieve the config for -->
template-id CDATA #REQUIRED>

ReportTemplateConfigResponse

ReportTemplateSave
Save the configuration for a report template.
ReportTemplateSaveRequest
If the user attempts to save a report with a scope of “silo” without being logged into a silo, an error
occurs.

ReportTemplateSaveResponse

ReportTemplateSave

ReportListing
Provide a listing of all report definitions the user can access on the Security Console.
ReportListingRequest

ReportListingResponse

ReportHistory
Provide a history of all reports generated with the specified report definition.

ReportListing

ReportHistoryRequest

ReportHistoryResponse

ReportConfig
Retrieve the configuration for a report definition.
ReportConfigRequest

ReportConfigResponse

ReportConfig

ReportSave
Save the configuration for a report definition.
ReportSaveRequest

ReportSaveResponse

ReportGenerate
Generate a new report using the specified report definition.
ReportGenerateRequest

ReportSave

ReportGenerateResponse

ReportDelete
Delete a previously generated report or report definition.
ReportDeleteRequest

ReportDeleteResponse

ReportAdhocGenerate
Generate a report once using a simple configuration, and send it back in a multi-part mime
response.

ReportDelete

ReportAdhocGenerateRequest

ReportAdhocGenerate

ReportAdhocGenerateResponse
Response to ReportAdhocGenerateRequest is a Multipart Mime message where the first part is
'response_xml' which contains the following xml element:

The rest of the parts of the multipart mime contain the actual report files depending upon how
many files are there. All these files are encoded using the base64 format.

ReportAdhocGenerate

User management functions
Only Global Administrators can use these functions.

UserListing
Provide a list of user accounts and information about those accounts.
UserListingRequest DTD

UserListingRequest sample

UserListingResponse DTD

User management functions

UserListingResponse sample

UserAuthenticatorListing
Provide a list of user authentication sources.
UserAuthenticatorListingRequest DTD

UserAuthenticatorListingRequest sample

UserAuthenticatorListing

UserAuthenticatorListingResponse DTD

UserAuthenticatorListingResponse sample

UserConfig
List information about a given user account.
DTD

UserConfigRequest sample

UserConfig

UserConfigResponse DTD

UserConfigResponse sample

UserSave
Create a new user account, or update the settings for an existing account. Note that specifying a
UserConfig with an id of -1 indicates a create request.UserSaveRequest
It is not possible to create user accounts with custom roles, but it is possible to query these
accounts with UserListing or UserConfig.
You cannot change the user name after you create an account. Therefore, the user name that
you specify in the update request must be the current user name.
UserSaveRequest DTD

UserSave

UserSaveRequest sample

UserSaveResponse

UserSaveResponse sample

UserDelete
Delete a user account. Note that you cannot delete a user account that is associated with reports
or tickets.
UserDeleteRequest DTD

UserDeleteRequest sample

UserDelete

UserDeleteResponse DTD
Note: You cannot delete your own user account.

UserDeleteResponse sample

UserDelete

ConsoleCommandResponse DTD

Tip: Set a higher timeout value for a command that requires a substantial amount of time to
execute and finish. Doing so ensures that the application has sufficient time to respond to the
command.

SystemInformation
Obtain system data, such as total RAM, free RAM, total disk space, free disk space, CPU speed,
number of CPU cores, and other vital information.

General management and diagnostic functions

SystemInformationRequest DTD

SystemInformationRequest sample

SystemInformationResponse DTD

SystemInformation

SystemInformationResponse sample

StartUpdate
Induce the application to retrieve required updates and restart if necessary.

StartUpdate

StartUpdateRequest DTD

Restart
Restart the application.
RestartRequest DTD

RestartRequest sample

restart

Restart

SendLogResponse DTD

SendLog

DTD listings
This section includes DTDs for validating the API calls listed throughout this document.

Device DTD

SiteSummary DTD

Site DTD
This DTD continues on the following three pages.

DTD listings

Note: Only enter DNS names in the host element. Do not enter an IP address in that element.
Use the range element for IP address ranges. For a single IP address, use the range element
where the from value is the IP address and the to value is empty.

Site DTD

Field checked CDATA #IMPLIED>
using ssh-key, this represents the PEM-format keypair

information -->

Site DTD

AssetGroupSummary DTD

AssetGroup DTD

EngineSummary DTD
Prior to the release dated October 15, 2008, EngineSummaryResponse always returned
“unknown” for EngineStatus values. As of October 15, 2008, the EngineSummaryResponse may
return a value other than “unknown.”

EngineSummary DTD

ScanConfig DTD

100

Examples of a scan schedules
The following schedule runs at 1:35 a.m. on the second Wednesday of every month, starting on
the following April. If the scan exceeds the maximum duration of 60 minutes, it restarts from the
beginning.

The following schedule runs weekly on Mondays, starting at 8 p.m.

The following schedule starts at 8 p.m. on the 18th day of the current month.

ScanConfig DTD

101

ScanSummary DTD

102

ReportTemplateSummary DTD

103

ReportTemplate DTD

104

ReportConfigSummary DTD

105

ReportConfig DTD

106

ReportConfig DTD

107

ReportConfig DTD

108

Email DTD
The sendAs and sendToAclAs attributes are optional, but one of them is required for sending
reports via e-mail. The sendAs attribute is required for sending e-mails to users who are not on
the report access list. The sendToAcl attribute is required for sending e-mails to report access list
members.
E-mails and attachments are sent via the Internet in cleartext and are not encrypted. If you do not
set a valid value for either attribute, the application will save the report but not send it via e-mail. If
you set a valid value for the sendAs attribute but not for the sendToAclAs attribute, the application
will send the report via e-mail to non-access-list members only. If you set a valid value for the
sendToAclAs attribute, the application will send the report via e-mail to access-list members only.
If you set a valid value for both attributes, the application will send reports via e-mail to access-list
members and non-members.

Email DTD

109

ReportSummary DTD

110

UserConfig DTD
The current version of the API does not support creating user accounts with custom roles. You
can only create user accounts with preset roles.
If values for allSites and allGroups are false or not specified, you can specify sites and groups
using nested site and group elements.
You cannot change the user name after you create an account.

UserConfig DTD

111

User Site DTD

User Group DTD

UserSummary DTD

User Site DTD

112

AuthenticatorSummary DTD

XMLResponse DTD
This DTD provides the structure for the API response to a call for a non-existent API function.

AuthenticatorSummary DTD

113

Failure DTD

My Nexpose API Guide

Navigation menu

Versions of this User Manual:

Views

Navigation