This functionality was first introduced in the Hillary release series. The specific methods described on this page work with Hillary R2 and later releases.

Prior to Hillary R1, the locations/target configuration could be created and edited via the iQSonar user interface, or optionally by uploading a CSV file. The facility to modify (add and remove) target configurations via the RestAPI was initially introduced in Hillary R1 and further refined in Hillary R2. At the time of writing, the facility to modify credentials is still restricted to CSV import or manual editing via the User Interface

Instructions

Target configuration via the RestAPI relies on data stored in the JSON file format, rather than CSV files. The data stored in the file is the same, but the format of the file is quite different. To edit a JSON file and text editor can be used (for example Notepad) but an editor specifically designed for use by Programmers (for example Notepad++) would be preferred.

The file is uploaded to the server using the HTTP POST method (not a GET method) http://<youriqsonarinstance>/api/v1/targets where the body of the request contains the JSON data.

The response will contain a message containing the status of the request and a request_id to allow the user to monitor the request status - a large set of locations may take some time to be stored in the database.

This response will contain a message indicating the status of request. You can then query http://youriqsonarinstance/api/v1/targets/poststatus/{request_id}/ to see the result of your request.

Error rendering macro 'code': Invalid value specified for parameter 'firstline'

{
	"message": "Completed",
	"details": "",
	"request_id": "1"
}

Status Message	Description
Queued	The RestAPI Request is queued
Processing	The RestAPI Request is being processed
Completed	The RestAPI Request has been successfully processed
Error	There was a fatal error processing the RestAPI Request
Invalid Request ID	The request_id is invalid.

JSON Data file format

A tutorial on how to create JSON data files is beyond the scope of this article. For a full description of the JSON data format see the wikipedia page or the JSON.org website. Users are expected to be familiar with this format before using the RestAPI to configure iQSonar. In many cases it may be easier to configure the Locations using a CSV import or the manual method if the JSON data is not being generated programatically.

The JSON data file should contain the fields "Name" (the value MUST be "LOCATION TARGET"), "Version" (the value MUST BE "1.3")and "Locations", where the Locations field contains an array of locations.

JSON File header

{
    "Name":"LOCATION TARGET",
    "Version":"1.3",
    "Locations":
    [
		{ "comment": "Array of locations belongs here" }
	]
}

Each Location should contain the following fields:

Field	Description	Can be empty?	Example or Possible Values
LocationPath	Name of the location. Sub-locations seperated by the pipe symbol "\|"	NO	Sample\|Node Sample\|Node2\|Leaf1 Sample\|Node2\|Leaf2
Target	What category of target is this (Either Application or Device)	NO	Device Application
Type	What sub-type of target is this (What type of Device, or Which Application)	NO	See the list of valid target types
Name	The name of the location (This is a freeform text field)	NO	Main Lab QA Lab My Test Location
Instance Name	The name of the database instance	YES	For scanning database application targets
Hostname	The host name for hostname targets	YES	vm-test.localdomain www.myserver.example.com vm-myserver
StartIP	The Start IP Address - use this for Application targets, Single, Range and Subnet targets	YES	10.0.0.1
EndIP	The End IP Address - use this for Range targets only	YES	10.0.0.99
SubnetMask	The netmask - as a number not as a dotted quad - use for Subnet targets only	YES	Use "24" not "255.255.255.0" "0" can be used for an empty target
Port	The port on which to scan, for Application Targets only	YES	E.g. an SQL Server is usually on port 1433 but can be set to an arbitrary number.
Exclusion	Whether this is a target exclusion. Use to exclude IP addresses from a larger list	NO	Valid values are "True" or "False".

For a row where the value can be empty, you can either omit the row, or pass in an empty string ("")

The list of valid Device Target types is:

"Hostname" (contains the hostname of a device),
"Range" (contains an ip address range defined by a Start IP address and an End IP address)
"Subnet" (contains an IP Address subnet, defined by a Start IP address and a netmask)
"Single" (contains a single IP Address)

The list of valid Application Target types is:

"vCenter" (a VMware vCenter application)
"Informix" (an Informix database application target)
"Oracle Database Server"
"SQL Server" (A Microsoft SQL Server application target)

An application target is used when we need to scan an application on a non-standard port, or when we need to scan an application if we cannot scan the underlying OS on the target.

Sample JSON data file

JSON Datafile

{
    "Name":"LOCATION TARGET",
    "Version":"1.3",
	"Locations":
	[
		{
			"LocationPath":"Demo|TestScan",
			"Target":"Device",
			"Type":"Hostname",
			"Name":"Hostname Target 1",
			"InstanceName":"",	
			"Hostname":"vm-myserver",
			"StartIP":"",
			"EndIP":"",
			"SubnetMask":"0",
			"Port":"",
			"Exclusion":"False"
		},
		{
			"LocationPath":"Demo|TestScan",
			"Target":"Device",
			"Type":"Single",
			"Name":"Single IP Address",
			"InstanceName":"",	
			"Hostname":"",
			"StartIP":"10.0.0.1",
			"EndIP":"",
			"SubnetMask":"0",
			"Port":"",
			"Exclusion":"False"
		},
		{
			"LocationPath":"Demo|TestScan",
			"Target":"Device",
			"Type":"Range",
			"Name":"Multiple IP Addresses",
			"InstanceName":"",	
			"Hostname":"",
			"StartIP":"10.0.0.2",
			"EndIP":"10.0.0.99",
			"SubnetMask":"0",
			"Port":"",
			"Exclusion":"False"
		},
		{
			"LocationPath":"Demo|SecondNetwork",
			"Target":"Device",
			"Type":"Subnet",
			"Name":"Different network",
			"InstanceName":"",	
			"Hostname":"",
			"StartIP":"192.168.1.0",
			"EndIP":"",
			"SubnetMask":"24",
			"Port":"",
			"Exclusion":"False"
		}
	]
}

How to invoke the command

For any non-trivial estate size, you will want to store the JSON as a file rather than trying to put the data on the command line. Save the JSON data file, either editing it manually or generating it from a data source. For these examples, we store the data in a file in the current directory called file.json

Call the RestAPI using cURL

Note: the encoded username and password pair in the CURL call corresponds to the login 'admin' and password 'password' which are the default iQSonar credentials you are forced to change on when you log in the first time.

Call using cURL

curl --data "@file.json" \
    -H 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
	-H "Content-Type: application/json" \
    -X 'POST' 'http://youriqsonarserver/api/v1/targets'

Call the RestAPI using PowerShell

Create Targets using PowerShell Invoke-RestMethod

$cred = Get-Credential
$body = Get-Content file.json
$url = 'http://youriqsonarserver/api/v1/targets'
Invoke-RestMethod -Method POST -ContentType 'application/json' -Credential $cred -Body $body -Uri $url

Worked Example using PowerShell

In the screenshot below, we add two targets (one hostname target and one IP Address target) to the location QALab | MikeTest. The host running iQSonar is on vm-mike-rc

Contents of target4.json

{
    "Name":"LOCATION TARGET",
    "Version":"1.3",
    "Locations":
    [
        {
            "LocationPath":"QALab|MikeTest",
            "Target":"Device",
            "Type":"Hostname",
            "Name":"Hostname Target 1",
            "InstanceName":"", 
            "Hostname":"vm-mike-se-w16",
            "StartIP":"",
            "EndIP":"",
            "SubnetMask":"0",
            "Port":"",
            "Exclusion":"False"
        },
		{
            "LocationPath":"QALab|MikeTest",
            "Target":"Device",
            "Type":"Single",
            "Name":"IP Address Target",
            "StartIP":"192.168.0.79",
            "Exclusion":"False"
        },
		{
            "LocationPath":"QALab|MikeTest",
            "Target":"Device",
            "Type":"Single",
            "Name":"IP Address Target 2",
            "StartIP":"192.168.0.148",
            "Exclusion":"False"
        }
	]
}

PowerShell screenshot:

Resulting Targets in the Locations screen in iQSonar

Error handling

If there is an error in your JSON data (for example a row that duplicates an existing target, or a syntaxt error) then rather than a result that shows "Completed" with an empty details column, you will get an error message in the Details column. PowerShell truncates this error message (see the screenshot below), but you can view the complete diagnostic error message in the back-end database

Query to return the diagnostic message:

Retrieve error code for request_id 4

SELECT TargetConfig, DataOut
  FROM [jobs].[t_TargetConfigRequest]
  WHERE TargetRequestID=4

Related articles

Page:

Enable DEBUG for each connection
Page:

Installation of New Code Signing Version of iQSonar
Page:

IBM .dll Files are not being loaded.
Page:

Installation of Second Scan Engine fails
Page:

Project Results - Scan Missing Data