diff --git a/docs/deployment/managed-scanning/azure.md b/docs/deployment/managed-scanning/azure.md new file mode 100644 index 000000000..669c06918 --- /dev/null +++ b/docs/deployment/managed-scanning/azure.md @@ -0,0 +1,126 @@ +--- +slug: azure +append_help_link: true +title: Azure DevOps +hide_title: true +description: Learn how to add an Azure DevOps repository to Semgrep Managed Scans. +tags: + - Beta + - Deployment + - Semgrep AppSec Platform +--- + +import ScanWithSms from "/src/components/procedure/_scan-with-sms.mdx" + +# Add an Azure DevOps repository to Semgrep Managed Scans + +Add Azure DevOps repositories to your Semgrep organization in bulk without adding or changing your existing CI workflows through **Managed Scans**. + + +## Prerequisites and permissions + +- Semgrep Managed Scanning requires repositories hosted by Azure DevOps Services. It currently doesn't support Azure DevOps Server. +- Semgrep recommends setting up and configuring Semgrep Managed Scanning with an Azure DevOps service account, not a personal account. Regardless of whether you use a personal or service account, the account must be assigned the **Owner** or **Project Collection Administrator** role for the organization. +- During setup and configuration, you must provide a personal access token generated by the account. This token must be granted the **Project and Team: Read & write** scope. + - Once you have Managed Scanning fully configured, you can update the token to **Project and Team: Read**, a more limited scope. + +## Enable Managed Scans and scan your first repository + + +1. In Semgrep AppSec Platform, click ** Projects**. +2. Click **Scan new project > Semgrep Managed Scan**. +3. Select **Azure Devops** as your source code manager. +4. On the **Add to Azure DevOps Pipeline** page, provide the following information: + 1. 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 token generation information. Ensure you set the Azure DevOps SCM name to `organization_name/project_name`. + 2. The name of your **Azure DevOps Project**. +5. Click **Connect** to proceed. + + +You have finished setting up a Semgrep managed scan. Click **Back to Managed Scans** to see your projects. + +- After enabling Managed Scans, Semgrep performs a full scan on all the repositories in batches. +- Once a repository has been added to Semgrep AppSec Platform, it becomes a **project**. A Semgrep AppSec Platform project includes all the repository's findings, history, and scan metadata. +- Projects scanned through Managed Scans are tagged with `managed-scan`. + +## Add additional Azure DevOps projects + +You can enable managed scanning for additional repositories after onboarding using the following steps: + + +1. In Semgrep AppSec Platform, click ** Projects**. +2. Click **Scan new project > Semgrep Managed Scan**. +3. On the **Enable Managed Scans for repos** page, select the repositories you want to add to Semgrep Managed Scans. + 1. Optional: If you don't see the repository you want to add, click **Sync projects**. +4. Select the repositories you want to scan from the list. +5. Click **Enable Managed Scans**. The **Enable Managed Scans** dialog appears. By default, Semgrep runs both full and diff-aware scans. +6. Optional: Disable PR or MR diff-aware scans by turning off the **Enable PR/MR scans** toggle. +7. Click **Enable**. + + +### If the page doesn't display any repositories + +1. In Semgrep AppSec Platform, click ** Projects**. +2. If the page doesn't display the repository you want to add, click **Sync projects**. +3. If the page doesn't display any repositories, click **Sync projects**. +4. Optional: Perform a hard refresh (Ctrl+F5 or Cmd+Shift+R). + +### Convert or migrate an existing Semgrep CI job + +You can immediately add any existing project to Managed Scans. + +1. Follow the steps in [Add additional Azure DevOps projects](#add-additional-azure-devops-projects). +2. Delete the existing pipeline configuration file in your repository if appropriate. + +If you plan to continue running some scans in Azure DevOps Pipelines (for example, using Managed Scans to run weekly full scans but Pipelines for diff-aware scans) you can leave the workflow file in place, and edit it to reflect your desired configuration. + +:::tip +Semgrep preserves your findings, scans, and triage history. +::: + + + +## Disable webhooks + +Managed scanning of Azure DevOps projects requires webhooks. The webhooks are enabled by default when you add Azure DevOps as a source code manager when setting up Managed Scanning. Webhooks are required for diff-aware scans and triaging by PR or MR comments. + +You can turn off webhooks at any time by following these steps: + +1. In Semgrep AppSec Platform, go to [Settings > Source code managers](https://semgrep.dev/orgs/-/settings/source-code). +2. Find your Azure DevOps connection, and click the toggle to turn off **Incoming webhooks**. + +## Revoke Semgrep's access to your repositories + +The following steps revoke the code access you previously granted Semgrep for all repositories you selected. + +1. In Semgrep AppSec Platform, click ** Settings > Source Code Managers**. +2. Find the Azure DevOps entry on the list of **Source code managers** and click **Remove**. +3. Click **Remove** to confirm. + +## Appendices + +
+Scan logs and statistics + +### Scan logs + +#### Most recent scan + +You can view logs for your most recent scan by clicking **Projects > the project's latest scan time** under **Scan status**. + +![Click the project's latest scan to view the log](/img/sms-logs.png) +_**Figure**. The Projects page. Click the project's latest scan (underlined) to view the log._ + +:::info +It can take a few minutes for your latest scan logs to appear. However, if the logs do not update 15 minutes after the scan, there may be issues with the scan itself. +::: + +#### All scans + +1. Click the project's **Details** page > **Scans** tab. +1. Click the **** scroll icon under **Logs** to view the log for the particular entry. + +### Scan statistics + +**Scan statistics**, such as how many of your repositories are being scanned, the scan success rate, and so on, can be provided once a week upon request. Contact your Semgrep account manager to request scan statistics. + +
\ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 50e72f1a4..fa34f40f1 100644 --- a/sidebars.js +++ b/sidebars.js @@ -98,6 +98,7 @@ module.exports = { collapsible: true, link: {type: 'doc', id: 'deployment/managed-scanning/overview'}, items: [ + 'deployment/managed-scanning/azure', 'deployment/managed-scanning/github', 'deployment/managed-scanning/gitlab' ]