Policy Merge

GET POST/api/2.0/fo/compliance/policy/?action=merge

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.

Input ParametersInput Parameters

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: Status in terms of enabling or disabling the control Criticality Reference text Control evaluation Operator and Value Set/Unset Fixed values
preview_merge={0\|1}	Optional	Integer	Set preview_merge= 1 to view the changes merged into Policy A without saving them.

Sample - Preview Merged PoliciesSample - Preview Merged Policies

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>

Sample - Save Merged PoliciesSample - Save Merged Policies

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>

Sample - Pass Policy XML, Preview Merged PolicySample - Pass Policy XML, Preview Merged Policy

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>

DTD

<platform API server>/api/2.0/fo/compliance/policy/policy_merge_result_output.dtd