Qualys API Release Notes

(1)

Version 8.3



November 15, 2014

Qualys 8.3 includes improvements to the Qualys API, giving you more ways to integrate your programs and API calls with Qualys Vulnerability Management (VM) and Qualys Policy

Compliance (PC). Looking for our API user guides? Just log in to your Qualys account and go to Help > Resources.

What’s New

New Authentication Vault API v2

Tell me about the base URL Our documentation and sample code use the API server URL for Qualys US Platform 1. Do you have another base URL? If yes please use it instead.

Account Login Base URL

Qualys US Platform 1 https://qualysapi.qualys.com

Qualys US Platform 2 https://qualysapi.qg2.apps.qualys.com Qualys EU Platform https://qualysapi.qualys.eu

(2)

New Authentication Vault API v2

The new Vault API (/api/2.0/fo/vault) allows you to manage authentication vaults for authentication records that use them. Using this API you can list vaults, create new vaults, update and view vault settings, and delete vaults.

Permissions: Managers, Unit Managers and Scanners can view vaults and their settings. Managers can perform more functions (create, update, delete). Unit Managers can perform these functions if they are granted the permission “Create/edit authentication records/vaults”.

List vaults

Use the parameter “action=list” to list the vaults defined in your account. API request:

curl -u "USERNAME:PASSWD" -H "X-Requested-With: curl" -d "action=list" "https://qualysapi.qualys.com/api/2.0/fo/vault/"

XML output:

<?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE AUTH_VAULT_LIST_OUTPUT SYSTEM

"https://qualysapi.qualys.com/api/2.0/fo/vault/vault_output.dtd"> <AUTH_VAULT_LIST_OUTPUT> <RESPONSE> <DATETIME>2014-09-12T13:55:57Z</DATETIME> <STATUS>Success</STATUS> <COUNT>13</COUNT> <AUTH_VAULTS> <AUTH_VAULT> <TITLE>

<![CDATA[added failover ip]]> </TITLE>

<VAULT_TYPE>

<![CDATA[Cyber-Ark PIM Suite]]> </VAULT_TYPE> <LAST_MODIFIED> <DATETIME>2014-02-13T12:05:21Z</DATETIME> <BY>quays_rn1</BY> </LAST_MODIFIED> <ID>1421</ID> </AUTH_VAULT> <AUTH_VAULT> <TITLE>

(3)

</TITLE> <VAULT_TYPE>

<![CDATA[Cyber-Ark PIM Suite]]> </VAULT_TYPE> <LAST_MODIFIED> <DATETIME>2014-02-19T06:43:44Z</DATETIME> <BY>quays_rn1</BY> </LAST_MODIFIED> <ID>1441</ID> </AUTH_VAULT> <AUTH_VAULT> <TITLE> <![CDATA[Blue]]> </TITLE> <VAULT_TYPE>

<![CDATA[CA Access Control]]> </VAULT_TYPE> <LAST_MODIFIED> <DATETIME>2013-09-21T05:26:32Z</DATETIME> <BY>quays_rn1</BY> </LAST_MODIFIED> <ID>1406</ID> </AUTH_VAULT> </AUTH_VAULTS> </RESPONSE> </AUTH_VAULT_LIST_OUTPUT> Parameters: Parameter Description action=list (Required)

echo_request={0|1} (Optional) Set to 1 to show (echo) the request’s input parameters (names and value) in the XML output. title={value} (Optional) Include vaults matching this title.

type={value} (Optional) Include a certain vault type only. A valid value is: Cyber-Ark PIM Suite

Thycotic Secret Server Quest Vault

CA Access Control Hitachi ID PAM Lieberman ERPM

modified={date} (Optional) Include vaults modified on or after a certain date/time, in this format: YYYY-MM-DD[THH:MM:SSZ] (UTC/GMT).

(4)

More sample requests:

1) List all vaults, order vaults by system name

curl -H "X-Requested-With:API" -u "USERNAME:PASSWD" -d "action=list&orderby=system_name"

"https://qualysapi.qualys.com/api/2.0/fo/vault/index.php/?"

2) List all vaults, order vaults by title in descending order

curl -H "X-Requested-With:API" -u "USERNAME:PASSWD" -d "action=list&sortorder=desc&title"

"https://qualysapi.eng.qualys.com/api/2.0/fo/vault/index.php/?"

3) List only 9th and 10th vault records

curl -H "X-Requested-With:API" -u "USERNAME:PASSWD" -d "action=list&limit=2&offset=9"

"https://qualysapi.qualys.com/api/2.0/fo/vault/index.php/?"

orderby={value} (Optional) Sort the vaults list by certain data. One of: “id”, “title”, “system_name”, “last_modified”,

“last_modified_by”. A date must be specified in YYYYMM-DD[THH:MM:SSZ] format (UTC/GMT).

sortorder={asc|desc} (Optional) The sort order, used when the request includes the

orderby parameter. One of: asc (for ascending order) or desc (for descending order).

limit={value} (Optional) The maximum number of vault records processed for the request, starting at the record number specified by the

offset parameter. These parameters must be specified together: limit and offset.

When not specified, default limit is set to 1,000 vault records. You can specify a value less than or greater than the default. It’s possible to specify “limit=0” for no limit. In this case the output is not paginated and all records are returned in a single output. Warning: This is not recommended since it may generate a very large output and processing large XML files can consume a lot of resources on the client side. offset={value} (Optional) The starting vault record number, used only when

the request includes the limit parameter.

(5)

Create a new vault

Use the parameter “action=create”. Parameters:

API request:

curl -u "USERNAME:PASSWD" -H "X-Requested-With: curl" -X "POST" -d

"title=My+Vault&type=Cyber-Ark+PIM+Suite&server_address=123.123.123.123&p ort=1858&safe=mysafe1&username=someusername&password=somepasswd"

"https://qualysapi.qualys.com/api/2.0/fo/vault/?action=create"

XML output:

<?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>2014-09-12T14:13:28Z</DATETIME> <TEXT>Success</TEXT> <ITEM_LIST> <ITEM> <KEY>ID</KEY> <VALUE>14836922</VALUE> </ITEM> </ITEM_LIST> </RESPONSE> </SIMPLE_RETURN> Parameter Description action=create (Required)

title={value} (Required) The vault title.

type={value} (Required) The vault type. A valid value is: Cyber-Ark PIM Suite

Thycotic Secret Server Quest Vault

CA Access Control Hitachi ID PAM Lieberman ERPM

comments={value} (Optional) User defined comments. {vault settings} Tell me about vault settings

(6)

Update vault settings

Use the parameter “action=update”. Parameters:

API request:

curl -u "USERNAME:PASSWD" -H "X-Requested-With: curl" -X "POST" -d "id=14836922&server_address=10.10.10.10"

"https://qualysapi.qualys.com/api/2.0/fo/vault/?action=update"

XML output:

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd"> <SIMPLE_RETURN> <RESPONSE> <DATETIME>2014-09-12T14:13:28Z</DATETIME> <TEXT>Success</TEXT> <ITEM_LIST> <ITEM> <KEY>ID</KEY> <VALUE>14836922</VALUE> </ITEM> </ITEM_LIST> </RESPONSE> </SIMPLE_RETURN>

View vault settings

Use the parameter “action=view”.

Parameter Description

action=update (Required)

id={value} (Required) A vault ID.

title={value} (Optional) A new title to replace the existing title. comments={value} (Optional) User defined comments.

{vault settings} Tell me about vault settings

Parameter Description

action=view (Required)

(7)

API request:

curl -u "USERNAME:PASSWD" -H "X-Requested-With: curl" "id=14836922"

"https://qualysapi.qualys.com/api/2.0/fo/vault/?action=view"

XML output:

<?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE VAULT_OUTPUT SYSTEM

"https://qualysapi.qualys.com/api/2.0/fo/vault/vault_view.dtd"> <VAULT_OUTPUT> <RESPONSE> <DATETIME>2014-09-12T14:25:04Z</DATETIME> <VAULT_QUEST> <TITLE> <![CDATA[My vault]]> </TITLE> <COMMENTS> <![CDATA[Some comments]]> </COMMENTS> <VAULT_TYPE>

<![CDATA[Thycotic Secret Server]]> </VAULT_TYPE> <CREATED_ON>2014-09-12T14:13:28Z</CREATED_ON> <OWNER>acme_ab1</OWNER> <LAST_MODIFIED> <DATETIME>2014-09-12T14:13:28Z</DATETIME> <BY>acme_ab1</BY> </LAST_MODIFIED> <USERNAME> <![CDATA[acme_ab1]]> </USERNAME> <URL> <![CDATA[https://corp1.corp.com]]> </URL> <DOMAIN> <![CDATA[corp-test.com]]> </DOMAIN> <ID>14836922</ID> </VAULT_QUEST> </RESPONSE> </VAULT_OUTPUT>

(8)

Delete a vault

Use the parameter “action=delete”.

API request:

curl -u "USERNAME:PASSWD" -H "X-Requested-With: curl" -d "id=43463" "https://qualysapi.qualys.com/api/2.0/fo/vault/?action=delete"

XML output:

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd"> <SIMPLE_RETURN> <RESPONSE> <DATETIME>2014-09-12T14:13:28Z</DATETIME> <TEXT>Success</TEXT> <ITEM_LIST> <ITEM> <KEY>Status</KEY> <VALUE>Deleted</VALUE> </ITEM> </ITEM_LIST> </RESPONSE> </SIMPLE_RETURN> Parameter Description action=view (Required)

(9)

Tell me about vault settings

The vault settings differ per vault type. CA Access Control

ca_url={value} (Required for new vault) The HTTP or HTTPS URL of the CA Access Control web services, an API interface to your CA Access Control Enterprise Management installation. Note that the web services URL is different from the web management URL.

Sample web services URL:

http://caac126u-32-235.caac125.domain.com:18080/iam/TE WS6/ac

Sample web management URL:

http://caac126p-33-166.caac125.domain.com:18080/iam/ac/ ca_api_username={value} (Required for new vault) The name of a user that is granted

GetAccountPassword API permissions.

ca_ssl_verify={1|0} (Required for new vault) When set to 1, our service will verify the SSL certificate of the web server to make sure the certificate is valid and trusted. When set to 0 our service will not verify the certificate of the web server.

ca_web_username={value} (Optional) The web user name used to access Basic Authentication of the CA Access Control web server. ca_web_password={value} (Optional) The web password used to access Basic

Authentication of the CA Access Control web server.

Cyber-Ark PIM Suite

server_address={value} (Required for new vault) The IP address of the vault server that stores system login credentials to be used.

port={value} (Optional) The port the vault server is running on. The port must be in the range 1025 to 65535. For a new vault the port is set to 1858 by default, if the port parameter is not specified. safe={value} (Required for new vault) The name of the digital password safe. The safe name can contain a maximum of 28 characters (leading and/or trailing space in the input value will be removed). These special characters cannot be included in a safe name: \ / : * ? " < > . |

username={value} (Required for new vault) The username for an account with access to your Cyber-Ark PIM Suite environment.

password={value} (Required for new vault) The password for an account with access to your Cyber-Ark PIM Suite environment.

(10)

Hitachi ID PAM

url={value} (Required for new vault) The HTTP or HTTPS URL of the Hitachi ID PAM webservices.

username={value} (Required for new vault) The username (ID) for the Hitachi ID PAM user account. To allow Qualys scanners to connect using this account, this user must have the following settings under Administrator information in the Hitachi ID Management Suite: 1) the privilege “OTP IDAPI caller” and 2) the value entered in the “IP address with CIDR bitmask” field must include the Qualys scanner IP addresses.

password={value} (Required for new vault) The password for the Hitachi ID PAM user account.

ssl_verify={1|0} (Required for new vault) When set to 1, our service will verify the SSL certificate of the web server to make sure the certificate is valid and trusted. When set to 0 our service will not verify the certificate of the web server.

Lieberman ERPM

url={value} (Required for new vault) The HTTP or HTTPS URL of the Lieberman ERPM server.

domain={value} (Optional) A domain name if your Lieberman ERPM server is part of a domain.

username={value} (Required for new vault) The username for the Lieberman ERPM server account.

password={value} (Required) The password for the Lieberman ERPM server account.

ssl_verify={1|0} (Required for new vault) Our service will verify the SSL certificate of the web server to make sure the certificate is valid and trusted, unless you set ssl_verify=0. For a new vault the default is set to 1 (i.e. verify).

Quest Vault

server_address={value} (Required for new vault) The IP address of the vault server, Quest One Privileged Password Manager.

port={value} (Optional) The listing port of the vault server. For a new vault the port is set to 22 by default, if the port parameter is not specified.

username={value} (Required for new vault) The username to be used for SSH authentication. We recommend you create a dedicated user account for Qualys scanning. Using Quest/Dell 2.4 or higher, enter the key for the API user account you've created for use with our service. We support both API and CLI keys but recommend use of an API key.

(11)

access_key={value} (Required for new vault) The DSA private key in PEM format for SSH authentication.

Thycotic Secret Server

url={value} (Required for new vault) The HTTP or HTTPS URL of the Secret Server webservices. The URL may contain a maximum of 256 characters, and must not contain multibyte characters. username={value} (Required for new vault) The username for a Secret Server

user. This user must have access to the secret names to be used for authentication.

password={value} (Required for new vault) The password for a Secret Server user.

domain={value} (Optional) Specify a fully qualified domain name if Secret Server is integrated with Active Directory. The domain may contain a maximum of 128 characters, and must not contain any multibyte characters.