diff --git a/assets/group_policy_tab.png b/assets/group_policy_tab.png new file mode 100644 index 00000000..4af27e8f Binary files /dev/null and b/assets/group_policy_tab.png differ diff --git a/assets/project_custom_policy_button.png b/assets/project_custom_policy_button.png new file mode 100644 index 00000000..218b5314 Binary files /dev/null and b/assets/project_custom_policy_button.png differ diff --git a/assets/project_policy_tab.png b/assets/project_policy_tab.png new file mode 100644 index 00000000..7162ac87 Binary files /dev/null and b/assets/project_policy_tab.png differ diff --git a/assets/remove_custom_policy.png b/assets/remove_custom_policy.png new file mode 100644 index 00000000..638c78d2 Binary files /dev/null and b/assets/remove_custom_policy.png differ diff --git a/docs/knowledge_base/policy.md b/docs/knowledge_base/policy.md index 67243e89..00b022c4 100644 --- a/docs/knowledge_base/policy.md +++ b/docs/knowledge_base/policy.md @@ -1,11 +1,7 @@ # Policy -Phylum's custom policy support allows you to take control over the allow/block decision for dependencies being added to a Phylum project. +Phylum uses a policy framework implemented with [Open Policy Agent] to evaluate dependencies and provide tailored results. A default set of Phylum-provided policies will be applied to all newly created groups/projects. Phylum PRO users may customize their resultant policy by toggling policies on/off in the Phylum UI. -## How it works - -When a developer introduces dependency changes, either in a pull request when using one of the source control server integrations or when using Phylum's CLI extensions, a simple policy is applied to determine whether or not that change should be allowed. This policy is implemented using [Open Policy Agent]. - -Phylum PRO users may specify custom policies for their projects, automating their threat model for risk decisions. +Phylum PRO users may also [develop custom policies](./policy_development.md) using the [rego query language](https://www.openpolicyagent.org/docs/latest/policy-language/) and apply those policies to their groups/projects. [Open Policy Agent]: https://www.openpolicyagent.org/ diff --git a/docs/knowledge_base/policy_apply.md b/docs/knowledge_base/policy_apply.md deleted file mode 100644 index 0eea4c63..00000000 --- a/docs/knowledge_base/policy_apply.md +++ /dev/null @@ -1,14 +0,0 @@ -# Policy Application - -Policies are stored in the project preferences. - -The easiest way to manage a small number of policies is to use the web UI. -1. Open an existing project in the Phylum UI -2. Select `Preferences` -3. Select `Custom` under the `Current Project Policy` section -4. Click `Upload Custom` and select your desired `.rego` file - - Note: Uploading a new custom policy will replace the current policy, be sure to save your current policy if you do not want to lose it - -![Apply custom policy](../../assets/apply_policy.png) - -If you are managing policies for a large number of projects, you may be interested in the [`get_project_preferences_endpoint`](https://api.phylum.io/api/v0/swagger/index.html#/Preferences/get_project_preferences_endpoint) and [`update_project_preferences_endpoint`](https://api.phylum.io/api/v0/swagger/index.html#/Preferences/update_project_preferences_endpoint) API calls. diff --git a/docs/knowledge_base/policy_basics.md b/docs/knowledge_base/policy_basics.md deleted file mode 100644 index 21120f8d..00000000 --- a/docs/knowledge_base/policy_basics.md +++ /dev/null @@ -1,27 +0,0 @@ -# Policy Basics - -This is a basic policy using an `issue` rule to block any HIGH/CRITICAL issues. - -```rego -# METADATA -# title: Limit risk -# description: | -# Block issues based on risk level. -package policy.v1 - -import data.phylum.level -import rego.v1 - -# METADATA -# title: risk level cannot exceed medium -deny contains issue if { - some issue in data.issues - issue.severity > level.MEDIUM -} -``` - -The `package policy.v1` line must be present. This is how OPA finds the policy's rules. - -The `deny` rule will contain the specified issue when the `if` statement is `true`. `OPA` iterates through the job input data evaluating the expression against the severity level of every issue in the job. - -The `title` field from the metadata comment above the rule will be associated with the failure in the output from Phylum. diff --git a/docs/knowledge_base/policy_development.md b/docs/knowledge_base/policy_development.md index 37260be3..0b1fcb91 100644 --- a/docs/knowledge_base/policy_development.md +++ b/docs/knowledge_base/policy_development.md @@ -1,5 +1,35 @@ # Policy Development +## Policy Basics + +This is a basic policy using an `issue` rule to block any HIGH/CRITICAL issues. + +```rego +# METADATA +# title: Limit risk +# description: | +# Block issues based on risk level. +package policy.v1 + +import data.phylum.level +import rego.v1 + +# METADATA +# title: risk level cannot exceed medium +deny contains issue if { + some issue in data.issues + issue.severity > level.MEDIUM +} +``` + +The `title` and `description` from the initial metadata comments are displayed in the Phylum UI and are highly recommended. + +The `package policy.v1` line must be present. This is how [Open Policy Agent](https://www.openpolicyagent.org/) (OPA) finds the policy's rules. + +The `deny` rule will contain the specified issue when the `if` statement is `true`. OPA iterates through the job input data evaluating the expression against the severity level of every issue in the job. + +The `title` field from the metadata comment above the rule will be associated with the failure in the output from Phylum. + ## Creating a local policy development environment It is recommended to set up a local development environment for a better policy development experience. With a local development environment, you gain benefits such as faster feedback, more diagnostic abilities, version control, and automated testing. @@ -105,6 +135,132 @@ If the endpoint is called with no body, the project's saved policy will be used. If policy evaluation is successful, the result will contain both the policy output as well as a generated report in Markdown format. -Issues and dependencies that have been suppressed via project preferences are visible in the policy input, but rejections related to those issues or dependencies will not be included in the Markdown report. +Issues that have been suppressed via project preferences are visible to the policy, but the related rejections will not be included in the Markdown report. Dependencies that are ignored via the `ignored_packages` parameter are filtered out before applying the policy and will not be visible in the policy input or output. + +## Policy Examples + +The policy transforms your threat model into a description of why the job is being blocked. There are multiple ways to define why a job should be blocked. + +The `METADATA` block contains OPA [Annotations](https://www.openpolicyagent.org/docs/latest/annotations/) which correlate to the schema and can be used for type checking. + +### Blocking an issue + +The most common reason to block a job is because one of the dependencies has a known issue within one of Phylum's risk domains. + +The following policy shows ways to block using an `issue` rule based on a per-domain threshold. + +```rego +package policy.v1 + +import data.phylum.domain +import data.phylum.level +import rego.v1 + +# METADATA +# title: risk level cannot exceed medium +deny contains issue if { + some issue in data.issues + issue.domain in {domain.AUTHOR, domain.ENGINEERING, domain.VULNERABILITY} + issue.severity > level.MEDIUM +} + +# METADATA +# title: malicious risk level cannot exceed low +deny contains issue if { + some issue in data.issues + issue.domain == domain.MALICIOUS + issue.severity > level.LOW +} + +# METADATA +# title: license risk level cannot exceed high +deny contains issue if { + some issue in data.issues + issue.domain == domain.LICENSE + issue.severity > level.HIGH +} +``` + +Given the following input: + +```json +{ + "issues": [{ + "id": "b8ad4443-d875-427b-9eda-b4b2fb1d6212", + "domain": "malicious", + "severity": 4, + "tag": "CM0004" + }] +} +``` + +When the policy fails, the output will look something like this: + +```json +{ + "deny": [{ + "id": "b8ad4443-d875-427b-9eda-b4b2fb1d6212", + "domain": "malicious", + "severity": 4, + "tag": "CM0004" + }] +} +``` + +When Phylum sees this output from the policy, it will block the job and generate a report naming the package and describing the issue. + +### Blocking a dependency + +You may also block on a dependency-level characteristic using a `dependency` rule. + +The following policy blocks packages belonging to a namespace. +Note: This is just an example, there is already a [policy](https://github.com/phylum-dev/policy/blob/main/copyleft_license.rego) for blocking copyleft licenses. + +```rego +package policy.v1 + +import rego.v1 + +# METADATA +# title: AGPL licensed software is not allowed. +deny contains dependency if { + some dependency in data.dependencies + regex.match("(?i)\\bAGPL\\b", dependency.license) +} +``` + +Given the following input: + +```json +{ + "dependencies": [{ + "ecosystem": "npm", + "id": "4cc36d79-b8ce-5b7d-89c1-6f6a31f59819", + "issues": [], + "issues_complete": true, + "license": "AGPL-3.0", + "name": "example-package", + "version": "1.0.0" + }] +} +``` + +When the policy fails, the output will look something like this: + +```json +{ + "deny": [{ + "ecosystem": "npm", + "id": "4cc36d79-b8ce-5b7d-89c1-6f6a31f59819", + "issues": [], + "issues_complete": true, + "license": "AGPL-3.0", + "name": "example-package", + "version": "1.0.0" + }] +} +``` + +When Phylum sees this output from the policy, it will block the job and generate a report naming the package and providing this message in the output. diff --git a/docs/knowledge_base/policy_examples.md b/docs/knowledge_base/policy_examples.md deleted file mode 100644 index ceca6ff0..00000000 --- a/docs/knowledge_base/policy_examples.md +++ /dev/null @@ -1,124 +0,0 @@ -# Policy Examples - -The policy transforms your threat model into a description of why the job is being blocked. There are multiple ways to define why a job should be blocked. - -The `METADATA` block contains `OPA` [Annotations](https://www.openpolicyagent.org/docs/latest/annotations/) which correlate to the schema and can be used for type checking. - -## Blocking an issue - -The most common reason to block a job is because one of the dependencies has a known issue within one of Phylum's risk domains. - -The following policy shows ways to block using an `issue` rule based on a per-domain threshold. - -```rego -package policy.v1 - -import data.phylum.domain -import data.phylum.level -import rego.v1 - -# METADATA -# title: risk level cannot exceed medium -deny contains issue if { - some issue in data.issues - issue.domain in {domain.AUTHOR, domain.ENGINEERING, domain.VULNERABILITY} - issue.severity > level.MEDIUM -} - -# METADATA -# title: malicious risk level cannot exceed low -deny contains issue if { - some issue in data.issues - issue.domain == domain.MALICIOUS - issue.severity > level.LOW -} - -# METADATA -# title: license risk level cannot exceed high -deny contains issue if { - some issue in data.issues - issue.domain == domain.LICENSE - issue.severity > level.HIGH -} -``` - -Given the following input: - -```json -{ - "issues": [{ - "id": "b8ad4443-d875-427b-9eda-b4b2fb1d6212", - "domain": "malicious", - "severity": 4, - "tag": "CM0004" - }] -} -``` - -When the policy fails, the output will look something like this: - -```json -{ - "deny": [{ - "id": "b8ad4443-d875-427b-9eda-b4b2fb1d6212", - "domain": "malicious", - "severity": 4, - "tag": "CM0004" - }] -} -``` - -When Phylum sees this output from the policy, it will block the job and generate a report naming the package and describing the issue. - -## Blocking a dependency - -You may also block on a dependency-level characteristic using a `dependency` rule. - -The following policy blocks packages belonging to a namespace. - -```rego -package policy.v1 - -import rego.v1 - -# METADATA -# title: AGPL licensed software is not allowed. -deny contains dependency if { - some dependency in data.dependencies - regex.match("(?i)\\bAGPL\\b", dependency.license) -} -``` - -Given the following input: - -```json -{ - "dependencies": [{ - "ecosystem": "npm", - "id": "4cc36d79-b8ce-5b7d-89c1-6f6a31f59819", - "issues": [], - "issues_complete": true, - "license": "AGPL-3.0", - "name": "example-package", - "version": "1.0.0" - }] -} -``` - -When the policy fails, the output will look something like this: - -```json -{ - "deny": [{ - "ecosystem": "npm", - "id": "4cc36d79-b8ce-5b7d-89c1-6f6a31f59819", - "issues": [], - "issues_complete": true, - "license": "AGPL-3.0", - "name": "example-package", - "version": "1.0.0" - }] -} -``` - -When Phylum sees this output from the policy, it will block the job and generate a report naming the package and providing this message in the output. diff --git a/docs/knowledge_base/policy_management.md b/docs/knowledge_base/policy_management.md new file mode 100644 index 00000000..cdf37ea5 --- /dev/null +++ b/docs/knowledge_base/policy_management.md @@ -0,0 +1,15 @@ +# Policy Management + +## Add custom policy + +Phylum allows group administrators to upload and apply custom policies. Whether added via the project or group view, these policies are stored at the group level and available to all projects in the group. + +![Project custom policy button](../../assets/project_custom_policy_button.png) + +The Phylum UI uses the metadata at the top of the policy file (rego) to display a `title` and `description` for the policy list, so this data is highly recommended. + +## Remove custom policy + +Removal of a custom policy requires the policy to be inactive on all projects. Removal is a destructive action and can only be performed by a group administrator. Phylum-provided policies cannot be removed from the available list. To remove a custom policy from the group, use the trash can icon on the policy tab of the group details view. + +![Remove custom policy](../../assets/remove_custom_policy.png) diff --git a/docs/knowledge_base/policy_usage.md b/docs/knowledge_base/policy_usage.md new file mode 100644 index 00000000..4665ef50 --- /dev/null +++ b/docs/knowledge_base/policy_usage.md @@ -0,0 +1,23 @@ +# Policy Usage + +The Phylum policy framework allows you to overlay your threat model and block packages by surfacing issues for packages that violate the defined policy. + +## Group Policy + +Policies applied at the group level will be inherited by all projects belonging to the group. Only a group administrator can add, remove, enable, and disable group policies. + +Group administrators may activate/deactivate group policies by selecting the `Policy` tab in the Group detail view. Use the toggles to activate or deactivate a policy from applying to all of the projects in that group. + +![Group policy tab](../../assets/group_policy_tab.png) + +## Project Policy + +Project policies can be applied to individual projects (in addition to any inherited group policies). This allows you to further customize the resultant policy for a specific project. + +> ⚠️ **INFO** ⚠️ +> +> Inherited group policies cannot be deactivated at the project level. + +Group members may activate/deactivate project policies by selecting the `Policy` tab in the Project Details view. Use the toggles to activate or deactivate a policy from applying to that specific project. + +![Project policy tab](../../assets/project_policy_tab.png) diff --git a/site/sidebars.js b/site/sidebars.js index e9cd2ae4..223f5b3f 100644 --- a/site/sidebars.js +++ b/site/sidebars.js @@ -99,21 +99,7 @@ const sidebars = { 'knowledge_base/issue_tags', 'knowledge_base/notifications', 'knowledge_base/transfer_group_ownership', - 'knowledge_base/search', - { - type: 'category', - label: 'Policy', - link: { - type: 'doc', - id: 'knowledge_base/policy', - }, - items: [ - 'knowledge_base/policy_basics', - 'knowledge_base/policy_development', - 'knowledge_base/policy_examples', - 'knowledge_base/policy_apply', - ], - }, + 'knowledge_base/search' ] }, { @@ -144,6 +130,19 @@ const sidebars = { 'package_firewall/npm', ], }, + { + type: 'category', + label: 'Policy', + link: { + type: 'doc', + id: 'knowledge_base/policy', + }, + items: [ + 'knowledge_base/policy_usage', + 'knowledge_base/policy_management', + 'knowledge_base/policy_development', + ], + }, 'knowledge_base/threat_feed', 'support/security', 'support/contact_us',