Skip to content

Commit

Permalink
Merge branch 'sara/sidebar-v3.02/deployment' into develop
Browse files Browse the repository at this point in the history
  • Loading branch information
@s-santillan
s-santillan committed Jan 19, 2024
2 parents cd07d08 + f02103a commit 7f16492
Show file tree
Hide file tree
Showing 39 changed files with 1,364 additions and 478 deletions.
11 changes: 11 additions & 0 deletions docs/cheat-sheets/overview.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
slug: /cheat-sheets/overview
append_help_link: true
title: Cheat sheets
hide_title: true
description: tk
tags:
- tk
---

# Cheat sheets
207 changes: 207 additions & 0 deletions docs/choose-oss-pro.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,207 @@
---
slug: choose-oss-pro
append_help_link: true
title: Choose between Semgrep Pro and Semgrep OSS
hide_title: true
description: tk
tags:
- Semgrep OSS
- Semgrep Team & Enterprise Tier
---

# Semgrep Pro versus Semgrep OSS

You can use Semgrep Pro or Semgrep OSS to scan your code for security issues, bugs, and compliance to coding standards. Semgrep uses both an engine and rules to scan your code.

**Rules**, which are written in YAML, describe how Semgrep generates a **finding**, such as a security issue. A rule encapsulates the pattern-matching logic and is meant to be readable and customizable.

The **engine** runs an analysis using the rules you have configured it to run. Semgrep provides both a proprietary Pro engine, and an OSS engine.

This document outlines key differences between the Semgrep OSS and Pro product lines.

The terms used in this document are defined as follows:

<dl>
<dt>Semgrep OSS</dt>
<dd>Refers to Semgrep offerings with an open-source license, primarily the Semgrep OSS Engine, a fast and customizable static application security testing (SAST) scanner. To run Semgrep completely on OSS, use the OSS Engine and rules in the <a href=" https://semgrep.dev/r/"><i class="fas fa-external-link fa-xs"></i> Semgrep Registry</a> with <strong>open source licenses</strong>, or write your own custom rules.</dd>
<dt>Semgrep Pro</dt>
<dd>Refers to proprietary product offerings from Semgrep, Inc. These include:<dl>
<dt>Semgrep Code</dt><dd>A SAST scanner that uses cross-file (interfile) analysis for improved results over Semgrep OSS. Semgrep Code includes premium rules, known as Pro rules, that use the cross-file analysis to reduce false positives.</dd>
<dt>Semgrep Supply Chain</dt><dd>A high-signal dependency scanner that detects reachable vulnerabilities in open source third-party libraries and functions across the software development life cycle (SDLC).</dd>
<dt>Semgrep Secrets (beta)</dt><dd>A a secrets scanner that, in addition to detecting secrets, validates these leaked secrets on a variety of services to help you prioritize active secrets.</dd>
<dt>Semgrep Cloud Platform</dt><dd>A a web application for the deployment, management, and monitoring of findings from Semgrep's SAST, SCA, and secrets scanners. It integrates with continuous integration (CI) providers such as GitHub Actions, GitLab CI/CD, CircleCI, and more.</dd>
</dl>
</dd>
</dl>

:::tip
The following products are **free** for up to 10 contributors:
* Semgrep Cloud Platform
* Semgrep Code
* Semgrep Supply Chain
* Semgrep Secrets
:::

## 🔎 Core scanning features

The following tables describe Semgrep's essential scanning and findings management capabilities.

### SAST (Static Application Security Testing)

| Feature | Semgrep OSS | Semgrep Pro |
| ------------------------------------------------------------------------------------- | ----------- | ---------------------- |
| Intrafile (single-file) analysis | ✔️ | ✔️ |
| Cross-file (across multiple files or interfile) analysis | -- | ✔️ |
| [Single-file taint](/writing-rules/data-flow/data-flow-overview/) (dataflow) analysis | ✔️ | ✔️ |
| [Cross-file taint](/semgrep-code/semgrep-pro-engine-intro/) (dataflow) analysis | -- | ✔️ |

### SCA (Software composition analysis)

| Feature | Semgrep OSS | Semgrep Pro |
| --------------------------------------------------------------- | ----------- | ------------------------------ |
| Reachability analysis for direct dependencies | -- | ✔️ |
| [License compliance](/semgrep-supply-chain/license-compliance/) | -- | ✔️ |
| [Dependency search](/semgrep-supply-chain/dependency-search) | -- | ✔️ |
| SBOM export | -- | ✔️ |

## 💬 Scan management and monitoring

The following table displays various notification channels and reporting features.

| Feature | Semgrep OSS | Semgrep Pro |
| --------------------------------------------------------------------------------------------------------------- | ----------- | ----------------- |
| [Centralized management of scan results (triage, remediation, fine-tuning noisy rules)](/semgrep-code/policies) | -- | ✔️ |
| [Notifications and reports (Slack, email, webhooks, and API)](/semgrep-cloud-platform/notifications/) | -- | ✔️ |
| Send scan results to GitLab SAST and GitHub Advanced Security | -- | ✔️ |
| [Findings dashboard](/semgrep-cloud-platform/dashboard/) | -- | ✔️ |
| Findings retention | -- | 5 years |

## 🧰 Scan customization features

The following table displays customization features and tools that enhance Semgrep's core scanning capabilities. These features can increase true-positive rate and provide deeper insights into remediation.

| Feature | Semgrep OSS | Semgrep Pro |
| ------------------------------------------------------------ | ----------------------------------------------- | -------------------------------------------- |
| Write your own rules | ✔️ | ✔️ |
| Private rules\* | n/a | ✔️ |
| [Community-contributed rule registry](https://semgrep.dev/r) | ✔️ | ✔️ |
| Proprietary rule registry | -- | ✔️ |
| [Policy-based workflows†](/semgrep-code/policies/) | -- | ✔️ |
| Rule-writing environment | ✔️ [Playground](https://semgrep.dev/playground) | ✔️ Playground and Editor for logged-in users |

\*Private rules refer to rules that are guaranteed a private access scope in the cloud. This scope of access does not apply to Semgrep OSS, as Semgrep OSS is purely CLI-based.<br />
† Policy-based workflows provide security teams a means to block merges, leave PR/MR comments, or silently monitor for potential issues based on the presence of a finding.

### 🤖 Developer experience

The following table lists tools to enable developers to resolve their own code.

| Feature | Semgrep OSS | Semgrep Pro |
| ------------------------- | ----------- | ----------------- |
| VS Code extension | ✔️ | ✔️ |
| IntelliJ extension | ✔️ | ✔️ |
| Autofix | ✔️ | ✔️ |
| Autofix in PR/MR comments | -- | ✔️ |
| Autofix AI | -- | ✔️ |
| `pre-commit`‡ | ✔️ | ✔️ |

‡`pre-commit` requires some manual set-up.

### 🏢 User and organization management

| Feature | Semgrep OSS | Semgrep Pro |
| ------------------------------------------------------------------------------------------------------------- | ----------- | ----------------- |
| [Role-based access control (RBAC)](/semgrep-cloud-platform/user-management/#controlling-access-through-roles) | -- | ✔️ |
| [Personal and organizational accounts](/semgrep-cloud-platform/user-management/) | -- | ✔️ |
| [SSO, OpenID, or OAuth2 authentication](/semgrep-cloud-platform/sso/) | -- | ✔️ |

## 🧾 Licenses and tiers

<table>
<thead>
<tr>
<th>Product line</th>
<th>License</th>
<th>Tiers</th>
</tr>
</thead>
<tbody>
<tr>
<td>Semgrep Pro</td>
<td>Proprietary</td>
<td><ul><li>Semgrep Team</li>
<li>Semgrep Enterprise</li></ul></td>
</tr>
<tr>
<td>Semgrep OSS Engine</td>
<td>GNU LGPL 2.1</td>
<td>--</td>
</tr>
<tr>
<td>Publicly-contributed rules</td>
<td>Various; dependent on author</td>
<td>--</td>
</tr>
</tbody>
</table>

See [<i class="fa-regular fa-file-lines"></i> Licensing](/licensing/#semgrep-registry-license) for more details.

<!-- don't have a good place to put this for now.
## Differences between Semgrep Code and Semgrep Supply Chain
The following table displays differences between Semgrep Code and Semgrep Supply Chain.
<table>
<thead>
<tr>
<th>Feature</th>
<th>Semgrep Code</th>
<th>Semgrep Supply Chain</th>
</tr>
</thead>
<tbody>
<tr>
<td>Type of tool</td>
<td>Static application security testing (SAST)</td>
<td>Software composition analysis (SCA)</td>
</tr>
<tr>
<td>Scan target</td>
<td>First-party code (your codebase or repository)</td>
<td>Open source dependencies</td>
</tr>
<tr>
<td>Triage workflow</td>
<td>
Findings can be categorized as:
<ul>
<li>Ignored (to triage false positives)</li>
<li>Closed (resolved) by refactoring code</li>
<li>Removed</li>
</ul>
</td>
<td>
Findings can be categorized as:
<ul>
<li>New</li>
<li>In progress</li>
<li>Fixed</li>
<li>Ignored</li>
</ul>
</td>
</tr>
<tr>
<td>Remediation workflow</td>
<td>Code refactoring</td>
<td>Upgrading or removing the dependency, code refactoring</td>
</tr>
<tr>
<td>Notification channels</td>
<td>Slack, Email, Webhooks</td>
<td>Slack</td>
</tr>
</tbody>
</table> -->

1 change: 1 addition & 0 deletions docs/contributing/contributing.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
---
slug: contributing
displayed_sidebar: contributingSidebar
description: "Semgrep is LGPL-licensed and contributions are welcome. Get started by filing an issue, fixing a bug, contributing rules to the registry, adding a feature, or updating the docs. You can also contribute by helping others in the Semgrep Community Slack!"
---

Expand Down
20 changes: 20 additions & 0 deletions docs/deployment/add-semgrep-to-cicd.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
---
slug: add-semgrep-to-cicd
title: Add Semgrep to CI/CD
hide_title: true
description: tk
tags:
- Deployment
---

import MoreHelp from "/src/components/MoreHelp"

# Add Semgrep to CI/CD

:::note Your deployment journey
- You have [<i class="fa-regular fa-file-lines"></i> created a Semgrep account and organization](/deployment/create-account-and-orgs).
- For GitHub and GitLab users: You have [<i class="fa-regular fa-file-lines"></i> connected your source code manager](/deployment/connect-scm).
- Optionally, you have [<i class="fa-regular fa-file-lines"></i> set up SSO](/deployment/sso).
:::

Semgrep is integrated into CI environments by creating a **job** (also known as an **action** for some CI providers) that is run by the CI provider. After a scan, findings are sent to Semgrep Cloud Platform for triage and remediation.
Empty file added docs/deployment/connect-an-org.md
View file
Empty file.
91 changes: 91 additions & 0 deletions docs/deployment/connect-scm.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,91 @@
---
slug: connect-scm
title: Connect a source code manager
hide_title: true
description: Connect a GitHub or GitLab organization to manage user authentication.
tags:
- Semgrep Cloud Platform
- Team & Enterprise Tier
- Deployment
---

# Connect a source code manager

:::note Your deployment journey
- You have [<i class="fa-regular fa-file-lines"></i> created a Semgrep account and organization](/deployment/create-account-and-orgs).
:::

Linking a source code manager provides the following benefits:

- Allows the Semgrep org membership to be managed by GitHub or GitLab.
- For GitHub users:
- Provides Semgrep access to post PR or MR comments.
- For GitHub Actions users: Enables you to add a Semgrep CI job to repositories in bulk.

You can only connect your Semgrep organization to the source code manager that you originally logged in with. If your organization uses both GitHub and GitLab to manage source code, log in with the source code manager that you would prefer to use to manage Semgrep org membership. You can still scan repositories from other sources.

The process to connect a source code manager depends on whether your SCM tool is cloud-hosted by the service provider, hosted on-premise, or hosted as a single-tenant by the service provider.

:::note Review necessary permissions
Refer to the [<i class="fa-regular fa-file-lines"></i> Pre-deployment checklist](/deployment/deployment-checklist) to ensure you have permissions necessary to perform these steps.
:::

## Connect to cloud-hosted orgs

To connect your SCM:

1. Sign in to Semgrep Cloud Platform.
2. On the sidebar, click **the organization account** you want to make a connection for.
3. Click **Settings** > **Source Code Managers**.
4. Click on your source code manager, for example, **Connect to GitHub**.
![Source code manager tab](/img/source-code-manager.png#md-width)
5. Follow the prompts in the Cloud Platform and select an organization or group to link.
6. After a successful link, you are signed out of Semgrep Cloud Platform automatically, as your credentials have changed after linking an organization.
7. Sign back in to Semgrep Cloud Platform.

You have successfully connected an org in Semgrep Cloud Platform with an organization in your source code management tool.

## Connect to on-premise GitHub or GitLab orgs

### Applicable plans

| GitHub | GitLab |
| ------ | ------ |
| GitHub Enterprise Server | Any GitLab Self Managed plan |

### Table of required scopes for PATs

Semgrep Cloud Platform requires PATs with assigned scopes. These scopes grant necessary permissions to the PAT and vary depending on the user's plan.

| GitHub Enterprise Server | GitLab Self-Managed |
|:---------------------------|:---------------------------|
| <ul><li>`public_repo`</li> <li>`repo:status`</li> <li>`user:email`</li> <li>`write:discussion`</li></ul> | `api` |

### Make the connection

Integrate Semgrep into these custom source code management (SCM) tools by following the steps below:

1. Sign in to [Semgrep Cloud Platform](https://semgrep.dev/login).
2. Click **Settings** > **Source Code Managers**.
![Source code manager tab](/img/source-code-manager.png#md-width)
3. Select your source code manager.
4. For **GitHub Enterprise Server**, follow these steps:
1. Create a PAT by following the steps outlined in this [guide to creating a PAT](https://docs.github.com/en/[email protected]/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). Ensure that the PAT is **[created with the required scopes](../scm/#table-of-required-scopes-for-pats)**.
2. Enter the personal access token generated into the **Access token** field.
3. Enter your GHE Server base URL into the **URL** field.
4. Ensure that your SCM integration successfully detects repositories by setting up a CI job for any repository you want to scan:
1. Commit a `semgrep.yml` configuration file into the `.github/workflows` folder. Refer to [Sample CI configurations](/docs/semgrep-ci/sample-ci-configs#github-actions) for a template you can copy and customize.
2. The CI job starts automatically to establish a connection with Semgrep Cloud Platform. Upon establishing a connection, your repository appears in **Semgrep Cloud Platform > [Projects](https://semgrep.dev/orgs/-/projects)** page.
5. For **GitLab Self Managed**, follow these steps:
1. Create a PAT by following the steps outlined in this [guide to creating a PAT](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html). Ensure that the PAT is **[created with the required scopes](../scm/#table-of-required-scopes-for-pats)**.
2. Enter the personal access token generated into the **Access token** field.
3. Enter your GLSM base URL into the **URL** field.
4. Ensure that your SCM integration successfully detects repositories by setting up a CI job for any repository you want to scan:
1. Create or edit your `.gitlab-ci.yml` configuration file to add Semgrep as part of your GitLab CI/CD pipeline. Refer to [Sample CI configurations](/docs/semgrep-ci/sample-ci-configs#gitlab-cicd) for a template you can copy and customize.
2. Commit the updated `.gitlab-ci.yml` file.
3. The CI job starts automatically to establish a connection with Semgrep Cloud Platform. Alternatively, if it does not start automatically, start the job from the GitLab CI/CD interface. Upon establishing a connection, your repository appears in **Semgrep Cloud Platform > [Projects](https://semgrep.dev/orgs/-/projects)** page.

## Next steps

- Optional: If you want to set up SSO to manage your users, see [<i class="fa-regular fa-file-lines"></i> SSO authentication](/deployment/sso).
- You are ready to start your first remote scan.
Loading

0 comments on commit 7f16492

Please sign in to comment.