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

 


 

 

Was this topic helpful?

success Thank you! We're glad to hear that this topic was useful.
success We appreciate your feedback. We'll work to make this topic better for you in the future.