Pre-deployment checklist
Before starting the deployment setup, use this checklist to ensure that:
- You and your organization agree on the scope of the deployment.
- You are aware of permissions that Semgrep needs to provide certain functions.
- You have access to the resources needed to carry out the deployment.
Ensure that your infrastructure meets all the Prerequisites to run Semgrep.
Stakeholders and deployment team
For medium-to-large teams, typically with more than 10 developers, coordinating with other departments before starting the deployment is crucial to an efficient roll-out. A complete deployment ensures that your licenses are fully used.
Here are some teams or departments that may be responsible for parts of your Semgrep deployment:
| Department | Tasks related to deployment |
|---|---|
| Infrastructure | SSO, CI/CD, and source code manager (SCM) configuration. |
| Engineering | Repository ownership, displaying findings to developers in PRs or MRs. |
| IT | Firewall or VPN configuration. |
Scope
Scope refers to the breadth of deployment integration within your organization. The more users and repositories you onboard to Semgrep, the more crucial training becomes for security champions within your organization.
Ensure that all stakeholders agree on:
- Which users and departments will use Semgrep.
- Which repositories you will scan with Semgrep.
- How frequently you run Semgrep scans, such as daily or weekly, and at what time. This may affect other processes, such as PR approvals.
- A timeframe for deployment. You may divide this into phases.
Deployment times vary greatly depending on your processes and size.
Monorepos may take longer to finish scanning. Semgrep provides several options to improve performance, including piecemeal scanning of the monorepo. See Scanning a monorepo in parts for more information.
Roles
Semgrep provides two primary roles: admin and member.
Deployments can also enable a third role, manager, through the Teams feature, which provides project-level role-based access control.
For single-user deployments, you are the sole admin of your deployment.
For multi-user deployments, determine the following:
- The administrators (admins) that own the Semgrep deployment.
- For
members, ensure that they have a sign-in method:- SSO
- GitHub Cloud
- GitLab Cloud
Required permissions and access
The following checklist breaks down permissions required by Semgrep features.
| Feature | Permission required |
|---|---|
| Run Semgrep continuously in your CI workflows. | Adding or making changes to CI jobs. This includes committing configuration files for each repository. |
| Defining environment variables and storing secrets. | |
| Run Semgrep continuously without changing your CI workflows. | Read access to user-selected repositories. |
| Manage user authentication with SSO. | Viewing and editing of SSO configurations. |
| Receive Slack notifications. | Being a Slack workspace owner; alternatively, coordinate with the team responsible. |
| Send pull or merge requests to your SCM. | Editing firewall or VPN allowlist for self-hosted repositories. |
SCM-specific required permissions
- Azure DevOps
- Bitbucket
- GitHub
- GitLab
GitHub
| Feature | Permission required |
|---|---|
| Create CI jobs for repositories in bulk and detect GitHub repositories automatically. | Installing GitHub apps. |
| AI-assisted triage and recommendations. | Code access. |
GitLab
| Feature | Permission required |
|---|---|
| Merge request (MR) comments. | Create personal access tokens. |
| AI-assisted triage and recommendations. | Create personal or project-level access tokens. |
| Read access to user-selected repositories. |
Bitbucket
| Feature | Permission |
|---|---|
| Pull request (PR) comments. | Able to create repository variables. |
Azure DevOps
| Feature | Permission |
|---|---|
| Pull request (PR) comments. | Able to create user personal access tokens. |
Appendices
Permissions
- Permissions for GitHub
- Permissions for GitLab
Permissions for GitHub
This section explains Semgrep AppSec Platform permissions that are requested in two different events:
- When you first sign in through GitHub.
- When you first add, integrate, or onboard your repositories to Semgrep AppSec Platform.
Permissions when signing in with GitHub
Semgrep AppSec Platform requests the following standard permissions set by GitHub when you first sign in. However, not all permissions are used by Semgrep AppSec Platform.
Click to review how Semgrep AppSec Platform uses permissions when signing in.
Permissions when adding members or repositories into Semgrep AppSec Platform
The public GitHub integration app is called semgrep-app. This app is used to integrate Semgrep into user-selected GitHub repositories.
Click to review how Semgrep AppSec Platform uses permissions when adding members or repositories.
Permissions when adding repositories into Semgrep AppSec Platform through managed scanning or using AI features
You can optionally create a private GitHub app, which follows the naming convention Semgrep Code - YOUR_ORG_NAME. This private app is used for the following features:
- To add repositories to Semgrep AppSec Platform without changing your existing CI workflows. To learn more, see Managed scanning.
- To integrate AI-asssisted features into your Semgrep organization. To learn more, see Semgrep Assistant overview.
These features require read access to your code.
Click to review how Semgrep AppSec Platform uses permissions when adding repositories through managed scanning.
Permissions for GitLab
Semgrep requires the following permissions (scopes) to enable the authentication of a session:
openidemailprofileAPI
IP addresses
If you are behind a firewall, are using a virtual private network (VPN), or have network restrictions regarding access, you may need to add the following IP addresses to the ingress allowlist and egress allowlist:
# Ingress IP addresses (from Semgrep to your infrastructure)
# and egress IP addresses (from your infrastructure to Semgrep)
35.166.231.235
52.35.248.246
52.34.137.110
44.225.64.41
Additional egress IP addresses
You must also add CloudFront IP addresses to your egress allowlist. Refer to Locations and IP address ranges of CloudFront edge servers for a list of IP addresses.
Allowlists when using Semgrep Network Broker
The Semgrep Network Broker facilities secure access with Semgrep, and its use can replace the allowlisting of the IP addresses required for ingress. The Network Broker, however, only facilitates requests from Semgrep to your network and doesn't assist with requests originating from your network, including those from your network to Semgrep.
In other words, the only address you would have to allow inbound is wireguard.semgrep.dev on UDP port 51820, but depending on how restrictive your network is, you may need to modify your allowlist to include the egress IP addresses provided in IP addresses.
Features that require inbound network connectivity
Semgrep versions
Many improvements to the Semgrep AppSec Platform experience only work with up-to-date Semgrep CLI versions. As such, Semgrep AppSec Platform only supports the 10 most recent minor versions of Semgrep CLI. For example, if the latest release was 1.60.0, all versions greater than 1.50.0 are supported, while earlier versions, such as 1.49.0, can be deprecated or can result in failures.
To update Semgrep, see Update Semgrep.
Docker users: use the latest tag to ensure you are up to date.
Semgrep AppSec Platform session details
- The time before you need to reauthenticate to Semgrep AppSec Platform is 7 days.
- A Semgrep AppSec Platform session token is valid for 7 days.
- This session timeout is not configurable.
- Semgrep AppSec Platform does not use cookies; instead it uses
localStorageto store access tokens. The data inlocalStorageexpires every 7 days.
Additional resources
Check out How to introduce Semgrep to your organization from Trail of Bits for tips on how to evaluate and deploy Semgrep for your org.
Not finding what you need in this doc? Ask questions in our Community Slack group, or see Support for other ways to get help.