You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Sara/tec 304 new conditions for ssc policies for ga (#2000)
* initial commit for GA ssc policies
* update with various components, new screenshots, updated behavior text
* wording change, links, change sidebar order
* remove old instructions about setting up ssc comments
* nicer instructions
* remove extraneous portions
* update with link
* add tidbit about supply chain
* add supply chain addendum for now
* change box to info
* address review notes
* Update docs/semgrep-supply-chain/getting-started.md
Co-authored-by: Katie Horne <[email protected]>
* update based on emma feedback
* address review notes and add icons
* style guide
* review
---------
Co-authored-by: Katie Horne <[email protected]>
Copy file name to clipboardexpand all lines: docs/semgrep-appsec-platform/azure-pr-comments.md
+9-10
Original file line number
Diff line number
Diff line change
@@ -13,9 +13,9 @@ tags:
13
13
import DeploymentJourney from "/src/components/concept/_deployment-journey.mdx"
14
14
import CommentTriggers from "/src/components/reference/_comment-triggers.mdx"
15
15
import PrCommentsInSast from "/src/components/procedure/_pr-comments-in-sast.mdx"
16
-
import DisableComments from "/src/components/procedure/_disable_ssc_pr_mr_comments.mdx"
17
16
import TroubleshootingPrLinks from "/src/components/reference/_troubleshooting-pr-links.mdx"
18
17
import NextAfterComments from "/src/components/procedure/_next-after-comments.mdx"
18
+
import CommentsInSupplyChain from "/src/components/concept/_comments-in-supply-chain.md"
19
19
20
20
<!-- vale on -->
21
21
@@ -51,13 +51,7 @@ PR comments are enabled by default for users who have connected their Azure DevO
51
51
1. In your Semgrep AppSec Platform account, click **Settings > Source code managers**.
52
52
2. Check that an entry for your Azure DevOps org exists and is correct.
53
53
54
-
### Configure comments for Semgrep Code
55
-
56
-
<PrCommentsInSastname="Azure"comment_type="PR" />
57
-
58
-
:::info
59
-
Only rules set to the **Comment** and **Block** rule modes in the [Policies page](https://semgrep.dev/orgs/-/policies) create PR comments.
60
-
:::
54
+
### Set up the configuration file
61
55
62
56
In the Azure Pipelines configuration file, export the `SEMGREP_REPO_URL` and `SEMGREP_REPO_NAME` variables to enable PR comments and ensure that findings and related data are accurately labeled with your project's information. Note that the namespace that's a part of the variable's value follows the format `{organization}/{project}`:
### Receive comments in your VPN or on-premise SCM
189
193
190
194
Bitbucket Premium provides [<i class="fas fa-external-link fa-xs"></i> access control features](https://support.atlassian.com/bitbucket-cloud/docs/control-access-to-your-private-content/) for content that your individual account owns. If you use this feature, you need to add several IP addresses into your allowlist.
_**Figure**. Permissions for select repositories. Ensure the repositories you have onboarded to Semgrep AppSec Platform are selected._
73
73
74
-
For GitHub Actions users, no further steps need to be undertaken. Continue setting up Semgrep Code PR comments by [setting rules to Comment or Block mode](#set-rules-to-comment-or-block-mode).
74
+
For GitHub Actions users, no further steps need to be undertaken. Continue setting up PR comments by configuring comments for Semgrep Code.
75
75
76
76
### Required environment variables
77
77
@@ -83,6 +83,10 @@ For GitHub Actions users, no further steps need to be undertaken. Continue setti
83
83
84
84
If you are using **GitHub Actions** to run Semgrep, no extra changes are needed to receive PR comments.
85
85
86
+
### Configure comments for Semgrep Supply Chain
87
+
88
+
<CommentsInSupplyChain />
89
+
86
90
### Receive comments in your VPN or on-premise SCM
87
91
88
92
<ReceiveCommentsScm />
@@ -130,10 +134,6 @@ Both GitHub and GitLab provide features to prevent or block a PR or MR from merg
### Receive comments in your VPN or on-premise SCM
125
129
126
130
:::info
@@ -156,10 +160,6 @@ To enable dataflow traces in your CI pipeline, fulfill the following prerequisit
156
160
- Not all Semgrep rules or rulesets make use of taint tracking. Ensure that you have a ruleset, such as the **default ruleset** added in your **[Policies](https://semgrep.dev/orgs/-/policies)**. If this ruleset is not added, go to [https://semgrep.dev/p/default](https://semgrep.dev/p/default), and then click **Add to Policy**. You can add rules that use taint tracking from [Semgrep Registry](https://semgrep.dev/explore).
Copy file name to clipboardexpand all lines: docs/semgrep-appsec-platform/tags.md
+2
Original file line number
Diff line number
Diff line change
@@ -11,6 +11,8 @@ tags:
11
11
12
12
# Tag projects
13
13
14
+
Tagging enables you to group projects together based on your organization's unique business structure or needs. By tagging projects, you are able to quickly apply Supply Chain policies and other Semgrep features to specific groups.
15
+
14
16
Add tags for specific projects in the Semgrep AppSec Platform through the following methods:
15
17
16
18
* Set tags through the **Semgrep AppSec Platform > Projects > Project details** page.
Copy file name to clipboardexpand all lines: docs/semgrep-supply-chain/getting-started.md
+1-19
Original file line number
Diff line number
Diff line change
@@ -136,22 +136,4 @@ Semgrep Supply Chain supports the scanning of monorepos. As outlined in [Project
136
136
137
137
## Block pull or merge requests
138
138
139
-
Semgrep can help block pull requests (PRs) or merge requests (MRs) when it matches a blocking finding. When one or more findings is blocking, Semgrep returns exit code `1`, and you can use this result to set up additional checks to enforce a block in your CI/CD pipeline, such as not allowing merge of the PR/MR. This action applies to full and [diff-aware scans](/semgrep-code/glossary#diff-aware-scan).
140
-
141
-
You can configure Semgrep Supply Chain to help block scans whenever all of the following conditions are met:
142
-
143
-
* It detects reachable findings in direct dependencies
144
-
* The reachable findings are of critical or high severity
145
-
* There is an upgrade available for the affected dependency; this is to prevent blocking when there is no resolution for the vulnerability
146
-
147
-
To enable **Scan Blocking**:
148
-
149
-
1. Sign in to Semgrep AppSec Platform.
150
-
2. Go to **Settings > Deployment** and navigate to the **Supply Chain (SCA)** section.
Copy file name to clipboardexpand all lines: docs/semgrep-supply-chain/glossary.md
+14-2
Original file line number
Diff line number
Diff line change
@@ -8,6 +8,8 @@ title: Supply Chain glossary
8
8
hide_title: true
9
9
---
10
10
11
+
import TransitivityTypes from "/src/components/concept/_transitivity-types.md"
12
+
import EpssTypes from "/src/components/concept/_epss-types.md"
11
13
import DefReachability from "/src/components/concept/_def-reachability.md"
12
14
13
15
# Semgrep Supply Chain glossary
@@ -26,6 +28,10 @@ Publicly available code used as a part of your application. Common examples incl
26
28
27
29
Exploitability is the practical assessment of a vulnerability's threat, typically proved with a real proof of exploit. Proving exploitability is often the last step of triaging a vulnerability.
28
30
31
+
## EPSS probability
32
+
33
+
<EpssTypes />
34
+
29
35
## Lockfile
30
36
31
37
A lockfile describes a dependency tree to ensure that deployments and organizations install the same **dependencies and exact versions** for their codebase. Lockfile information includes versions of the dependency and any transitive (indirect) dependencies. Lockfiles are automatically generated by a package manager such as `pip` or `npm`.
@@ -54,7 +60,7 @@ A package registry stores dependencies and provides a means to upload or downloa
A reachable finding means that you are using both a vulnerable piece of code (the **usage**) and the vulnerable version of a dependency. Within Semgrep Supply Chain, specific findings (usages) are grouped together by their vulnerability.
63
+
A reachable finding means that you are using both a vulnerable code pattern (the **usage**) and the vulnerable version of a dependency. Within Semgrep Supply Chain, specific findings (usages) are grouped together by their vulnerability.
58
64
59
65
Continuous integration scans with Semgrep Supply Chain rules can block pull or merge requests upon detecting any reachable findings.
60
66
@@ -66,7 +72,7 @@ See also [Reachability](#reachability).
66
72
67
73
## Reachability rules
68
74
69
-
A type of Semgrep Supply Chain rule that performs reachability analysis. A reachability rule can determine if the vulnerable piece of code from a dependency is used in the codebase that imports it.
75
+
A type of Semgrep Supply Chain rule that performs reachability analysis. A reachability rule can determine if the vulnerable code pattern from a dependency is used in the codebase that imports it.
70
76
71
77
Compare its opposite: [rules without reachability analysis](#rules-without-reachability-analysis)
72
78
@@ -88,6 +94,12 @@ A transitive or indirect dependency is a dependency of a dependency. If your cod
88
94
89
95
For more information, see [Supported languages](/docs/supported-languages#semgrep-supply-chain).
90
96
97
+
## Transitivity
98
+
99
+
Pertains to a dependency's relationship to your codebase or first-party code.
100
+
101
+
<TransitivityTypes />
102
+
91
103
## Usage
92
104
93
105
In Semgrep Supply Chain scans, a **usage **is a specific finding in your codebase where Semgrep has found a vulnerability. A vulnerability may have more than one usage, such as when a library is imported and used in many code files.
Copy file name to clipboardexpand all lines: docs/semgrep-supply-chain/policies.md
+43-6
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ tags:
12
12
13
13
By default, Semgrep AppSec Platform collects Supply Chain findings without notifying developers, similar to the [**Monitor** mode](/semgrep-code/policies#block-a-pr-or-mr-through-rule-modes) in Semgrep Code. This prevents developers from receiving notifications while you evaluate the tool.
14
14
15
-
Once you are ready to to notify developers through a **comment**, or potentially **block** them from merging a pull or merge request (PR or MR), define a **Supply Chain policy**. This feature helps you manage noise and ensures that developers are only notified or potentially blocked based on the conditions you set.
15
+
Once you are ready to notify developers through a **comment**, or potentially **block** them from merging a pull or merge request (PR or MR), define a **Supply Chain policy**. This feature helps you manage noise and ensures that developers are only notified or potentially blocked based on the conditions you set.
16
16
17
17
This feature enables you to configure the following:
18
18
@@ -32,20 +32,52 @@ Only **admins** can view, create, edit, or delete policies.
32
32
33
33
1. Sign in to [<iclass="fas fa-external-link fa-xs"></i> Semgrep AppSec Platform](https://semgrep.dev/login).
34
34
1. From the navigation menu, click **Rules** to expand the drop-down box, then click **Policies**.
35
-
1. Click **Supply Chain**. This takes you to the Supply Chain policies tab.
35
+
1. Click **Supply Chain**. This takes you to the Supply Chain policies tab. Your policies are arranged as cards.
_**Figure**. A single card within the Semgrep Supply Chain Policies page._
38
+
39
+
- To view and edit an existing policy, click its **name** or **the three-dot ellipsis (<iclass="fas fa-ellipsis-h"></i>) > Edit policy**.
40
+
- View a popup of a policy's **scope** (affected projects or tags) or a summary of its **actions and conditions** by clicking on the two summary links beside the policy name.
36
41
37
42
## Create a policy
38
43
39
-
1. From the Supply Chain policies tab, Click **Create policy**.
44
+
1. From the Supply Chain policies tab, Click **<iclass="fa-solid fa-plus"></i> Create policy**.
40
45
1. Provide a **Policy name**.
41
46
1. Define the scope of the policy:
42
-
1. Click the drop-down box to select between **All Projects**, **Project**, or **Project tag**.
47
+
1. Click the drop-down box to select between **All Projects**, **Project**, or **Project tag**. Note that you can only select either a scope based on projects or tags, but not both.
43
48
1. For **Project** or **Project tag** values, a second drop-down box appears. Choose the **projects** or **project tags** to finish defining the scope.
44
-
1. Define the conditions of the policy by selecting either **Reachable** or **Critical or high severity, reachable, upgrades available**. Selecting **Reachable** typically results in more findings shown to developers.
49
+
1. Define the conditions of the policy. See the [Policy conditions](#policy-conditions) section for more information. You can create more than one condition by clicking **Add condition**.
50
+
- For each condition, you can select multiple values by clicking on the **plus sign (<iclass="fa-solid fa-plus"></i>)** on the same row. The policy is applied when **any** of those values are met (`OR`).
51
+
- Each additional condition is additive. The policy is applied when **all** conditions are met (`AND`).
1. Define the actions of the policy. You can choose to **Leave a comment** or **Block and leave a comment**.
46
54
1. Click **Save**. This brings you back to the Supply Chain policies tab.
55
+
1. After creating a policy, it is **not** automatically enabled. Click the **<iclass="fa-solid fa-toggle-large-on"></i> toggle** to enable a policy. This applies the policy to future scans.
56
+
57
+
## Common use cases for policies
58
+
59
+
- Blocking reachable findings with upgradeable dependencies. This is a reasonable policy as it provides a path to unblock the user, as Semgrep can leave a comment with the upgrade instructions.
60
+
- Leaving a comment for:
61
+
- Reachable findings without upgradeable dependencies, to make the developer aware of the risk.
62
+
- Reachable, yet transitive findings; depending on your organization's policies, these may need to be flagged for risk.
63
+
64
+
## Policy scopes
65
+
66
+
A policy's scope can consist of tags or projects, but not both. If you need to create a policy with both tags and projects, simply make another policy.
47
67
48
-
After creating a policy, it is automatically **enabled** and will be applied to subsequent scans.
68
+
If a project or project tag that's included in a policy scope gets deleted, it is **removed from the policy scope**. If all projects or all project tags are deleted for a given policy, you must edit the policy for it to be applied to a valid scope.
69
+
70
+
## Policy conditions
71
+
72
+
The following table lists available conditions and their values:
Copy file name to clipboardexpand all lines: docs/semgrep-supply-chain/triage-remediation.md
+1-15
Original file line number
Diff line number
Diff line change
@@ -84,18 +84,4 @@ The **Vulnerabilities** tab allows you to identify the reachable, true positives
84
84
85
85
## Block pull or merge requests
86
86
87
-
Semgrep can help block pull requests (PRs) or merge requests (MRs) when it matches a blocking finding. When one or more findings is blocking, Semgrep returns exit code `1`, and you can use this result to set up additional checks to enforce a block in your CI/CD pipeline, such as not allowing merge of the PR/MR. This action applies to full and [diff-aware scans](/semgrep-code/glossary#diff-aware-scan).
88
-
89
-
Semgrep Supply Chain versions **v0.122.0** and earlier automatically aided in blocking pull or merge requests if it discovered reachable findings in the code, but later versions do not do this. You can, however, configure Semgrep Supply Chain to help block scans whenever all of the following conditions are met:
90
-
91
-
* It detects reachable findings in direct dependencies
92
-
* The reachable findings are of critical or high severity
93
-
* There is an upgrade available for the affected dependency; this is to prevent blocking when there is no resolution for the vulnerability
94
-
95
-
To enable **Scan Blocking**:
96
-
97
-
1. Sign in to Semgrep AppSec Platform.
98
-
2. Go to **Settings > Deployment** and navigate to the **Supply Chain (SCA)** section.
0 commit comments