Troubleshooting Qualys API

Document created by Spencer Brown Employee on Dec 21, 2019Last modified by Spencer Brown Employee on Jan 3, 2020
Version 13Show Document
  • View in full screen mode

This document is intended to help customers isolate API issues and provide sufficient evidence to Qualys Support for quick resolution.  The API examples are from the Host List Detection; however, other API endpoints can use the same methodology.

 

When encountering API issues, follow the steps below until remediation.

Basic Steps

1) Validate API access has been granted to user 

 

Expected output without API access
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM "https://qualysapi.qg2.apps.qualys.com/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
    <RESPONSE>
        <DATETIME>2019-12-21T19:34:26Z</DATETIME>
        <CODE>2000</CODE>
        <TEXT>Bad Login/Password</TEXT>
    </RESPONSE>
</SIMPLE_RETURN>

2) Validate user has correct permissions. 

Qualys recommends using the "Manager" role as this gives permissions to pull all assets

3) Validate server and gateway URL for user account

Use the platform identifier in your Qualys username to determine your Qualys platform: Qualys Platform Identification | Qualys, Inc. 

 

Expected output using incorrect server URL
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM "https://qualysapi.qg2.apps.qualys.com/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
    <RESPONSE>
        <DATETIME>2019-12-21T19:29:50Z</DATETIME>
        <CODE>2000</CODE>
        <TEXT>Bad Login/Password</TEXT>
    </RESPONSE>
</SIMPLE_RETURN>

 

Isolation Steps 

1) Attempt API call using Postman or curl

 

  • Attempting with Postman

   More about using Postman with Qualys APIs: Quick Start Guide for the Qualys API (Postman Edition)

 

 

  • Attempting with curl

 

Sample curl command

curl -u "username:password" -H "X-Requested-With: curl" "https://qualysapi.qualys.com/api/2.0/fo/asset/host/vm/detection/?action=list"

 

2) Attempt API call off of the corporate network

  • Corporate networks can additional variables such as proxy and latency

 

If API errors or timeouts are intermittent and are not reproducible, Qualys recommends adding error handling and retry logic to your automation

 

Issue still persists

Contact customer via How to Contact Qualys Support and attach the following to case:

  1. Full API call with parameters using Postman or curl from Isolation Steps
  2. Full XML output

 

Please run curl command with verbose flag for additional logging

 

Curl command with -v flag

curl -v -u "username:password" -H "X-Requested-With: curl" "https://qualysapi.qualys.com/api/2.0/fo/asset/host/vm/detection/?action=list"

 

Curl output with -v flag
* Trying 64.39.96.202...
* TCP_NODELAY set
* Connected to qualysapi.qg2.apps.qualys.com (64.39.96.202) port 443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* successfully set certificate verify locations:
* CAfile: /etc/ssl/cert.pem
CApath: none
* TLSv1.2 (OUT), TLS handshake, Client hello (1):
* TLSv1.2 (IN), TLS handshake, Server hello (2):
* TLSv1.2 (IN), TLS handshake, Certificate (11):
* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
* TLSv1.2 (IN), TLS handshake, Server finished (14):
* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
* TLSv1.2 (OUT), TLS change cipher, Change cipher spec (1):
* TLSv1.2 (OUT), TLS handshake, Finished (20):
* TLSv1.2 (IN), TLS change cipher, Change cipher spec (1):
* TLSv1.2 (IN), TLS handshake, Finished (20):
* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256
* ALPN, server accepted to use http/1.1
* Server certificate:
* subject: C=US; ST=California; L=Foster City; O=Qualys, Inc.; OU=Production; CN=qualysapi.qg2.apps.qualys.com
* start date: Jul 30 00:00:00 2019 GMT
* expire date: Jul 30 12:00:00 2020 GMT
* subjectAltName: host "qualysapi.qg2.apps.qualys.com" matched cert's "qualysapi.qg2.apps.qualys.com"
* issuer: C=US; O=DigiCert Inc; CN=DigiCert SHA2 Secure Server CA
* SSL certificate verify ok.
* Server auth using Basic with user 'quays2kb58'
> GET /api/2.0/fo/asset/host/vm/detection/?action=list HTTP/1.1
> Host: qualysapi.qg2.apps.qualys.com
> Authorization: Basic cXVheXMya2I1ODpDVjA=
> User-Agent: curl/7.64.1
> Accept: */*
> X-Requested-With: curl
>
< HTTP/1.1 401 Unauthorized
< Date: Sat, 21 Dec 2019 19:51:00 GMT
< Server: Qualys
< Strict-Transport-Security: max-age=63072000;
< X-XSS-Protection: 1; mode=block
< X-Content-Type-Options: nosniff
< X-Frame-Options: SAMEORIGIN
< Strict-Transport-Security: max-age=31536000; includeSubDomains
< Transfer-Encoding: chunked
< Content-Type: text/xml;charset=UTF-8
<
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM "https://qualysapi.qg2.apps.qualys.com/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
<RESPONSE>
<DATETIME>2019-12-21T19:51:00Z</DATETIME>
<CODE>2000</CODE>
<TEXT>Bad Login/Password</TEXT>
</RESPONSE>
</SIMPLE_RETURN>
* Connection #0 to host qualysapi.qg2.apps.qualys.com left intact
* Closing connection 0

 

 

More about roles: User Roles Comparison (Vulnerability Management) 

Attachments

    Outcomes