docs: Update policy documentation (#194)

- Brought policy to the top level of the side nav as it seems like a prominent feature at this point - The previous documentation was focused on developing custom policies, so I consolidated that - I created a page for usage and a page for management of policies --------- Co-authored-by: Charles Coggins <[email protected]> Co-authored-by: Jana Sheehan <[email protected]>
phylum-dev · Aug 7, 2024 · cd07331 · cd07331
1 parent ab10664
commit cd07331
Show file tree

Hide file tree

Showing 12 changed files with 211 additions and 187 deletions.
diff --git a/assets/group_policy_tab.png b/assets/group_policy_tab.png
diff --git a/assets/project_custom_policy_button.png b/assets/project_custom_policy_button.png
diff --git a/assets/project_policy_tab.png b/assets/project_policy_tab.png
diff --git a/assets/remove_custom_policy.png b/assets/remove_custom_policy.png
diff --git 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
diff --git a/docs/knowledge_base/policy_basics.md b/docs/knowledge_base/policy_basics.md
diff --git 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
diff --git a/docs/knowledge_base/policy_management.md 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
@@ -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)