Security Scan API

You can now offer Golem scanning services completely through third part websites and tools to your customers. This page descirbed how to ingtegrate and use the API, as well as the costs of using the scanner.

Using the Scanner with Your Account

All users of Security Basic, Professional, or Elite have access to the scan API. Submitting a scan through the API is very similar to submitting a scan through the web interface. When a scan is scheduled, it decreases the amount of available scans in your account by 1. In the case of API scans, if you submit scans beyond your monthly allowance, a $5 charge per additional scan is added automatically. This way, you don't have to worry about whether a given API call will succeed - using the API will always schedule a scan.

Setting up API access

Once you log in, there is a link to the API generator. You must generate an API key for your account before using the API. Keep the key safe, since anyone using the key can use your account scan automatically.

Using the API

The API is very simple. All requests are submitted to golemtechnologies.com/api.php which takes several parameters. The return values are always in JSON format. Every return value will include at a minimum 2 pieces of data, success indicated true or false, and message, which will contain an error message when success is false, and be blank otherwise.

Paramaters:

api_key: required. Your API key.

action: Required. The action to take. At this time, allowable actions are createscan, getscanstatus and getscandata

url: Required. The URL you are testing

job_id: optional, can be given to specify a particular scan job

Sample return data after submitting a scan:

{"success":"True","message":"","job_id":79}

Using the API:

Using the API is as simple as submitting a GET request along with the specified data. For instance, to schedule a scan for goiemtechnologies.com, you would submit something like the following:

http://www.golemtechnologies.com/api.php?api_key=16473565d6a0c3f5ab560a886cd6&url=www.golemtechnologies.com&action=startscan

API Examples

The following examples show cases of requesting actions automatically using a URL.

Starting a scan:

http://www.golemtechnologies.com/api.php?api_key=16473565d6a0c3f5ab560a886cd6&url=www.golemtechnologies.com&action=startscan

Return data:

{"success":"True","message":"","job_id":79}

Checking Scan Status:

http://www.golemtechnologies.com/api.php?api_key=16473565d6a0c3f5ab560a886cd6&url=www.golemtechnologies.com&action=getscanstatus

OR

http://www.golemtechnologies.com/api.php?api_key=16473565d6a0c3f5ab560a886cd6&url=www.golemtechnologies.com&action=getscanstatus&job_id=79

Note: You MUST include the job ID if you have scheduled multiple scans for the same URL within a 7 day period, or the results will only return the status of one of the scanning jobs.

Sample results:

{"success":"True","message":"","status":"In Queue"}

Getting Scan Results

http://www.golemtechnologies.com/api.php?api_key=16473565d6a0c3f5ab560a886cd6&url=www.golemtechnologies.com&action=getscandata

This will return all the report data, in JSON format, for the scanned URL. You can build a complete report from this data, including replicating the Golem reports in full. The data is returned with the following JSON format:

{"success":"True",
"message":"",
"scan_date":"<date>",
"vulnerabilities":
   {"Extremely High Risk":[],
   "High Risk":
      [{"vulnerabilityid":<id>,
      "vulnerability":"<vulnerability name>",
      "count":<count of how many URL's this was found for>,
      "description":"<complete description of problem and solutions, pre-formatted, though without CSS rules>"
      "urls":[{<JSON containing a lit of URL's in the format "url":"<url>, "message":<detail on what the scanner found>, "url_id":<Unique url ID>,"}]  
      }]
   }]
}

API Integration Examples: JavaScript

Here is a sample for integrating the API with Javascript using AJAX and JQuery:

var API_KEY = "16473565d6a0c3f5ab560a886cd6";
function startScan(url)
{
    jQuery.ajax({
         url:    "https://www.golemtechnologies.com?action=createscan&api_key="+API_KEY+"&url="+url, 
         success: function(data) {
                    alert("Scan: " + data);
                  },
         async:   false
    });
}