Replace your old "/msp/scan.php" API requests with the new "scan" API v2

Document created by Eric Perraudeau Employee on Apr 9, 2013Last modified by Eric Perraudeau Employee on Apr 12, 2013
Version 7Show Document
  • View in full screen mode

If you only have 1 minute

  • Replace all your "/msp/scan.php" API calls (used to launch Vulnerability scans) by "/api/2.0/fo/scan/?action=launch"
  • Benefit 1: This API is asynchronous as opposed to the former "/msp/scan.php" API.
  • Benefit 2: Use this API to launch VM scan with Asset Tags
  • Available in QualysGuard 7.9, available in a couple of weeks
  • Example: Launch a VM scan for the IP address 10.10.10.10, with the scanner appliance "scanner1"

 

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"
      -X "POST" -d "action=launch&scan_title=My+Vulnerability+Scan&ip=10.10.10.10&iscanner_name=scanner1"
      "https://qualysapi.qualys.com/api/2.0/fo/scan/"

 

Detailed explanation

The API v1 "/msp/scan.php", that allows users to launch new Vulnerability scans, is one of our most popular APIs. With QualysGuard version 7.9, that will be released in production over the course of April and May 2013 (please check the release notifications here: US Platform 1, US Platform 2, EU Platform), we are introducing a new API v2 function that can be used to launch new VM scans. This new Launch Scan API v2 provides new features and added value to users as explained below.

 

Although we strongly recommend that you update all your "/msp/scan.php" API calls with this new API, we don't have any plan to retire the old v1 scan.php API.

 

This new "scan" API v2 function is an extension of the existing "/api/2.0/fo/scan" API endpoint that has been available since the introduction of the API v2 framework. This "scan" API v2 endpoint was first released to provide the list of the scan jobs by using the parameter "action=list", download the scan results by using the parameter "action=fetch", and manage scan jobs with the parameters "action={cancel|pause|resume}". And more recently, we also added to this API function the option to launch Policy Compliance scans with QualysGuard version 7.5 (more details).

 

All the details about these existing capabilities are fully detailled in the API v2 user guide available here.

 

With the QualysGuard 7.9 release, we’ve added support for launching and deleting vulnerability (VM) scans (new parameters action=launch and action=delete). Also we’ve updated permissions for this API, so now any user with permission to scan hosts in their account (not just Managers) also has permission to cancel, pause and resume scans.

 

Benefits of using the new Launch Scan API v2:

  1. This is a truly asynchronous API function as opposed to the former "/msp/scan.php" API. In other words, when you make a request to launch a scan using this API, the service will return a scan reference ID right away and the call will quit without waiting for the complete scan results.
  2. Support for Asset Tags

 

 

Example using cURL:

 

Note: Curl is a multi-platform command-line tool used to transfer data using multiple protocols including http and https. This tool is supported on many systems, including Windows, Unix, Linux and Mac. For more information: curl/haxx/se

 

This request launches a vulnerability scan on hosts with the asset tag Windows using the scanner appliance “scanner1”:

 

 

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST"
     -d "action=launch&scan_title=My+Vulnerability+Scan&target_from=tags&tag_set_by=name&tag_set_include=Windows&iscanner_name=scanner1
     "https://qualysapi.qualys.com/api/2.0/fo/scan/"

 

XML Output for this request that returns the scan reference "scan/1358285558.36992" that can be used to fetch the results once the scan finished

 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM
"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
  <RESPONSE>
    <DATETIME>2013-01-15T21:32:40Z</DATETIME>
    <TEXT>New vm scan launched</TEXT>
    <ITEM_LIST>
      <ITEM>
        <KEY>ID</KEY>
        <VALUE>136992</VALUE>
      </ITEM>
      <ITEM>
        <KEY>REFERENCE</KEY>
        <VALUE>scan/1358285558.36992</VALUE>
      </ITEM>
    </ITEM_LIST>
  </RESPONSE>
</SIMPLE_RETURN>

Attachments

    Outcomes