Last updated at Tue, 03 Sep 2024 15:47:06 GMT
The prerequisite is that you get the client: clee-r7/nexpose_java_api · GitHub
This blog post will show you how to augment the java api client and use it in 4 easy steps.
The Java API client uses XML templates to generate requests. Browse to the src/org/rapid7/nexpose/api folder within the API source code, you will see the templates for the currently supported API client requests. i.e: AssetGroupSaveRequest.xml.
There are currently 2 versions of our APIs, v1.1, and v1.2, schemas for v1.2 are shipped with the product:
Schemas for v1.1 are attached to this blog post.
1 Step: Pick the request you want to add to the java API client
Let's pick the request that we want added to the API client, lets say you are interested in pausing active scans.
Grab the schema for the API request you want to add.
In this case ScanPauseRequest:
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:redefine schemaLocation="ScanRequestType.xsd"/>
<xsd:element name="ScanPauseRequest" type="ScanRequestType"/>
</xsd:schema>
ScanRequestType looks like this:
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:redefine schemaLocation="session-id_Type.xsd"/>
<xsd:complexType name="ScanRequestType">
<xsd:attribute name="sync-id" type="xsd:string" use="optional"/>
<xsd:attribute name="session-id" type="session-id_Type"/>
<xsd:attribute name="scan-id" type="xsd:positiveInteger"/>
</xsd:complexType>
</xsd:schema>
2 Step. Create the template for the selected request.
Come up with the xml required for this ScanPauseRequest, based on the previous step xsd definition:
<ScanPauseRequest session-id="1234567GFT67890" sync-id="my synch id" scan-id="12345"/>
Make it a template to be used by the java api-client:
<ScanPauseRequest session-id="${session-id}" sync-id="${sync-id}" scan-id="${scanId}"/>
Save the template file in the src/org/rapid7/nexpose/api folder with the name ScanPauseRequest.xml
3.Step. Create the Java class to support the template.
The Java request for the ScanPauseRequest is very simple, the TemplateAPIRequest.java already takes care of the heavy load, all you will have to do is to extend the TemplateAPIRequest.java and use a setter method:
package org.rapid7.nexpose.api;
import org.rapid7.nexpose.api.APISession.APISupportedVersion;
/**
* Represents the ScanPauseRequest NeXpose API request.
*
* @author Leonardo Varela
*/
public class ScanPauseRequest extends TemplateAPIRequest
{
/////////////////////////////////////////////////////////////////////////
// Public methods
/////////////////////////////////////////////////////////////////////////
/**
* Creates a ScanPauseRequest NeXpose API Request. Sets the first API
* supported version to 1.0 and the last supported version to 1.1.
*
* NOTE: All parameters are strings or generators, since we want to be able
* to test edge cases and simulate incorrect usage of the tool for robustness
*
* @param sessionId the session to be used if different from the current
* acquired one (You acquire one when you authenticate correctly with
* the login method in the {@link APISession} class). This is a
* String of 40 characters.
* @param syncId the synchronization id to identify the response associated
* with the response in asynchronous environments. It can be any
* string. This field is optional.
* @param scanId the positive integer that represents the scan id of the
* scan to be stopped.
*/
public ScanPauseRequest(String sessionId, String syncId, String scanId)
{
super(sessionId, syncId);
set("scanId", scanId);
m_firstSupportedVersion = APISupportedVersion.V1_0;
m_lastSupportedVersion = APISupportedVersion.V1_1;
}
}
There you go, you are ready to give this to the community!
4. Step. Now what? How do I use it?
We will create a site, launch a scan, pause it, using our newly created ScanPauseRequest, stop it and deleted the site.
APISession session = createAPISession(new URL("<Nexpose URL>"), APISupportedVersion.V1_2);
// Create your site with a single host to scan
List<String> hosts = new ArrayList<String>();
hosts.add("127.0.0.1");
// Get the session ID from the session.
String sessionID = session.getSessionID();
// Now create a simple Site Save Request host generator, this is required for elements in the xml that can be
// repeated N times, in this case the <host> element on the SiteSaveRequest, please see
// SiteSaveRequest.xml for details.
SiteSaveRequestHostsGenerator hostsGenerator = new SiteSaveRequestHostsGenerator();
hostsGenerator.setHosts(hosts);
// Now create the SaveSiteRequest
SiteSaveRequest siteSaveRequest = new SiteSaveRequest(
sessionID, // The session ID
null, // the sync id
"-1", // -1 to create the site.
"My API site", // The name of the site
"This site was created through The Java API client", // The description of the site
"1.00", // The risk factor.
hostsGenerator, // The host generator
null, // the ip ranges generator
null, // the credentials generator
null, // the alerts generator
"Full audit", // The name of the configuration
"3", // the configuration version
"-1", // -1 to denote a new configuration
"full-audit", // the configuration template id
"2", // the ID of the engine to use
"false", //whether scheduling is enabled or not.
"false", // whether the schedule is incremental
"daily", // the type of scheduling
"0", // the interval of scheduling
"20120310T061011000", // the date to start the schedule
"100", // the max duration of scheduled scans
"20120310T061011000"); // the expiration date of the schedule
// now we are going to save the site.
APIResponse response = session.executeAPIRequest(siteSaveRequest);
// we are going to grab the site ID for reference.
int siteID = response.grabInt("/SiteSaveResponse/@site-id");
// Let's start the scan now.
SiteScanRequest siteScanRequest = new SiteScanRequest(sessionID, null, Integer.toString(siteID));
response = session.executeAPIRequest(siteScanRequest);
// We are going to grab the scan-id for reference
int scanID = response.grabInt("//Scan/@scan-id");
// Now let's pause the scan with our newly created Java API client request.
ScanPauseRequest scanPauseRequest = new ScanPauseRequest(sessionID, null, Integer.toString(scanID));
session.executeAPIRequest(scanPauseRequest);
// Now that the scan is paused, stop it to be able to delete the site.
ScanStopRequest scanStopRequest = new ScanStopRequest(sessionID, null, Integer.toString(scanID));
session.executeAPIRequest(scanStopRequest);
SiteDeleteRequest siteDeleteRequest = new SiteDeleteRequest(sessionID, Integer.toString(siteID), null);
session.executeAPIRequest(siteDeleteRequest);
We would love to see people contributing their own augmentations to the java API client and sharing with the community.