Configuring the Unified Agent Scan for Policy Check
This article will help you understand the different configuration parameters that can be used to configure the behavior of the Unified Agent scan regarding policies. It will provide you with information about the behavior of each parameter, along with examples to help you select the configuration that best suits your needs.
Introduction
Policies define a set of rules that reflect how an organization can handle specific conditions detected in the open-source libraries used by its software. These can include:
Restrictive license types
High-security vulnerabilities
Interdepartmental workflows
Mend enables users to enforce policies automatically throughout their Software Development Life Cycle (SDLC).
The Unified Agent (UA) is a Java command-line tool that scans directories' open-source components for vulnerable libraries, source files, and license compliance. It uploads the results to the Mend web application. Throughout this article, we will refer to the Unified Agent by its acronym, UA.
Policies can be applied during the UA scan, performed independently, or as part of a pipeline.
By applying the policies during the UA scan, an organization can bring awareness to specific conditions detected in the open-source code or even fail a build based on these conditions, preventing open-source code that doesn’t comply with the organization’s policy from being added to the inventory.
Prerequisites
Policies must first be set via the Mend UI or API. You can read more about setting up policies here: https://docs.mend.io/bundle/sca_user_guide/page/managing_automated_policies.html
Once set, policies can be used to change the behavior of a UA scan.
Unified Agent policy parameters & examples
The UA can be configured using environment variables or configuration parameters as described here: https://docs.mend.io/bundle/unified_agent/page/unified_agent_configuration_parameters.html
Below is a list of all policy parameters that can be configured for the UA scan. Their explanations and examples can be found in their respectively-named sections in this article:
checkPoliciesforceCheckAllDependenciesupdateInventoryforceUpdateforceUpdate.failBuildOnPolicyViolation
checkPolicies
The checkPolicies parameter is set to false by default.
When set to false, the UA will not perform any policy check, and no policy-related data will be generated.
Setting checkPolicies=true will trigger a policy check.
This check is only designed to trigger a violation if any of the libraries scanned into your inventory have a feature about them (such as a specific license or a vulnerability) that has a “reject” type policy set for it in the Mend application.
Example: If a reject type policy is set for an MIT license, and a library with an MIT license is scanned with checkPolicies=false, the scan will complete successfully.
However, if checkPolicies=true, the scan will fail with exit code POLICY_VIOLATION (-2)
The checkPolicies parameter allows an organization to fail the build by using the exit code.
forceCheckAllDependencies
The forceCheckAllDependencies parameter is set to false by default and is used only if checkPolicies and updateInventory are both set to True.
When set to false, the UA will only check policies for newly added libraries. Newly added libraries are considered newly added if they are not currently in the project inventory. This is the default to allow an organization to continue scanning successfully without failing the build based on issues that are already known.
Setting forceCheckAllDependencies=true will result in the scan checking for policies against all libraries, newly added and pre-existing.
Example: If a reject type policy is set for an MIT license and a project that contains library ‘x’ with an MIT license, scanning it with forceCheckAllDependencies=false will result in a successful scan as library x is already a part of the project and is not newly added.
However, if we set forceCheckAllDependencies=true, every time a scan runs, it will check all libraries in the inventory, newly added and pre-existing. As library 'x' with an MIT license is scanned, the scan will fail with exit code POLICY_VIOLATION (-2).
The forceCheckAllDependencies parameter allows an organization to fail the build based on the exit code for all libraries in the project, not only the newly added ones.
updateInventory
The updateInventory parameter is set to true by default.
When set to true, the UA will send an update request to the Mend application to update the Mend UI with the new libraries added to your inventory.
Note: The UA scan will update the application only if the policy check did not find any violations. You can find additional information on changing this behavior in the forceUpdate parameter section in this article.
Setting updateInventory=false allows the users to run a scan to verify that the open-source code currently in the project is compliant with the policies without making any changes to the inventory within the Mend UI.
Example: If a reject type policy is set for an MIT license, and a library with an MIT license is scanned with checkPolicies=true and updateInventory=false, the scan will fail with exit code POLICY_VIOLATION (-2) and NO results will be updated in the application.
If a reject type policy is set for an MIT license, the scan contains NO library with an MIT license, and parameters checkPolicies=true and updateInventory=true are set, the scan will succeed, and results will be updated in the application.
If a reject type policy is set for an MIT license, the scan contains NO library with an MIT license, and parameters checkPolicies=true and updateInventory=false are set, the scan will succeed, and NO results will be updated in the application.
The updateInventory parameter allows users to check policy compliance without making any changes to the inventory in the Mend application.
forceUpdate
The forceUpdate parameter is set to false by default and used only if checkPolicies and updateInventory are both set to True.
When set to false, the UA will send an update request to the Mend application to update the Mend UI with the new libraries added to your inventory ONLY if the policy check did not find any violations.
If violations were found, the application would not be updated, and the scan will fail with exit code POLICY_VIOLATION (-2). This is the default so that the Mend inventory reflects your actual inventory. If your build failed and the libraries are not added to your project, they should not be added to your Mend inventory either.
Setting forceUpdate=true updates the Mend application even if the policy check finds a violation. This results in the application reflecting the inventory with the libraries that resulted in the policy violation. As a result, when the parameter is set to true, the scan will exit with (0) SUCCESS. Find additional information on changing this behavior in the forceUpdate.failBuildOnPolicyViolation parameter section in this article.
Example: If a reject type policy is set for an MIT license, and a library with an MIT license is scanned with forceUpdate=false, the scan will fail with exit code POLICY_VIOLATION (-2), and NO results will be updated in the application.
If a reject type policy is set for an MIT license, and a library with an MIT license is scanned with forceUpdate=true, the scan will fail with exit code (0) SUCCESS, and the results WILL be updated in the application.
If a reject type policy is set for an MIT license, and NO library with an MIT license is scanned with checkPolicies=true and updateInventory=false, the scan will succeed, and NO results will be updated in the application.
The forceUpdate parameter allows users to check policy compliance and update the Mend inventory to reflect the libraries that resulted in the policy violation.
forceUpdate.failBuildOnPolicyViolation
The forceUpdate.failBuildOnPolicyViolation parameter is set to false by default and used only if checkPolicies, updateInventory, and forceUpdate are set to True.
When forceUpdate.failBuildOnPolicyViolation is set to false, the scan's exit code will reflect whether the results were sent to the Mend application or not.
Setting forceUpdate.failBuildOnPolicyViolation=true allows you to force the exit code to reflect the policy check status and not whether the results were sent to the Mend application.
Example: If a reject type policy is set for an MIT license, and a library with an MIT license is scanned with the following parameters forceUpdate=true, updateInventory=true, and forceUpdate.failBuildOnPolicyViolation=false, the scan will succeed with exit code (0) SUCCESS, and the results WILL be updated in the application.
If a reject type policy is set for an MIT license, and a library with an MIT license is scanned with the following parameters forceUpdate=true, updateInventory=true, and forceUpdate.failBuildOnPolicyViolation=true, the scan will fail with exit code POLICY_VIOLATION (-2), and the results WILL be updated in the application.
The forceUpdate.failBuildOnPolicyViolation parameter allows users to determine whether the UA exit code will result from the policy check or the scan result.