-
Notifications
You must be signed in to change notification settings - Fork 90
add docs for ADO SMS #1910
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
add docs for ADO SMS #1910
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
0d27efe
begin draft of ADO SMS doc
khorne3 7a804d4
minor edits
khorne3 2f9f718
Apply suggestions from review
khorne3 53e040a
add info on when webhooks are required
khorne3 20f2c70
Merge branch 'katiehorne/tec-256-new-docs-sms-for-ado' of https://git…
khorne3 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,123 @@ | ||
--- | ||
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 instead of 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 one with a more limited scope, specifically **Project and Team: Read**. | ||
khorne3 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## Enable Managed Scanning and scan your first repository | ||
khorne3 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
<!-- vale off --> | ||
1. In Semgrep AppSec Platform, click **<i class="fa-solid fa-folder-open"></i> 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, then click **Connect** to proceed: | ||
khorne3 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
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**. | ||
<!-- vale on --> | ||
khorne3 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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: | ||
|
||
<!-- vale off --> | ||
1. In Semgrep AppSec Platform, click **<i class="fa-solid fa-folder-open"></i> 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**. | ||
<!-- vale on --> | ||
|
||
### If the page doesn't display any repositories | ||
|
||
1. In Semgrep AppSec Platform, click **<i class="fa-solid fa-folder-open"></i> 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 (<kbd>Ctrl</kbd>+<kbd>F5</kbd> or <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>R</kbd>). | ||
|
||
### 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. | ||
khorne3 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
::: | ||
|
||
<ScanWithSms /> | ||
|
||
## Disable webhooks | ||
khorne3 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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. 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 <i class="fa-solid fa-toggle-large-on"></i> 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 **<i class="fa-solid fa-gear"></i> 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 | ||
|
||
<details> | ||
<summary>Scan logs and statistics</summary> | ||
|
||
### Scan logs | ||
|
||
#### Most recent scan | ||
khorne3 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
You can view logs for your most recent scan by clicking **Projects > the project's latest scan time** under **Scan status**. | ||
|
||
 | ||
_**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 **<i class="fas fa-scroll"></i>** 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. | ||
|
||
</details> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.