Qualys API Release Notes

Transcription

1 Qualys API Release Notes 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 Qualys US Platform 1 Qualys US Platform 2 Qualys EU Platform Qualys Private Cloud Platform Base URL Copyright 2014 by Qualys, Inc. All Rights Reserved.

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" " XML output: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE AUTH_VAULT_LIST_OUTPUT SYSTEM " <AUTH_VAULT_LIST_OUTPUT> <RESPONSE> <DATETIME> T13: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> T12:05:21Z</DATETIME> <BY>quays_rn1</BY> </LAST_MODIFIED> <ID>1421</ID> </AUTH_VAULT> <AUTH_VAULT> <TITLE> <![CDATA[added failover ip1]]> Qualys API Release Notes 2

3 </TITLE> <VAULT_TYPE> <![CDATA[Cyber-Ark PIM Suite]]> </VAULT_TYPE> <LAST_MODIFIED> <DATETIME> T06: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> T05:26:32Z</DATETIME> <BY>quays_rn1</BY> </LAST_MODIFIED> <ID>1406</ID> </AUTH_VAULT> </AUTH_VAULTS> </RESPONSE> </AUTH_VAULT_LIST_OUTPUT> s: action=list echo_request={0 1} title={value} type={value} modified={date} (Required) (Optional) Set to 1 to show (echo) the request s input parameters (names and value) in the XML output. (Optional) Include vaults matching this title. (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 (Optional) Include vaults modified on or after a certain date/time, in this format: YYYY-MM-DD[THH:MM:SSZ] (UTC/GMT). Qualys API Release Notes 3

4 orderby={value} sortorder={asc desc} limit={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). (Optional) The sort order, used when the request includes the orderby parameter. One of: asc (for ascending order) or desc (for descending order). (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. offset={value} 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. (Optional) The starting vault record number, used only when the request includes the limit parameter. 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" " 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" " 3) List only 9th and 10th vault records curl -H "X-Requested-With:API" -u "USERNAME:PASSWD" -d "action=list&limit=2&offset=9" " Qualys API Release Notes 4

5 Create a new vault Use the parameter action=create. s: action=create title={value} type={value} comments={value} {vault settings} (Required) (Required) The vault title. (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 (Optional) User defined comments. Tell me about vault settings API request: curl -u "USERNAME:PASSWD" -H "X-Requested-With: curl" -X "POST" -d "title=my+vault&type=cyber-ark+pim+suite&server_address= &p ort=1858&safe=mysafe1&username=someusername&password=somepasswd" " XML output: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE SIMPLE_RETURN SYSTEM " <SIMPLE_RETURN> <RESPONSE> <DATETIME> T14:13:28Z</DATETIME> <TEXT>Success</TEXT> <ITEM_LIST> <ITEM> <KEY>ID</KEY> <VALUE> </VALUE> </ITEM> </ITEM_LIST> </RESPONSE> </SIMPLE_RETURN> Qualys API Release Notes 5

6 Update vault settings Use the parameter action=update. s: action=update id={value} title={value} comments={value} {vault settings} (Required) (Required) A vault ID. (Optional) A new title to replace the existing title. (Optional) User defined comments. Tell me about vault settings API request: curl -u "USERNAME:PASSWD" -H "X-Requested-With: curl" -X "POST" -d "id= &server_address= " " XML output: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE SIMPLE_RETURN SYSTEM " <SIMPLE_RETURN> <RESPONSE> <DATETIME> T14:13:28Z</DATETIME> <TEXT>Success</TEXT> <ITEM_LIST> <ITEM> <KEY>ID</KEY> <VALUE> </VALUE> </ITEM> </ITEM_LIST> </RESPONSE> </SIMPLE_RETURN> View vault settings Use the parameter action=view. action=view id={value} (Required) (Required) A vault ID. Qualys API Release Notes 6

7 API request: curl -u "USERNAME:PASSWD" -H "X-Requested-With: curl" "id= " " XML output: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE VAULT_OUTPUT SYSTEM " <VAULT_OUTPUT> <RESPONSE> <DATETIME> T14: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> T14:13:28Z</CREATED_ON> <OWNER>acme_ab1</OWNER> <LAST_MODIFIED> <DATETIME> T14:13:28Z</DATETIME> <BY>acme_ab1</BY> </LAST_MODIFIED> <USERNAME> <![CDATA[acme_ab1]]> </USERNAME> <URL> <![CDATA[ </URL> <DOMAIN> <![CDATA[corp-test.com]]> </DOMAIN> <ID> </ID> </VAULT_QUEST> </RESPONSE> </VAULT_OUTPUT> Qualys API Release Notes 7

8 Delete a vault Use the parameter action=delete. action=view id={value} (Required) (Required) A vault ID. API request: curl -u "USERNAME:PASSWD" -H "X-Requested-With: curl" -d "id=43463" " XML output: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE SIMPLE_RETURN SYSTEM " <SIMPLE_RETURN> <RESPONSE> <DATETIME> T14:13:28Z</DATETIME> <TEXT>Success</TEXT> <ITEM_LIST> <ITEM> <KEY>Status</KEY> <VALUE>Deleted</VALUE> </ITEM> </ITEM_LIST> </RESPONSE> </SIMPLE_RETURN> Qualys API Release Notes 8

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: WS6/ac ca_api_username={value} ca_ssl_verify={1 0} ca_web_username={value} ca_web_password={value} Cyber-Ark PIM Suite server_address={value} port={value} safe={value} username={value} password={value} Sample web management URL: (Required for new vault) The name of a user that is granted GetAccountPassword API permissions. (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. (Optional) The web user name used to access Basic Authentication of the CA Access Control web server. (Optional) The web password used to access Basic Authentication of the CA Access Control web server. (Required for new vault) The IP address of the vault server that stores system login credentials to be used. (Optional) The port the vault server is running on. The port must be in the range 1025 to For a new vault the port is set to 1858 by default, if the port parameter is not specified. (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: \ / : *? " < >. (Required for new vault) The username for an account with access to your Cyber-Ark PIM Suite environment. (Required for new vault) The password for an account with access to your Cyber-Ark PIM Suite environment. Qualys API Release Notes 9

10 Hitachi ID PAM url={value} username={value} password={value} ssl_verify={1 0} Lieberman ERPM url={value} domain={value} username={value} password={value} ssl_verify={1 0} Quest Vault server_address={value} port={value} username={value} (Required for new vault) The HTTP or HTTPS URL of the Hitachi ID PAM webservices. (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. (Required for new vault) The password for the Hitachi ID PAM user account. (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. (Required for new vault) The HTTP or HTTPS URL of the Lieberman ERPM server. (Optional) A domain name if your Lieberman ERPM server is part of a domain. (Required for new vault) The username for the Lieberman ERPM server account. (Required) The password for the Lieberman ERPM server account. (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). (Required for new vault) The IP address of the vault server, Quest One Privileged Password Manager. (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. (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. Qualys API Release Notes 10

11 access_key={value} Thycotic Secret Server url={value} username={value} password={value} domain={value} (Required for new vault) The DSA private key in PEM format for SSH authentication. (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. (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. (Required for new vault) The password for a Secret Server user. (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. Qualys API Release Notes 11