English | Deutsch | Español | Português
 UserID:
 Passwd:
new user
 About  | API Guide  | API Key  | JavaScript Example | PHP CLI Example
 
REST API Guide

Table of Contents

Introduction

Technology
HTTP Service calls
Access to security space API services is done exclusively over HTTP POST requests, running over an SSL protocol. Responses are received in JSON. A sample transaction is shown below.

HTTP Request
POST /api/auth.php HTTP/1.0
Host: secure1.securityspace.com
Content-Length: 78
Content-type: application/x-www-form-urlencoded

apikey=WjN5ZkVoWm9KS2FvaHVGbE5VQ2loeHdP&userid=youruseridpassword=yourpassword

HTTP Response
HTTP/1.1 200 OK
Date: Mon, 17 Nov 2014 22:07:24 GMT
Server: Apache
X-Powered-By: PHP/5.4.4-14+deb7u14
Cache-Control: no-cache, must-revalidate
Expires: Mon, 17 Nov 2014 17:07:24 EST
Content-Length: 814
Connection: close
Content-Type: application/json

{ "status": "0", "sessionToken": "VhvF93vCXKScVlxdh2332343j4oFdXC8R7lkF3FX ...<snipped for brevity>"}

JSON (JavaScript Object Notation) Data Format
APIs return information in JSON. JSON's advantages are:
  1. Low overhead (efficient data transfer)
  2. Human readable
  3. Support in a large number of languages (check here)

An example of a JSON data response would be
{
    "status": "0",
    "sessionToken": "VhvF93vCXKScVlxdh2332343j4oFdXC8R7lkF3FX ...<snipped for brevity>"
}

API Error Indicators

All responses to SecuritySpace APIs will contain a "status" field, which will have a value of "0" if the request was successful, or a non-zero value on error. When there is an error, a static error response will be returned consisting of the status field and an "error" field, with the error field containing an error message indicating the reason for the failure.

An example of a successful JSON data response would be
{
    "status": "0",
    "sessionToken": "VhvF93vCXKScVlxdh2332343j4oFdXC8R7lkF3FX ...<snipped for brevity>"
}

An example of an error response is:
{
    "status": "-1",
    "error": "invalidLogin"
}

APIs

Authentication (auth.php)
DescriptionAuthenticate to your SecuritySpace account and get back a session token that can be used in all APIs accessing/manipulating your account information. Returned tokens are valid for 24 hours, after which they expire and a new token must be requested.
URLhttps://secure1.securityspace.com/api/auth.php
PrerequisitesValid API key, active account
InputapikeyYour SecuritySpace api key
useridYour SecuritySpace account userid
passwordYour SecuritySpace account password
Success
Response
Schema
{
    "required": true,
    "type": "object" ,
    "properties": {
	"status" : { "required": true, "type": "number" },
	"sessionToken" : { "required": true, "type": "string" }
    } 
} 
ErrorsnotSSLAPI must be invoked via an SSL connection
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
missing credentialsInput parameters missing userid and/or password
invalidLoginLogin incorrect - wronger userid/password combination
sysErrEntitlementLoadSystem Error - unable to load account entitlements
tokenCreationSystem Error - unable to create token
sysErrdoLoginSystem Error - unspecified error returned from authentication request

Security Audit - Get Audit List (saGetAuditList.php)
DescriptionRetrieve the list of audit reports in your account, along with some basic audit information
URLhttps://secure1.securityspace.com/api/saGetAuditList.php
PrerequisitesValid API key, valid session token
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
Success
Response
Schema
{
    "required": true,
    "type": "object",
    "properties": {
	"status" : { "required": true, "type": "number" },
	"scancount" : { "required": true, "type": "number" },
	"scans" : {
	    "required": false,
	    "type": "array" ,
	    "items": {
		"required": true,
		"type": "object" ,
		"properties": {
		    "scanuid" : { "required": true, "type": "string" },
		    "folder" : { "required": true, "type": "string" },
		    "hostip" : { "required": true, "type": "string" },
		    "time_end" : { "required": true, "type": "string" },
		    "time_queued" : { "required": true, "type": "string" },
		    "time_start" : { "required": true, "type": "string" },
		    "type" : { "required": true, "type": "string" }
		} 
	    }
	}
    }
}

ErrorsnotSSLAPI must be invoked via an SSL connection
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid

Security Audit - Get Audit Report (saGetAuditReport.php)
DescriptionRetrieve the specified audit report
URLhttps://secure1.securityspace.com/api/saGetAuditReport.php
PrerequisitesValid API key, valid session token
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
scanuidA valid scan identifier
Success
Response
Schema

{
  "required": true,
  "type": "object" ,
  "properties": {
    "status" : { "required": true, "type": "number" },
    "scaninfo" : {
      "required": true,
      "type": "object" ,
      "properties": {
	"basic" : {
	  "required": true,
	  "type": "object" ,
	  "properties": {
	      "detail_supplement" : { "required": true, "type": "number" },
	      "ejtime" : { "required": true, "type": "string" },
	      "hostip" : { "required": true, "type": "string" },
	      "merge" : { "required": true, "type": "number" },
	      "mergelist" : { "required": true, "type": "string" },
	      "promocode" : { "required": true, "type": "string" },
	      "qjtime" : { "required": true, "type": "number" },
	      "reporttype" : { "required": true, "type": "string" },
	      "scanattr" : { "required": true, "type": "string" },
	      "scanportstcp" : { "required": true, "type": "string" },
	      "scantype" : { "required": true, "type": "string" },
	      "scanuid" : { "required": true, "type": "number" },
	      "sjtime" : { "required": true, "type": "number" },
	      "title" : { "required": true, "type": "string" },
	      "totalnaslentries" : { "required": true, "type": "number" }
	  } 
	},
	"entries" : {
	  "required": false,
	  "type": "object" ,
	  "properties": {
	    "<high|medium|low|other>" : { //test results organized by risk groups
	      "required": false,
	      "type": "object" ,
	      "properties": {
		"<scanuid_sequence#>" : {// E.g. Property name of 1100005104_58
		  "required": true,
		  "type": "object" ,
		  "properties": {
		    // Which report this came from (required for merged view)
		    "repid" : { "required": true, "type": "string" },
		    // The test ID (full ID)
		    "id" : { "required": true, "type": "string" },
		    // The short form test ID
		    "shortid" : { "required": true, "type": "string" },
		    // IP address of the host
		    "ip" : { "required": true, "type": "string" },
		    // Port# on which this is applicable
		    "port" : { "required": true, "type": "string" },
		    // Category of this test
		    "cat" : { "required": true, "type": "string" },
		    // Any CVE identifiers (CSV)
		    "cve" : { "required": true, "type": "string" },
		    // The unique entry key (e.g. 1100005104_58)
		    "entrykey" : { "required": true, "type": "string" },
		    // The risk level (one of high,medium,low,other)
		    "risk" : { "required": true, "type": "string" },
		    // The short entry key (sequence # - e.g. 58)
		    "shortkey" : { "required": true, "type": "number" },
		    // The static test description
		    "static_description" : { "required": true, "type": "string" },
		    // The full test description, including dynamically
		    // generated elements
		    "description" : { "required": true, "type": "string" },
		    "title" : { "required": true, "type": "string" },
		    // Type of test entry report (LOG,NOTE,HOLE)
		    "type" : { "required": true, "type": "string" }
		    // Baseline assessment results
		    "baseline" : { "required": true, "type": "string" },
		  } 
		}
	      } 
	    }
	  } 
	},
	"ports" : { // Report the open ports that were found.
	  "required": true,
	  "type": "array" ,
	  "items": {
	    "required": true,
	    "type": "object" ,
	    "properties": {
	      // Which report this item belonged to (useful only for merged views)
	      "repid" : { "required": true, "type": "string" }
	      "hostip" : { "required": true, "type": "string" },
	      // first port in range
	      "portend" : { "required": true, "type": "number" },
	      // last port in range, -1 if not a range
	      "portnum" : { "required": true, "type": "string" },
	      // Protocol (TCP/UDP)
	      "portprot" : { "required": true, "type": "string" },
	      // Name of service typically residing on this port
	      "portservice" : { "required": true, "type": "string" },
	    } 
	  }
	},
	"risk" : { // The number of vulnerabilities at each risk level
	  "required": true,
	  "type": "object" ,
	  "properties": {
	    "high" : { "required": false, "type": "number" },
	    "low" : { "required": false, "type": "number" },
	    "medium" : { "required": false, "type": "number" },
	    "other" : { "required": false, "type": "number" }
	  } 
	},
	"riskcatgrid" : {
	  "required": true,
	  "type": "object" ,
	  "properties": {
	    // Multiple entries, with property name consisting of the
	    // the test category:risk level. E.g. "RPC:other"
	    "<category:risk>" : { "required": false, "type": "number" },
	  }
	}
      }
    }
  }
} 

ErrorsnotSSLAPI must be invoked via an SSL connection
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
reportLoadFailure[<code>]report failed to load

Security Audit - Run Audit (saRunAudit.php)
DescriptionRun a security audit against an IP address or a range of addresses.
URLhttps://secure1.securityspace.com/api/saRunAudit.php
PrerequisitesValid API key, active account
InputapikeyYour SecuritySpace api key
sessionTokenA valid session token returned from auth.php
ipaddrOptional:IP address(es) of the host(s) to be audited. Wild cards (*) and hyphens for ranges may be employed on any portion of an IP address, and multiple comma separated values may be specified. E.g. "192.168.1.*,10.1.1-2.32-63" would request an audit of all 256 addreesses in the 192.168.1.0/24 range, as well as another 2 /27 ranges of 10.1.1.32/27 and 10.1.2.32/27. If not specified, will default to the detected IP address of the client making the request.
audittypeMust be specified as one of { advanced, standard, norisk, desktop, basic }
excludedosOptional:If set (to any value), the audit will exclude tests in the denial of service category. Otherwise, all tests will be run.
notificationOptional:Set to OCMP to receive an on completion notification email that the audit has finished running. Defaults to not sending any notification.
Success
Response
Schema
{
    "required": true,
    "type": "object" ,
    "properties": {
	"status" : { "required": true, "type": "number" },
    } 
} 
ErrorsnotSSLAPI must be invoked via an SSL connection
invalid apikey formatNot a valid API key
invalid apikey - not in dbAPI key not in DB
sessionTimeoutthe session token has expired
sessionAuthenticationFailurethe session token is not valid
missingAuditTypeThe audit type was not specified.
invalidAuditTypeAn invalid audit type was specified
IPPermissionsProblemUser doesn't have permissions on this account to audit one or more addresses in the audit request. Full request has been rejected.
missingScanClientsRecAn internal system error.
notEntitledA request was made to run an audit for which the user has not subscribed.
noriskAlreadyRunA limit of one no risk audit per IP address per month is enforced. This is a second request, and has been rejected.



Home | About Us | Contact Us | Partner Programs | Developer APIs | Privacy | Mailing Lists | Abuse
Security Audits | Managed DNS | Network Monitoring | Site Analyzer | Internet Research Reports
Web Probe | Whois

© 1998-2017 E-Soft Inc. All rights reserved.