Merge combines two compliance policies using Qualys Policy Audit (PA)/Policy Compliance (PC). You can merge specific parts of a new policy into an existing one as defined by the parameter options given under input parameters. The merged changes can also be previewed before saving. This API is available to Managers and Auditors.
For example, if you imported a policy from our library (Policy A) and configured it to add asset groups, controls, and sections. Later, an updated version of this policy (Policy B) with new controls and technologies may be released. In this scenario, you can use the Policy
Merge API to add the new controls and technologies from Policy B into Policy A (your existing policy) without losing the asset groups, controls, and sections you added.
The policy merge input parameters provide flexibility in merging different parts of a new policy (Policy B) into an existing one (Policy A). For example, you can update controls with revised definitions, replace asset groups, and add new technologies and controls. By default, no changes are applied to your existing policy unless the required parameters (see below) are specified:
Parameter |
Required/Optional |
Data Type |
Description |
---|---|---|---|
action=merge |
Required |
String |
Specifies the action type for merging the policies. |
ids={value} |
Required |
Integer |
ID of the policy that will be updated with merged content (let’s call this Policy A). |
merge_policy_id={value} -or- policy XML data |
Required |
Integer/ File |
Policy with the content that will be merged into Policy A (let's call this Policy B). You can specify a policy ID using "merge_policy_id" or policy XML data. To upload XML data, use this syntax: --data-binary @path_to_xml_file.xml These options are mutually exclusive: policy XML data and merge_policy_id. You must provide only one of the above options. If both options are provided, the API will return an error. |
replace_cover_page={0|1} |
Optional |
Integer |
Set replace_cover_page=1 to replace the cover page in Policy A with the cover page in Policy B. |
replace_asset_groups={0|1} |
Optional |
Integer |
Set replace_asset_groups=1 to replace asset groups in Policy A with asset groups in Policy B. These options are mutually exclusive: add_new_asset_groups and replace_asset_groups. You must provide only one of the above options. If both options are provided, the API will return an error. |
add_asset_groups={0|1} |
Optional |
Integer |
Set add_asset_groups=1 to add new asset groups, i.e. add asset groups from Policy B if they are not already present in Policy A. |
add_new_technologies={0|1} |
Optional |
Integer |
Set add_new_technologies=1 to add new technologies and to add technologies from Policy B if they are not already in Policy A. This will also add the technology within all controls already specified in the policy for which this technology is relevant. For example, consider a policy to have 20 controls, of which ten controls are applicable for centOS v4.0. You can add this technology to the policy to reflect these ten controls. |
add_new_controls={0|1} |
Optional |
Integer |
Set add_new_controls=1 to add new controls, i.e. add controls from Policy B if they are not already in Policy A. |
update_section_heading={0|1} |
Optional |
Integer |
Set update_section_heading=1 to replace the section heading in Policy A with the one in Policy B, based on section number (applies only to common sections). This parameter must be specified with: add_new_controls or update_existing_controls. |
update_existing_controls={0|1} |
Optional |
Integer | Set update_existing_controls=1 to replace the common controls in Policy A with the ones in Policy B. These are controls that exist in both policies. (Controls will not be removed). This setting currently updates the following properties of a control:
|
preview_merge={0|1} |
Optional |
Integer |
Set preview_merge= 1 to view the changes merged into Policy A without saving them. |
Policy ID 15993 (Policy A) will be updated with content merged from policy ID 15994 (Policy B) and the XML output will show the merged policy in preview mode. Policy changes will not be saved in Policy 15993 since the request includes “preview_merge=1”.
API Request
https://<qualys_base_url>/api/2.0/fo/compliance/policy/?action=merge&id=15993&merge_policy_id=15994&replace_cover_page=1&add_new_asset_groups=1&add_new_technologies=1&update_section_heading=1&add_new_controls=1&update_existing_controls=1&preview_merge=1
XML Output
<!DOCTYPE POLICY_MERGE_RESULT_OUTPUT SYSTEM "https://<qualys_base_url>/api/2.0/fo/compliance/policy/policy_merge_result_output.dtd">
<POLICY_MERGE_RESULT_OUTPUT>
<RESPONSE>
<DATETIME>2018-12-24T05:28:04Z</DATETIME>
<POLICY_MERGE_RESULT>
<NOTE>Policy changes were not merged or saved since the request had preview_merge=1.</NOTE>
<NEW_COVER_PAGE><![CDATA[My Cover Page]]></NEW_COVER_PAGE>
<ASSET_GROUPS_ADDED>
<ASSET_GROUP>
<ID>424422</ID>
<NAME><![CDATA[<script>alert("xss");</script>]]></NAME>
</ASSET_GROUP>
<ASSET_GROUP>
<ID>424577</ID>
<NAME><![CDATA[10.10.32.26]]></NAME>
</ASSET_GROUP>
</ASSET_GROUPS_ADDED>
<TECHNOLOGIES_ADDED>
<TECHNOLOGY>
<ID>1</ID>
<NAME>Windows XP desktop</NAME>
</TECHNOLOGY>
</TECHNOLOGIES_ADDED>
<SECTIONS_UPDATED>
<SECTION>
<ID>1</ID>
<HEADING><![CDATA[First section]]></HEADING>
</SECTION>
<SECTION>
<ID>2</ID>
<HEADING><![CDATA[Second section]]></HEADING>
</SECTION>
</SECTIONS_UPDATED>
<SECTIONS>
<SECTION>
<ID>1</ID>
<CONTROLS_UPDATED>
<CONTROL>
<ID>1061</ID>
</CONTROL>
</CONTROLS_UPDATED>
</SECTION>
<SECTION>
<ID>2</ID>
<CONTROLS_ADDED>
<CONTROL>
<ID>1045</ID>
</CONTROL>
<CONTROL>
<ID>1048</ID>
</CONTROL>
</CONTROLS_ADDED>
</SECTION>
</SECTIONS>
</POLICY_MERGE_RESULT>
</RESPONSE>
</POLICY_MERGE_RESULT_OUTPUT>
Policy ID 15993 (Policy A) will be updated with content merged from policy ID 15994 (Policy B). The merged policy will be saved in policy 15993.
API Request
https://<qualys_base_url>/api/2.0/fo/compliance/policy/?action=merge&id=15993&merge_policy_id=15994&replace_cover_page=1&add_new_asset_groups=1&add_new_technologies=1&update_section_heading=1&add_new_controls=1&update_existing_controls=1&preview_merge=0
XML Output
<!DOCTYPE POLICY_MERGE_RESULT_OUTPUT SYSTEM "https://<qualys_base_url>/api/2.0/fo/compliance/policy/policy_merge_result_output.dtd">
<POLICY_MERGE_RESULT_OUTPUT>
<RESPONSE>
<DATETIME>2013-12-24T05:31:26Z</DATETIME>
<POLICY_MERGE_RESULT>
<NOTE>Policy changes have been merged successfully.</NOTE>
<NEW_COVER_PAGE><![CDATA[My Cover Page]]></NEW_COVER_PAGE>
<ASSET_GROUPS_ADDED>
<ASSET_GROUP>
<ID>424422</ID>
...
</POLICY_MERGE_RESULT>
</RESPONSE>
</POLICY_MERGE_RESULT_OUTPUT>
Policy ID 15993 (Policy A) will be updated with content merged from the policy defined in the file “path_to_policy_xml_file.xml.” The merged changes will not be saved in policy 15993 since the request includes “preview_merge=1”.
API Request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With: curl" -H "Content-type: text/xml" "https://<qualys_base_url>/api/2.0/fo/compliance/policy/?action=merge&id=15993&replace_cover_page=1&replace_asset_groups=1&add_new_technologies=1&update_section_heading=1&add_new_controls=1&update_existing_controls=1&preview_merge=1" --data-binary @/home/aamin/PC_XML/path_to_policy_xml_file.xml>
XML Output
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE POLICY_MERGE_RESULT_OUTPUT SYSTEM
"https://<qualys_base_url>/api/2.0/fo/compliance/policy/policy_merge_result_output.dtd">
<POLICY_MERGE_RESULT_OUTPUT>
<RESPONSE>
<DATETIME>2018-04-24T05:38:26Z</DATETIME>
<POLICY_MERGE_RESULT>
<NOTE>Policy changes were not merged or saved since the request had preview_merge=1.</NOTE>
<NEW_COVER_PAGE><![CDATA[My Cover Page]]></NEW_COVER_PAGE>
<SECTIONS_UPDATED>
<SECTION>
<ID>1</ID>
<HEADING><![CDATA[First section]]></HEADING>
</SECTION>
<SECTION>
<ID>2</ID>
<HEADING><![CDATA[Second section]]></HEADING>
</SECTION>
</SECTIONS_UPDATED>
<SECTIONS>
<SECTION>
<ID>1</ID>
<CONTROLS_UPDATED>
<CONTROL>
<ID>1061</ID>
</CONTROL>
</CONTROLS_UPDATED>
</SECTION>
<SECTION>
<ID>2</ID>
<CONTROLS_ADDED>
<CONTROL>
<ID>1045</ID>
</CONTROL>
<CONTROL>
<ID>1048</ID>
</CONTROL>
</CONTROLS_ADDED>
</SECTION>
</SECTIONS>
</POLICY_MERGE_RESULT>
</RESPONSE>
</POLICY_MERGE_RESULT_OUTPUT>
<platform API server>/api/2.0/fo/compliance/policy/policy_merge_result_output.dtd
Was this topic helpful?