Qualys Blog

www.qualys.com

Automate the Delivery of Security Intelligence for New Assets

As 2013 comes to a close, enterprise partnerships and mergers and acquisitions in the tech sector have continued to occur at billion dollar levels. One can infer there is much to gain from adding the confidential intellectual properties of others. The true puzzle is understanding if the intellectual properties are, in fact, truly confidential. After all, what is the value in acquiring trade secrets if they are not secret?

Your organization’s threat landscape dramatically expands as a result of these types of corporate asset purchases. Defining a vulnerability baseline of your newly onboarded assets enables your organization to adopt a risk-based approach. QualysGuard is capable of providing that baseline in short order. Leveraging QualysGuard’s API, one can extend this capability to an automated process that aligns with best practices to protect your business expansions and investments.

Getting started on baselining new external assets

A joining of organizations or new partnerships eventually leads to attaching a foreign set of IP addresses to your IT environment. These IP addresses may be an via external VPN connection or perhaps through a merging of internal networks. However the case, the end result is adding IP addresses with an unknown security posture.

Workflow

The following describes the steps to programmatically have QualysGuard scan your new external assets.

Workflow:

  1. Gather ingredients for automation (new IP addresses, option profile, etc.).
  2. Subscribe IP address of new assets.
  3. Assign the IP addresses to a new asset group, which could be the name of the business group.
  4. Scan the IP addresses.
  5. Poll scan status until scan completes.
  6. Create action items via reporting.

Gather ingredients

To fulfill this automation, you will need the following:

  1. QualysGuard user with API access and privilege level of manager or unit manager.
  2. An option profile configuration of your scan.
  3. External target IP addresses.
  4. An asset group name to reference these target IP addresses.
  5. A scan title to label these automated scans.

Subscribe new assets

The first step to automating the baselining of new assets is to define the IP addresses that you would like to target. If you have gotten this far, you have completed the hardest step! The rest of the automated process is all performed within QualysGuard via the API with manager level access.

Let’s walk through programmatically adding and scanning externally facing hosts. Before QualysGuard can scan the new IP addresses, we must permit QualysGuard to scan them by adding the IP addresses to your subscription.

API call details:

  • API v1
  • Call = asset_ip.php
  • Method = GET
  • Parameters
    • action = add
    • host_ips = IP addresses to add

Sample request response from adding target IP addresses:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE GENERIC_RETURN SYSTEM "https://qualysapi.qualys.com/generic_return.dtd">
<GENERIC_RETURN>
  <API name="asset_ip.php" username="username" at="2013-12-10T18:03:00Z" />
  <RETURN status="SUCCESS">The operation was successfully completed</RETURN>
</GENERIC_RETURN>
<!-- CONFIDENTIAL AND PROPRIETARY INFORMATION. Qualys provides the QualysGuard Service "As Is," without any warranty of any kind. Qualys makes no warranty that the information contained in this report is complete or error-free. Copyright 2013, Qualys, Inc. //-->

We can confirm this request was successful from the XML response’s GENERIC_RETURN.RETURN tag:

<RETURN status="SUCCESS">The operation was successfully completed</RETURN>

Assign IP addresses to asset group

Before we scan the IP addresses, let’s add them to an asset group for easy referencing. You may want to customize the comments.

API call details:

  • API v1
  • Call = asset_group.php
  • Method = GET
  • Parameters
    • action = add
    • comments = Created via automation for organization_name.
    • host_ips = IP addresses to add
    • title = organization_name

Sample request response from creating asset group for target IP addresses:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE GENERIC_RETURN SYSTEM "https://qualysapi.qualys.com/generic_return.dtd">
<GENERIC_RETURN>
  <API name="asset_group.php" username="username" at="2013-12-10T18:20:17Z" />
  <RETURN status="SUCCESS">The operation was successfully completed</RETURN>
</GENERIC_RETURN>
<!-- CONFIDENTIAL AND PROPRIETARY INFORMATION. Qualys provides the QualysGuard Service "As Is," without any warranty of any kind. Qualys makes no warranty that the information contained in this report is complete or error-free. Copyright 2013, Qualys, Inc. //-->

We can confirm this request was successful from the XML response’s GENERIC_RETURN.RETURN tag:

<RETURN status="SUCCESS">The operation was successfully completed</RETURN>

Launch scan

Next, a one time setup of the option profile to be used should be assigned or created. In this example, we will use the option profile titled, “New IPs option profile”.

We are all set to scan! Let’s shoot off a quick scan from Qualys’s external scanners. You may want to customize the scan title.

API call details:

  • API v2
  • Call = /api/2.0/fo/scan/
  • Method = POST
  • Parameters
    • action = launch
    • asset_groups = organization_name
    • option_title = New external
    • scan_title = Acquisition scan of organization_name

This launch request will return an XML response containing the scan reference identifier. We want to remember that value so we can easily keep tabs on when the scan completes.

Note: In this example, we will scan 64.39.106.0-64.39.106.3. You should only scan IPs that you own or are authorized to scan.

Sample request response from launching scan:

<?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-12-12T19:41:32Z</DATETIME>
    <TEXT>New vm scan launched</TEXT>
    <ITEM_LIST>
      <ITEM>
        <KEY>ID</KEY>
        <VALUE>15018226</VALUE>
      </ITEM>
      <ITEM>
        <KEY>REFERENCE</KEY>
        <VALUE>scan/1386877291.18226</VALUE>
      </ITEM>
    </ITEM_LIST>
  </RESPONSE>
</SIMPLE_RETURN>

The scan reference from the above XML is in the SIMPLE_RETURN.RESPONSE.ITEM_LIST.ITEM.VALUE tag:

<VALUE>scan/1386877291.18226</VALUE>

Poll for scan status

Now that the scan just launched, we should wait about 7 minutes before we see check on its status.

API call details:

  • API v2
  • Call = /api/2.0/fo/scan/
  • Method = POST
  • Parameters
    • action = list
    • scan_ref = scan/1386877291.18226

Sample request response with scan still running:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE SCAN_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/scan/scan_list_output.dtd">
<SCAN_LIST_OUTPUT>
  <RESPONSE>
    <DATETIME>2013-12-12T19:54:48Z</DATETIME>
    <SCAN_LIST>
      <SCAN>
        <REF>scan/1386877291.18226</REF>
        <TYPE>API</TYPE>
        <TITLE><![CDATA[Acquisition scan of organization_name]]></TITLE>
        <USER_LOGIN>username</USER_LOGIN>
        <LAUNCH_DATETIME>2013-12-12T19:41:31Z</LAUNCH_DATETIME>
        <STATUS>
          <STATE>Running</STATE>
        </STATUS>
        <TARGET><![CDATA[64.39.106.0-64.39.106.3]]></TARGET>
      </SCAN>
    </SCAN_LIST>
  </RESPONSE>
</SCAN_LIST_OUTPUT>
<!-- CONFIDENTIAL AND PROPRIETARY INFORMATION. Qualys provides the QualysGuard Service "As Is," without any warranty of any kind. Qualys makes no warranty that the information contained in this report is complete or error-free. Copyright 2013, Qualys, Inc. //-->

The state of the scan is the value we are interested in.

State from the above polling request showing the scan is still running:

<STATE>Running</STATE>

Continue to poll the scan every 5 minutes. This will give enough of a buffer to avoid going over your API limit.

We are looking for the state value to show "Finished" like below:

<STATE>Finished</STATE>

Create action items

Congratulations! QualysGuard now has up to date security intellegence of your new assets. The results will be merged into your auto data momentarily. Let’s explore leveraging QualysGuard’s reporting functionality to make this scan actionable.

In case you would like to parse the results immediately, perhaps for alerting purposes, the following methods can work:

  1. Leveraging a report template against the manual scan data and downloading that report (recommended).
  2. Downloading the raw scan data for a complete view.

Important to note

This workflow is specific to external IP addresses being added. Programmatic input of these IP addresses should be thorougly reviewed as QualysGuard will scan what its told is okay to scan.

The following should be considered if this capability is to be extended to internal IP addresses:

  • Host tracking type should be considered when adding the IPs into the subscription.
  • Scanner appliances and a default scanner appliance should be assigned to the asset group during the asset group creation.
  • The launch step should include which scanner appliance to scan the target hosts with.

Proof of concept implementations

Note, the following are unsupported. They are unofficial proof of concept implementations of the above workflow.

POSTMAN

This POSTMAN collection contains all the API calls preconfigured for the workflow above:

Blog, scan new assets.json.postman_collection

You can find more information on setting up POSTMAN for QualysGuard here.

Python code

Coming soon…

2 responses to “Automate the Delivery of Security Intelligence for New Assets”

Leave a Reply