resolve merge conflicts

Author: khorne3

docs/contributing/contributing-rules.md

@@ -2,29 +2,30 @@
 slug: contributing-to-semgrep-rules-repository
 description: "This article outlines how to contribute to Semgrep Registry."
 hide_title: true
+title: Contribute rules to the Semgrep Registry
 toc_max_heading_level: 4
 ---
 
 import LinkToRegistryRule from "/src/components/LinkToRegistryRule"
-
 import RequiredRuleFields from "/src/components/reference/_required-rule-fields.mdx"
 
-# Contributing rules
+# Contribute rules to the Semgrep Registry
 
-Publish rules in the open source Semgrep Registry and share them with the Semgrep community to help others benefit from your rule-writing efforts and contribute to the field of software security. There are two ways in which you can contribute rules to the Semgrep Registry:
+Publish rules to the Semgrep Registry to share them with the Semgrep community and contribute to the field of software security. There are two ways in which you can contribute rules to the Semgrep Registry:
 
 <dl>
     <dt>For users of Semgrep AppSec Platform</dt>
-    <dd>Contribute rules to the Semgrep Registry through Semgrep AppSec Platform. This workflow is recommended. See <a href="#contributing-through-semgrep-appsec-platform-recommended"> Contributing through Semgrep AppSec Platform (recommended)</a>. This workflow creates the necessary pull request for you and streamlines the whole process.</dd>
+    <dd>Contribute new rules to the Semgrep Registry through Semgrep AppSec Platform. This workflow is recommended. See <a href="#contribute-through-semgrep-appsec-platform-recommended"> Contribute through Semgrep AppSec Platform (recommended)</a>. This workflow creates the necessary pull request for you and streamlines the whole process.</dd>
     <dt>For contributors to the repository through GitHub</dt>
-    <dd>Contribute rules to the Semgrep Registry through a pull request. See the <a href="#contributing-through-github"> Contributing through GitHub</a> section for detailed information.</dd>
+    <dd>Contribute rules to the Semgrep Registry, or suggest changes to existing rules, through a pull request to `semgrep-rules`. See the <a href="#contribute-through-github"> Contribute through GitHub</a> section for detailed information.</dd>
 </dl>
 
-## Contributing through Semgrep AppSec Platform (recommended)
+## Contribute through Semgrep AppSec Platform (recommended)
 
-To contribute and publish rules to the Semgrep Registry through Semgrep AppSec Platform, follow these steps:
+This is the recommended path for adding a new rule. To suggest a change to an existing rule, see [Update existing rules in Semgrep Registry](#update-existing-rules-in-semgrep-registry).
 
-1. Go to [Playground](https://semgrep.dev/playground/new).
+1. Sign in to [<i class="fas fa-external-link fa-xs"></i> Semgrep AppSec Platform](https://semgrep.dev/login).
+1. Go to the [<i class="fas fa-external-link fa-xs"></i> Semgrep Playground](https://semgrep.dev/playground/new).
 1. Click <i className="fa-solid fa-file-plus-minus inline_svg"></i> **Create New Rule**.
 1. Choose one of the following:
     - Create a new rule and test code by clicking <i class="fa-solid fa-circle-plus"></i> **plus** icon, select **New rule** and then click <i className="fa-solid fa-floppy-disk inline_svg"></i> **Save**. Note: The test file must contain at least one true positive and one true negative test case to be approved. See the [Tests](#tests) section of this document for more information.
@@ -34,21 +35,30 @@ To contribute and publish rules to the Semgrep Registry through Semgrep AppSec P
 1. Fill in the required and optional fields.
 1. Click <i className="fa-solid fa-circle-check inline_svg"></i> **Continue**, and then click <i className="fa-solid fa-code-pull-request inline_svg"></i> **Create PR**.
 
-This workflow automatically creates a pull request in the GitHub [Semgrep Registry](https://github.com/semgrep/semgrep-rules). Find more about the Semgrep Registry by reading the [Rule writing](#writing-a-rule-for-semgrep-registry) and [Tests](#tests) sections.
+This workflow automatically creates a pull request in the GitHub [Semgrep Registry](https://github.com/semgrep/semgrep-rules). Find more about the Semgrep Registry by reading the [Rule writing](#write-a-rule-for-semgrep-registry) and [Tests](#tests) sections.
 
 You can also publish rules as private rules outside of Semgrep Registry. These rules are not included in the Semgrep Registry, but they are accessible to your Semgrep organisation. See the [Private rules](/writing-rules/private-rules) documentation for more information.
 
-## Contributing through GitHub
+## Contribute through GitHub
 
-Fork our repository and make a pull request. Sign our Contributor License Agreement (CLA) on GitHub before Semgrep, Inc. can accept your contributions. Make a pull request to the [Semgrep Registry](https://github.com/semgrep/semgrep-rules) with two files:
-1. The semgrep pattern (as YAML file).
-2. The test file (with the file extension of the language or framework). The test file must contain at least one true positive and one true negative test case to be approved. See the [Tests](#tests) section of this document for more information.
+1. Create a pull request in the [<i class="fas fa-external-link fa-xs"></i> semgrep/semgrep-rules](https://github.com/semgrep/semgrep-rules) repository. The pull request requires two files:
+    - The Semgrep rule saved as a YAML file.
+    - The test file with the file extension of the language or framework. The test file must contain at least one true positive and one true negative test case to be approved. See the [Tests](#tests) section of this document for more information.
+1. Sign the Contributor License Agreement (CLA) on GitHub; this is required before Semgrep can accept your contributions.
 
 Pull requests require the approval of at least one maintainer and successfully passed [CI jobs](https://github.com/semgrep/semgrep-rules/actions).
 
-Find more about the Semgrep Registry by reading the [Rule writing](#writing-a-rule-for-semgrep-registry) and [Tests](#tests) sections.
+Find more about the Semgrep Registry by reading the [Rule writing](#write-a-rule-for-semgrep-registry) and [Tests](#tests) sections.
+
+## Licensing
+
+The Semgrep Registry can import rules from different repositories. These repositories can enforce their own licensing for rules. If you'd like to enforce a specific license, such as the MIT license or GNU Lesser GPL:
 
-## Writing a rule for Semgrep Registry
+1. Create a GitHub repository and store your rules there.
+1. Reach out to the Semgrep team through the [<i class="fas fa-external-link fa-xs"></i> Community Slack](https://go.semgrep.dev/slack)  or [Support](/support)
+
+
+## Write a rule for Semgrep Registry
 
 The following sections document necessary fields in rule files of Semgrep Registry, provide information about rule messages, inform about test files, mention rule quality checkers, and describe additional fields required by rules in the security category.
 
@@ -175,7 +185,7 @@ In addition to the fields mentioned above, rules submitted to Semgrep Registry h
 - Cross-file (interfile) analysis requires `interfile: true` under the `options` key in YAML rules. For more information, see [Creating rules that analyze across files](/semgrep-code/semgrep-pro-engine-intro/#write-rules-that-analyze-across-files-and-functions).
 :::
 
-### Understanding rule namespacing
+### Rule namespace
 
 The namespacing format for contributing rules in the [Semgrep Registry](https://github.com/semgrep/semgrep-rules) is `<language>/<framework>/<category>/$MORE`. If the rule does not belong to a particular framework, add it to the language directory, which uses the word `lang` in place of the `<framework>` - `<language>/<lang>`.
 
@@ -235,7 +245,7 @@ For an example of a good rule message, see: [this rule for Django's `mark_safe`]
 
 When you contribute rules to the Semgrep Registry, our quality checkers (linters) evaluate if the rule conforms to Semgrep, Inc. standards. The `semgrep-rule-lints` job runs linters on a new rule to check for mistakes, performance problems, and best practices for submitting to the Semgrep Registry. To improve your rule writing, use Semgrep itself to [scan semgrep-rules](https://semgrep.dev/blog/2021/how-we-made-semgrep-rules-run-on-semgrep-rules/).
 
-### Including fields required by security category
+### Fields required by the `security` category
 
 Rules in category `security` in the Semgrep Registry require specific metadata fields that ensure consistency across the ecosystem in both Semgrep AppSec Platform and Semgrep CLI. Nest these metadata under the `metadata` field.
 
@@ -542,9 +552,7 @@ You can provide custom values. Sample values include:
 - XML Injection
 - XPath Injection
 
-## Updating existing open source rules in Semgrep Registry
-
-To update an existing open source rule, follow these steps:
+## Update existing rules in Semgrep Registry
 
 1. Find a rule you want to update in the [semgrep-rules](https://github.com/semgrep/semgrep-rules/) repository.
 2. Submit a PR to the repository with your new update.

docs/deployment/connect-scm.md

@@ -11,6 +11,7 @@ tags:
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import PL from '@site/src/components/Placeholder';
 
 # Connect a source code manager
 
@@ -52,11 +53,11 @@ If you opted to scan a GitHub or GitLab repository when you initially signed in,
 1. Optional: If you have created more than one Semgrep account, select the account you want to make a connection for by clicking on the **Navigation bar > Your account name > The account you want to connect**.<br />
    <img src="/docs/img/more-accounts-dropdown.png" height="350px" />
 1. Go to **<i class="fa-solid fa-gear"></i> Settings > Source code managers > Add > Azure DevOps**. 
-1. In the **Connect your Azure DevOps organization** dialog box, provide:
-   - The **Name of your Azure DevOps organization**
+1. In the **Connect your Azure DevOps Project** dialog box, provide:
+   - The **Name of your Azure DevOps Project**. Ensure that the value you provide follows the format <PL>organization</PL>/<PL>project</PL>. This information can be seen in the project URL, for example `https://dev.azure.com/organization/project`. 
    - Your **Access token**. See [User personal access tokens](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate) for information on generating a token.
 2. Click **Connect** to save and proceed.
-3. The Azure DevOps organization is now listed under **Source Code managers**. Click **Test** to verify that the new integration is installed correctly.
+3. The Azure DevOps project is now listed under **Source code managers**. Click **Test** to verify that the new connection is installed correctly.
 
 </TabItem>
 <TabItem value='bitbucket-cloud'>
@@ -67,34 +68,46 @@ If you opted to scan a GitHub or GitLab repository when you initially signed in,
 1. Go to **<i class="fa-solid fa-gear"></i> Settings > Source code managers > Add > Bitbucket Cloud**.
 1. In the **Connect your Bitbucket Workspace** dialog box, provide:
    - The **Name of your Bitbucket Workspace**
-   - Your **Access token**. Semgrep expects a [workspace-level access token](https://support.atlassian.com/bitbucket-cloud/docs/create-a-workspace-access-token/).
+   - Your **Access token**. Semgrep requires a [workspace-level access token](https://support.atlassian.com/bitbucket-cloud/docs/create-a-workspace-access-token/).
 1. Click **Connect** to save and proceed.
-1. The Bitbucket project is now listed under **Source Code managers**. Click **Test** to verify that the new integration is installed correctly.
+1. The Bitbucket project is now listed under **Source code managers**. Click **Test** to verify that the new connection is installed correctly.
 
 </TabItem>
 <TabItem value='github-cloud'>
 
+### GitHub Cloud with GitHub SSO
+
+These steps are for users that sign in to Semgrep through GitHub.
+
 1. Sign in to [<i class="fas fa-external-link fa-xs"></i> Semgrep AppSec Platform](https://semgrep.dev/login).
 1. Optional: If you have created more than one Semgrep account, select the account you want to make a connection for by clicking on the **Navigation bar > Your account name > The account you want to connect**.<br />
    <img src="/docs/img/more-accounts-dropdown.png" height="350px" />
 1. From the **Navigation bar**, click **<i class="fa-solid fa-gear"></i> Settings > Source code managers**.
-1. Click **Connect to GitHub**.
+1. Click **Add > GitHub**.
 1. Review the permissions requested by Semgrep, then click **Continue**.
 1. Click the organization you want to install Semgrep on.
 1. Choose to authorize and install Semgrep for **<i class="fa-regular fa-circle-dot"></i> All repositories** or **<i class="fa-regular fa-circle-dot"></i> Only select repositories**.
 1. Click **Install and authorize**.
 1. After a successful link, you are signed out of Semgrep AppSec Platform automatically, as your credentials have changed after linking an organization.
 1. Sign back in to Semgrep AppSec Platform.
 
-</TabItem>
+### GitHub Cloud with non-GitHub SSO
 
-<!-- removed temporarily because we're using the "old flow"
-:::tip
-- Getting Assistant recommendations grants Semgrep **code access**.
-- **Leave PR comments** refers to Semgrep's capability to post findings to developers in PRs.
-:::
+These steps are for users that sign in to Semgrep through a **non-GitHub** SSO provider.
+
+1. Navigate to the following link: [<i class="fas fa-external-link fa-xs"></i> Semgrep GitHub app](https://github.com/marketplace/semgrep-dev) and install the Semgrep GitHub app onto the GitHub org you want to connect to.
+1. Sign in to [<i class="fas fa-external-link fa-xs"></i> Semgrep AppSec Platform](https://semgrep.dev/login) using SSO.
+1. Optional: If you have created more than one Semgrep account, select the account you want to make a connection for by clicking on the **Navigation bar > Your account name > The account you want to connect**.<br />
+   <img src="/docs/img/more-accounts-dropdown.png" height="350px" />
+1. From the **Navigation bar**, click **<i class="fa-solid fa-gear"></i> Settings > Source code managers**.
+1. Click **Add > GitHub**.
+1. In the **Name of your GitHub Organization** field, enter the slug of the org that the app was installed on in step 1. For example, if the GitHub URL of your org is `https://github.com/acme-corp`, then the slug is typically `acme-corp`.
+1. Leave the access token field empty.
+1. Click **Connect**.
+1. Your GitHub org is now listed under **Source Code managers**. Click **Test** to verify that the new connection is installed correctly.
+
+</TabItem>
 
--->
 
 <TabItem value='gitlab-cloud'>
 
@@ -106,7 +119,7 @@ If you opted to scan a GitHub or GitLab repository when you initially signed in,
 1. Enter the personal access token generated into the **Access token** field.
 1. Enter your GitLab group's name into the **Name of your GitLab Group** field. If your repositories are organized in subgroups, you only need to provide the name of the top-level group.
 1. Optional, but recommended: if you have multiple GitLab groups in your GitLab account, create a source code manager per group. Repeat steps 1, 3-4 for each GitLab group.
-1. The GitLab groups are now listed under **Source code managers**. Click **Test** to verify that the new integration is configured correctly.
+1. The GitLab groups are now listed under **Source code managers**. Click **Test** to verify that the new connection is configured correctly.
 
 You have successfully connected an org in Semgrep AppSec Platform with an organization in your source code management tool.
 
@@ -126,16 +139,21 @@ You have successfully connected an org in Semgrep AppSec Platform with an organi
 
 <TabItem value='bitbucket-data-center'>
 
+
+1. Create an HTTP Access Token for your project following the steps outlined in [<i class="fas fa-external-link fa-xs"></i> Bitbucket Data Center documentation](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html). Ensure that the access token is created with `PROJECT_ADMIN` permissions.
+1. Copy the token for use in the next steps.
 1. Sign in to [<i class="fas fa-external-link fa-xs"></i> Semgrep AppSec Platform](https://semgrep.dev/login).
 1. Optional: If you have created more than one Semgrep account, select the account you want to make a connection for by clicking on the **Navigation bar > Your account name > The account you want to connect**.<br />
    <img src="/docs/img/more-accounts-dropdown.png" height="350px" />
 1. Go to **<i class="fa-solid fa-gear"></i> Settings** > **Source code managers**, and click **Add > Bitbucket Data Center**.
 1. In the **Connect your Bitbucket project (key)** dialog box, provide:
    - The **Name of your Bitbucket project (key)**. This must be the project key, which you can find by navigating to `<YOUR_BITBUCKET_DATA_CENTER_BASE_URL>/projects`.
-   - The **URL** to access your installation of Bitbucket Data Center
-   - The **Access Token** that [grants Semgrep permission to communicate with your project](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html). Semgrep expects a [workspace-level access token](https://support.atlassian.com/bitbucket-cloud/docs/create-a-workspace-access-token/)
-2. Click **Connect** to save and proceed.
-3. The Bitbucket project is now listed under **Source code managers**. Click **Test** to verify that the new integration was installed correctly.
+   - The **URL** to access your installation of Bitbucket Data Center; this is your fully-qualified domain name.
+   - The **Access Token** that grants Semgrep permission to communicate with your project. Semgrep expects an [HTTP access token](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html) with `PROJECT_ADMIN` permissions.
+1. Click **Connect** to save and proceed.
+1. The Bitbucket project is now listed under **Source code managers**. Click **Test** to verify that the new connection was installed correctly.
+1. To enable merge request comments, click **<i class="fa-solid fa-toggle-large-on"></i> Incoming webhooks**.
+1. Optional: Click **Auto scan** to onboard all current and future repositories under your project to Semgrep Managed Scanning.
 
 </TabItem>
 <TabItem value='github-enterprise'>
@@ -214,7 +232,7 @@ Connect Semgrep and GitLab Self-Managed accounts by creating a PAT and providing
 1. Enter your GLSM base URL into the **URL** field.
 1. Enter your GitLab group's name into the **Name of your GitLab Group** field. If your repositories are organized in subgroups, you only need to provide the name of the top-level group.
 1. If you have multiple GitLab groups in your GitLab account, you need to create a source code manager per group. Repeat steps 1, 3-5 for each GitLab group.
-1. The GitLab groups are now listed under **Source Code managers**. Click **Test** to verify that the new integration is installed correctly.
+1. The GitLab groups are now listed under **Source Code managers**. Click **Test** to verify that the new connection is installed correctly.
 
 </TabItem>
 </Tabs>

docs/deployment/create-account-and-orgs.md

@@ -80,7 +80,7 @@ Semgrep organizations can be **connected** to equivalent GitHub, GitLab, and SSO
 
 ### Next steps for Bitbucket and Azure Repos users
 
-- Connect your Semgrep org to your Bitbucket Data Center project or your Azure DevOps organization. Refer to [<i class="fa-regular fa-file-lines"></i> Connect a source code manager](/deployment/connect-scm) for steps.
+- Connect your Semgrep org to your Bitbucket Data Center project or your Azure DevOps project. Refer to [<i class="fa-regular fa-file-lines"></i> Connect a source code manager](/deployment/connect-scm) for steps.
 - To add members to your Semgrep organization, set up [<i class="fa-regular fa-file-lines"></i> SSO authentication](/deployment/sso).
 - You can also opt to scan a repository instead.