Have a question? Want to report an issue? Contact JFrog support

Skip to end of metadata
Go to start of metadata

Overview

Policies define security and license compliance behavior specifications. They are enforced by applying them to Watches. A policy is contextless, which means that it only defines what to enforce and not what to enforce it on. A single policy can be applied to many watches. A single Watch may have multiple Policies assigned to it.

Policies enable you to create a set of rules, in which each rule defines a license/security criteria, with a corresponding set of automatic actions according to your needs. 

Watches only define the scope of the resources you want to watch. You can define a policy once and assign it to as many watches as you like.

Separating the behavior you want to enforce from the context you want to enforce it on provides you with the following values:

  • Efficiency. Reduce work and save time by configuring your policies once and assigning them to multiple watches.
  • Flexibility. Configure multiple behaviours with additional functionality such as priority of your security rules.
  • Separate Concerns. Delegate permissions to different teams in your organization. Everything related to resources and filters is in the watch, and everything related to security and license compliance is in policies.

Learn More

To learn how Policies are processed within a Watch, Click here.

Page Contents


Creating and Editing a Policy

To create a new policy, click New Policy and complete the fields.

Name
A logical name for this Policy.
Type

The policy rule types to create.

Security: Lets you create a set of rules around security vulnerabilities. Choose how you want Xray to respond to each vulnerability severity.

License: Lets you create a set of rules around allowed/banned sets of licenses.

Description
A general description of the Policy.
Rules
The rules search filter.
Priority
The Rules priority. Drag and drop the rules to place them according to their priority.
Rule Name
The Rule(s) attached to this Policy.
Criteria
The Rule criteria. If the criteria is met, then the automatic actions of this rule are executed and the policy is considered as processed (no further rules will be checked).
Automatic Actions
The actions to take if a criteria is met.

Editing a Policy

Edit an existing Policy, from the Policy table, by hovering over it and clicking on the Edit icon on the right.

Edits made to a policy will automatically be applied to all watches the policy is assigned to. This will take affect only for newly scanned artifacts. You can manually apply the watch on existing artifacts.

Security Rule

A Security Rule allows you to create a set of rules around security vulnerabilities. There are two possible criteria:

  1. Minimal Severity (Minor, Major, Critical, All): The minimal security vulnerability severity as it is in the JFrog vulnerabilities database. If the artifact or build contains a vulnerability with the selected severity or higher, the rule will meet the criteria, the automatic actions will be executed, and the policy will stop processing.
  2. CVSS Score (1-10): The CVSS score range to apply to the rule. This is used for a fine-grained control, rather than using the predefined severities.

To create a new Security Rule, select "Security" from the Type drop down and click New Rule.

New Security Rule

Rule Name
A logical name for this Rule.
Criteria

The set of security conditions to examine when an scanned artifact is scanned.

Automatic Actions

Specifies the actions to take once a security policy violation has been triggered.

License Rule

A licence Rule allows you to create a set of rules around license compliance. There are three possible criteria:

  1. Allowed Licenses: Specifies a whitelist of OSS licenses that may be attached to a component. If a component has an OSS license outside the specified whitelist, The rule will meet the criteria, a violation will be generated, automatic actions will be executed, and the policy will stop processing.
  2. Banned Licenses: Specifies a blacklist of OSS licenses that may not be attached to a component. If a component has any of the OSS licenses specified, The rule will meet the criteria, a violation will be generated, automatic actions will be executed, and the policy will stop processing.
  3. Disallow Unknown License: Specifies the wanted behavior for components whose license cannot be determined. A violation will be triggered if a component with unknown license is found. 

To create a new License Rule, select "License" from the Type drop down and click New Rule.

Rule Name
A logical name for this Rule.
Criteria

The set of license conditions to examine when an scanned artifact is scanned.

Automatic Actions
Specifies the actions to take once a license policy violation has been triggered.

Automatic Actions

An action determines the automatic response to a detected Policy violation. You can define one or more action within each Policy Rule. Actions include the following:

  1. Generate Violation (Minor, Major, Critical): The severity of the violations that is generated if the criteria is met.
  2. Notify Email: This action lets you specify email addresses to which Xray should send an email message about a violation when one is triggered. For this to work, you need to have a mail server configured in Xray.
  3. Trigger Webhook: This action lets you specify webhooks you have configured in Xray that should be invoked when a violation is triggered (See payload below).
  4. Block Download: This action lets you specify that artifacts should be blocked for download from Artifactory.

    Block Download
    When set, Artifactory will block download of artifacts that meet the Artifact Filter and Severity Filter specifications for this watch.
    Block Unscanned
    When set, Artifactory will block download of artifacts that meet the Artifact Filter specifications for this watch, but have not been scanned yet
  5. Fail Build: This action lets you specify that if a CI server requests a build to be scanned, and the Watch triggers a violation, Xray will respond with an indication that the build job should fail.
    This action is only available if the Watch is defined with an All Builds target type.

    No Fail Build Job Actions defined?

    If a request to scan a build is received by Xray, but there are no Watches with a Fail Build action defined, Xray will always respond with an indication that the build job should indeed fail, whether build artifacts or dependencies are found to have vulnerabilities or not.

Webhook Payload

The payload provided to any triggered webhook is a JSON object describing a list of Alerts with the following format:

{
  "created": "<Alert creation time stamp in ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
  "top_severity": "<Top severity of any issue in the alert>",
  "watch_name": "<Logical name for the watch>",
  "issues": [
	{
		"severity": "<Issue severity>",
    	"type": "<Issue type>",
    	"provider": "<Issue provider>",
    	"created": "<Issue creation time stamp in ISO8601 (yyyy-MM-dd'T'HH:mm:ss.SSSZ)>",
    	"summary": "<Issue summary>",
      	"description": "<Issue description>",
      	"impacted_artifacts": [
			{
	      		"name": "<Artifact name>",
          		"display_name": "<Artifact dispalay name>",
          		"path": "<Artifact path in Artifactory>",
          		"pkg_type": "<Package type>",
          		"sha256": "<Artifact SHA 256 checksum>",
          		"sha1": "<Artifact SHA 1 checksum>",
          		"depth": <Artifact depth in its hierarchy>,
         		"parent_sha": "<Parent artifact SHA 1 checksum>",
  				"infected_files": [
            		{
              			"name": "<File name>",
              			"path": "<File path>",
              			"sha256": "<File SHA 256 checksum>",
              			"depth": <File depth in hierarchy>,
              			"parent_sha": "<File's parent SHA 1 checksum>",
              			"display_name": "<File's display name>",
              			"pkg_type": "File's package type"
            		}
				]	
			}
		]
	}
  ]
}

The following shows an example payload for a webhook

{
  "created": "0001-01-01T00:00:00Z",
  "top_severity": "Critical",
  "watch_name": "no-Apache-2.0-builds",
  "issues": [
    {
      "severity": "Critical",
      "type": "security",
      "provider": "Custom",
      "created": "2018-03-12T19:12:06.702Z",
      "summary": "custom-glassfish",
      "description": "custom-glassfish",
      "impacted_artifacts": [
        {
          "name": "test",
          "display_name": "test:6639",
          "path": "artifactory-xray/builds/",
          "pkg_type": "Build",
          "sha256": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
          "sha1": "737145943754ac99a678d366269dcafc205233ba",
          "depth": 0,
          "parent_sha": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
          "infected_files": [
            {
              "name": "ant-1.9.4.jar",
              "path": "",
              "sha256": "649ae0730251de07b8913f49286d46bba7b92d47c5f332610aa426c4f02161d8",
              "depth": 0,
              "parent_sha": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
              "display_name": "ant-1.9.4.jar",
              "pkg_type": "Generic"
            },
            {
              "name": "aopalliance-repackaged-2.4.0-b09.jar",
              "path": "",
              "sha256": "a97667a617fa5d427c2e95ce6f3eab5cf2d21d00c69ad2a7524ff6d9a9144f58",
              "depth": 0,
              "parent_sha": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
              "display_name": "org.glassfish.hk2.external:aopalliance-repackaged:2.4.0-b09",
              "pkg_type": "Maven"
            }
          ]
        }
      ]
    },
    {
      "severity": "Critical",
      "type": "License",
      "summary": "Apache-2.0",
      "description": "Apache License 2.0",
      "impacted_artifacts": [
        {
          "name": "test",
          "display_name": "test:6639",
          "path": "artifactory-xray/builds/",
          "pkg_type": "Build",
          "sha256": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
          "sha1": "737145943754ac99a678d366269dcafc205233ba",
          "depth": 0,
          "parent_sha": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
          "infected_files": [
            {
              "name": "ant-1.9.4.jar",
              "path": "",
              "sha256": "649ae0730251de07b8913f49286d46bba7b92d47c5f332610aa426c4f02161d8",
              "depth": 0,
              "parent_sha": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
              "display_name": "ant-1.9.4.jar",
              "pkg_type": "Generic"
            },
            {
              "name": "aopalliance-repackaged-2.4.0-b09.jar",
              "path": "",
              "sha256": "a97667a617fa5d427c2e95ce6f3eab5cf2d21d00c69ad2a7524ff6d9a9144f58",
              "depth": 0,
              "parent_sha": "c9be3f74c49d2f3ea273de9c9e172ea99be696d995f31876d43185113bbe91bb",
              "display_name": "org.glassfish.hk2.external:aopalliance-repackaged:2.4.0-b09",
              "pkg_type": "Maven"
            }
          ]
        }
      ]
    }
  ]
}

Watch the Screencasts





  • No labels