[PLUG-Devel] Rapid7 NeXpose API Development Guide - Script Your NeXpose Code Scanning with msfconsole Automation for Proof of Concept Exploit - Easily Build Your Own API

Wed Feb 2 21:02:06 MST 2011

On the heels of Steve Kaplan's Hackfest presentation of a Rapid7 evaluation
licensed Nexpose Application Scanner install, [which allows for actual point
and click escalation/exploit of targeted vulnerability signatures (which are
updated upon initialization of Nexpose and match those available in
Metasploit) discovered (via point and click (provided you have loaded the
correct modules, and payload, similar to Metasploit)] we would like to
*showcase
for you Ladies and Gents, the Developer API Guide.*  *

FAST and EASY - NO Rapid7 License key NEEDED!*

While Metasploit has automation for mfsconsole via resource files that
provide all the "command line typed" basic elements required to be matched
for any "service" as part of the exploit pentest.

$ *./msfconsole -r documentation/msfconsole_rc_ruby_example.rc*
                _                  _       _ _
               | |                | |     (_) |
 _ __ ___   ___| |_ __ _ ___ _ __ | | ___  _| |_
| '_ ` _ \ / _ \ __/ _` / __| '_ \| |/ _ \| | __|
| | | | | |  __/ || (_| \__ \ |_) | | (_) | | |_
|_| |_| |_|\___|\__\__,_|___/ .__/|_|\___/|_|\__|
                            | |
                            |_|

       =[ metasploit v3.3.4-dev [core:3.3 api:1.0]
+ -- --=[ 542 exploits - 295 auxiliary
+ -- --=[ 198 payloads - 23 encoders - 8 nops
       =[ svn r8873 updated today (2010.03.22)

resource (documentation/msfconsole_rc_ruby_example.rc)> use
exploit/multi/handler
resource (documentation/msfconsole_rc_ruby_example.rc)> set PAYLOAD
windows/meterpreter/reverse_tcp
resource (documentation/msfconsole_rc_ruby_example.rc)> set LPORT 4444
resource (documentation/msfconsole_rc_ruby_example.rc)> set LHOST 192.168.0.228
resource (documentation/msfconsole_rc_ruby_example.rc)> set ExitOnSession false

While some 3.500 possibilities are available, generally our application is
only going using a limited number of these, which can be preconfigured and
called after the scan process using the NeXpose (Free Community Edition) API
via an application that sends and receives XML messages to and from the
NeXpose Security Console. There are no restrictions on which language you
use to write this program, except that the language needs libraries or
routines to send POST requests over HTTPS. The API does not support requests
over HTTP.

It is helpful if your client language has a library or routines to support
XML processing, since all messages sent to and received from NeXpose are XML
messages.

You access the API through a URL of the form:
https://<host>:3780/api/api-version/xml

The application connecting to NeXpose must use HTTPS to engage the console.
The application must then log on with valid NeXpose 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:

1. Open an HTTPS connection to the Web console, usually on port 3780.
2. Construct a LoginRequest XML request containing valid NeXpose
credentials.
3. Verify that the Content-type HTTP header is set to "text/xml".
4. Send the XML request to https://ncs:3780/api/1.1/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
NeXpose Security Console Configuration page of the Web interface. See the
NeXpose 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:  <!ELEMENT Failure
((message|Exception)*)> 
<!ELEMENT message (#PCDATA)>  <!ATTLIST message source CDATA #IMPLIED>
 <!ATTLIST message code CDATA
#IMPLIED>  <!ELEMENT Exception
(message, stacktrace?)>  <!ATTLIST Exception name CDATA #IMPLIED> <!ELEMENT
stacktrace (#PCDATA)>

As the success and failure information is stored within the returned XML
document, all requests processed by the NeXpose API will return HTTP status
code 200. Any other status code implies a problem on the NeXpose server.
Common causes of server errors include an older version of NeXpose that do
not have API support built-in, out of memory conditions, etc.
If you use a command that is not listed in the in NeXpose Administrator's
Guide, NeXpose will return the XMLResponse.

For a sample implementation of some of the API functionality, see the Code
samples section in the API Development v.1.1.2 Guide

Here's the list of all the functions used:

API applications

The API can be used for various applications, not limited to the following:

NeXpose API data interface

Since the NeXpose API responses are XML, it is straightforward to write
scripts that extract relevant data from the
responses, rather than exporting the data from the NeXpose Web interface.
The extracted data can then be processed
according to the needs of your organization. The API simplifies the process
of integrating NeXpose data with other
applications such as databases or third-party security tools.

NeXpose API custom interfaces

Most NeXpose users will only use a subset of NeXpose functions on a regular
basis. Since all major functionality is
available through the API, you can write your own custom interface that
exposes only necessary functions to the
user—either a graphic user interface, or a text-only interface.

Control of NeXpose scanning

The API is a convenient way to configure and run scans. You can run scans as
needed without using the NeXpose
Web interface, and write scripts to run scans at scheduled intervals.

Lists of all commands in the NeXpose API

Session management commands

Login
Log on to the security console and establish a session.

Logout
Log off from from the security console, free
ing the session and all related resources.

Site management commands

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

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

SiteSave
Save changes to a new or existing site.

SiteDelete
Delete the specified site and all associated scan data.

SiteScan
Scan the specified site.

SiteScanHistory
Provide a list of all previous scans of the site

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.

SiteDevicesScan
Scan a specified subset of site assets.

Asset management commands

DeviceDelete
Delete the specified asset

Asset group management commands

AssetGroupListing
Provide a list of all asset groups the user is authorized to view or manage.

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

AssetGroupSave
Save changes to a new or existing asset group.

AssetGroupDelete
Delete the specified asset group and all associated scan data.

Scan commands

EngineListing
Provide a list of all scanning engines managed by the security console.

EngineActivity
Provide a list of current scan activities for a specific scan engine.

ScanActivity
Provide a list of current scan activities across all scan engines managed by
the security console.

ScanPause
Pause a  running scan.

ScanResume
Resume a running scan.

ScanStop
Stop a running scan.

ScanStatus
Check the current status of a scan.

ScanStatistics
Get scan statistics, including node and vulnerability breakdowns.

Vulnerability assessment commands
VulnerabiltyListing

Provide a list of vulnerabilities checked by NeXpose.

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

Reporting commands

ReportTemplateListing

Provide a list of all report templates the user can access on the security
console.

ReportTemplateConfig

Retrieve the configuration for a report template.

ReportTemplateSave
Save the configuration for a report template.

ReportListing
Provide a listing of all report definitions the user can access on the
security console.

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

ReportConfig
Retrieve the configuration for a report definition.

ReportSave
Save the configuration for a report definition.

ReportGenerate
Generate a new report using the specified report definition.

ReportDelete
Delete a previously generated report or report definition.

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

User management commands

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

UserAuthenticator
Provide a list of user authentication sources.

UserConfig
List information about a given user account.

UserSave
Create a new user account, or update the settings for an existing account.

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

General management and diagnostic commands

ConsoleCommand
Execute an arbitrary NeXpose console command that is supplied as text via an
API parameter. The NeXpose console commands are documented in the
NeXpose Administrator's Guide. If you use a command that is not listed in
the in NeXpose Administrator's Guide, NeXpose will return the XMLResponse.

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

StartUpdate
Induce NeXpose to retrieve required updates and restart if necessary.

Restart
Induce NeXpose to restart.

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 email 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 Rapid7 default key.

Session Management

Login
Log on to the security console and establish a session.

 Exact syntax for each command available with additional information from

 http://download2.rapid7.com/download/NeXpose-v4/NeXpose_Extended_API_v1.2_Guide.pdf

mfsconsole automation Resource files:

http://vimeo.com/9695470

NOTE: These don't include the spidering functions in API_12.

NeXpose XML API Examples
http://community.rapid7.com/redmine/projects/nexpose/wiki/XML_API_11_Examples

http://community.rapid7.com/redmine/projects/nexpose/wiki/Xml-api-11-ruby-code

Ben Hamilton's GitHub Project for Ruby XML_API 11
https://github.com/beingben/r7api11-r<https://github.com/beingben/r7api11-r>

And my OpenVAS friend KOST's NeXpose API Perl gitHub https://github.com/kost

See also Rapid7/Metasploit Exploit Engineer Wanted:
http://plug.phoenix.az.us/rapid7
-- 

(503) 754-4452
(623) 688-3392

 http://www.obnosis.com
*Catch My MetaSploit & IP CAM Surveillence
Presentations @ ABLEConf.com in April!*
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.PLUG.phoenix.az.us/pipermail/plug-devel/attachments/20110202/c6ec77bc/attachment.html>