Understanding the Parts of a Policy

A policy is the set of rules or criteria Sonatype Lifecycle uses to evaluate components in your applications and repositories.

Summary

The Policy Name and Threat Level are defined in the Summary section.

Policy Name

The Policy Name indicates the risk or violation it is associated with. This Policy Name will appear in all reports and views. To avoid confusion, assign a unique name to every policy. Policy Name can be up to 60 characters long and include alphanumerics, underscores (_), periods (.), dashes (-), or spaces.  

Threat Level

The Threat Level is a subjective value placed on the perceived risk of a policy violation. Its main purpose is for sorting policy violations in IQ Server reports and views; the violations with the highest threat level appear first followed by those with lower threat levels. The Threat Level values are grouped by severity and identified by specific colors as shown in the table below:

LevelColorNumber
CriticalRed8-10
SevereOrange4-7
ModerateYellow2-3
LowBlue1

When setting the Threat Level, avoid causing unnecessary alarm for those who review policy violations. Select the lowest possible value that’s helpful to you, such as an informational level (1) or low level (2-3). Save the high-level values (8-10) for only the most critical violations.

Inheritance

The Inheritance setting is available only for organizations (including the Root organization). It allows you to specify how a policy is implemented when there are multiple applications attached to a specific organization. There are two choices:

  • All Applications and Repositories - The policy is applied to every application and repository below this level of the hierarchy.
  • Applications of the specified Application Categories in Root Organization/Organization - The policy is applied only to applications that have specific application categories assigned to them. With this setting, you select which application categories to use.

The latter choice lets you tailor the implementation of a policy to applications with similar characteristics by using application categories. For more information on how to create and assign application categories, see Application Categories under Advanced Policy Management.

Inheritance Overrides

Checking these boxes allows you to override actions/notifications for this policy at lower levels.

Constraints

Constraints define the violating conditions you want to detect. A constraint is a collection of multiple conditions. A policy must have at least one constraint, and each constraint must have at least one condition.

Constraints can be configured to be satisfied if ANY or ALL of the conditions are true. Multiple constraints inside a policy are combined with OR, so a policy is violated if any one constraint in that policy is violated.

Constraints are made up of the following parts:

ItemDescription
Constraint NameIndicates the violation you want to detect, for example, a High-risk CVSS score or License needs legal review.
Conditions

Refer table below to choose the appropriate violation condition from the drop-down.

 

Setting Conditions

Select a value for “Any or All" and then a condition and its parameters from the drop-down menus. For more details on any of the conditions and their parameters, please see the Application Composition Report.

Policy Type

A policy type is automatically assigned, based on the conditions selected for the policy constraint. You can filter results on the dashboard based on the Policy type.

The following rules are used to determine policy type :

  • Security if it has any security conditions, it is considered a Security policy.
  • License if it has any license conditions, it is considered a License policy.
  • Quality if it has any age or popularity conditions, it is considered a Quality policy.
  • Other if none of its conditions are of types mentioned above, it is considered to be of type Other.

NOTE: A policy can only be of one type. In cases where a policy has conditions that meet more than one of the rules above, the policy type is assigned according the order listed above. For example, if a policy has security and license conditions, it is assigned policy type as Security.

Constraint Conditions supported

ConditionTypeDescription
Any or All---

Determines how constraints are evaluated. You can choose one of the following options:

  • Any - If any one of the conditions is met, then a policy violation is triggered. It is the equivalent of placing an or between each condition. This setting tends to produce a lot of policy violations.
  • All - If every condition is met, then a policy violation is triggered. This setting is the equivalent of placing an and between each condition. It tends to produce fewer policy violations.
LabelOtherVerify if a specific component label is or is not assigned to a component.
LicenseLicenseVerify if the component license is or is not a specified license. If you’ve used the Component Information Panel to set a component’s license status to Overridden, then any licenses designated as Declared or Observed are ignored. If a component’s license status has not been overridden, then any occurrence (declared or observed) of the specified license is considered a match.
License StatusLicense

Verify if the status of a user-defined license is or is not one of the following values: Open, Acknowledged, Overridden, Selected, Confirmed.

License Threat GroupLicenseVerify if a component’s license is or is not in a license threat group. The special value [unassigned] can be used to check whether a license has not been assigned to any of your license threat groups, i.e. represents an unknown risk.
License Threat Group LevelLicenseVerify if the threat level of a component’s license threat group is less than or equal or greater than or equal to a specified threat level value.
Security Vulnerability SeveritySecurity
Verify if a security vulnerability with a numeric severity is =, <, ⇐, >, or >= to a specified value.

If a vulnerability identifier is prefixed with  SONATYPE or CVE, then the vulnerability severity is its Common Vulnerability Scoring System (CVSS) version 3 score.

In the case that a version 3 score is not available, the severity compared will be to the CVSS version 2 score.

161

If there is a Custom Vulnerability Severity value applicable for the evaluated application, it will be used for this comparison.

Security Vulnerability StatusSecurity

Verify if a component’s security vulnerability status is or is not one of the following values: Open, Acknowledged, Not Applicable, Confirmed.

Relative Popularity (Percentage)Quality

Verify if the relative popularity of a component’s version (as compared to other versions of the same component) is =, <, ⇐, >, or >= to a specified percentage value.

Relative Popularity

The Popularity of a component is calculated as a function of successful download counts from the Open Source Software repositories and package managers. As a baseline, the most popular version of the component will have 100% popularity. If all versions of component have the same popularity, roughly, then they would all have 100% popularity.

AgeQualityVerify if a component is older than or younger than a specified value.
Match StateOtherVerify if the comparison of a component to known components is or is not a match in one of the following ways: Exact, Similar, or Unknown.

Format 136

OtherVerify if the component is in specified format. E.g. npm, maven, etc. 
CoordinatesOther

Verify if a component matches or does not match Maven, A-Name, or PyPI coordinates. For each type of coordinates, you enter specific attributes. You can use a wildcard (*) at the end of an attribute to broaden the search.

Maven: You fill in a component’s GAVEC, i.e. Group ID, Artifact ID, Version, Extension, and a Classifier. For example:

Group ID: org.sonatype.nexus
Artifact ID: nexus-indexer
Version: 1.0
Extension: jar
Classifier: sources
Group ID: org.sonatype*
Artifact ID: nexus-indexer
Version: 1.*
Extension: *
Classifier: 

A-Name: A-Name is short for Authoritative Name, an identifier created by Sonatype to identify components agnostic of the repository format. You fill in a Name, Qualifier, and Version, for example:

Name: log4net
Qualifier: Framework 3.5
Version: 2.0.5
Name: log4net
Qualifier:
Version: 1.*

PyPI : The Python Package Index format. You fill in a Name, Version, Qualifier, and Extension. For example:

Name: MarkupSafe
Version: 1.1.0
Qualifier: 
Extension: *
Package URLOther

Verify if a component matches or does not match a specified package URL. You can use a wildcard (*) at the end of an optional attribute to broaden the search. The package URL must have the format below:

pkg:type/namespace/name@version?qualifiers

Where:

  • type : the package "type" or package "protocol" such as maven, npm, etc. Required
  • namespace : some name prefix such as a Maven groupid (optional and type-specific). Optional
  • name : name of the package. Required
  • version : version of the package. Optional
  • qualifiers : extra qualifying data for a package such as type, classifier for maven (optional and type-specific). Optional

Package URL examples

Maven

pkg:maven/tomcat/tomcat-util@5.5.23?type=jar

A-name:

pkg:a-name/startbootstrap-agency@4.0.0-beta
ProprietaryOtherVerify if a component is or is not considered proprietary.

Proprietary Name Conflict

REPOSITORY FIREWALL

Security

Determine whether a component from a proxy repository has a name that matches the name of any proprietary component in a hosted.

Note that this policy condition is only relevant to Sonatype Repository Firewall and the Proxy stage.

Identification SourceOther

Verify if the identification of a component is or is not one of the following:

    • Sonatype - When the identification is done based on IQ Server data sources
    • Manual - When the identification is done based on a component claimed by you
    • Clair - When the identification is done based on a Clair scan result
    • Package Manifest - When the identification is done based on any manifest file scan

Component Category 

Other

Verify if the component category is or is not a specified category.  These categories are what the component is used for, as categorized by Sonatype. Possible values include designations like "Data Protocols," "Logging," "Networking Utilities," etc. If a parent category is selected, a match will occur on any child category as well.

Data Source 

Other

Verify whether the data source where the component information was found has support  for one of the following features: Identity or License

Dependency Type 

Other

Verify if the dependency type is or is not the following:

  • Direct - When the dependency is determined to be defined in the application/project
  • Transitive - When the dependency is brought in from another dependency
  • InnerSource - When a direct dependency is determined as an internally developed module. Note that this will not match transitive components that are brought in by InnerSource components.

For more information see the dependency type section in Reviewing a Report

NOTE: Policy is not evaluated on components with a dependency type of unknown. This policy condition is not applicable to Repositories.

Security Vulnerability Category 

Security

Verify if the security vulnerability category is or is not a specified category.  If you've used the Component Information Panel, the vulnerability category values can be seen when viewing vulnerability information.

  • Data - The exploit involves the attacker sending a tainted request
  • Operational - The component is involved in the operation of the webserver
  • Functional - Affects a specific piece of the component that isn't integral to the operation of the component
  • Configuration - Dependent on a specific configuration of the component implementation
  • Test Code - The vulnerability is in test code that is not required for production
  • Sample Code - The vulnerability is in an example included with the component
  • Privileged - The attacker needs to have elevated privilege levels to exploit
  • Malicious Code - The component has embedded malicious code
  • Other - Not covered in the above categories

Hygiene Rating


Quality

Verify if the Hygiene Rating of a component is or is not one of the following:

  • Laggard
  • Exemplar

Integrity Rating


Quality

Verify if the Integrity Rating of a component is or is not one of the following:

  • Normal
  • Suspicious
  • Malicious

Security Vulnerability CWE


Security

Verify if a component’s security vulnerability CWE ID is or is not equal to a specified value.

161

If there is a Custom Vulnerability CWE ID value applicable for the evaluated application, it will be used for this comparison.

Security Vulnerability Group

152

SecurityVerify if a component belongs to a specific vulnerability group. Custom vulnerability groups can be added using the Vulnerability Groups REST API - experimental.

Security Research Type

152

SecurityVerify if a component has undergone deep dive research by the Sonatype Data Research team. To exclude the "Deep Dive" condition i.e. , include only "Fast Track" research type, choose IS NOT as the logical operator while defining the constraint.
IaC Compliance FamilySecurityMap the component to a specific compliance standard from those available in the IaC Pack.

Security Vulnerability Custom Remediation

161

SecurityVerify if there is a Custom Vulnerability Remediation value or not for the vulnerability and evaluated application.

Security Vulnerability Custom CVSS

161

SecurityVerify if there is a Custom Vulnerability CVSS Vector value for the vulnerability and evaluated application matching or not with a given regular expression.

Unknown components can only meet the "Match State", "Proprietary" and "Data Source" conditions. All other conditions will never be satisfied by an unknown component, regardless of which operator or value the condition employs. For example,

  1. An unknown component has no defined relative popularity, not even 0, so a condition like "Relative Popularity >= 0" would not be met by an unknown component.
  2. An unknown component has no specific coordinates, not even a condition like "Coordinates do not match ..." would be satisfied by it.

Actions

Policy actions allow you to designate an action to take when violations occur at a particular stage in the development lifecycle. For each stage, you can assign one of the following actions:

  • No Action - This is the default setting.
  • Warn - Policy violations are worthy of a warning.
  • Fail - Policy violations are severe enough to potentially halt the development lifecycle.

If Sonatype Lifecycle is integrated with a third-party external tool, the action selected can have a direct effect on the tool. When an external tool requests a policy evaluation (of an application, repository, or component), IQ Server provides policy violation information along with the action, which the tool may (or may not) implement. For example, if you set the Build stage to Fail in a policy, a CI tool (such as Bamboo, Jenkins, or Hudson) may stop the build of an application when that policy is violated. Similarly, in a different tool, if you set a stage to Warn, a warning message may be displayed or logged in a file when policy violations occur. For more details on using actions, see Usage Suggestions for Each Stage.

To add actions to a policy:

  1. In the Organization & Policy area, create a new policy or open an existing one for repositories or an organization or application.
  2. In the Policy editor, click the Actions button to scroll to the Actions section.
  3. Click the desired action — No Action, Warn, or Fail  at specific stage(s). In case of repositories, actions can be set only for the Proxy stage.
  4. Click Update (or Create) to save the policy.


        Actions at root organization or organization or application level

Actions at Repositories level 

Usage Suggestions for Each Stage

Sonatype provides various tools and plugins to enable policy evaluation during each stage of development lifecycle:

  • CLI
  • Maven plugin
  • Sonatype Repository Firewall
  • IDE plugins
  • CI plugins
StageUsage Suggestion
Proxy
  • Available for the Sonatype Repository Firewall solution
  • Refers to proxy repositories where components enter your binary repository
  • Use the 'fail' action to quarantine components for quality review before being automatically downloaded by developers
Develop
  • Intended for evaluations where changes are not tracked, typically in IDE environments
  • Actions and notifications on this stage are ignored
  • Evaluations will not show up in the dashboard or reporting


Source

  • Intended for scans in the source control repository
  • Scans on the default branch will use this stage
  • Pull Requests scan results are only reported as comments on that pull request
Build
  • Use in ad-hoc scans or Continuous Integration workflows
  • The 'warn' action will flag a CI build as unstable
  • Only use 'fail' to halt builds when crtiical violations are discovered
Stage Release
  • Use with Lifecycle plugins for user acceptance testing (UAT) before the release phase
  • The 'warn' action is recommend
  • Use 'fail' when applications do not meet quality requirements
Release
  • A last line of defense to protect production environments from non-complaint risk
  • The 'warn' action will flag a CI build as unstable
  • Use 'fail' to halt deployments when crtiical violations are discovered
  • Configure continuous monitoring on this stage to discover risk after after deploying to production
Operate
  • For integrations with deployment tools (e.g udeploy) or script
  • Evaluations on this stage will not show up in the dashboard or reporting views

Notifications

Notifications let you send a summary of new policy violations when they occur at a specific stage of development. Notifications are sent whenever an application is evaluated either manually (e.g. using the Evaluate a File command in the Organization & Policy area) or automatically via any tool integrated into the IQ Server (e.g. Sonatype Lifecycle for Hudson/Jenkins 1.x) or if Continuous Monitoring is activated. The notifications can be delivered to email addresses. The emails are sent to individual addresses or users assigned to a particular role such as Owner or Application Evaluator.

When a notification is sent, it will only display new violations found in the latest evaluation. If you find yourself not receiving notifications, verify there are new violations, as well as confirm you have configured your IQ Server SMTP settings.

When you have a repository auditing setup, then notifications will be sent when a new component that violates policy enters your repository manager.

The initial repository audit and re-evaluations of policies on repositories do not send notifications.

To set notifications in a policy:

  1. In the Organization & Policy area, create a new policy or open an existing one for repositories or an organization or application.
  2. In the Policy editor, click the Notifications button to scroll to the Notifications section.
  3. Provide recipient information:
    1. Select a Recipient Type. If Email, then enter an email address. If Role, then select a user role from the list. For Jira notifications, enter a project and select an applicable issue type.
    2. Click Add to insert the recipient.
  4. Click to select the stage(s) for which to send notifications to a recipient. In case of repositories, all stages except Proxy  are disabled.

    For the Continuous Monitoring stage, you must have monitoring activated for the application or a parent organization. To learn more about continuous monitoring, see our documentation on the topic.

  5.  Click Create (or Update) to save the new policy.

To remove a recipient, click on the delete icon .


          Notifications at root organization or organization or application level

Notifications at Repositories level

Usage Suggestions for Notifications at Each Stage

StageUsage Suggestion
ProxyConsider setting up notifications to inform repository owners or Nexus Repository administrators that are responsible for safeguarding components entering the organization. You can also view any policy violations that occur during this stage in the Repository Results.
DevelopPolicy violations triggered by IDE-related activity generally do not send any notifications.
Source

If not sending notifications at the build or later stages consider setting up notifications to inform developers here.

BuildConsider setting up notifications to inform owners, as well as developers.
Stage ReleaseIf something fails, the development process can not move forward. Make sure to notify anyone who is responsible for the application’s release and/or capable of researching and addressing any violations.
ReleaseSimilar to Stage Release, make sure to notify anyone responsible for ensuring an application does not go into production with policy violations.
OperateTypically the application owner or anyone responsible for ongoing maintenance of an application in production should be notified.

Jira Notifications

Configuring notifications for Atlassian Jira are is longer supported from the policy setup page. Use  Sonatype Lifecycle for Jira plug-in for integration with Jira.