Using the Qualys API? You'll see the following API changes when AGMS is enabled for your subscription.
Jump to a section below:
List Asset Group: All group is no longer listed in output
List Asset Group: List asset groups with business unit IDs
List Asset Group: Output will now show domain netblocks
Update IPs: Unit Managers/Scanners must specify network ID
Add User: Asset Groups cannot be assigned to Contact user
Scan List: Update to Scan List Output for Sub-Users
The Asset Group API will not list the "ALL" group in the XML output. The API will only list individual asset groups. Here is a sample when AGMS is enabled.
curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -X "POST" -d
"action=list"
"https://qualysapi.qualys.com/api/2.0/fo/asset/group/"
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE ASSET_GROUP_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/asset/group/asset_group_list_output.dtd">
<ASSET_GROUP_LIST_OUTPUT>
<REQUEST>
<DATETIME>2019-11-09T08:22:20Z</DATETIME>
<USER_LOGIN>john_doe</USER_LOGIN>
<RESOURCE>https://qualysapi.qualys.com/api/2.0/fo/asset/group/</RESOURCE>
<PARAM_LIST>
<PARAM>
<KEY>action</KEY>
<VALUE>list</VALUE>
</PARAM>
</PARAM_LIST>
</REQUEST>
<RESPONSE>
<DATETIME>2019-11-09T08:22:20Z</DATETIME>
<ASSET_GROUP_LIST>
<ASSET_GROUP>
<ID>1024368</ID>
<TITLE><![CDATA[AG_VM_1]]></TITLE>
<NETWORK_ID>0</NETWORK_ID>
<IP_SET>
<IP_RANGE>10.10.30.10-10.10.30.30</IP_RANGE>
</IP_SET>
</ASSET_GROUP>
...
<ASSET_GROUP>
<ID>7038084</ID>
<TITLE><![CDATA[Windows]]></TITLE>
<NETWORK_ID>0</NETWORK_ID>
<IP_SET>
<IP>10.10.10.81</IP>
</IP_SET>
</ASSET_GROUP>
</ASSET_GROUP_LIST>
</RESPONSE>
</ASSET_GROUP_LIST_OUTPUT>
Now when you list asset groups and include show_attributes=ASSIGNED_UNIT_IDS in the request, you won’t see any asset groups listed for business units with the All asset group.
curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -X "POST" -d
"action=list&echo_request=1&show_attributes=ASSIGNED_UNIT_IDS"
"https://qualysapi.qualys.com/api/2.0/fo/asset/group/"
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE ASSET_GROUP_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/asset/group/asset_group_list_output.dtd">
<ASSET_GROUP_LIST_OUTPUT>
<RESPONSE>
<DATETIME>2020-02-05T05:18:05Z</DATETIME>
</RESPONSE>
</ASSET_GROUP_LIST_OUTPUT>
Now when you list asset groups and you include show_attributes=All in the request, the domain list in the output will show the netblock for each domain when a netblock has been defined. Without AGMS you won’t see netblock information in the output.
curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -X "POST" -d
"action=list&ids=5443081&show_attributes=ALL"
"https://qualysapi.qualys.com/api/2.0/fo/asset/group/"
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE ASSET_GROUP_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/asset/group/asset_group_list_output.dtd">
<ASSET_GROUP_LIST_OUTPUT>
<RESPONSE>
<DATETIME>2020-01-16T04:16:38Z</DATETIME>
<ASSET_GROUP_LIST>
<ASSET_GROUP>
<ID>5443081</ID>
<TITLE><![CDATA[AG1]]></TITLE>
<OWNER_USER_ID>64060</OWNER_USER_ID>
<LAST_UPDATE>2020-01-16T04:16:07Z</LAST_UPDATE>
<BUSINESS_IMPACT>High</BUSINESS_IMPACT>
<CVSS_ENVIRO_CDP>Not Defined</CVSS_ENVIRO_CDP>
<CVSS_ENVIRO_TD>Not Defined</CVSS_ENVIRO_TD>
<CVSS_ENVIRO_CR>Not Defined</CVSS_ENVIRO_CR>
<CVSS_ENVIRO_IR>Not Defined</CVSS_ENVIRO_IR>
<CVSS_ENVIRO_AR>Not Defined</CVSS_ENVIRO_AR>
<DOMAIN_LIST>
<DOMAIN netblock="10.10.10.10-10.10.10.12">abc123.com</DOMAIN>
</DOMAIN_LIST>
<COMMENTS><![CDATA[My-Comments]]></COMMENTS>
<OWNER_USER_NAME><![CDATA[Joe User (Manager)]]></OWNER_USER_NAME>
</ASSET_GROUP>
</ASSET_GROUP_LIST>
</RESPONSE>
</ASSET_GROUP_LIST_OUTPUT>
When a Unit Manager or Scanner with the "Add assets" permission adds new IPs to the subscription the user must pick an asset group to add the IPs to. The options available depend on whether the user was assigned the All group.
- When the user making the request was assigned the All group (with or without other asset groups) the user must specify ag_title=All in the API request. The user must also specify network_id in the request if the subscription has the Network Support feature enabled.
- When the user making the request was NOT assigned the All group, the user must specify the title of one of their assigned asset groups, and network_id is optional for accounts with the Network Support feature enabled.
In this sample, ag_title=All and network_id=114075 is specified in the request.
curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -X "POST" -d
"action=add&ips=10.111.25.20&enable_vm=1&ag_title=All&network_id=114075"
"https://qualysapi.qualys.com/api/2.0/fo/asset/ip/"
<?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>2020-01-20T06:33:49Z</DATETIME>
<TEXT>IPs successfully added to Vulnerability Management</TEXT>
</RESPONSE>
</SIMPLE_RETURN>
In this sample, ag_title=All is NOT specified in the request (a different group is specified) but the user making the request was assigned the All group. The message “All is assigned to user, so please specify All in ag_title” appears in the output.
curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -X "POST" -d
"action=add&echo_request=0&ips=10.111.25.20&enable_vm=1&ag_title=MyGroup"
"https://qualysapi.qualys.com/api/2.0/fo/asset/ip/"
<?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>2020-01-20T06:33:49Z</DATETIME>
<CODE>1905</CODE>
<TEXT>All is assigned to user, so please specify All in ag_title</TEXT>
</RESPONSE>
</SIMPLE_RETURN>
When a Unit Manager or Scanner updates IPs using the API, the user must specify network_id in the request if the subscription has the Network Support feature enabled.
curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -d
"action=update&ips=1.1.1.1-1.1.1.254&network_id=114075&tracking_method=DNS"
"https://qualysapi.qualys.com/api/2.0/fo/asset/ip/"
<?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>2020-02-20T09:42:12Z</DATETIME>
<TEXT>IPs successfully updated</TEXT>
</RESPONSE>
</SIMPLE_RETURN>
When a Unit Manager or Scanner with the “Manage virtual scanner appliances” permission adds new virtual scanner appliances to the subscription the user must pick an asset group to add the scanner to. The asset group ID specified in the API request must be a valid asset group ID in the user’s account. If the Unit Manager/Scanner has been assigned the All group then the user will have the Manager created asset groups which are in scope of the business unit belonging to the user, as previously described. The user can specify the ID for any of the Manager created asset groups in their scope when adding a scanner appliance.
In the example below, the user specified a valid asset group ID in their account.
curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -d
"action=create&name=MyScanner&asset_group_id=5480600"
"https://qualysapi.qualys.com/api/2.0/fo/appliance/"
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE APPLIANCE_LIST_OUTPUT SYSTEM
"https://qualysapi.qualys.com/api/2.0/fo/appliance/appliance_create_output.dtd">
<APPLIANCE_CREATE_OUTPUT>
<RESPONSE>
<DATETIME>2020-01-28T05:11:12Z</DATETIME>
<ID>777</ID>
<NAME>MyScanner</NAME>
<ACTIVATION CODE>70171268144764</ACTIVATION CODE>
<REMAINING_QVSA_LICENSES>4</REMAINING_QVSA_LICENSES>
</RESPONSE>
</APPLIANCE_CREATE_OUTPUT>
In the example below, the user specified an asset group ID that is not in their account so the message “parameter asset_group_id has invalid value” appears in the output.
curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -d
"action=create&name=MyScanner&asset_group_id=5475586"
"https://qualysapi.qualys.com/api/2.0/fo/appliance/"
<?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>2020-01-28T05:11:12Z</DATETIME>
<CODE>1905</CODE>
<TEXT>parameter asset_group_id has invalid value (Given Asset Group is not in user's scope: 5475586)</TEXT>
</RESPONSE>
</SIMPLE_RETURN>
When AGMS is enabled users with the Contact user role cannot be assigned asset groups. When you create a new Contact user using the Add User API (/msp/user.php) you’ll get an error when you include asset groups in the request. Here’s an example of a request to add a new Contact user and asset group AG1 is specified in the request.
curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -d
"action=add&user_role=contact&business_unit=BU1&first_name=Joe&last_name=User&title=Security+Consultant&phone=6508016100&email=joe_user@qualys.com&address1=919+Hillsdale+Blvd&city=Foster+City&country=United+States+of+America&state=California&zip_code=94404"
"https://qualysapi.qualys.com/msp/user.php"
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE USER_OUTPUT SYSTEM "https://qualysapi.qualys.com/user_output.dtd">
<USER_OUTPUT>
<API name="user.php" username="user" at="2019-11-05T04:24:50Z" />
<RETURN status="FAILED" number="1905">
<MESSAGE><![CDATA[Invalid value for 'asset_groups' : AG1. This asset group is not accessible.]]></MESSAGE>
</RETURN>
</USER_OUTPUT>
The VM Scan List API (/api/2.0/fo/scan/?action=list) is used to list vulnerability scans in the user's account. The Compliance Scan List API (/api/2.0/fo/scan/compliance/?action=list) is used to list compliance scans in the user's account.
We made changes to the list of scans that are visible to sub-users. When a sub-user uses the API to list vulnerability or compliance scans, the XML output will include the following scans:
- Scans launched by the sub-user
- Finished scans launched by Managers on the user's assigned assets (assets in your user scope). Sub-users will only see scans by their Managers that are finished with scan results that have been processed.
When an asset in the sub-user's scope has been purged by a Manager, scans for that asset will no longer appear in the scan list for the sub-user.
See Changes to Scans List to learn more.
curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -d
"action=list" "https://qualysapi.qualys.com/api/2.0/fo/scan/"
curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -d
"action=list" "https://qualysapi.qualys.com/api/2.0/fo/scan/compliance/"
Several error messages have changed.
Old message:
<TEXT>parameter title has invalid value: An asset group with title ‘Title' already exists. Please use a different title</TEXT>
New message:
<TEXT> (Asset Group name - An asset group with name Title already exists. Please use a different title)</TEXT>
Old message:
<TEXT>parameter Asset Group has invalid value: Tried to delete invalid Asset Group - NNNN. Asset Group id does not exist or you do not have permission to delete this Asset Group</TEXT>
New message:
<TEXT> (Invalid Parameter Ids Data not found for Asset Group, NNNN)</TEXT>
Old message:
<TEXT> parameter IPs has invalid value: One or more IPs are not assigned to this user: N.N.N.N-N.N.N.N</TEXT>
New message:
<TEXT> (IPs N.N.N.N-N.N.N.N are not in user account scope.)</TEXT>