+ i. Before merging PR B, make sure the branch on repo B is **not + lagging behind** the main branch. This ensures that the submodule + includes all the latest changes made by others.
+ ii. Make sure PR B is merged **before** PR A. + This ensures that other developers will pick up the changes on B + when making their own changes.
+ iii. After merging PR A, check that submodule B is still up-to-date + with respect to its main branch, especially if PR B was merged + more than an hour ago. + Good to know: + - Merging in B can be done with a merge commit or by squashing the + commits. + - If squashing commits in B, you must know that the original commit + referenced by A becomes orphaned when the branch is deleted but + remains cached by git for a while. This is usually sufficient to + not require A to point to the newly-squashed commit. _If this turns + out to be problematic in practice, we may have to disallow + commit squashing in the future._ diff --git a/mintlify-docs/contributing/contributing-to-semgrep-rules-repository.mdx b/mintlify-docs/contributing/contributing-to-semgrep-rules-repository.mdx new file mode 100644 index 0000000000..c69d55a0d4 --- /dev/null +++ b/mintlify-docs/contributing/contributing-to-semgrep-rules-repository.mdx @@ -0,0 +1,534 @@ +--- +title: "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: + +**For users of Semgrep AppSec Platform** + +Contribute new rules to the Semgrep Registry through Semgrep AppSec Platform. This workflow is recommended. See [Contribute through Semgrep AppSec Platform (recommended)](#contribute-through-semgrep-appsec-platform-recommended). This workflow creates the necessary pull request for you and streamlines the whole process. + +**For contributors to the repository through GitHub** + +Contribute rules to the Semgrep Registry, or suggest changes to existing rules, through a pull request to `semgrep-rules`. See the [Contribute through GitHub](#contribute-through-github) section for detailed information. + +## Contribute through Semgrep AppSec Platform (recommended) + +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). + +
- `references`
- `category`
- `technology`
Additional keys required when `category` is `security`:
- `cwe`
- `owasp`
- `confidence`
- `subcategory`
- `likelihood`
- `impact`
- `vulnerability_class`
`cwe:`
`- "CWE-94: (...)"`
`category: security`
`technology:`
`- unicode`
`references`:
- https://trojansource.codes/| +| `technology` | Nested under the `metadata` field. Additional information about the technology. This helps to specify rulesets in Semgrep Registry. |
- `django`
- `docker`
- `express`
- `kubernetes`
- `nginx`
- `react`
- `terraform`
- `--no-technology--`
`technology:`
`- react`| +| `category` | Nested under the `metadata` field. If you use category `security`, include additional metadata. See Including fields required by security category. |
- `best-practice`
- `correctness`
- `maintainability`
- `performance`
- `portability`
- `security`
- [OWASP DOM based XSS Prevention Cheat Sheet][OWASP-DOM-based-XSS-prevention] | + + +
security, include additional metadata. See Including fields required by security category.
+- 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).
+| Required metadata field | +Values | +Example use | +
|---|---|---|
cwe |
+ A Comment Weakness Enumeration (CWE) | +cwe: "CWE-502: Deserialization of Untrusted Data" |
+
owasp |
+ An OWASP Top 10 category | +
+ owasp:+ |
+
confidence |
+ HIGH, MEDIUM, LOW |
+ confidence: MEDIUM |
+
likelihood |
+ HIGH, MEDIUM, LOW |
+ likelihood: MEDIUM |
+
impact |
+ HIGH, MEDIUM, LOW |
+ impact: HIGH |
+
subcategory |
+ vuln, audit, secure default |
+
+ subcategory:+ |
+
vulnerability_class |
+ See [Vulnerability class](#vulnerability-class) for a list of sample values. Accepts custom values. | +
+ vulnerability_class:+ |
+
+ i. Click **Create new token** to create a `SEMGREP_APP_TOKEN`, which is used to when sending results to Semgrep AppSec Platform.
+ ii. Copy and paste the `SEMGREP_APP_TOKEN` and its value. Store it as an environment variable or secret in your CI provider.
+ iii. Optional: Click **Review CI config** to see Semgrep's default YAML configuration file for your CI provider.
+ iv. Click **Copy snippet** and paste it into your CI provider's configuration file (the filename is typically indicated in the page). Depending on your CI provider, you may have to create a custom configuration file or use an existing one.
+ v. Commit the configuration file to your repository.
+ vi. Return to Semgrep AppSec Platform and click **Check connection**. +
+ i. For repositories in personal accounts: Click your **profile photo > Settings > Applications**.
+ ii. For repositories in org accounts: Click your **profile photo > Your organizations > NAME_OF_ORG > Settings > GitHub Apps**. +
+ i. All repositories will display all current and future public and private repositories.
+ ii. Only select repositories will display explicitly selected repositories. +
+ i. Reference or add the [Semgrep Docker image](https://hub.docker.com/r/semgrep/semgrep). This is the recommended method.
+ ii. Add `pipx install semgrep` (or `uv tool install semgrep` if you use [`uv`](https://docs.astral.sh/uv/)) into your configuration file as a step or command, depending on your CI provider's syntax. See the [Python Packaging guide](https://packaging.python.org/en/latest/guides/installing-stand-alone-command-line-tools/) for more on installing standalone Python CLI tools. +
+Enables Semgrep AppSec Platform to read your GitHub profile data, such as your username. + +**Know which resources you can access**
+Semgrep does not use or access any resources when first logging in. However, you can choose to share resources at a later point to add repositories into Semgrep AppSec Platform. + +**Act on your behalf**
+Enables Semgrep AppSec Platform to perform certain tasks **only on resources that you choose to share with Semgrep AppSec Platform**. Semgrep AppSec Platform never uses this permission and never performs any actions on your behalf, even after you have installed `semgrep-app`. See [When does a GitHub App act on your behalf?](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/authorizing-github-apps) in GitHub documentation. +
+Enables Semgrep AppSec Platform to list repository names on the project setup page. + +**Reading the list of organization members**
+Enables Semgrep AppSec Platform to determine who can manage your Semgrep organization based on your GitHub organization's members list. + +**Reading and writing pull requests**
+Enables Semgrep AppSec Platform to comment about findings on pull requests. + +**Reading and writing actions**
+Enables Semgrep AppSec Platform to cancel stuck jobs, rerun jobs, pull logs from jobs, and perform on-demand scanning. + +**Reading [GitHub Checks](https://docs.github.com/en/rest/reference/checks)**
+Facilitates debugging of Semgrep AppSec Platform when configured out of [GitHub Actions](https://docs.github.com/en/actions). + +**Reading and writing security events**
+Enables integration with GitHub Advanced Security (for example, to show Semgrep results). + +**Reading and writing secrets**
+Enables automatically adding of the Semgrep AppSec Platform Token to your repository secrets when onboarding projects. Note: Semgrep cannot read the values of your existing or future secrets (only the names). + +**Reading and writing 2 files**
+Enables Semgrep AppSec Platform to configure itself to run in CI by writing to `.github/workflows/semgrep.yml` and `.semgrepignore` files. + +**Reading and writing workflows**
+Enables Semgrep AppSec Platform to configure itself to run in CI by writing to `.github/workflows/semgrep.yml`. GitHub allows writing to files within `.github/workflows/` directory only if this permission is granted along with "Writing a single file." + +**Reading and writing pull requests**
+Write permissions allow Semgrep AppSec Platform to leave pull request comments about findings. Read permissions allow Semgrep AppSec Platform to automatically remove findings when the pull request that introduced them is closed without merging. +
+Lets Semgrep list their names on the project setup page. + +**Reading the list of organization members**
+Lets Semgrep determine who can manage your Semgrep organization based on your GitHub organization's members list. + +**Writing (and reading) pull requests**
+Lets Semgrep comment about findings on pull requests. + +**Writing (and reading) actions**
+Allows Semgrep AppSec Platform to cancel stuck jobs, rerun jobs, pull logs from jobs, and perform on-demand scanning. + +**Reading checks**
+Facilitates debugging of Semgrep AppSec Platform when configured out of GitHub Actions + +**Writing (and reading) security events.**
+Enables integration with GitHub Advanced Security (for example, to show Semgrep results) + +**Writing (and reading) secrets**
+Enables automatic adding of the Semgrep AppSec Platform Token to your repository secrets when onboarding projects. Note: We cannot read the values of your existing or future secrets (only the names). + +**Writing (and reading) 2 files**
+Lets Semgrep configure itself to run in CI by writing to .github/workflows/semgrep.yml and .semgrepignore. + +**Writing (and reading) workflows**
+Lets Semgrep configure itself to run in CI by writing to .github/workflows/semgrep.yml. GitHub allows writing to files within .github/workflows/ only if this permission is granted along with "Writing a single file." + +**Read source code of the repositories you select**
+Allows Semgrep Multimodal to fetch source code files on-demand to construct AI prompts. +
+ +
+
++ +
+
++ +
+
++ +
+
++ i. Under **Enter GitHub information**, indicate that you want to install the app on your **Organization**, and select the **Organization name** where the app is installed. If you have multiple GitHub organizations that you'd like to use with Semgrep, ensure that you select the **Use for multiple GitHub orgs** box.
+ ii. Under **Select features to enable**, indicate whether you would like to grant code access to Semgrep.
+ iii. Review the permissions requested by Semgrep.
+ iv. Click **Register a Semgrep GitHub App**. Semgrep asks if you'd like to be redirected to GitHub to continue creating the app. Click **Continue** to proceed.
+ v. You are taken to your GHE instance and asked to name your app. You can choose whatever name you'd like, but Semgrep recommends that you name it something that indicates that this is the Semgrep GHE app.
+ vi. After you name your app, choose the GHE org you want to install it on.
+ vii. Select the org, then click **Install**.
+ viii. Wait for the installation to complete. When done, you are redirected to Semgrep.
+ ix. Verify the installation by navigating to **Settings** > **Source code managers**. Ensure that the entry for your GitHub organization shows a **Connected** badge.
+ x. In GHE, you should see the app listed as installed on the **GitHub Apps** page.
+ - You can click **Configure** to choose the repositories to which the app has access. Additionally, you can go to **App settings** to customize the permissions granted to the app. +
+ +
+
++ +
+
+
++Choose another account by clicking the **account name** and selecting an account from the drop-down box. Then, perform the following steps to set up the connection: + +
+ +
+
+- Can scan your language and that the language's maturity matches your security needs. See
Supported languages. - Provides rulesets that you can use out-of-the-box. See
Semgrep Registry.
- OpenID Connect or OAuth 2
- SAML 2.0
If you use Bitbucket or Azure Repos, you can use SSO to manage the authentication of your users, then add repositories for scanning through your CI provider. | +| Scanning remote repositories through CI | Semgrep fully supports many popular CI providers. See
- GitHub
- GitLab
- Bitbucket
- Slack
- Webhooks
- Microsoft Visual Studio Code
- IntelliJ Ultimate IDEA
- Emacs
+ i. 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`.
+ ii. The name of your **Azure DevOps Project**. +
+ i. Optional: If you don't see the repository you want to add, click **Sync projects**. +
+ i. Leave the **Status to check** box blank, since this value is auto-populated as you provide values in subsequent steps.
+ ii. Select the **Enter genre/name separately** box. Provide the following values:
+ a. **Genre**: `security`
+ b. **Name**: `semgrep-cloud-platform/scan` + + Once you provide the **Genre** and **Name**, Azure DevOps auto-populates **Status to check**.
+ iii. Choose whether the status check needs to succeed or not to complete pull requests. Selecting **Required** means that a status of `succeeded` is necessary to complete pull requests. Selecting **Optional** means that a status of `failed` will not block the completion of pull requests. + +  + +
+ i. Select **Bitbucket** or **Bitbucket Data Center**.
+ ii. Provide your **Access token**.
+ iii. Provide the name of your **Bitbucket workspace**.
+ iv. *For Bitbucket Data Center users only*: provide the **Bitbucket Data Center URL**.
+ v. Click **Connect**. +
+ i. Optional: If you don't see the repository you want to add, click **Can't find your project?** and follow the troubleshooting steps provided. +
+ i. Follow the steps in the page to create and register both a public and private Semgrep GitHub app. +
+ i. Optional: If you don't see the repository you want to add, click **Can't find your project?** and follow the troubleshooting steps provided. +
+ i. Optional: If you don't see the repository you want to add, click **Can't find your project?** and follow the troubleshooting steps provided. +
+ i. Select **GitLab Cloud** or **GitLab Self-Managed**.
+ ii. Provide your **Access token**.
+ iii. Provide your **GitLab group**.
+ iv. *For GitLab Self-Managed users only*: provide the **GitLab URL**.
+ v. Click **Connect**. +
+ i. Optional: If you don't see the repository you want to add, click **Can't find your project?** and follow the troubleshooting steps provided. +
+ i. Once you successfully create the connection, the role for the person who owns the token can be downgraded to **Developer**. +
semgrep login, you are also already signed in with the Visual Studio Code Semgrep extension. Alternatively, you can log in through your command-line interface by running `semgrep login`.
+- `Semgrep: Sign out`: Log out from Semgrep AppSec Platform. Alternatively, you can sign out through your command-line interface by running `semgrep logout`.
+- `Semgrep: Update rules`: For logged-in users. If the rules in the [Policies](https://semgrep.dev/orgs/-/policies) or rules included through the **Semgrep › Scan: Configuration** configuration option have been changed, this command loads the new configuration of your rules for your following scan.
+
+and many other IntelliJ products |[
+This appears if a finding fails the CI job. Organizations typically block PRs or MRs with failed jobs. + +**B - Finding description**
+A human-written description always appears in a PR or MR comment, describing why your code is flagged. References may also be included to help you learn more about the finding. + +**C - Dataflow graph**
+Some Code findings have a dataflow graph, which indicates that the finding was detected through %%taint analysis|taint_analysis%%. The dataflow graph provides the lines of code identifying sources, sinks, and traces of unsanitized data flowing through your program. You can click the links on the boxes to take you to the lines of code. + +**D - Resolution or remediation section**
+Various options are provided to help your resolve the finding. Depending on the type of finding, resolution options may vary. + +**E - Ignore instructions**
+Click to view instructions about how to ignore the finding by replying to the comment. + +### Type of findings by resolution + +**Code finding**
+This type of finding is typically resolved by refactoring your code. This finding typically catches bugs, security issues, or violations of best practices. + +**Dependency finding**
+Semgrep found that you're using a vulnerable version of a dependency. It can also detect if you're using the vulnerable function or code of the dependency. + +**License finding**
+Semgrep has found that you're using a dependency with a license that may violate the guidelines set by your organization. + +**Secrets finding**
+Semgrep has detected a leaked secret. Rotate the secret to resolve this finding. + + + + + + diff --git a/mintlify-docs/for-developers/resolve-findings-through-app.mdx b/mintlify-docs/for-developers/resolve-findings-through-app.mdx new file mode 100644 index 0000000000..1e2efbf3a2 --- /dev/null +++ b/mintlify-docs/for-developers/resolve-findings-through-app.mdx @@ -0,0 +1,80 @@ +--- +title: "Resolve findings through Semgrep AppSec Platform" +description: "This guide explains how you can view and triage findings in bulk through the Semgrep AppSec Platform web app." +--- + + +
+ **Then** the finding in the current branch is triaged to that same state. + - **Diff-aware scan**: findings introduced in a diff-aware scan are **not** automatically triaged at scan time, even if there are other instances of that finding on branches that have been triaged. + + +
+This appears if a finding fails the CI job. Organizations typically block PRs or MRs with failed jobs. + +**B - Finding description**
+A human-written description always appears in a PR or MR comment, describing why your code is flagged. References may also be included to help you learn more about the finding. + +**C - Dataflow graph**
+Some Code findings have a dataflow graph, which indicates that the finding was detected through %%taint analysis|taint_analysis%%. The dataflow graph provides the lines of code identifying sources, sinks, and traces of unsanitized data flowing through your program. You can click the links on the boxes to take you to the lines of code. + +**D - Resolution or remediation section**
+Various options are provided to help your resolve the finding. Depending on the type of finding, resolution options may vary. + +**E - Ignore instructions**
+Click to view instructions about how to ignore the finding by replying to the comment. + +## Resolve findings + +Different types of findings require different remediations. The following sections describe how Semgrep can help you resolve a finding. + +### Autofix + +Some Semgrep Code findings provide an **autofix**, which can be human-written or generated by Semgrep Multimodal. The fix can be committed directly, such as by clicking **Commit suggestion** in GitHub repositories. This is the fastest way to fix a finding. + +All Semgrep-supported SCMs provide this feature. + + + + + +
/fp <REASON> | Triage a finding as **Ignored** with the triage reason **false positive**. |
+ | /ar <REASON> | Triage a finding as **Ignored** with the triage reason **acceptable risk**. |
+ | /other <REASON> | Triage a finding as **Ignored** without specifying the reason; the triage reason value is set to **No triage reason**. |
+ | /open <REASON> | Reopen a finding that has been triaged as **Ignored**. The comment is optional. |
+
+
+
+
+_**Figure**. ._
+
+## Re-run a job or workflow
+
+Resolving or ignoring findings does not automatically re-run Semgrep checks. After resolving or triaging the findings in your PR or MR, you must re-run the Semgrep job or workflow. See the following list for a link to your CI provider's documentation:
+
+
+- [+ **Then** the finding in the current branch is triaged to that same state. + - **Diff-aware scan**: findings introduced in a diff-aware scan are **not** automatically triaged at scan time, even if there are other instances of that finding on branches that have been triaged. + +
YOUR_TOKEN with the login token value you copied in the previous step:
+
+ ```bash
+ docker run -e SEMGREP_APP_TOKEN=YOUR_TOKEN --rm -v "${PWD}:/src" semgrep/semgrep semgrep ci
+ ```
+
+ The provided `-v` option mounts the current directory into the container to be scanned. Navigate into a different project or provide a specific local directory in the command to scan a different project.
+
+ iii. For users running Docker on **Windows**:
+
+ a. Log in to your Semgrep account (running this command will launch a browser window, but you can also use the link that's returned in the CLI to proceed):
+
+ ```bash
+ docker run -it semgrep/semgrep semgrep login
+ ```
+
+ b. In the **Semgrep CLI login**, click **Activate** to proceed. Return to the CLI, and copy the login token that's shown.
+
+ c. Navigate into the root of your project, and run your first scan. Be sure to substitute YOUR_TOKEN with the login token value you copied in the previous step:
+
+ ```bash
+ docker run -e SEMGREP_APP_TOKEN=YOUR_TOKEN --rm -v "%cd%:/src" semgrep/semgrep semgrep ci
+ ```
+
+ The provided `-v` option mounts the current directory into the container to be scanned. Navigate into a different project or provide a specific local directory in the command to scan a different project.
+
+ - Query console
- Auto PRs for Supply Chain findings
- Semgrep Multimodal
- Semgrep Managed Scans
- Pull request comments
- Query console
- Diff-aware scans
- Sending findings to Semgrep AppSec Platform
- Default branch identification
- Auto PRs for Supply Chain findings
- Generic secrets (requires Semgrep Multimodal)
- Semgrep Multimodal†
- Semgrep Managed Scan†
- Query console
- Auto PRs for Supply Chain findings
- Generic secrets (requires Semgrep Multimodal)
- Semgrep Multimodal†
- Semgrep Managed Scan†
- Query console
- Auto PRs for Supply Chain findings
- Generic secrets (requires Semgrep Multimodal)
- Query console
- Auto PRs for Supply Chain findings
- Query console
- Diff-aware scans and triage through PR comments require Bitbucket Data Center version 8.8 or later.
- Auto PRs for Supply Chain findings
- Auto PRs for Supply Chain findings
- Semgrep Managed Scans*
- Triage though MR comments*
- Query console
- Auto PRs for Supply Chain findings
- Query console
- Auto PRs for Supply Chain findings
- Query console
- Auto PRs for Supply Chain findings
- Query console
- Auto PRs for Supply Chain findings
- Semgrep Managed Scans*
- Query console
- Auto PRs for Supply Chain findings
- Query console
- Auto PRs for Supply Chain findings
- Query console
- Auto PRs for Supply Chain findings
For example:
` // nosemgrep`
`// nosemgrep: rule-id`
`# nosemgrep` | +| For Semgrep AppSec Platform users:
- Ignore files and folders through the use of Semgrep AppSec Platform's **Project or Global ignores**
- Override the implicit ignorelist through the use of a `.semgrepignore` file.
| +| For Semgrep Community Edition (CE) users:
Ignore files and folders through a `.semgrepignore` file | Create a `.semgrepignore` file in your **repository's root directory** or your **project's working directory** and add patterns for files and folders there. Patterns follow `.gitignore` syntax with some caveats. See [Defining ignored files and folders in `.semgrepignore`](#define-ignored-files-and-folders-in-semgrepignore). | [`.semgrepignore` sample file](https://raw.githubusercontent.com/semgrep/semgrep/develop/cli/src/semgrep/templates/.semgrepignore) | + +## Understand Semgrep defaults + +Without user customization, Semgrep refers to the following to define ignored files and folders: + +* Semgrep's default `.semgrepignore` file +* Your repository's `.gitignore` file (if it exists) +* For Semgrep AppSec Platform users: each project (repository or subfolder in monorepo) in Semgrep has a list of ignored files and folders in its project details page. + +In the absence of a user-generated `.semgrepignore`, Semgrep refers to [its repository's default template](https://github.com/semgrep/semgrep/blob/develop/cli/src/semgrep/templates/.semgrepignore): + +```text +# Administrative folder or file used by popular version control systems +.git +.svn +.hg +_darcs +CVS + +# Paths to files and folders that are typically large and ignorable +build/ +vendor/ +dist/ +*.min.js +.env/ +.tox/ + +# Package managers +node_modules/ +.npm/ +.yarn/ +.venv/ +_opam/ +_build/ +_cargo/ +# Note that PHP composer uses vendor/ and C++ conan uses build/ +# .venv is used both by Go and Python. + +# Common test paths +test/ +tests/ +testsuite/ +*_test.go + +``` + + +## Override defaults + +The default `.semgrepignore` file causes Semgrep to skip these folders: + +* `/tests`, `/test` +* `/vendors` + +To include these folders: + +
+
+
diff --git a/mintlify-docs/integrating.mdx b/mintlify-docs/integrating.mdx
new file mode 100644
index 0000000000..44d6861dc0
--- /dev/null
+++ b/mintlify-docs/integrating.mdx
@@ -0,0 +1,16 @@
+---
+title: "Semgrep integration guide for partners"
+description: "We're excited that you're integrating Semgrep into your tooling! Our goal with Semgrep is to bring world-class security tools to developers based on our conviction that software will run the most exciting parts of the future. It's not something that we can do alone; we want to build a community around sharing programmatic knowledge about how to build secure software."
+---
+
+## Requirements for integrators
+
+* Do not resell rules from the Registry, unless you acquire an explicit license from Semgrep, Inc. Semgrep rules are [released under the Semgrep Rules License](https://github.com/semgrep/semgrep-rules/blob/develop/LICENSE), which prohibits redistribution in a commercial product.
+* State that you are using Semgrep; refer to Semgrep as capital S with the trademark: Semgrep™
+* Link to [semgrep.dev/login](https://semgrep.dev/login) to allow users to get an API token to pass to Semgrep so they can access the Pro Engine and rules.
+* Set `SEMGREP_INTEGRATION_NAME` in your environment to your domain name (for example, "xyz.com"). This helps us reproduce and debug issues with Semgrep in your environment.
+* Don't integrate `semgrep scan` in a CI setup. Instead use `semgrep ci`, which has diff-awareness built-in and is designed to be easy to integrate into dozens of CI environments. It's also much faster.
+* Enable metrics (`--metrics=on`) by default, which lets the Semgrep team prioritize languages and technologies to improve speed and accuracy.
+* Contribute new public rules back to the [semgrep-rules repository](https://github.com/semgrep/semgrep-rules). This helps us avoid community fragmentation and will automatically pull your rule into the searchable Registry on semgrep.dev; plus Semgrep will maintain it for you!
+
+For more information, please refer to [the section on licensing](/licensing) in our documentation. If you have additional questions, email us at [partners@semgrep.com](mailto:partners@semgrep.com).
diff --git a/mintlify-docs/introduction.mdx b/mintlify-docs/introduction.mdx
new file mode 100644
index 0000000000..c82e79cbcc
--- /dev/null
+++ b/mintlify-docs/introduction.mdx
@@ -0,0 +1,99 @@
+---
+title: "Introduction to Semgrep"
+description: "Semgrep is a software security tool that provides static application security testing (SAST), software composition analysis (SCA), and secrets detection. Semgrep identifies vulnerabilities in your source code without executing your code. It integrates with IDEs and CI/CD, and can also run from the Semgrep AppSec Platform."
+---
+
+Semgrep uses rules written in a simple schema that match code semantically. You can use out-of-the-box rules, apply community-maintained rules, or write your own to fit your workflow.
+
+Scan results can be triaged and remediated in the Semgrep AppSec Platform. The platform includes Semgrep Multimodal, which offers remediation guidance and Suggested fixes for Semgrep Code and Secrets findings.
+
+## Offerings
+
+* **Community Edition** (CE): is an open source static analysis tool that can find insecure coding patterns and security vulnerabilities in source code. Semgrep CE encompasses a SAST scanning engine, community rules, and integrated development environment plugins. The core scanner supports over 30 programming languages. [Get started with CE](/getting-started/quickstart-ce).
+
+* **Semgrep AppSec Platform** (Pro): is a commercial offering recommended for enterprise use cases. It shares the command-line interface with CE and adds additional capabilities. These include organization-wide managed scans, advanced Pro rules, software composition analysis (SCA), secrets detection, pull request comments, and AI-assisted triage and remediation. The platform now combines deterministic static analysis with AI-powered detection to extend coverage to complex business-logic flaws like insecure direct object reference (IDORs) and broken authentication. Semgrep AppSec Platform supports more than 35 programming languages, with new ones added regularly.
+
+
+ 
+
+
+[Learn more](/semgrep-pro-vs-oss) about the differences between CE and Pro offerings and the features that distinguish them.
+
+## The analysis workflow
+
+Semgrep's analysis workflow can be divided into three stages:
+
+### Deployment
+
+[Deployment](/deployment/core-deployment) is the process of integrating Semgrep into your developer and infrastructure workflows. Completing the deployment process provides you with the Semgrep features that meet your security program's needs. Semgrep does not require code access to complete the core deployment process. Your code is **not** sent anywhere.
+
+### Scan
+
+Scanning is the process of analyzing your code to identify security vulnerabilities, exposed secrets, or risks introduced through dependencies. Semgrep provides three scanning tools that help you detect and address issues early in development and throughout your software lifecycle:
+
+* [Semgrep Code](/semgrep-code/overview): a static application security testing (SAST) tool that detects security vulnerabilities in your **first-party code**. You can use it to scan local repositories or integrate it into your CI/CD pipeline to automate the continuous scanning of your code.
+
+* [Semgrep Supply Chain Analysis](/semgrep-supply-chain/overview): a software composition analysis (SCA) tool that detects security vulnerabilities in your codebase introduced by open source dependencies.
+
+* [Semgrep Secrets](/semgrep-secrets/conceptual-overview): scans code to detect exposed API keys, passwords, and other credentials.
+
+### Triage and remediation
+
+After each scan, your findings are displayed in the Semgrep AppSec Platform. The filters provided allow you to manage and triage your findings.
+
+Triage is the process of reviewing, prioritizing, and managing findings identified during Semgrep scans. It helps security teams and developers decide which issues to address, ignore, or assign for further investigation. Within the Semgrep AppSec Platform, triage tools such as filtering, tagging, and assigning owners streamline this process and integrate seamlessly into existing workflows.
+
+Remediation is the process of fixing security issues identified during scanning. Semgrep supports remediation by providing detailed findings, contextual code examples, and, in many cases, Suggested fixes that can automatically or semi-automatically resolve vulnerabilities. These tools help developers quickly implement secure fixes while maintaining development speed.
+
+[Semgrep Multimodal](/semgrep-multimodal/overview) enhances this workflow by providing AI-powered security recommendations to help you understand findings, assess severity, and prioritize fixes. It can also suggest potential remediation, explain rule matches in context, and guide developers toward faster resolution of issues.
+
+## Ways to incorporate Semgrep into your development workflow
+
+| Goal | Recommended Option | Available In |
+| :--- | :--- | :--- |
+| Quick local checks | Run Semgrep locally | CE & Pro |
+| Catch issues before commit | IDE extension or pre-commit framework | CE & Pro |
+| Integrate into builds | CI/CD integration | CE & Pro |
+| Org-wide management & automation | Semgrep Managed Scans | Pro only |
+
+### Run Semgrep locally
+
+Run Semgrep directly on your machine to scan code before pushing changes. This is the quickest way to get started and experiment with rules. You can [run scans manually from the command line](/getting-started/cli) or set up local automations.
+
+### Use Semgrep in your IDE or before commits
+
+Incorporate Semgrep early in your development workflow by using a [supported IDE extension](/extensions/overview#official-ide-extensions) or by setting up the [pre-commit framework](/extensions/pre-commit), which runs Semgrep checks automatically before code is committed. This helps you catch issues before they ever reach your repository.
+
+### Add Semgrep to CI/CD
+
+[Integrate Semgrep into your CI/CD environment](/deployment/add-semgrep-to-ci) like GitHub Actions, GitLab CI/CD, Jenkins, CircleCI, Azure Pipelines, Bitbucket, or Buildkite by creating a job that your CI provider runs. After each scan, findings are sent to the Semgrep AppSec Platform for triage and remediation.
+
+
+
+
+
+
+
+
+
+ 
+
+
+
+
+
+
+
+ Semgrep docs
++ Find bugs and reachable dependency vulnerabilities in code. Enforce your code standards on every commit. +
+ +
+
+
+
+
+
+
+ Run your first Semgrep scan.
+
+
+ Deploy Semgrep to your organization quickly and at scale.
+
+
+ Triage and remediate findings; fine-tune guardrails for developers.
+
+
+ Enforce your organization’s coding standards with custom rules.
+
+
+
+
+
+
+
+Scan with Semgrep AppSec Platform
+Deploy static application security testing (SAST), software composition analysis (SCA), and secrets scans from one platform.
+
+
+
+
+
+
+Supported languages
+ +| Product | +Languages | +
|---|---|
| Semgrep Code | +
+
+ Generally available (GA)
+ + C and C++ • C# • Generic • Go • Java • JavaScript • JSON • Kotlin • Python • TypeScript • Ruby • Rust • JSX • PHP • Scala • Swift • Terraform +
+ Beta
+ + APEX • Elixir +
+ Experimental
+ + Bash • Cairo • Circom • Clojure • Dart • Dockerfile • Hack • HTML • Jsonnet • Julia • Lisp • Lua • Move on Aptos • Move on Sui • OCaml • R • Scheme • Solidity • YAML • XML + |
+
| Semgrep Supply Chain | +
+
+ Generally available reachability
+ + C# • Go • Java • JavaScript and TypeScript • Kotlin • PHP • Python • Ruby • Rust • Scala • Swift +
+ Languages without support for reachability analysis
+ + Dart • Elixir + |
+
| Semgrep Secrets | ++ Language-agnostic; can detect 630+ types of credentials or keys. + | +
See e.target.style.textDecoration = 'underline'} onMouseOut={(e) => e.target.style.textDecoration = 'none'}>Supported languages documentation for more details.
+
+
+
+April 2026 release notes summary
+-
+
- Added the ability to manually run full scans for the non-default or non-primary branches using Semgrep Managed Scans, as well as the ability to retry Semgrep Managed Scans that failed or didn't complete. +
- The interfile analysis engine has been redesigned to improve performance. These improvements change how findings are generated, which might result in additional true positives and fewer false positives. +
- Semgrep Playground is now mobile-friendly. +
- The Finding Details page now displays the reason why a finding was ignored at the top. Users no longer need to go to the Activity section to see this information. +
- Added Supply Chain reachability coverage for Rust. +
- Added dependency path information to SBOM exports and the
/issuesAPI endpoint.
+ - Findings of critical or high severity with high or medium confidence identified during diff-aware scans are now included in autotriage analysis. +
+ ii. In that DefectDojo product, create an [engagement](https://defectdojo.github.io/django-DefectDojo/usage/models/#engagement), called `semgrep`. This is a CI/CD engagement type and the name designates the CI/CD tool used. +
python3 integrations/defectdojo/import_semgrep_to_defect_dojo.py --host DOJO_URL --product PRODUCT_NAME --engagement ENGAGEMENT_NAME --report REPORT_FILE+ i. Sign in to Semgrep AppSec Platform.
+ ii. Navigate to **[Settings > Access > Login methods](https://semgrep.dev/orgs/-/settings/access/loginMethods)**. + iii. Click **Add SSO configuration** and select **SAML2 SSO**.
+ iv. Copy the **Audience URL (SP Entity ID)** value from Semgrep AppSec Platform. Return to **Basic SAML Configuration**. Click **Add identifier** to paste this value as the **Identifier (Entity ID)**.
+ v. Copy the **SSO URL** value from Semgrep AppSec Platform. Return to **Basic SAML Configuration**. Click **Add reply URL** to paste this value as the **Reply URL (Assertion Consumer Service URL)**. +
+ i. Click **Add new claim**.
+ ii. Enter `name` in the **Name** field.
+ iii. For the **Source attribute** drop-down box, select `user.displayname`.
+ iv. Click **Save**. +
+ i. Click **Add new claim**
+ ii. Enter `email` in the **Name** field.
+ iii. From the **Source attribute** drop-down box, select `user.mail`.
+ iv. Click **Save**. +
+ i. Provide the **Display name** and the **Email domain** you are using for the integration.
+ ii. Copy the **Login URL** value from Microsoft Entra ID and paste it in into Semgrep AppSec Platform's **IDP SSO URL** field.
+ iii. Copy and paste the **Microsoft Entra ID Identifier** value into Semgrep AppSec Platform's **IdP Issuer ID** field.
+ iv. In Entra ID's **SAML-based Sign-on** page, click **Download** to obtain the **Certificate (Base64)**.
+ v. In Semgrep AppSec Platform, under **Upload/Paste certificate**, click **Browse** and then select the certificate you downloaded. + +  + +
https://MY_COMPANY.semgrep.dev
+
+
+## To log in to the correct tenant site
+
+Set the environment variable `SEMGREP_APP_URL` before calling the `semgrep login` function.
+```bash
+export SEMGREP_APP_URL=https://mycompany.semgrep.dev
+semgrep login
+```
+If you frequently log in from the command line, set the SEMGREP_APP_URL variable in your shell initialization file, such as `~/.zshrc` or `~ /.bash_profile`, depending on your operating system.
diff --git a/mintlify-docs/kb/semgrep-appsec-platform/sso-attribute-error.mdx b/mintlify-docs/kb/semgrep-appsec-platform/sso-attribute-error.mdx
new file mode 100644
index 0000000000..30913d7bfe
--- /dev/null
+++ b/mintlify-docs/kb/semgrep-appsec-platform/sso-attribute-error.mdx
@@ -0,0 +1,15 @@
+---
+title: "SAML SSO error BadRequest: Missing attribute"
+description: "When setting up SAML-based SSO for Semgrep AppSec Platform, you may see the following error:"
+---
+
+```text
+Semgrep encountered an SSO error BadRequest.
+Could not process SAML parameters. Missing attribute: email
+```
+
+Semgrep AppSec Platform requires two SAML attributes to be sent: `name` and `email`. If either one is missing, this error appears during the login process. For example, if the `name` attribute is missing, the message reads `Missing attribute: name`.
+
+When you see this error, review your SAML configuration or the SAML assertion content. Most commonly, when setting up the SAML app, you provided the right information (the user's name and email) but the name or namespace of the attributes isn't an exact match to `name` or `email`. For example, you are sending the user's full name, but the attribute is called `user.fullName`. You should rename the attribute to `name`.
+
+Review step 4 of the [SAML setup process](/deployment/sso/#saml-20) for guidance in setting up the attributes as required by Semgrep. For Microsoft Entra ID, see steps 4 and 5 of [Set up SAML SSO with Microsoft Entra ID](/kb/semgrep-appsec-platform/saml-microsoft-entra-id).
diff --git a/mintlify-docs/kb/semgrep-ci.mdx b/mintlify-docs/kb/semgrep-ci.mdx
new file mode 100644
index 0000000000..9954b7c849
--- /dev/null
+++ b/mintlify-docs/kb/semgrep-ci.mdx
@@ -0,0 +1,69 @@
+---
+title: "Semgrep in CI"
+---
+
++ i. In the **Repository** list, select **Push**.
+ ii. In the **Pull request** list, select **Created** and **Updated**. +
+ i. Click **Add**.
+ ii. Select one of the following: **Bitbucket Cloud Pull Request**, **Bitbucket Server Pull Request**, or **Push**.
+ iii. In **Select an Action**, select **Created**.
+ iv. Click **Add** again, and select the same trigger as before: **Bitbucket Cloud Pull Request**, **Bitbucket Server Pull Request**, or **Push**.
+ v. In **Select an Action**, select **Updated**. +
+ i. In **SCM**, select **Git**.
+ ii. In **Repositories > Repository URL**, enter your Bitbucket repository URL.
+ iii. In **Branch Specifier (blank for 'any')**, enter the name of your main branch.
+ iv. In **Script Path**, enter `Jenkinsfile`. +
+ i. Add your Bitbucket **Repository URL**
+ ii. Add the **Credentials** needed to check out your sources
+ iii. Add the **Branches to build** +
+ i. Click **Add**.
+ ii. Select one of the following: **Bitbucket Cloud Pull Request** or **Bitbucket Server Pull Request**.
+ iii. In **Select an Action**, select **Created**.
+ iv. Click **Add** again, and select the same trigger as before: **Bitbucket Cloud Pull Request** or **Bitbucket Server Pull Request**.
+ v. In **Select an Action**, select **Updated**.
+ vi. Click **Add > Push**.
+
+ i. In the **Environment** section, select **Use secret text(s) or file(s)**.
+ ii. Under **Bindings**, select **Secret text**.
+ iii. Set **Variable** to `SEMGREP_APP_TOKEN`.
+ iv. Under **Credentials > Specific credentials**, choose the defined credential for the token.
+ v. Click **Add** to save your changes. +
git merge-base --all SHA FETCH_HEADgit cat-file -e REFUSERNAME).
+
+For more information on all of these variables see GitLab documentation [Predefined variables reference](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html).
+
+Example with sample values:
+
+```sh
+export GITLAB_CI='true'
+export CI_PROJECT_PATH="gitlab-org/gitlab-foss"
+export CI_MERGE_REQUEST_PROJECT_URL="https://example.com/gitlab-org/gitlab-foss"
+export CI_PROJECT_URL="$CI_MERGE_REQUEST_PROJECT_URL"
+export CI_COMMIT_SHA="1ecfd275763eff1d6b4844ea3168962458c9f27a"
+export CI_COMMIT_REF_NAME="main"
+export CI_MERGE_REQUEST_TARGET_BRANCH_NAME="main"
+export CI_JOB_URL="https://gitlab.com/gitlab-examples/ci-debug-trace/-/jobs/379424655"
+export CI_PIPELINE_SOURCE='merge_request_event'
+export CI_MERGE_REQUEST_IID="1"
+export CI_MERGE_REQUEST_DIFF_BASE_SHA="1ecfd275763eff1d6b4844ea6874447h694gh23d"
+export CI_MERGE_REQUEST_TITLE="Testing branches"
+```
diff --git a/mintlify-docs/kb/semgrep-ci/new-scm-connections.mdx b/mintlify-docs/kb/semgrep-ci/new-scm-connections.mdx
new file mode 100644
index 0000000000..5583247347
--- /dev/null
+++ b/mintlify-docs/kb/semgrep-ci/new-scm-connections.mdx
@@ -0,0 +1,7 @@
+---
+title: "Why are there new source code manager (SCM) connections that I didn't manually configure listed in Semgrep AppSec Platform?"
+---
+
+If you initiate Semgrep scans using GitHub Actions or GitLab CI/CD pipeline, Semgrep may automatically create new SCM connections and add the accompanying projects to Semgrep AppSec Platform. This can happen if the CI job has sufficient permissions through the access token you provide to create the connection between Semgrep and GitHub or GitLab.
+
+The projects associated with the newly created SCM connections are listed in Semgrep AppSec Platform on the **Projects > Not scanning** page. They are not automatically scanned by Semgrep.
diff --git a/mintlify-docs/kb/semgrep-ci/scan-compressed-files-artifacts.mdx b/mintlify-docs/kb/semgrep-ci/scan-compressed-files-artifacts.mdx
new file mode 100644
index 0000000000..a9902cfb0c
--- /dev/null
+++ b/mintlify-docs/kb/semgrep-ci/scan-compressed-files-artifacts.mdx
@@ -0,0 +1,19 @@
+---
+title: "Does Semgrep scan compressed files or other non-code files?"
+---
+
+Semgrep is a pre-build security tool optimized to search for code and text patterns. It does not scan the files within a compressed archive, nor does it scan binaries (built files).
+
+## How can I scan the files inside a compressed archive file?
+
+To scan code or text files that are stored in a compressed archive file with Semgrep, uncompress the files before performing the scan. When the scan is complete, delete the temporary files that were created.
+
+For local scans, this can be done manually. For scans in CI, add appropriate actions to the CI config.
+
+When implementing this method, it's optimal to place the compressed files in a consistent location, so that Semgrep can detect that any findings within the temporary files are the same across scans.
+
+### What are the limitations of this approach?
+
+When possible, Semgrep AppSec Platform generates hyperlinks to a finding's location within a repository and file. If the file is not persistent in the repository, and is scanned at a temporary path, then the hyperlink will lead to that temporary path and will not work properly. This may make it more difficult for developers to identify where and how to fix issues identified in the temporary files.
+
+Currently, it is not possible to uncompress files before running a scan in [Semgrep Managed Scans](/deployment/managed-scanning/overview).
diff --git a/mintlify-docs/kb/semgrep-ci/scan-monorepo-in-parts.mdx b/mintlify-docs/kb/semgrep-ci/scan-monorepo-in-parts.mdx
new file mode 100644
index 0000000000..e97596b411
--- /dev/null
+++ b/mintlify-docs/kb/semgrep-ci/scan-monorepo-in-parts.mdx
@@ -0,0 +1,177 @@
+---
+title: "Scanning a monorepo in parts"
+---
+
+With default CI configurations, monorepos will be scanned as a single project in Semgrep. However, monorepos very often contain a large amount of code and the code is usually divided into to different components or modules.
+
+As such, it can be helpful to scan a monorepo in parts for multiple reasons:
+
+- To improve scan performance in CI and reduce CI run times
+- To logically split the monorepo to simplify managing findings
+
+semgrep scan --config='SEMGREP_RULES_FOLDER/'
+
+ semgrep scan --config='SEMGREP_RULES_FOLDER/NAME_OF_IMPROVED_RULE.yaml'+ + +### Remove the rule from the scan + +Delete the rule from the folder containing your Semgrep rules. + +## Use advanced analyses and Pro rules + +Optimizing rules can be a time-consuming process. Often, rules are not necessarily noisy, but lack additional analysis to detect true positives while ignoring false positives. + +[Semgrep Code](/semgrep-code/overview/) provides cross-function (interprocedural) and cross-file (interfile) analyses. These analyses both reduce false positives and detect true positives that Semgrep Community Edition (CE) can't find. + +For some languages and frameworks, such as Java or the Python Django framework, Semgrep also provides advanced analyses that take into account the language's characteristics, framework-specific dataflows, and the like. These analyses are available by default once you've signed in to Semgrep. + +
+semgrep ci --pro ++ +
x.y.z is a placeholder for a version string.
+
+## Running different versions using pipx
+
+Install a specific Semgrep version using `pipx`'s version syntax:
+
+pipx install semgrep==x.y.zpipx install --force semgrep==x.y.zuv tool install semgrep==x.y.zuvx semgrep@x.y.z --versiondocker pull semgrep/semgrep:x.y.zdocker run --rm -v "/PATH/TO/SRC:/src" semgrep/semgrep:x.y.z semgrep --config=auto+ ii. To search for a **specific version** of a package, click **Exact match**, then enter the **version** number.
+ iii. To search for a **range of versions**, click **Range**, then enter the minimum and maximum versions.
+ iv. Click **Apply** to save your changes and see your results. +
+
You searched for:
+ + +``` + +Here, the code takes the value of `q` from the URL and inserts it directly into the page. If someone navigates to `https://semgrep.dev/search?q=+ The [Semgrep Registry](https://semgrep.dev/explore) is a collection of rules and rulesets: + - All rules, which includes both Community and Pro rules, listed in the [semgrep-rules](https://github.com/semgrep/semgrep-rules) repository are licensed under [Semgrep Rules License v.1.0](https://semgrep.dev/legal/rules-license). They are available only for internal business use. Vendors cannot use Semgrep-maintained rules in competing products or SaaS offerings. Individuals, security consultants, and companies are welcome to use the rules internally. + - Rules from third-party repositories in the [Semgrep Registry](https://semgrep.dev/explore) inherit the licenses of their source repositories. These licenses are displayed within the rule definition in the editor. For example: [Rules written by Trail of Bits](https://semgrep.dev/p/trailofbits) security experts licensed under AGPL-3.0 license. + +**Semgrep AppSec Platform**
+ Proprietary. See [Terms of Service](https://semgrep.dev/terms). + +**Semgrep Code**
+ Proprietary. See [Terms of Service](https://semgrep.dev/terms). + + +**Semgrep Secrets**
+ Proprietary. See [Terms of Service](https://semgrep.dev/terms). + + +**Semgrep Supply Chain**
+ Proprietary. See [Terms of Service](https://semgrep.dev/terms). + +**Semgrep Community Edition (CE)**
+ The Semgrep CE engine is an open source project licensed under [LGPL 2.1](https://github.com/semgrep/semgrep/blob/develop/LICENSE). The proprietary extension of Semgrep CE is Semgrep Code, see also [Terms of Service](https://semgrep.dev/terms). + +## License Semgrep for use + +If you are interested in using Semgrep products for your own solutions and code analysis tools, send us an email at [partnerships@semgrep.com](mailto:partnerships@semgrep.com) \ No newline at end of file diff --git a/mintlify-docs/logo/dark.svg b/mintlify-docs/logo/dark.svg new file mode 100644 index 0000000000..48815c80ed --- /dev/null +++ b/mintlify-docs/logo/dark.svg @@ -0,0 +1,16 @@ + diff --git a/mintlify-docs/logo/light.svg b/mintlify-docs/logo/light.svg new file mode 100644 index 0000000000..ba4052461e --- /dev/null +++ b/mintlify-docs/logo/light.svg @@ -0,0 +1,16 @@ + \ No newline at end of file diff --git a/mintlify-docs/metrics-1.mdx b/mintlify-docs/metrics-1.mdx new file mode 100644 index 0000000000..562644b21a --- /dev/null +++ b/mintlify-docs/metrics-1.mdx @@ -0,0 +1,9 @@ +--- +title: "Semgrep metrics" +sidebarTitle: "Metrics" +description: "Semgrep CLI may collect aggregate metrics to help improve the product. This document describes:" +--- + +import Metrics from "/snippets/metrics.mdx" + +
+ + + ___ + + ' + title: Semgrep Web App + version: 1.0.0 +openapi: 3.0.3 +paths: + /api/v1/bootstrap-sms-vpc: + get: + description: 'VPC support for Managed Scans is in private beta. + + + Returns the Managed Scans VPC Bootstrap CloudFormation template in JSON format + for setting up cross-account infrastructure. + + + This template creates IAM roles and policies needed for Semgrep Managed Scanning + (SMS) VPC infrastructure automation, + + including the semgrep-sms-vpc-automation role and EC2 Image Builder distribution + roles for gVisor container runtime. + + + See the original AWS cloudformation template format at https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-formats.html + + ' + operationId: MiscService_GetBootstrapSmsVpc + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.GetBootstrapSmsVpcResponse' + description: OK + summary: '[Beta] Get SMS VPC Bootstrap CloudFormation Template' + tags: + - MiscService + x-badges: [] + /api/v1/deployments: + get: + description: 'Request the deployments your auth can access. + + + Currently available auth scope does not extend over more than one deployment. + This endpoint returns the single deployment your token can access. The endpoint + additionally returns links to related resources available on this API.' + operationId: DeploymentsService_ListDeployments + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.ListDeploymentsResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: List deployments + tags: + - DeploymentsService + x-badges: [] + /api/v1/deployments/{deploymentId}/dependencies: + post: + operationId: SupplyChainService_ListDependencies + parameters: + - in: path + name: deploymentId + required: true + schema: + description: 'Deployment ID (numeric). Example: `123`. Can be found at `/deployments`, + or in your Settings in the web UI.' + example: 123 + format: uint64 + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.ListDependenciesRequest' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.ListDependenciesResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: List dependencies + tags: + - SupplyChainService + x-badges: [] + /api/v1/deployments/{deploymentId}/dependencies/repositories: + post: + operationId: SupplyChainService_ListRepositoriesForDependencies + parameters: + - in: path + name: deploymentId + required: true + schema: + description: 'Deployment ID (numeric). Example: `123`. Can be found at `/deployments`, + or in your Settings in the web UI.' + format: uint64 + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.ListRepositoriesForDependenciesRequest' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.ListRepositoriesForDependenciesResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: List repositories with dependencies + tags: + - SupplyChainService + x-badges: [] + /api/v1/deployments/{deploymentId}/dependencies/repositories/{repositoryId}/lockfiles: + post: + operationId: SupplyChainService_ListLockfilesForDependencies + parameters: + - in: path + name: deploymentId + required: true + schema: + description: 'Deployment ID (numeric). Example: `123`. Can be found at `/deployments`, + or in your Settings in the web UI.' + format: uint64 + type: string + - in: path + name: repositoryId + required: true + schema: + description: Repository ID to filter by. Use Projects endpoints to retrieve + repository IDs. + format: uint64 + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.ListLockfilesForDependenciesRequest' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.ListLockfilesForDependenciesResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: List lockfiles in a given repository with dependencies + tags: + - SupplyChainService + x-badges: [] + /api/v1/deployments/{deploymentId}/policies: + get: + operationId: PoliciesService_ListPolicies + parameters: + - in: path + name: deploymentId + required: true + schema: + description: 'Deployment ID (numeric). Example: `123`. Can be found at `/deployments`, + or in your Settings in the web UI.' + example: 123 + format: uint64 + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.ListPoliciesResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: List policies + tags: + - PoliciesService + x-badges: [] + /api/v1/deployments/{deploymentId}/policies/{policyId}: + get: + operationId: PoliciesService_ListPolicyRules + parameters: + - in: path + name: deploymentId + required: true + schema: + description: 'Deployment ID (numeric). Example: `123`. Can be found at `/deployments`, + or in your Settings in the web UI.' + example: 123 + format: uint64 + type: string + - in: path + name: policyId + required: true + schema: + description: 'Policy ID (numeric). Example: `456`. Can be found at `/deployments/{deploymentId}/policies`.' + example: 456 + format: uint64 + type: string + - in: query + name: cursor + schema: + description: Cursor to paginate through the rules. Provide a cursor value + from the response to retrieve the next page. + type: string + - in: query + name: limit + schema: + description: Page size to paginate through the rules. The default page size + is `500` and the maximum allowed page size is `2000`. + format: uint32 + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.ListPolicyRulesResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: List policy rules + tags: + - PoliciesService + x-badges: [] + put: + operationId: PoliciesService_UpdatePolicy + parameters: + - in: path + name: deploymentId + required: true + schema: + description: 'Deployment ID (numeric). Example: `123`. Can be found at `/deployments`, + or in your Settings in the web UI.' + example: 123 + format: uint64 + type: string + - in: path + name: policyId + required: true + schema: + description: 'Policy ID (numeric). Example: `456`. Can be found at `/deployments/{deploymentId}/policies`.' + example: 456 + format: uint64 + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.UpdatePolicyRequest' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.UpdatePolicyResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: Update policy + tags: + - PoliciesService + x-badges: [] + /api/v1/deployments/{deploymentId}/sbom/export: + post: + operationId: SupplyChainService_CreateSbomExport + parameters: + - in: path + name: deploymentId + required: true + schema: + description: 'Deployment ID (numeric). Example: `123`. Can be found at `/deployments`, + or in your Settings in the web UI.' + example: 123 + format: uint64 + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.CreateSbomExportRequest' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.CreateSbomExportResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: Create a new SBOM export job + tags: + - SupplyChainService + x-badges: [] + /api/v1/deployments/{deploymentId}/sbom/export/{taskToken}: + get: + operationId: SupplyChainService_GetSbomExport + parameters: + - in: path + name: deploymentId + required: true + schema: + description: 'Deployment ID (numeric). Example: `123`. Can be found at `/deployments`, + or in your Settings in the web UI.' + example: 123 + format: int64 + type: string + - in: path + name: taskToken + required: true + schema: + description: Task token for the SBOM export job. + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.GetSbomExportResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: Get the status of a SBOM export job + tags: + - SupplyChainService + x-badges: [] + /api/v1/deployments/{deploymentId}/scan/{scanId}: + get: + description: Request the details of a scan including the associated deployment, + repository, and commit information. + operationId: ScansService_GetScan + parameters: + - in: path + name: deploymentId + required: true + schema: + description: 'Deployment ID (numeric). Example: `123`. Can be found at `/deployments`, + or in your Settings in the web UI.' + example: 123 + format: uint64 + type: string + - in: path + name: scanId + required: true + schema: + description: 'Scan ID (numeric). Example: `456`. Can be found at `/deployments/{deploymentId}/scans/search`.' + example: 456 + format: uint64 + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.GetScanResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: Get scan details + tags: + - ScansService + x-badges: [] + /api/v1/deployments/{deploymentId}/scans/search: + post: + description: List the scans associated with a particular repository over the + past 30 days. + operationId: ScansService_SearchScans + parameters: + - in: path + name: deploymentId + required: true + schema: + description: 'Deployment ID (numeric). Example: `123`. Can be found at `/deployments`, + or in your Settings in the web UI.' + example: 123 + format: uint64 + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.SearchScansRequest' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.SearchScansResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: List scans (beta) + tags: + - ScansService + x-badges: [] + /api/v1/deployments/{deploymentId}/secrets: + get: + operationId: SecretsService_ListSecretsPath + parameters: + - in: path + name: deploymentId + required: true + schema: + description: 'Deployment ID (numeric). Example: `123`. Can be found at `/deployments`, + or in your Settings in the web UI.' + example: 123 + format: uint64 + type: string + - in: query + name: cursor + schema: + description: Cursor to paginate through the rules. Provide a cursor value + from the response to retrieve the next page. + type: string + - in: query + name: limit + schema: + description: Page size to paginate through the results. + format: uint32 + type: integer + - in: query + name: since + schema: + format: date-time + type: string + - in: query + name: validationState + schema: + description: "Whether the finding was validated or not.\n\n - VALIDATION_STATE_UNSPECIFIED: + Return results for all validation states (can also omit this parameter).\n- + VALIDATION_STATE_CONFIRMED_VALID: Secret has been tested and is confirmed + valid.\n - VALIDATION_STATE_CONFIRMED_INVALID: Secret has been tested + and is confirmed invalid.\n - VALIDATION_STATE_VALIDATION_ERROR: Secret + test was attempted and there was an error.\n - VALIDATION_STATE_NO_VALIDATOR: + There is no validator for this secret." + format: string + items: + enum: + - VALIDATION_STATE_UNSPECIFIED + - VALIDATION_STATE_CONFIRMED_VALID + - VALIDATION_STATE_CONFIRMED_INVALID + - VALIDATION_STATE_VALIDATION_ERROR + - VALIDATION_STATE_NO_VALIDATOR + format: enum + type: string + type: array + - in: query + name: status + schema: + default: FINDING_STATUS_UNSPECIFIED + description: "Status of the finding.\n\n - FINDING_STATUS_UNSPECIFIED: Return + results for all finding statuses (if used as a parameter).\n - FINDING_STATUS_OPEN: + Finding is open and needs to be triaged\n - FINDING_STATUS_IGNORED: Finding + has been triaged and is being ignored\n - FINDING_STATUS_FIXED: Finding + has been fixed\n - FINDING_STATUS_REMOVED: Finding has been removed\n + - FINDING_STATUS_UNKNOWN: Finding status is unknown" + enum: + - FINDING_STATUS_UNSPECIFIED + - FINDING_STATUS_OPEN + - FINDING_STATUS_IGNORED + - FINDING_STATUS_FIXED + - FINDING_STATUS_REMOVED + - FINDING_STATUS_UNKNOWN + - FINDING_STATUS_PROVISIONALLY_IGNORED + format: enum + type: string + - in: query + name: severity + schema: + description: "Severity of the finding.\n\n - SEVERITY_UNSPECIFIED: Return + results for all severities (if used as a parameter)." + format: string + items: + enum: + - SEVERITY_UNSPECIFIED + - SEVERITY_HIGH + - SEVERITY_MEDIUM + - SEVERITY_LOW + - SEVERITY_CRITICAL + format: enum + type: string + type: array + - in: query + name: repo + schema: + description: Repositories to view results for. If not specified, returns + all. + format: string + items: + type: string + type: array + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.ListSecretsPathResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: List secrets + tags: + - SecretsService + x-badges: [] + /api/v1/deployments/{deploymentId}/ticketing/v2/tickets/{externalTicketId}: + delete: + description: Unlink a Jira ticket by its ID + operationId: TicketingService_DeleteTicket + parameters: + - in: path + name: deploymentId + required: true + schema: + description: Deployment ID. Can be found at /deployments, or in your Settings + in the web UI. + example: 123 + type: string + - in: path + name: externalTicketId + required: true + schema: + description: The ID of the external ticket + example: 456 + format: uint32 + type: integer + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.DeleteTicketResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: Unlink a Jira ticket + tags: + - TicketingService + x-badges: [] + /api/v1/deployments/{deploymentSlug}/findings: + get: + description: 'Request the list of code or supply chain findings in an organization, + paginated in pages of 100 entries and limited by the `since` timestamp. Findings + are returned by `relevant_since` descending (see `since` in the Query Parameters + list). Examples: List SAST findings with pagination, List SCA findings since + timestamp, List findings with filters.' + operationId: FindingsService_ListFindings + parameters: + - in: path + name: deploymentSlug + required: true + schema: + description: Slug of the deployment name. Can be found at `/deployments`, + or in your Settings in the web UI. + example: your-deployment + type: string + - in: query + name: issue_type + schema: + default: sast + description: 'Type of findings to return. If not specified, returns `sast` + (Code) findings. Can either be `sast` (Code) or `sca` (Supply Chain). + Valid values: sast, sca' + enum: + - sast + - sca + example: sca + type: string + - in: query + name: since + schema: + description: 'What timestamp should the results start at? If not specified, + returns results from all timestamps. Provide epoch timestamp in seconds. + Filters using the `relevant_since` field: the timestamp when this finding + was detected by Semgrep (the first time, or when reintroduced).' + example: 1636942398.45 + format: double + type: number + - in: query + name: page + schema: + default: '0' + description: Which page of the results do you require? If not specified, + returns first page. Pages are numbered from zero (0). + example: 1 + format: uint32 + type: integer + - in: query + name: dedup + schema: + default: false + description: Deduplicates findings across all your refs/branches if true. + If not specified, returns all findings across all refs/branches without + deduplicating them. Set this to `true` if you are not filtering for a + particular set of refs/branches in order to match the counts listed in + the Semgrep UI. + example: true + type: boolean + - in: query + name: page_size + schema: + default: '100' + description: 'Maximum number of records per returned page. If not specified, + defaults to 100 records. Minimum: 100, Maximum: 3000' + example: 100 + format: uint32 + maximum: 3000.0 + minimum: 100.0 + type: integer + - in: query + name: repos + schema: + description: Which repositories (by name) do you want to include? If not + specified, includes all. + example: + - myorg/repo1 + - myorg/repo2 + items: + type: string + type: array + - in: query + name: repository_ids + schema: + description: Which repositories (by ID) do you want to include? If not specified, + includes all. + example: + - 1 + - 2 + - 3 + items: + format: uint32 + type: integer + type: array + - in: query + name: status + schema: + description: 'Which status do you want to include? If not specified, includes + all. Valid values: open, fixed, ignored, reviewing, fixing' + enum: + - open + - fixed + - ignored + - reviewing + - fixing + example: open + type: string + - in: query + name: triage_reasons + schema: + description: 'Which triage reasons do you want to include? If not specified, + includes all. This filter is applicable when `status` is `ignored`. Valid + values: acceptable_risk, false_positive, no_time, no_triage_reason' + enum: + - acceptable_risk + - false_positive + - no_time + - no_triage_reason + example: + - acceptable_risk + - false_positive + items: + type: string + type: array + - in: query + name: severities + schema: + description: 'What severities of issues do you want to include? If not specified, + returns all. Valid values: low, medium, high, critical' + enum: + - low + - medium + - high + - critical + example: + - low + - high + items: + type: string + type: array + - in: query + name: ref + schema: + description: Which ref (branch) do you want to filter for? + example: refs/pull/1234/merge + type: string + - in: query + name: policies + schema: + description: 'Which policy modes do you want to include? If not specified, + includes all. Monitor: `rule-board-audit`, Comment: `rule-board-pr-comments`, + Block: `rule-board-block`. This filter is applicable when `issue_type` + is `sast` or unspecified.' + example: + - rule-board-block + - rule-board-pr-comments + - rule-board-audit + items: + type: string + type: array + - in: query + name: rules + schema: + description: Which rule names do you want to include? If not specified, + includes all. This filter is applicable when `issue_type` is `sast` or + unspecified. + example: + - typescript.react.security.audit.react-no-refs.react-no-refs + - ajinabraham.njsscan.hardcoded_secrets.node_username + items: + type: string + type: array + - in: query + name: categories + schema: + description: Which categories of findings do you want to include? If not + specified, includes all. This filter is applicable when `issue_type` is + `sast` or unspecified. + example: + - security + - correctness + - caching + items: + type: string + type: array + - in: query + name: confidence + schema: + description: 'Which rule confidence level do you want to include? If not + specified, includes all. This filter is applicable when `issue_type` is + `sast` or unspecified. Valid values: low, medium, high' + enum: + - low + - medium + - high + example: high + type: string + - in: query + name: autotriage_verdict + schema: + description: 'Which autotriage verdict do you want to include? If not specified, + includes all. This filter is applicable when `issue_type` is `sast` or + unspecified. Valid values: true_positive, false_positive' + enum: + - true_positive + - false_positive + example: true_positive + type: string + - in: query + name: component_tags + schema: + description: Which component tags do you want to include? If not specified, + includes all. + example: + - user authentication + - user data + items: + type: string + type: array + - in: query + name: exposures + schema: + description: 'List of exposures or reachability types to filter by. If not + specified, returns findings across all exposures. This filter is applicable + when `issue_type=sca` is specified. Valid values: reachable, always_reachable, + conditionally_reachable, unreachable, unknown' + enum: + - reachable + - always_reachable + - conditionally_reachable + - unreachable + - unknown + example: + - reachable + - always_reachable + items: + type: string + type: array + - in: query + name: transitivities + schema: + description: 'List of transitivities to filter by. If not specified, returns + all transitivities. This filter is applicable when `issue_type=sca` is + specified. Valid values: direct, transitive, unknown' + enum: + - direct + - transitive + - unknown + example: + - transitive + items: + type: string + type: array + - in: query + name: is_malicious + schema: + description: 'Filter SCA findings by whether they are from malicious dependencies. + If not specified, returns all SCA findings. This filter is only applicable + when `issue_type=sca` is specified. + + - true: Returns only findings from malicious dependencies + + - false: Returns only findings from all other reachabilities (reachable + in code, always reachable, conditionally reachable, etc.)' + example: true + type: boolean + - in: query + name: click_to_fix_pr_state + schema: + description: 'Filter findings by Click-to-Fix PR state. If not specified, + returns all findings regardless of autofix PR status. This filter applies + to both sast and sca issue types. Valid values: open, merged' + enum: + - open + - merged + example: + - open + - merged + items: + type: string + type: array + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.ListFindingsResponse' + description: OK + default: + content: + application/json: + schema: + properties: + findings: + items: + oneOf: + - title: Sast Finding + allOf: + - $ref: '#/components/schemas/protos.openapi.v1.SastFinding' + - title: Sca Finding + allOf: + - $ref: '#/components/schemas/protos.openapi.v1.ScaFinding' + type: array + type: object + description: OK + security: + - SemgrepWebToken: [] + summary: List code or supply chain findings + tags: + - FindingsService + x-badges: [] + /api/v1/deployments/{deploymentSlug}/projects: + get: + description: Request the list of projects that have been scanned or onboarded + to Managed Scans. Does not return archived repositories. Returns 100 projects + per page by default. + operationId: ProjectsService_ListProjects + parameters: + - in: path + name: deploymentSlug + required: true + schema: + description: Slug of the deployment name. Can be found at `/deployments`, + or in your Settings in the web UI. + example: your-deployment + type: string + - in: query + name: page + schema: + description: Which page of the results do you require? If not specified, + returns first page. Pages are numbered from zero (0). + example: 1 + format: uint32 + type: number + - in: query + name: page_size + schema: + default: 100.0 + description: Maximum number of records per returned page. If not specified, + defaults to 100 records. + example: 100 + format: uint32 + type: number + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.ListProjectsResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: List all projects + tags: + - ProjectsService + x-badges: [] + /api/v1/deployments/{deploymentSlug}/projects/{projectName}: + delete: + description: Delete a project for a deployment you have access to. This will + also delete all of the associated findings. + operationId: ProjectsService_DeleteProject + parameters: + - in: path + name: deploymentSlug + required: true + schema: + description: Slug of the deployment name. Can be found at `/deployments`, + or in your Settings in the web UI. + example: your-deployment + type: string + - in: path + name: projectName + required: true + schema: + description: Name of the project, typically the repository formatted as + a path. + example: organization/project + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.DeleteProjectResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: Delete project + tags: + - ProjectsService + x-badges: [] + get: + description: Retrieve details for a single project associated with a deployment + that you have access to. + operationId: ProjectsService_GetProject + parameters: + - in: path + name: deploymentSlug + required: true + schema: + description: Slug of the deployment name. Can be found at `/deployments`, + or in your Settings in the web UI. + example: your-deployment + type: string + - in: path + name: projectName + required: true + schema: + description: Name of the project, typically the repository formatted as + a path. + example: organization/project + type: string + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.GetProjectResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: Get project details + tags: + - ProjectsService + x-badges: [] + patch: + description: 'Update attributes for the project using the value passed in to + the request body. + + + Note: The only attribute that is supported as of January 2023 is `tags`.' + operationId: ProjectsService_UpdateProject + parameters: + - in: path + name: deploymentSlug + required: true + schema: + description: Slug of the deployment name. Can be found at `/deployments`, + or in your Settings in the web UI. + example: your-deployment + type: string + - in: path + name: projectName + required: true + schema: + description: Name of the project, typically the repository formatted as + a path. + example: organization/project + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.UpdateProjectRequest' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.UpdateProjectResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: Update project details + tags: + - ProjectsService + x-badges: [] + /api/v1/deployments/{deploymentSlug}/projects/{projectName}/managed-scan: + patch: + description: 'Enable or disable + + [Semgrep Managed Scans](/deployment/managed-scanning/overview) + + for a project.' + operationId: ProjectsService_ToggleProjectManagedScan + parameters: + - in: path + name: deploymentSlug + required: true + schema: + description: Slug of the deployment name. Can be found at `/deployments`, + or in your Settings in the web UI. + example: your-deployment + type: string + - in: path + name: projectName + required: true + schema: + description: Name of the project, typically the repository formatted as + a path. + example: organization/project + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.ToggleProjectManagedScanRequest' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.ToggleProjectManagedScanResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: Toggle Managed Scans for a project + tags: + - ProjectsService + x-badges: [] + /api/v1/deployments/{deploymentSlug}/projects/{projectName}/tags: + delete: + description: 'Remove tags from a project for a deployment you have access to. + + + This request will not delete project tags from the deployment and will only + remove + + them from the requested project. Any other projects associated with the requested + + tag will remain unaffected.' + operationId: ProjectsService_DeleteProjectTags + parameters: + - in: path + name: deploymentSlug + required: true + schema: + description: Slug of the deployment name. Can be found at `/deployments`, + or in your Settings in the web UI. + example: your-deployment + type: string + - in: path + name: projectName + required: true + schema: + description: Name of the project, typically the repository formatted as + a path. + example: organization/project + type: string + - in: query + name: tags + schema: + example: + - tag + items: + type: string + type: array + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.DeleteProjectTagsResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: Remove tags from project + tags: + - ProjectsService + x-badges: [] + put: + description: 'Add tags to a project for a deployment you have access to. + + + Any project tags that do not already exist for the deployment will be created + automatically and associated with the project.' + operationId: ProjectsService_AddProjectTags + parameters: + - in: path + name: deploymentSlug + required: true + schema: + description: Slug of the deployment name. Can be found at `/deployments`, + or in your Settings in the web UI. + example: your-deployment + type: string + - in: path + name: projectName + required: true + schema: + description: Name of the project, typically the repository formatted as + a path. + example: organization/project + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.AddProjectTagsRequest' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.AddProjectTagsResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: Add tags to project + tags: + - ProjectsService + x-badges: [] + /api/v1/deployments/{deploymentSlug}/tickets: + post: + description: Create Jira tickets for your findings. You can create tickets by + passing in a list of issue_ids or by passing in filter query parameters to + dynamically select findings. If passing in filters, Semgrep will skip already + ticketed findings. This endpoint is synchronous, so it may take some time + for your request to resolve. Unlike creating tickets in-app, if ticket creation + fails we won't automatically retry. This endpoint accepts a limit parameter + (defaulting to 20) to limit the number of tickets created per request. If + you specify a list of issue_ids greater than this limit, or your selected + filters match on a number of issues greater than this limit, issues that were + not ticketed are included in the Failed part of the response object. You can + send another request to create tickets for these skipped issues. By default, + findings belonging to the same repository and the same rule will be grouped + together into a single Jira ticket. You can override this using the group_issues + query parameter. Up to 50 issues can be grouped into a single ticket. You + can optionally override the Jira project you create tickets in by passing + in a Jira project ID as jira_project_id (the numeric ID rather than the project + key). You can fetch this ID using the Jira API. + operationId: TicketingService_CreateTicket + parameters: + - in: path + name: deploymentSlug + required: true + schema: + description: Deployment slug. Can be found at `/deployments`, or in your + Settings in the web UI. + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.CreateTicketRequest' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.CreateTicketResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: Create Jira tickets + tags: + - TicketingService + x-badges: [] + /api/v1/deployments/{deploymentSlug}/triage: + post: + description: Bulk triage your findings. You can select the findings to triage + by passing in a list of finding IDs as issue_ids, or by passing in filter + query parameters. You must specify the issue_type of the findings you want + to bulk triage. One of new_triage_state or new_note is required. If specifying + a new_triage_reason, you must also use new_triage_state=ignored. Some filters + only apply for findings associated with a given product. + operationId: TriageService_BulkTriage + parameters: + - in: path + name: deploymentSlug + required: true + schema: + description: Deployment slug. Can be found at /deployments, or in your Settings + in the web UI. + type: string + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.BulkTriageRequest' + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.BulkTriageResponse' + description: OK + security: + - SemgrepWebToken: [] + summary: Bulk triage + tags: + - TriageService + x-badges: [] + /api/v1/ping: + get: + description: Use to ping the server and assert liveness. + operationId: MiscService_Ping + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/protos.openapi.v1.PingResponse' + description: OK + summary: Ping + tags: + - MiscService + x-badges: [] +tags: +- description: Deployments encapsulate your organization's security organization, + with multiple projects, policies, and integrations. As the root object of the + organization, they're similarly the root object of the API. + name: DeploymentsService + x-displayName: Deployment +- description: Manage and retrieve code and supply chain security findings from Semgrep + scans + name: FindingsService + x-displayName: Code and Supply Chain +- description: Utility endpoints. + name: MiscService + x-displayName: Other +- description: View and manage the Policies of your organization. + name: PoliciesService + x-displayName: Policies +- name: ProjectsService + x-displayName: Projects +- description: View details of scans associated with projects in your organization. + name: ScansService + x-displayName: Scans +- description: View and manage the Secrets of your organization. + name: SecretsService + x-displayName: Secrets +- description: 'Manage the Supply Chain findings and dependencies of your organization. + + + A request body is required, but may be an empty object.' + name: SupplyChainService + x-displayName: Supply Chain +- description: Create and manage external tickets + name: TicketingService + x-displayName: Ticketing +- description: View and manage the triage of your organization. + name: TriageService + x-displayName: Triage diff --git a/mintlify-docs/references/feature-definitions.mdx b/mintlify-docs/references/feature-definitions.mdx new file mode 100644 index 0000000000..bc24954862 --- /dev/null +++ b/mintlify-docs/references/feature-definitions.mdx @@ -0,0 +1,23 @@ +--- +title: "Feature definitions" +--- + +This document defines the terms used when discussing Semgrep analysis features in [Supported languages](/supported-languages). + +## Cross-file dataflow analysis + +Cross-file analysis (also known as **interfile analysis**) takes into account how information flows between files. In particular, cross-file analysis includes **cross-file taint analysis**, which tracks unsanitized variables flowing from a source to a sink through arbitrarily many files. Other analyses performed across files include constant propagation and type inference. + +Cross-file analysis is usually used in contrast to intrafile, or per-file analysis, where each file is analyzed as a standalone block of code. + +Languages with cross-file support also include cross-function support. + +## Cross-function dataflow analysis + +Cross-function analysis means that interactions between functions are taken into account. This improves taint analysis, which tracks unsanitized variables flowing from a source to a sink through arbitrarily many functions. + +## Reachability analysis + +Reachability refers to whether or not a vulnerable code pattern from a dependency is used in the codebase that imports it. In Semgrep Supply Chain, both a dependency's vulnerable version and code pattern must match for a vulnerability to be considered reachable. + +See [Overview of Semgrep Supply Chain](/semgrep-supply-chain/overview) to learn how Semgrep leverages its code-scanning and rule syntax capabilities to provide high-signal rules that determine a finding's reachability. This assists security engineers in remediation and triage processes. diff --git a/mintlify-docs/references/language-maturity-levels.mdx b/mintlify-docs/references/language-maturity-levels.mdx new file mode 100644 index 0000000000..ee43123a75 --- /dev/null +++ b/mintlify-docs/references/language-maturity-levels.mdx @@ -0,0 +1,40 @@ +--- +title: "Language maturity levels" +--- + +This document defines the language maturity levels used on the [Supported languages](/supported-languages) page. + +## Semgrep Code + +Semgrep Code languages can be classified into four maturity levels: + +- Generally available (GA) +- Beta +- Experimental +- Community supported\* + +\*Community supported languages meet the parse rate and syntax requirements of +**Experimental** languages. Users can still access community rules or write their +own rules. + +| Feature | GA | Beta | Experimental | Community supported | +| :--- | :--- | :--- | :--- | :--- | +| Support | Highest quality support by the Semgrep team. Reported issues are resolved promptly. | Supported by the Semgrep team. Reported issues are fixed after GA languages. | There are limitations to this language's functionality. Reported issues are tracked and prioritized with best effort. | These languages are supported by the Semgrep community. While Semgrep may develop rules or engine updates for these languages, they are not prioritized. | +| Parse Rate | 99\%\+ | 95\%\+ | 90\%\+ | 90\%\+ | +| Number of Pro rules | 10\+ | 5\+ | 0\+. Query the [Registry](https://semgrep.dev/r) to see if any rules exist for your language. | 0\+. Query the [Registry](https://semgrep.dev/r) to see if any rules exist for your language. | +| Semgrep syntax | Regex, equivalence, deep expression operators, types and typing. All features supported in Beta. | Complete metavariable support, metavariable equality. All features supported in Experimental. | Syntax, ellipsis operator, basic metavariable functionality. | Syntax, ellipsis operator, basic metavariable functionality. | + +## Semgrep Supply Chain + +Semgrep Supply Chain has two language maturity levels: + +- Generally available +- Beta + +| Feature | Generally available | Beta | +| :--- | :--- | :--- | +| Number of reachability rules | As defined by [CVE coverage](/semgrep-supply-chain/sca-feature-support#cve-coverage). | All critical severity CVEs from [supported sources](/semgrep-supply-chain/sca-feature-support#supported-sources) starting 2022 onwards, for packages used by customers with an active, paid subscription. | +| Semgrep, Inc. rule-writing support | Quickly support CVE coverage with reachability analysis for all critical and high vulnerabilities based on the latest [security advisories](https://nvd.nist.gov/vuln). | Coverage for CVEs but without reachability analysis. | +| [Semgrep Community Edition (CE) language support](/supported-languages#semgrep-oss-language-support) | Semgrep CE support is GA. | Semgrep CE support is at least Beta. | + +Not finding what you need in this doc? Ask questions in our [Community Slack group](https://go.semgrep.dev/slack), or see [Support](/support/) for other ways to get help. diff --git a/mintlify-docs/release-notes.mdx b/mintlify-docs/release-notes.mdx new file mode 100644 index 0000000000..6160198a9e --- /dev/null +++ b/mintlify-docs/release-notes.mdx @@ -0,0 +1,124 @@ +--- +title: "Semgrep release notes" +rss: true +--- + +
+ i. Upgrade the dependency to a safe version.
+ ii. Lets the developer know if the upgrade is safe or if there are breaking changes and what those changes are. +- **Transitive reachability** is now in **private beta**. For JavaScript projects, Semgrep reachability now extends to transitive dependencies. + +### Changed + +- Increased the rate limit for SBOM exports through the Semgrep API. +- Improved Supply Chain PR comments by adding separate templates for conditionally reachable and always reachable findings, as well as manual review advice for conditionally reachable findings. {/* 20446 */} +- Improved the user introduction to Supply Chain to focus on reachable findings. {/* 20290 */} +- Improved the **Supply Chain > Details** page. {/* 20236 */} + +## 🤖 Semgrep Assistant + +### Added + +- Semgrep Assistant now attempts to create a memory during triage if possible. If Semgrep creates a memory, you'll see a dialog appear, indicating that this has happened, along with a link to the list of your organization's memories for review. +- Assistant Memories v2 is now in **private beta**: + - Managing memories in Semgrep AppSec Platform now occurs under **Policies**, not **Settings**. + - Semgrep AppSec Platform displays data on the scope and impact of memories, including the number of findings affected and which findings affected + - Assistant now provides **suggested memories**, which are those that Assistant has generated based on your past triage actions. You can view these memories at any time in Semgrep AppSec Platform by navigating to **Rules & Policies > Assistant Memories > Suggested**. For each suggestion, you can choose one of the following actions: + - Activate the suggested memory to inform Assistant's future advice. + - Edit the memory, then activate it. + - Delete the memory. + +## 🔐 Semgrep Secrets + +### Fixed + +- Fixed an issue where Semgrep AppSec Platform didn't display the correct number of Secrets findings in the navigation bar. + +## 📝 Documentation and knowledge base + +### Added + +- Semgrep release notes are now available through RSS. You can subscribe to the: + - [
semgrep scan --config PRODUCT_NAME now uses the same endpoint as semgrep ci to fetch the scan configuration. You must be logged in when using these commands. You can continue running `semgrep scan` without logging in by providing configuration such as --config auto.
+
+
+### Fixed
+
+- **API:** Fixed an issue where the severities filter did not return the correct value. {/* gh-11307 */}
+- **CLI tool:**
+ - The `--severity=[VALUE]` option, which can be added to a `semgrep scan` command, has been fixed. {/* gh-9062 */}
+ - The `--sarif` flag no longer crashes when Semgrep itself encounters errors.
+- Semgrep now refuses to run incompatible versions of the Pro Engine, rather than crashing and returning a confusing error message. {/* (gh-8873) */}
+- Fixed an issue where the CI provider icons disappeared from the **Scan new project in CI** window. The icons now appear. {/* 11228 */}
+- Implemented minor fixes for the new onboarding flow. {/* 11209, 11207 */}
+
+## 💻 Semgrep Code
+
+### Changed
+
+- **Scanning timeout:** The timeout per rule and per file has increased from 2 seconds to 5 seconds.
+
+### Fixed
+
+- **Findings page:** Fixed an issue where filtering by repositories wasn't working. {/* (11414) */}
+
+## ⛓️ Semgrep Supply Chain
+
+### Fixed
+
+- **Slack messages:**
+ - Improved readability of Semgrep Supply Chain messages by adding new lines between sections. {/* (11396) */}
+ - Fixed links that were not working. {/* (11210) */}
+- Fixed out-of-bounds list access error in `Cargo.lock` parser. {/* (sc-1072) */}
+
+## 🔐 Semgrep Secrets (beta)
+
+### Added
+
+- Added an optional `--no-secrets-validation` flag to skip secrets validation. To run a Secrets scan without validation, use the command `semgrep ci --secrets --no-secrets-validation`.
+- **Secrets and Secrets details page:** Added a **
+
+
+Other:
+- Fixed message typo: Expand the list with all removed rules
+-semgrep --config=auto --exclude RULE_ID. (Issue [2530](https://github.com/semgrep/semgrep/issues/2530), PR [5974](https://github.com/semgrep/semgrep/pull/5974))
+
+- You can now have multiple metavariables under `focus-metavariable`, which allows. Semgrep to highlight the values matched by multiple metavariables more easily in certain circumstances. For more information, see [Using multiple focus metavariables](/writing-rules/experiments/multiple-focus-metavariables) documentation. (Issue [5686](https://github.com/semgrep/semgrep/issues/5686))
+
+- You can add tags for specific projects in the Semgrep App on the configuration page of a project. With this update, you can create `.semgrepconfig.yml` file in the root directory of your repository and add tags in this file also. See [Tagging projects](/semgrep-appsec-platform/tags).
+
+- The Semgrep CLI output now displays non-blocking and blocking findings separately. CLI output also provides a list of the blocking rules that matched the code.
+
+- taint-mode: Experimental support for basic field-sensitive taint tracking. Semgrep can now track `x.a` and `x.b` separately, so that for example: `x.a` can be tainted at the same time as `x.b` is clean, hence `sink(x.a)` can produce a finding but `sink(x.b)` does not. It is also possible for `x` to be tainted while `x.a` is clean. As a result, the number of false positives that Semgrep reports is reduced.
+
+### Changes
+
+- generic mode: Allow text input up to 500 bytes without human-readable indentation. This value is subject to change. This relaxation is intended to facilitate testing a long line without a trailing newline. Semgrep users should not expect files that are not human-readable to be processed by Semgrep's generic mode, or in any mode. (Issues [6071](https://github.com/semgrep/semgrep/issues/6071), [6162](https://github.com/semgrep/semgrep/issues/6162))
+
+- Changed behavior for renamed files in diff-aware scans. Semgrep no longer displays old issues to developers when they rename a file. As a result, findings in renamed files are displayed for security engineers but do not block or spam developers. (Issue [6157](https://github.com/semgrep/semgrep/pull/6157))
+
+## Additional information
+
+Minor bug fixes are not included in the release notes unless they are potentially breaking your workflow. To see the complete change notes for Semgrep CLI and CI that include fixes, visit the [Semgrep changelog](https://github.com/semgrep/semgrep/releases/).
+
+## Documentation updates
+
+- New documentation for experimental [Taint labels](/writing-rules/data-flow/taint-mode/advanced#taint-labels-).
+- New documentation for [Display matched metavariables in rule messages](/writing-rules/pattern-syntax/#display-matched-metavariables-in-rule-messages) and experimental [Displaying propagated value of metavariables](/writing-rules/experiments/display-propagated-metavariable).
+- New documentation for [Using multiple focus metavariables](/writing-rules/experiments/multiple-focus-metavariables).
+- Added information about [Ellipsis operator scope](/writing-rules/pattern-syntax/#ellipsis-operator-scope).
+- Many documents, such as [Getting started with Semgrep App](/deployment/core-deployment) now display minimal Semgrep tier required for a particular feature documented on the page.
+- Updated [Managing findings in Semgrep App](/semgrep-code/findings).
+- [Taint mode](/writing-rules/data-flow/taint-mode/overview) documentation has been updated and now includes introductory video.
+- Updated [Getting started with Semgrep in continuous integration (CI)](/deployment/core-deployment)
+- Updated [Data-flow analysis engine overview](/writing-rules/data-flow/data-flow-overview).
+- Updated [Integrating Semgrep into source code management (SCM) tools](/deployment/connect-scm).
+- Updated [Evaluating your security posture through the Dashboard](/semgrep-appsec-platform/dashboard).
+- Updated [Notifications](/semgrep-appsec-platform/notifications) documentation.
+
diff --git a/mintlify-docs/release-notes/september-2023.mdx b/mintlify-docs/release-notes/september-2023.mdx
new file mode 100644
index 0000000000..6e32c8494d
--- /dev/null
+++ b/mintlify-docs/release-notes/september-2023.mdx
@@ -0,0 +1,109 @@
+---
+title: "September 2023"
+description: "September 30, 2023 · 4 min read"
+rss: true
+---
+
+
+- `category`
- `confidence`
- `likelihood`
- `impact`
- `subcategory`
Read the [metadata reference documentation](/contributing/contributing-to-semgrep-rules-repository#fields-required-by-the-security-category). | +| Verify that the rule matches as intended |
- See [Testing rules](/writing-rules/testing-rules).
- Enable [Code search (beta)](/semgrep-code/editor#code-search-beta) to test the rule on live repositories.
- [Ensure that PR or MR comments have been set up correctly.](/category/pr-or-mr-comments)
- Set the rule to [Comment or Block mode](/semgrep-code/policies#block-a-pr-or-mr-through-rule-modes).
For IDEs: Require developers to install the [Semgrep extension for their IDE](/extensions/overview).
For `pre-commit`: [Install and configure Semgrep for `pre-commit`](/extensions/pre-commit).
| + + +### Secure default snippet + +When creating a custom secure default, you must use `category: security` and `subcategory: secure default` values in your rule: + +```yaml +rules: + - id: some-custom-default + ... + metadata: + category: security + subcategory: + - secure default + ... +``` diff --git a/mintlify-docs/secure-guardrails/secure-defaults.mdx b/mintlify-docs/secure-guardrails/secure-defaults.mdx new file mode 100644 index 0000000000..0fa99f342b --- /dev/null +++ b/mintlify-docs/secure-guardrails/secure-defaults.mdx @@ -0,0 +1,34 @@ +--- +title: "Secure defaults" +--- + +**Secure defaults** are inherently secure libraries, frameworks, configurations, or settings. They mitigate common security concerns, such as preventing cross-site request forgery (CSRF) by properly verifying inbound requests in Django or Flask applications. By adopting secure defaults, teams minimize the need for developers to manually implement security measures. + +Secure default rules are Semgrep Code (SAST) rules that codify a secure default. The Semgrep team recommends deploying these rules as guardrails because the early adoption of secure defaults helps prevent additional vulnerabilities. + +Some secure default rules codify universally secure practices and work out of the box, while others are organization-specific and require customization. + +In the following example, the rule detects if a Flask [WTForm](https://flask-wtf.readthedocs.io/en/0.15.x/config/) view is protected from CSRF by default by checking the configuration variable `WTF_CSRF_CHECK_DEFAULT`. If it is set to `False` then the developer must call `csrf.protect()` whenever they handle a request—a manual process they must remember every time. Thus, `WTF_CSRF_CHECK_DEFAULT=True` is a secure default, which this Semgrep rule enforces. + + + + + +## Semgrep Code supported languages + +Semgrep Code provides secure default rules for the following languages: + +- C# +- Python (Flask, FastAPI, and Django frameworks) + +Custom rules to deploy secure default rules can be written in any of [Semgrep Code’s supported languages](/supported-languages). + +## View Semgrep secure default rules + +View all proprietary Semgrep secure default rules through the ruleset [p/secure-defaults](https://semgrep.dev/p/secure-defaults). + +## Next steps + +
+
+
+
+Secure guardrails consist of:
+
+
+**Content**+ The content that identifies, explains, and provides remediation guidance for the security issue, such as the Semgrep rule and Semgrep Multimodal (AI) remediation guidance. + + Semgrep uses **rules**, which are instructions that detect patterns in your code, such as security issues, bugs, and more. Semgrep generates and reports **findings** to you whenever it finds code that matches the patterns defined by rules. + + Semgrep rules also include a **message** that guides remediation and provides other metadata about the vulnerability, such as its OWASP category, which are presented to the developer. Further improvements to this guidance are made through Semgrep Multimodal. + +**Interface**
+The developer-native **interface** where the developer can see the content and triage or remediate the finding, such as Visual Studio Code (VS Code), pre-commit on CLI, or GitHub pull request comments. See [all supported interfaces](#support-for-developer-interfaces-pre-build). + +
+
+ _**Figure**. Semgrep products provide the content of the guardrail, namely its rules and suggested remediations. The [Semgrep web app](https://semgrep.dev/login) provides the means to configure and deploy guardrails: what rules to deploy as well as where and how to alert developers._
+
+## Qualities of secure guardrails
+
+### Speed
+
+Scans must be quick to successfully integrate into developer workflows without slowing them down.
+
+The following table lists the speed of a Semgrep scan in relation to the environment the scan is run in:
+
+| Interface | Scope of scan | Analysis | Typical speed |
+| :--- | :--- | :--- | :--- |
+| IDE (per keystroke and on save) | Current file | Single-function, single-file | In a few seconds |
+| CLI on commit (through [`pre-commit`](https://pre-commit.com/)) | Files staged for commit (cross-function, single-file analysis) | Cross-function, single-file | Under 5 minutes |
+| PR or MR comments | All committed files and changes in the PR or MR | Cross-function, single-file analysis | Under 5 minutes |
+
+### Support for developer interfaces (pre-build)
+
+Guardrails should be able to provide remediation guidance and means to triage findings or give feedback within developer interfaces.
+
+Semgrep supports the following interfaces:
+
+| Interface | Supported providers and apps | Triage and remediation actions |
+| :--- | :--- | :--- |
+| IDEs | [Visual Studio Code (VS Code)](https://marketplace.visualstudio.com/items?itemName=Semgrep.semgrep) | - Receive human-written remediation guidance.
- Ignore or apply a [Rule-defined fix](/writing-rules/rule-defined-fix), if it is available, to findings individually.
- Receive human-written remediation guidance.
- Ignore or apply a [Rule-defined fix](/writing-rules/rule-defined-fix), if it is available, to findings individually.
- Receive human-written and Semgrep Multimodal remediation guidance\*; you can customize the confidence level at which the AI leaves a comment.
- Ignore or apply a [Rule-defined fix](/writing-rules/rule-defined-fix), if it is available, to findings individually.
- Receive human-written and Semgrep Multimodal remediation guidance\*; you can customize the confidence level at which the AI leaves a comment.
- Ignore or apply a [Rule-defined fix](/writing-rules/rule-defined-fix), if it is available, to findings individually.
- Receive human-written and Semgrep Multimodal remediation guidance\*; you can customize the confidence level at which the AI leaves a comment.
- Ignore or apply a [Rule-defined fix](/writing-rules/rule-defined-fix), if it is available, to findings individually.
- Receive human-written and Semgrep Multimodal remediation guidance\*; you can customize the confidence level at which the AI leaves a comment.
- Ignore or apply a [Rule-defined fix](/writing-rules/rule-defined-fix), if it is available, to findings individually.
- Receive human-written remediation guidance.
- Ignore or apply a [Rule-defined fix](/writing-rules/rule-defined-fix), if it is available, to findings individually.
+
+ + +
+
+_**Figure**. Remediation message provided in VS Code. The message appears when a user hovers over findings, which are marked with squiggly lines. Developers can click the **Quick Fix** button to either ignore the finding or, if there's a Rule-defined fix, apply the fix._
+
+
+
+
+
+
+### Customizability
+
+Every organization has its own secure coding practices. Customizability ensures that the tool can adapt to the unique needs of an organization.
+
+Semgrep provides customizability through:
+
+- Custom rules: You can create custom rules and deploy them as guardrails. Learn more about Semgrep rule structure in [the next section](#remediation-guidance).
+- Memories: this feature allows you to add and save additional context when Semgrep Multimodal provides remediation. For example, you can provide organization-specific public keys, which Semgrep Multimodal remembers.
+
+
+### Remediation guidance
+
+Remediation guidance can come in three forms:
+
+- The rule's `message`
+- AI-generated remediation guidance through Semgrep Multimodal
+- The rule's `fix`
+
+Much of the remediation guidance originates from the rule itself, which is also used to generate Semgrep Multimodal's advice (if Multimodal is enabled). Learning the basic Semgrep rule structure can help you:
+
+- Customize remediation through your organization-specific rules.
+ - Writing your own rules provides you with a means to tailor Semgrep to your organization with or without Multimodal.
+- Write and deploy guardrails of your own.
+
+The following example illustrates a basic Semgrep rule.
+
+
+
+
+_**Figure**. A simple Semgrep rule that illustrates the common fields or keys used to create guardrails. Scroll through the **Rule** pane to view all the fields used to define the rule._
+
+
+
+
+1. [Confirm your Semgrep account's connection and access to your source code manager](#confirm-your-semgrep-accounts-connection).
2. [Configure comments for Semgrep Code](#configure-comments-for-semgrep-code). | +| Software composition analysis (SCA) | Semgrep Supply Chain (SSC) | A comment appears based on the conditions you explicitly set in a [Supply Chain policy](/semgrep-supply-chain/policies) or when Semgrep detects a [license violation](/semgrep-supply-chain/license-compliance). | To receive Supply Chain comments, complete the steps in [Confirm account connection and access](#confirm-your-semgrep-accounts-connection) and [set up a policy](/semgrep-supply-chain/policies).
To receive license violation comments, [enable dependency search](/semgrep-supply-chain/dependency-search#enable-and-use-dependency-search). | +| Secrets | Semgrep Secrets | A comment appears when a finding is generated by a rule in **Comment or Block mode**. A comment also appears for invalid findings and validation errors if these conditions are set to **Comment or Block mode**. | Complete the steps in the following sections:
1. [Confirm your Semgrep account's connection and access to your source code manager](#confirm-your-semgrep-accounts-connection).
2. [Configure comments for Semgrep Secrets](#configure-comments-for-semgrep-secrets). | + +Comments from Supply Chain scans include the following information: + +**Risk**
+A description of the vulnerability, including the types of attack it is vulnerable to. + +**Fix**
+Indicates what versions to upgrade to, if any, that resolves or eliminates the vulnerability. + +**Reference**
+A link to additional information about the vulnerability from its source, such as the GitHub Advisory Database and the National Vulnerability Database (NVD), if available. + + +## Steps to set up PR comments + +### Prerequisites + +Semgrep currently supports repositories hosted by Azure DevOps Cloud. + +In addition to finishing the previous steps in your deployment journey, it is recommended to have completed a **full scan** on your **default branch** for the repository in which you want to receive comments. + +### Confirm your Semgrep account's connection + +PR comments are enabled by default for users who have connected their Azure DevOps project to Semgrep AppSec Platform. Confirm that you have the correct connection and access: + +
1. [Confirm your Semgrep account's connection and access to your source code manager](#confirm-your-semgrep-accounts-connection).
2. [Configure comments for Semgrep Code](#configure-comments-for-semgrep-code). | +| Software composition analysis (SCA) | Semgrep Supply Chain (SSC) | A comment appears based on the conditions you explicitly set in a [Supply Chain policy](/semgrep-supply-chain/policies) or when Semgrep detects a [license violation](/semgrep-supply-chain/license-compliance). | To receive Supply Chain comments, complete the steps in [Confirm account connection and access](#confirm-your-semgrep-accounts-connection) and [set up a policy](/semgrep-supply-chain/policies).
To receive license violation comments, [enable dependency search](/semgrep-supply-chain/dependency-search#enable-and-use-dependency-search). | +| Secrets | Semgrep Secrets | A comment appears when a finding is generated by a rule in **Comment or Block mode**. A comment also appears for invalid findings and validation errors if these conditions are set to **Comment or Block mode**. | Complete the steps in the following sections:
1. [Confirm your Semgrep account's connection and access to your source code manager](#confirm-your-semgrep-accounts-connection).
2. [Configure comments for Semgrep Secrets](#configure-comments-for-semgrep-secrets). | + +Comments from Supply Chain scans include the following information: + +**Risk**
+A description of the vulnerability, including the types of attack it is vulnerable to. + +**Fix**
+Indicates what versions to upgrade to, if any, that resolves or eliminates the vulnerability. + +**Reference**
+A link to additional information about the vulnerability from its source, such as the [GitHub Advisory Database](https://github.com/advisories) and the [National Vulnerability Database (NVD)](https://nvd.nist.gov/vuln), if available. + + +## Supported Bitbucket plans + +- Any of the following Bitbucket plans are supported: + - Cloud Free + - Standard + - Premium + +There are two ways in which you can integrate Semgrep comments into Bitbucket depending on the Bitbucket plan you use: + +- **Workspace access token**: If you use the Bitbucket Cloud Premium plan, you can create a workspace access token. This option saves time because you can create one access token for all repositories in the workspace. With one workspace access token, you can bulk-onboard more repositories at once from a whole workspace. However, you can also use the option of a repository access token to onboard repositories one by one. +- **Repository access token**: If you do **not** have the Bitbucket Cloud Premium plan, create a separate repository access token for each repository where you want to use Semgrep. This configuration option is also useful if you have the Bitbucket Cloud Premium plan, but prefer to onboard repositories one by one instead of bulk onboarding. + +
1. [Confirm your Semgrep account's connection and access to your source code manager](#confirm-your-semgrep-accounts-connection).
2. [Configure comments for Semgrep Code](#configure-comments-for-semgrep-code). | +| Software composition analysis (SCA) | Semgrep Supply Chain (SSC) | A comment appears based on the conditions you explicitly set in a [Supply Chain policy](/semgrep-supply-chain/policies) or when Semgrep detects a [license violation](/semgrep-supply-chain/license-compliance). | To receive Supply Chain comments, complete the steps in [Confirm account connection and access](#confirm-your-semgrep-accounts-connection) and [set up a policy](/semgrep-supply-chain/policies).
To receive license violation comments, [enable dependency search](/semgrep-supply-chain/dependency-search#enable-and-use-dependency-search). | +| Secrets | Semgrep Secrets | A comment appears when a finding is generated by a rule in **Comment or Block mode**. A comment also appears for invalid findings and validation errors if these conditions are set to **Comment or Block mode**. | Complete the steps in the following sections:
1. [Confirm your Semgrep account's connection and access to your source code manager](#confirm-your-semgrep-accounts-connection).
2. [Configure comments for Semgrep Secrets](#configure-comments-for-semgrep-secrets). | + +Comments from Supply Chain scans include the following information: + +**Risk**
+A description of the vulnerability, including the types of attack it is vulnerable to. + +**Fix**
+Indicates what versions to upgrade to, if any, that resolves or eliminates the vulnerability. + +**Reference**
+A link to additional information about the vulnerability from its source, such as the [GitHub Advisory Database](https://github.com/advisories) and the [National Vulnerability Database (NVD)](https://nvd.nist.gov/vuln), if available. + +## Enable PR comments in Bitbucket + +### Prerequisites + +- You must have a Bitbucket Data Center HTTP access token. Ensure that the [HTTP access token that you create](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html) has been granted **Project write** permissions. You'll provide this token to your CI provider during the setup process. +- Semgrep has been tested with Bitbucket Data Center v8.19. If you are using a different version of BBDC and there are issues, please [reach out to support](/support). + +### Confirm your Semgrep account's connection + +Confirm that you have the correct connection and access: + +
+ Findings generated by a rule with the severity value set to
ERROR. These include security backdoors and highly vulnerable code. If you filter for another time period than All time the displayed number badge compares the number of high-severity findings within the given time period against the previous time period.
+
+**Open findings**+ The number of open findings over the given time period. The badge number indicates whether this number has gone up or down compared to the previous timeframe. If you filter for another time period than All time the displayed number badge compares the most recent number of open findings against the previous timeframe. + +**Comment fix rate**
+ The percentage of findings that were fixed when findings surfaced to developers through PR or MR comments in previous scans. If you filter for another time period than All time the displayed number badge compares PR and MR fix rate in the given time period against the previous time period. + +## Filtering findings by time + +The Dashboard displays data from scans for the **All time** by default. This time range can be set to a narrower value. By broadening the time range, security teams are able to see total numbers and statistics across an entire time period. Narrow time ranges can give insights into the most recent vulnerabilities creeping into the project. + +To change the time range of scan data over time: + +
+ Contains three items: Reachable, Unreachable, and Undetermined vulnerabilities. + +**Most vulnerabilities**
+ The number of dependency vulnerabilities over the given time period next to the calendar icon. + +**New advisories**
+ Announcements of new vulnerabilities. + + +
- How is my security posture doing over time?
- Is my backlog decreasing or increasing?
- Is the team addressing findings faster than new findings are coming in? | +| [Secure guardrails](/secure-guardrails/secure-guardrails-in-semgrep) | Displays data relevant to the deployment and adoption of secure guardrails. It helps address the following:
- How many vulnerabilities did Semgrep prevent from entering production over time?
- Am I effectively introducing guardrails to my developers?
- Of the issues shown to developers, are they being fixed, or are they being ignored? | +| Most findings by project | Lists projects arranged by most open findings to least, grouped by **product** or **severity**. Helps answer the following:
- Which of my projects have the most findings in a particular product area?
- Which of my projects have the most findings for a particular severity? | +| Median open age | A graph showing the middle age of all Open findings, grouped by product or severity. Half of the open findings are older than this age, and half are newer. Helps you answer:
- What is the amount of time a finding remains open, by product or by severity? | + +
Hover over the chart to see a breakdown of findings by product for the selected time period. | +| Backlog activity | Displays the number of new, net new, fixed, and ignored, including provisionally ignored, findings. A greater **Fixed** value is better.
Hover over the chart to see a breakdown of findings by triage state for that selected time period. | + + +## Secure guardrails + +This provides an overview of how secure guardrails in **PR or MR comments** are used in your organization, including how often Semgrep shows findings to developers, how the developers handle the findings, and how often Semgrep flags a finding as provisionally ignored. + +Other guardrail interfaces, such as the IDE or `pre-commit`, are not counted in this section. + +### Key metrics + +| Key metrics | Description | +| :--- | :--- | +| Findings shown to devs | Number of findings shown to developers in PR or MR comments (the numerator) against the total findings count (denominator). An upward or stable trend is better. | +| Findings fixed in development | Number of findings that were fixed before they could be detected in a default branch or production backlog (numerator) against the total findings count in the specified time period (denominator). An upward or stable trend is better.
Hover over the chart to see a breakdown of findings by triage state for that selected time period. | + +### Charts + +| Chart | Description | +| :--- | :--- | +| Secure guardrails adoption | Percent of new findings shown to developers over the specified time period. An upward or stable trend is better. | +| Guardrails activity | This chart displays a breakdown of the status of findings shown to developers; whether they were ignored, provisionally ignored, fixed, or remained open. A greater **Fixed** value is better.
Hover over the chart to see a breakdown of findings by triage state for that selected time period. | + +## Most findings by project + +A table listing projects from most open findings to least, grouped by product or severity. Lower values are better. + +
+Alert boxes now display critical triage information. + +**B - Rule details and finding details**
+These details are now presented at the right sidebar and provide additional metadata. + +**C - Your code and dataflow panels**
+The relevant lines of code of the match and the dataflow graph are now presented side-by-side. The rule pattern tab has been removed and Rule metadata is presented as part of the rule or finding details rather than as a YAML snippet. + +**D - Multimodal generated fix**
+Generate and view a Semgrep Multimodal fix. You can also customize the fix provided by the Multimodal. + +**E - Activity**
+All triage activity pertaining to the finding. + + diff --git a/mintlify-docs/semgrep-appsec-platform/github-pr-comments.mdx b/mintlify-docs/semgrep-appsec-platform/github-pr-comments.mdx new file mode 100644 index 0000000000..7647951e6a --- /dev/null +++ b/mintlify-docs/semgrep-appsec-platform/github-pr-comments.mdx @@ -0,0 +1,345 @@ +--- +title: "Set up GitHub pull request comments" +sidebarTitle: "GitHub PR comments" +--- + +
+This appears if a finding fails the CI job. Organizations typically block PRs or MRs with failed jobs. + +**B - Finding description**
+ A human-written description always appears in a PR or MR comment, describing why your code is flagged. **References** may also be included to help you learn more about the finding. + +**C - Dataflow graph**
+Some Code findings have a dataflow graph, which indicates that the finding was detected through %%taint analysis|taint_analysis%%. The dataflow graph provides the lines of code identifying sources, sinks, and traces of unsanitized data flowing through your program. You can click the links on the boxes to take you to the lines of code. + +**D - Resolution or remediation section**
+Various options are provided to help your resolve the finding. Depending on the type of finding, resolution options may vary. + +**E - Ignore instructions**
+Click to view instructions about how to ignore the finding by replying to the comment. + +Depending on the features you have enabled, your PR comment can also appear more straightforward: + + + + + +## Conditions for PR comment creation + +PR comments appear for the following types of scans under these conditions: + +| Type of scan | Product name | Trigger condition | How to set up | +| :--- | :--- | :--- | :--- | +| Static application security testing (SAST) | Semgrep Code | A comment appears when a finding is generated by a rule in **Comment or Block mode**. This means you can fully customize what comments your developers receive. | Complete the steps in the following sections:
1. [Confirm your Semgrep account's connection and access to your source code manager](#confirm-your-semgrep-accounts-connection).
2. [Configure comments for Semgrep Code](#configure-comments-for-semgrep-code). | +| Software composition analysis (SCA) | Semgrep Supply Chain (SSC) | A comment appears based on the conditions you explicitly set in a [Supply Chain policy](/semgrep-supply-chain/policies) or when Semgrep detects a [license violation](/semgrep-supply-chain/license-compliance). | To receive Supply Chain comments, complete the steps in [Confirm account connection and access](#confirm-your-semgrep-accounts-connection) and [set up a policy](/semgrep-supply-chain/policies).
To receive license violation comments, [enable dependency search](/semgrep-supply-chain/dependency-search#enable-and-use-dependency-search). | +| Secrets | Semgrep Secrets | A comment appears when a finding is generated by a rule in **Comment or Block mode**. A comment also appears for invalid findings and validation errors if these conditions are set to **Comment or Block mode**. | Complete the steps in the following sections:
1.[Confirm your Semgrep account's connection and access to your source code manager](#confirm-your-semgrep-accounts-connection).
2. [Configure comments for Semgrep Secrets](#configure-comments-for-semgrep-secrets). | + +Comments from Supply Chain scans include the following information: + +**Risk**
+A description of the vulnerability, including the types of attack it is vulnerable to. + +**Fix**
+Indicates what versions to upgrade to, if any, that resolves or eliminates the vulnerability. + +**Reference**
+A link to additional information about the vulnerability from its source, such as the [GitHub Advisory Database](https://github.com/advisories) and the [National Vulnerability Database (NVD)](https://nvd.nist.gov/vuln), if available. + + +## Steps to set up PR comments + +### Prerequisites + +In addition to finishing the previous steps in your deployment journey, it is recommended to have completed a **full scan** on your **default branch** for the repository in which you want to receive comments. + +### Confirm your Semgrep account's connection + +Confirm that you have the correct connection and access: + +
1. [Confirm your Semgrep account's connection and access to your source code manager](#confirm-your-semgrep-accounts-connection).
2. [Configure comments for Semgrep Code](#configure-comments-for-semgrep-code). | +| Software composition analysis (SCA) | Semgrep Supply Chain (SSC) | A comment appears based on the conditions you explicitly set in a [Supply Chain policy](/semgrep-supply-chain/policies) or when Semgrep detects a [license violation](/semgrep-supply-chain/license-compliance). | To receive Supply Chain comments, complete the steps in [Confirm account connection and access](#confirm-your-semgrep-accounts-connection) and [set up a policy](/semgrep-supply-chain/policies).
To receive license violation comments, [enable dependency search](/semgrep-supply-chain/dependency-search#enable-and-use-dependency-search). | +| Secrets | Semgrep Secrets | A comment appears when a finding is generated by a rule in **Comment or Block mode**. A comment also appears for invalid findings and validation errors if these conditions are set to **Comment or Block mode**. | Complete the steps in the following sections:
1. [Confirm your Semgrep account's connection and access to your source code manager](#confirm-your-semgrep-accounts-connection).
2. [Configure comments for Semgrep Secrets](#configure-comments-for-semgrep-secrets). | + +Comments from Supply Chain scans include the following information: + +**Risk**
+A description of the vulnerability, including the types of attack it is vulnerable to. + +**Fix**
+Indicates what versions to upgrade to, if any, that resolves or eliminates the vulnerability. + +**Reference**
+A link to additional information about the vulnerability from its source, such as the [GitHub Advisory Database](https://github.com/advisories) and the [National Vulnerability Database (NVD)](https://nvd.nist.gov/vuln), if available. + + +## Steps to set up MR comments + +### Confirm your Semgrep account's connection + +PR comments are enabled by default for users who have connected their GitLab group to Semgrep AppSec Platform. Confirm that you have the correct connection and access: + +
• Semgrep AppSec Platform
• For Semgrep Code and Supply Chain: User-defined notifications
Set rules to this mode to evaluate their true positive rate and other criteria you may have. By keeping rules in Monitor, developers do not receive potentially noisy findings in their PRs or MRs. | +| Comment | Rules in **Comment mode** display findings in:
• Developers' PRs or MRs
• Semgrep AppSec Platform
• **For Semgrep Code and Supply Chain:** User-defined notifications
Set rules that have met your performance criteria to this mode when you are ready to display findings to developers. | +| Block | Rules in **Block mode** cause the scan job to fail with an exit code of `1` if Semgrep Secrets detects a finding from these rules. You can use this result to enforce a block on the PR or MR. For example, GitHub users can enable branch protection and set the PR to fail if the Semgrep step fails.
These rules display findings in:
• Developers' PRs or MRs
• Semgrep AppSec Platform
• **For Semgrep Code and Supply Chain:** User-defined notifications
These are typically high-confidence, high-severity rules. | + +
`pullrequest:read` | `repository:write`
`pullrequest:write` | +| Bitbucket Data Center | `repository:read` | `repository:write` | +| GitHub.com and Github Enterprise | `contents:read` | `contents:write` | +| GitLab and Gitlab Self-Managed | `read_repository` | `write_repository` | + +## Grant code access to Semgrep with a private GitHub app + +If you already have a private Semgrep GitHub app set up and configured for your deployment that **doesn't** have code access enabled, follow these steps to update the app and grant code access to Semgrep. + +
+ i. For organization accounts, go to
https://github.com/organizations/ORGANIZATION_NAME/settings/apps/APP_SLUG/permissions.+ ii. For user accounts, go to
https://github.com/settings/apps/APP_SLUG/permissions
+https://dev.azure.com/ORGANIZATION_NAME/_usersSettings/tokens.
+https://bitbucket.org/WORKSPACE/workspace/settings/access-keys.
+BITBUCKET_BASE_URL/plugins/servlet/access-tokens/projects/PROJECT.
+https://gitlab.com/groups/GROUP/-/settings/access_tokens.
++
/semgrep_subscribe ACCOUNT_NAME/REPOSITORY_NAME
+ @Semgrep in conversations that the app is in. | Enables the Semgrep Slack app to respond when users mention it in the chat. |
+| **[channels:read](https://api.slack.com/scopes/channels:read)** | View basic information about public channels in a workspace. | Basic channel information such as channel_id is used to ensure that Semgrep findings (results) are sent to the appropriate channel. |
+| **[chat:write](https://api.slack.com/scopes/chat:write)** | Send messages as @Semgrep. | Enables the Semgrep Slack app to send findings to channels. |
+| **[chat:write.customize](https://api.slack.com/scopes/chat:write.customize)** | Send messages as @Semgrep with a customized username and avatar. | Helps users identify Semgrep Slack app messages through the use of an image and username. |
+| **[chat:write.public](https://api.slack.com/scopes/chat:write.public)** | Send messages to channels @Semgrep isn't a member of. | Enables users to invoke Semgrep Slack app features in any public channel using the slash command. |
+| **[commands](https://api.slack.com/scopes/commands)** | Add shortcuts or slash commands that people can use. | Enables the Semgrep Slack app to register custom slash commands such as /semgrep_subscribe used for notification subscription. |
+| **[emoji:read](https://api.slack.com/scopes/emoji:read)** | View custom emoji in a workspace. | Allows Semgrep to support a workspace's custom emojis. |
+| **[im:write](https://api.slack.com/scopes/im:write)** | Start direct messages with people. | Allows users to interact with the Semgrep Slack app and use the slash commands in direct messages. |
+| **[links:write](https://api.slack.com/scopes/links:write)** | Show previews of URLs in messages. | Enables Semgrep Slack app to include links in messages. |
+| **[users:read](https://api.slack.com/scopes/users:read)** | View profile details about people in a workspace. | Enables Semgrep Slack app to correctly address users in messages. |
+| **[users:write](https://api.slack.com/scopes/users:write)** | Set presence for Semgrep. | Used by the Semgrep Slack app to interact with the workspace and enables users to add the Semgrep Slack app to relevant channels. |
+| **[workflow.steps:execute](https://api.slack.com/scopes/workflow.steps:execute)** | Add steps that people can use in Workflow Builder. | Enables Semgrep to make use of modals and drop-down boxes when a user creates or updates their notifications. |
+| **[groups:read](https://api.slack.com/scopes/groups:read)** | View basic information about private channels that your Slack app has been added to. | Semgrep Slack app uses channels_id_changed to update its notifications configuration if the channel that receives findings is updated. This ensures that you are able to receive findings ever renaming a channel. |
+| **[team:read](https://api.slack.com/scopes/team:read)** | View the name, email domain, and icon for workspaces your slack app is connected to. | Semgrep Slack app uses team_name_changed to update its notifications configuration if the team name is updated. This ensures that you are able to receive findings notifications even after renaming your team. |
+| **[channels:read](https://api.slack.com/scopes/channels:read)** | View basic information about public channels in a workspace. | Enables Semgrep Slack app to monitor if channels that receive Semgrep findings have been deleted or archived. |
+
+#### Additional resources
+
+* https://api.slack.com/apps
+* https://api.slack.com/messaging/webhooks#enable_webhooks
diff --git a/mintlify-docs/semgrep-appsec-platform/sysdig.mdx b/mintlify-docs/semgrep-appsec-platform/sysdig.mdx
new file mode 100644
index 0000000000..5085b53903
--- /dev/null
+++ b/mintlify-docs/semgrep-appsec-platform/sysdig.mdx
@@ -0,0 +1,70 @@
+---
+title: "View runtime context from Sysdig"
+sidebarTitle: "Sysdig"
+description: "The Semgrep Sysdig integration can ingest runtime context from your Sysdig account into Semgrep AppSec Platform. This allows you to prioritize findings based on deployment status."
+---
+
+## Prerequisites
+
+Before proceeding, ensure that:
+
+- You have a license for **Semgrep Supply Chain**
+- You have the following tools and integrations set up in your Sysdig account:
+ - [+ i. Select the rules by clicking the checkboxes next to their names, then click **Change scanning behavior (n)**. If you're modifying only one rule, you can click the rule’s link in the **Projects scanning** column.
+ ii. The **Projects scanning** dialog appears. You can choose to use the rules with **All projects**, **Selected projects** by **Project name**, **Selected projects** by **Tags**, **All with exceptions**, or **None (disable)**.
+ iii. To use the rules with all of your projects, click **All projects**, then click **Save**.
+ iv. To use the rules with some of your projects, click **Selected projects**, then click the checkboxes next to the projects to which the rule applies. Click **Save** to proceed.
+ v. To exclude specific projects, click **All with exceptions**, then select the projects to which the rule doesn’t apply. Click **Save** to proceed.
+ vi. To prevent the rules from being used at all, click **None (Disable)**, then **Save** to proceed. +
+ i. Click **+ Create automation**.
+ ii. Provide a **Policy name**.
+ iii. Set the **Scope** of the policy by selecting all of the projects to which this policy applies.
+ iv. Define the **Conditions** that trigger the policy by clicking **+ Add condition** to expand a drop-down list of attributes that you can use. Select the attribute, then set the specific conditions. + - For example, you can select **Severity**, then complete the conditional statement provided to read **When Severity is any of Critical, High**. + - You can define as many conditions as necessary, and Semgrep treats them additively. + + v. Choose the **Actions** that occur if there are findings that trigger the policy by clicking **+ Add action**. You can choose multiple **Actions**, including: +
Scope: All projects | +| :--- | :--- | +| **Rule B** | Enabled.
Scope: All projects | +| **Rule C** | Enabled.
Scope: All projects | +| **Rule D** | Enabled.
Scope: All projects | + +### Remediation policy + +| | | | +| :--- | :--- | :--- | +| **Automation 1** | Name | Comment on PR or MR with findings | +| **Automation 1** | Scope | All projects | +| **Automation 1** | Conditions | Rule is one of:
- Rule B
- Rule C
- Rule D
+A `semgrep_scan` object contains information about the CI job and other scan parameters, such as ignored files. Semgrep sends a single `semgrep_scan` object **every time a scan is run**. This includes diff-aware scans, full scans, and scans that have no findings. + +`semgrep_finding` JSON object
+A `semgrep_finding` object is a single record of a new finding. Semgrep sends new `semgrep_finding` objects based on how you have configured your notifications in Policies. See [Set up webhooks](#set-up-webhooks) to learn more. + +## Set up webhooks + +Perform these steps in Semgrep AppSec Platform to set up webhooks: + +
+ ii. Authentication URL + You can find both values at a later date under [tenant info](https://app.wiz.io/tenant-info/general). + +
• Cross-file dataflow analysis
• 150+ Pro rules | Community supported
• Limited to single-function analysis
• Community rules | +| C# | **Generally available **
• Cross-file dataflow analysis
• Supports up to C# 13
• 170+ Pro rules | Community supported
• Limited to single-function analysis
• Community rules
• Supports up to C# 7.0 | +| Go | **Generally available**
• Cross-file dataflow analysis
• 80+ Pro rules | Community supported
• Limited to single-function analysis
• Community rules | +| Java | **Generally available**
• Cross-file dataflow analysis
• Framework-specific control flow analysis
• 190+ Pro rules | Community supported
• Limited to single-function analysis
• Community rules | +| JavaScript | **Generally available**
• Cross-file dataflow analysis
• Framework-specific control flow analysis
• 250+ Pro rules | Community supported
• Limited to single-function analysis
• Community rules | +| Kotlin | **Generally available **
• Cross-file dataflow analysis
• 60+ Pro rules | Community supported
• Limited to single-function analysis
• Community rules | +| [Python](/languages/python) | **Generally available**
• Cross-file dataflow analysis
• Framework-specific control flow analysis
• 710+ Pro rules
• See [Python-specific support details](/languages/python) | Community supported
• Limited to single-function analysis
• Community rules | +| Typescript | **Generally available **
• Cross-file dataflow analysis
• Framework-specific control flow analysis
• 230+ Pro rules | Community supported
• Limited to single-function analysis
• Community rules | +| Ruby | **Generally available **
• Cross-function dataflow analysis
• 40+ Pro rules | Community supported
• Limited to single-function analysis
• Community rules | +| Rust | **Generally available **
• Cross-function dataflow analysis
• 40+ Pro rules | Community supported
• Limited to single-function analysis
• Community rules | +| JSX | **Generally available **
• Cross-function dataflow analysis
• 70+ Pro rules | Community supported
• Limited to single-function analysis
• Community rules | +| PHP | **Generally available **
• Cross-function dataflow analysis
• 50+ Pro rules | Community supported
• Limited to single-function analysis
• Community rules | +| Scala | **Generally available **
• Cross-function dataflow analysis
• Community rules | Community supported
• Limited to single-function analysis
• Community rules | +| Swift | **Generally available **
• Cross-function dataflow analysis
• 60+ Pro rules | Community supported
• Limited to single-function analysis
• Community rules | +| Terraform | **Generally available**
• Cross-function dataflow analysis
• Community rules | Community supported
• Limited to single-function analysis
• Community rules | +| Generic | **Generally available ** | Community supported | +| JSON | **Generally available ** | Community supported | +| APEX | **Beta** | Not available | +| Elixir | **Beta** | Not available | + +
semgrep ci || true | CI **passes** on blocking findings and internal errors. |
+
+To change Semgrep's behavior, modify your pipeline or job file, specifically the `semgrep ci` command, to the CI option that best fits your needs. For example, GitHub users should edit the `semgrep.yml` workflow file and include the following under the `run` key:
+
+```yaml
+run:
+ semgrep ci --suppress-errors
+```
+
+GitLab users would include the following under the `script` key:
+
+```yaml
+script:
+ semgrep ci --suppress-errors
+```
+
+If you use any other CI provider, refer to its documentation for information on where to provide this information. Additionally, see the sample configurations in the following section.
+
+## Sample configurations for blocking findings and errors
+
+The following is a sample `.semgrep.yml` file you can use with GitHub Actions. Semgrep's default behavior regarding blocking findings and errors applies here:
+
+- Semgrep returns exit code `1` if there are blocking findings
+- Semgrep returns exit code `0` if there are *no* blocking findings, even if there are internal errors. Semgrep does, however, send an anonymous report to the crash-reporting server.
+
+This means that, by default, Semgrep doesn't report statuses other than `0` or `1`.
+
+```yaml expandable
+# Name of this GitHub Actions workflow.
+name: Semgrep
+
+on:
+ # Scan changed files in PRs (diff-aware scanning):
+ pull_request: {}
+ # Scan on-demand through GitHub Actions interface:
+ workflow_dispatch: {}
+ # Scan mainline branches if there are changes to .github/workflows/semgrep.yml:
+ push:
+ branches:
+ - main
+ - master
+ paths:
+ - .github/workflows/semgrep.yml
+ # Schedule the CI job (this method uses cron syntax):
+ schedule:
+ - cron: '20 17 * * *' # Sets Semgrep to scan every day at 17:20 UTC.
+ # It is recommended to change the schedule to a random time.
+
+permissions:
+ contents: read
+
+jobs:
+ semgrep:
+ # User definable name of this GitHub Actions job.
+ name: semgrep/ci
+ # If you are self-hosting, change the following `runs-on` value:
+ runs-on: ubuntu-latest
+
+ container:
+ # A Docker image with Semgrep installed. Do not change this.
+ image: semgrep/semgrep
+
+ # Skip any PR created by dependabot to avoid permission issues:
+ if: (github.actor != 'dependabot[bot]')
+
+ steps:
+ # Fetch project source with GitHub Actions Checkout. Use either v3 or v4.
+ - uses: actions/checkout@v6
+ # Run the "semgrep ci" command on the command line of the docker image.
+ - run: semgrep ci
+ env:
+ # Connect to Semgrep AppSec Platform through your SEMGREP_APP_TOKEN.
+ # Generate a token from Semgrep AppSec Platform > Settings
+ # and add it to your GitHub secrets.
+ SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
+```
+
+Optionally, you can explicitly indicate that Semgrep is using the default settings by including the `--suppress-errors` flag. The modified portion of the configuration file is as follows:
+
+```yaml
+steps:
+ - uses: actions/checkout@v6
+ - name: Scan and suppress internal errors
+ run: semgrep ci --suppress-errors
+```
+
+The following code snippets display the position of the default flag in the configuration files of various CI providers:
+
+semgrep ci || true | CI **passes** on blocking findings and internal errors. |
+
+To change Semgrep's behavior, modify your pipeline or job file, specifically the `semgrep ci` command, to the CI option that best fits your needs. For example, GitHub users should edit the `semgrep.yml` workflow file and include the following under the `run` key:
+
+```yaml
+run:
+ semgrep ci --suppress-errors
+```
+
+GitLab users would include the following under the `script` key:
+
+```yaml
+script:
+ semgrep ci --suppress-errors
+```
+
+If you use any other CI provider, refer to its documentation for information on where to provide this information. Additionally, see the sample configurations in the following section.
+
+## Sample configurations for blocking findings and errors
+
+The following is a sample `.semgrep.yml` file you can use with GitHub Actions. Semgrep's default behavior regarding blocking findings and errors applies here:
+
+- Semgrep returns exit code `1` if there are blocking findings
+- Semgrep returns exit code `0` if there are *no* blocking findings, even if there are internal errors. Semgrep does, however, send an anonymous report to the crash-reporting server.
+
+This means that, by default, Semgrep doesn't report statuses other than `0` or `1`.
+
+```yaml expandable
+# Name of this GitHub Actions workflow.
+name: Semgrep
+
+on:
+ # Scan changed files in PRs (diff-aware scanning):
+ pull_request: {}
+ # Scan on-demand through GitHub Actions interface:
+ workflow_dispatch: {}
+ # Scan mainline branches if there are changes to .github/workflows/semgrep.yml:
+ push:
+ branches:
+ - main
+ - master
+ paths:
+ - .github/workflows/semgrep.yml
+ # Schedule the CI job (this method uses cron syntax):
+ schedule:
+ - cron: '20 17 * * *' # Sets Semgrep to scan every day at 17:20 UTC.
+ # It is recommended to change the schedule to a random time.
+
+permissions:
+ contents: read
+
+jobs:
+ semgrep:
+ # User definable name of this GitHub Actions job.
+ name: semgrep/ci
+ # If you are self-hosting, change the following `runs-on` value:
+ runs-on: ubuntu-latest
+
+ container:
+ # A Docker image with Semgrep installed. Do not change this.
+ image: semgrep/semgrep
+
+ # Skip any PR created by dependabot to avoid permission issues:
+ if: (github.actor != 'dependabot[bot]')
+
+ steps:
+ # Fetch project source with GitHub Actions Checkout. Use either v3 or v4.
+ - uses: actions/checkout@v6
+ # Run the "semgrep ci" command on the command line of the docker image.
+ - run: semgrep ci
+ env:
+ # Connect to Semgrep AppSec Platform through your SEMGREP_APP_TOKEN.
+ # Generate a token from Semgrep AppSec Platform > Settings
+ # and add it to your GitHub secrets.
+ SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
+```
+
+Optionally, you can explicitly indicate that Semgrep is using the default settings by including the `--suppress-errors` flag. The modified portion of the configuration file is as follows:
+
+```yaml
+steps:
+ - uses: actions/checkout@v6
+ - name: Scan and suppress internal errors
+ run: semgrep ci --suppress-errors
+```
+
+The following code snippets display the position of the default flag in the configuration files of various CI providers:
+
++View and open rules owned by your organization or available through the [Semgrep Registry](https://semgrep.dev/r). + +**Rule editor**
+Enter your rule's YAML in this pane. This pane supports both structure and advanced modes. This pane also contains metadata editing functionality in Structure mode, and match review functionality in Advanced mode. + +**Sample code**
+Enter test code in this pane and click **Run** to verify that the rule performs as intended. A matches panel appears after Semgrep runs to display matches and tests. + +**Top menu**
+Save, share, and add your rule to one of your policies. + +### Group Registry rules + +By default, Semgrep Registry rules are grouped by **directory**. Most of these directories correspond to languages. The Library can also be grouped by **rulesets**, which are rules sorted by category, such as security, best practices, and frameworks. + +To group by ruleset, right-click on the empty space on the registry's name entry and select **Group by ruleset**. + +## Create a rule + +To create a rule, click **Create rule** on the splash page or the **(+) sign** next to the Library label. + +Semgrep Editor offers two rule-writing modes: + +**Structure mode (beta)**
+Structure mode is a hybrid interface that offers guidance for rule writing while supporting additional features the way advanced mode does. +**Advanced mode**
+Advanced mode provides the minimum required YAML keys for a Semgrep rule. To complete the rule, you must fill in additional keys, such as pattern operators or metadata. + +### Write a rule using structure mode (beta) + +Structure mode is a UI-based ruled writing editor that guides you through the process of writing a rule. + +Structure mode features include: + +- **Match badges**: Match badges are visual indicators paired with pattern operators. The match badge shows the number of matches associated with each pattern operator. +- **Automatic indentation**: When adding a new pattern to a nested operator such as `patterns` or `pattern-either`, the editor automatically indents sub-patterns correctly. +- **Differentiation between patterns and pattern constraints**: A pattern is one of six different operators that describes zero or more locations in a rule. These include `pattern`, `any`, `all`, `inside`, `regex`, and `not`. You can combine these in prescribed ways, such as `any` and `all`, using range union and intersection, but they still define ranges. Pattern constraints describe Boolean constrains that must be met for a match to occur. If the constraint doesn't hold, then the ranges determined by the pattern operators aren't applicable. +- **Interoperability with advanced mode**: You can write a rule using structure mode and view or export it in YAML, or you can paste in the YAML for a rule and edit it with structure mode. +- **Drag and drop**" You can move around the elements of a rule using drag and drop. +- **Pattern disabling**: You can toggle individual patterns on or off for actions like testing. + +To write a **search** rule using structure mode: + +
- Low
- Medium
- High
- Critical
Only Semgrep Supply Chain and Code findings provide this field. | +| Category | The finding's category, such as **best practices**, **security**, or **correctness**. | +| Is pro rule | Boolean value that returns `TRUE` if the rule that generated the finding is a pro rule. | +| Assistant triage result | Provides Semgrep Multimodal's assessment. Possible values are `True positive` or `False positive`. These values appear only if Multimodal is enabled. | +| Assistant triage reason | A short AI-generated reason why Multimodal thinks the finding is a true or false positive. These values appear only if Multimodal is enabled. | + +The following fields are exclusive to **Supply Chain** scans: + +| Field | Description | +| :--- | :--- | +| Dependency | The name of the dependency where the findings was found. | +| Reachability | The reachability status of the finding, such as **Reachable**, **No Reachability Analysis**, or **Unreachable**. | +| Transitivity | States whether the finding originates from a direct or transitive dependency. | +| CVE | The CVE number that the finding is assigned to. | +| EPSS | The EPSS score, which estimates the likelihood that a software vulnerability can be exploited in the wild. | + +The following fields are exclusive to **Secrets** scans: + +| Field | Description | +| :--- | :--- | +| Secret type | Possible values include **AI-detected**, **Generic secret**, **Connection URI**, and so on. | +| Validation | States whether or not the secret was validated. | +| Project visibility | States whether the project (repository) is public or private. This feature supports GitHub-hosted repositories only. It returns an **Unknown** value for non-GitHub SCMs. | +
+ The top header consists of: + - **Policies view drop-down**, which lets you choose between: + - Grouping rules by vulnerability class + - No grouping + -
+Displays filters to quickly select and perform operations on rules in bulk. See [Policies filter reference](#policies-filter-reference) for more information. + +**Rule pane**
+ The rule pane displays the rules that Semgrep scans use to detect findings and allows you to edit their assigned rule modes. You can make these edits either one by one or through bulk editing of many rules. You can also use the **Search for rule names or ids** box. See [Policies filter reference](#policies-filter-reference) for more information. + + +### Policies page filters + +This section defines the Policies page filters: + +| Filter | Description | Examples or possible values | +| :--- | :--- | :--- | +| Modes | Filter by the workflow action Semgrep performs when a rule detects a finding. An additional filter, **Disabled**, is provided for rules that you have turned off and are no longer included for scanning. | See [Rule modes](#block-a-pr-or-mr-through-rule-modes) documentation. | +| Category | Filter by the type of security issue or vulnerability that the rule detects. |
- Dangerous method or function
- SQL injection
- Active debug code
- Critical
- High
- Medium
- Low
- High
- Medium
- Low
- **Pro:** Authored by Semgrep with cross-file (interfile) and cross-function (interprocedural) analysis capabilities, providing you with enhanced scan accuracy. For more information, see
Pro rules. - **Community:** Authored by Semgrep, Inc or external contributors such as Trail of Bits.
- **Custom:** Rules created within your Semgrep organization. For more information, see
Private rules.
- Python
- JavaScipt
- Ruby
- 10
- 100
- 500
- Security
- Code injection
- PHP
- High
- Medium
- Low
- High
- Medium
- Low
- **Pro:** Authored by Semgrep with cross-file (interfile) and cross-function (interprocedural) analysis capabilities, providing you with enhanced scan accuracy. For more information, see
Pro rules. - **Community:** Authored by Semgrep, Inc or external contributors such as Trail of Bits.
- **Custom:** Rules created within your Semgrep organization. For more information, see
Private rules.
- Semgrep AppSec Platform
- **For Semgrep Code and Supply Chain**: User-defined notifications
- Developers' PRs or MRs
- Semgrep AppSec Platform
- **For Semgrep Code and Supply Chain**: User-defined notifications
These rules display findings in:
- Developers' PRs or MRs
- Semgrep AppSec Platform
- **For Semgrep Code and Supply Chain**: User-defined notifications
+Scans the repository in its entirety. It is recommended to perform full scans on mainline branches, such as `master` or `main`. Full scans are typically performed on a scheduled basis or on merge to a default branch. + +**Diff-aware scan**
+Diff-aware scans are performed on non-mainline branches, such as in pull requests and merge requests. Diff-aware scans traverse the repository's files based on the commit where the branch diverged from the mainline branch. + +## How Semgrep distinguishes between new and duplicate findings + +Semgrep generates a finding whenever it scans a repository and one of its rules matches a piece of code. Since Semgrep usually scans a repository multiple times, it needs a way to track the same finding in a file over time. Semgrep does this using two types of fingerprints: `match_based_id` and `syntactic_id`. + +
+ **Then** the finding in the current branch is triaged to that same state. + - **Diff-aware scan**: findings introduced in a diff-aware scan are **not** automatically triaged at scan time, even if there are other instances of that finding on branches that have been triaged. + +## Triage and remediation + +The following sections show you how to manage your findings by: + +* Fixing the underlying code +* Disabling a rule or a ruleset +* Ignoring a finding +* Reopening a finding + +Note that some actions, such as ignoring and reopening findings, require different steps based on whether you have chosen **Group by Rule** or **No Grouping** when viewing your results on the **Findings** page. + +## Review provisionally ignored findings + +If you have Semgrep Multimodal enabled, review the findings that have been **provisionally ignored**. These are findings that Semgrep Multimodal has flagged as false positives. For each finding, you can change the status to **Ignored** if you agree with Multimodal's assement. Otherwise, you can change the status to **To fix** if you disagree. + +Findings with a status of **provisionally ignored** block pull requests and merge requests if the matching rule is included in a blocking policy. + +### Ignore findings + +To handle **false positives** without changing the rule or your code, set the finding's triage status to **ignore**. + +
+ i. Click **Settings**. This takes you to the **General > Global** settings tab.
+ ii. Enable the toggle under **Triage via code review comments**.
+ - *For SCMs other than GitHub:* + - Granted Semgrep permission to interact with pull requests and create webhooks for your SCM + - Enabled the **Incoming webhooks** option on the SCM connection + +### Grant permission to interact with pull requests and create webhooks for your SCM + +See the following documents for instructions on granting the correct permissions to enable pull request interaction and webhook management: + +
/fp <COMMENT> | Triage a finding as **Ignored** with the triage reason **false positive**. Provide a <COMMENT> with information about the triage decision. |
+| /ar <COMMENT> | Triage a finding as **Ignored** with the triage reason **acceptable risk**. Provide a <COMMENT> with information about the triage decision. |
+| /other <COMMENT> | Triage a finding as **Ignored** without specifying the reason; the triage reason value is set to **No triage reason**. Provide a <COMMENT> with information about the triage decision. |
+| /open <REASON> | Reopen a finding that has been triaged as **Ignored**. Optionally, provide a <COMMENT> with information about the decision to reopen the finding. |
+
+/semgrep ignore <REASON> - triage a finding as **Ignored**.
+- /semgrep open <REASON> - reopen a finding that has been triaged as **Ignored**.
+- Low
- Medium
- High
- Critical
- Scans from local developer machines.
- Scans from any non-GitHub source code manager, such as GitLab.
Only Semgrep Supply Chain and Code findings provide this field. | +| Category | The finding's category, such as **best practices**, **security**, or **correctness**. | +| Is pro rule | Boolean value that returns `TRUE` if the rule that generated the finding is a pro rule. | +| Assistant triage result | Provides Semgrep Multimodal's assessment. Possible values are `True positive` or `False positive`. These values appear only if Multimodal is enabled. | +| Assistant triage reason | A short AI-generated reason why Multimodal thinks the finding is a true or false positive. These values appear only if Multimodal is enabled. | + +The following fields are exclusive to **Supply Chain** scans: + +| Field | Description | +| :--- | :--- | +| Dependency | The name of the dependency where the findings was found. | +| Reachability | The reachability status of the finding, such as **Reachable**, **No Reachability Analysis**, or **Unreachable**. | +| Transitivity | States whether the finding originates from a direct or transitive dependency. | +| CVE | The CVE number that the finding is assigned to. | +| EPSS | The EPSS score, which estimates the likelihood that a software vulnerability can be exploited in the wild. | + +The following fields are exclusive to **Secrets** scans: + +| Field | Description | +| :--- | :--- | +| Secret type | Possible values include **AI-detected**, **Generic secret**, **Connection URI**, and so on. | +| Validation | States whether or not the secret was validated. | +| Project visibility | States whether the project (repository) is public or private. This feature supports GitHub-hosted repositories only. It returns an **Unknown** value for non-GitHub SCMs. | + + +
- **Low**: low privilege; for example, write-only access like a webhook
- **Medium**: may have read and write access depending on what scope the account has
- **High** and **Critical**: has access to critical resources or full account access
- **Pro:** Authored by Semgrep.
- **Custom:** Rules created within your Semgrep organization.
- Semgrep AppSec Platform
- For Semgrep Code and Supply Chain: User-defined notifications
- Developers' PRs or MRs
- Semgrep AppSec Platform
- For Semgrep Code and Supply Chain: User-defined notifications
These rules display findings in:
- Developers' PRs or MRs
- Semgrep AppSec Platform
- For Semgrep Code and Supply Chain: User-defined notifications
- Critical
- High
- Medium
- Low
- Confirmed valid
- Confirmed invalid
- Validation error
- No validator
- Public
- Private
- Unknown
2. Under **Branches**, select a branch from the drop-down menu. | +| View findings of a specific type of secret, such as **personal token** or **password**. | Under **Type**, select a type of secret. +| View findings of a specific severity | Under **Severity**, select a value. | + +You can triage findings in bulk by performing the following steps: + +
Only Semgrep Supply Chain and Code findings provide this field. | +| Category | The finding's category, such as **best practices**, **security**, or **correctness**. | +| Is pro rule | Boolean value that returns `TRUE` if the rule that generated the finding is a pro rule. | +| Assistant triage result | Provides Semgrep Multimodal's assessment. Possible values are `True positive` or `False positive`. These values appear only if Multimodal is enabled. | +| Assistant triage reason | A short AI-generated reason why Multimodal thinks the finding is a true or false positive. These values appear only if Multimodal is enabled. | + +The following fields are exclusive to **Supply Chain** scans: + +| Field | Description | +| :--- | :--- | +| Dependency | The name of the dependency where the findings was found. | +| Reachability | The reachability status of the finding, such as **Reachable**, **No Reachability Analysis**, or **Unreachable**. | +| Transitivity | States whether the finding originates from a direct or transitive dependency. | +| CVE | The CVE number that the finding is assigned to. | +| EPSS | The EPSS score, which estimates the likelihood that a software vulnerability can be exploited in the wild. | + +The following fields are exclusive to **Secrets** scans: + +| Field | Description | +| :--- | :--- | +| Secret type | Possible values include **AI-detected**, **Generic secret**, **Connection URI**, and so on. | +| Validation | States whether or not the secret was validated. | +| Project visibility | States whether the project (repository) is public or private. This feature supports GitHub-hosted repositories only. It returns an **Unknown** value for non-GitHub SCMs. | +
| Event | +Scope of scan | +Dependency rule set | +
| Pull request or merge request | +Diff-aware scan | +All dependency rules | +
| Push or scheduled event, such as a cron job | +Full scan | +All dependency rules | +
- Always reachable
- Reachable
- Conditionally reachable
- Unreachable
- No reachability analysis
- Critical
- High
- Medium
- Low
- Upgrade available
- Upgrade unavailable
- Direct
- Transitive
- High
- Medium
- Low
- None
| Language | +Reachability (see CVE coverage) |
+Scan without lockfiles (beta) | +License detection | +Malicious dependency detection |
+
|---|---|---|---|---|
| C# | +✅ | +✅ CI and CLI only |
+✅ | +✅ | +
| Go | +✅ | +-- | +✅ | +✅ | +
| Java | +✅ | +✅ | +✅ | +-- | +
| JavaScript or TypeScript | +✅ | +-- | +✅ | +✅ | +
| Kotlin | +✅ | +✅ | +✅ | +-- | +
| Python | +✅ | +✅setup.py in CLI or CI |
+✅ For PyPi only |
+✅ | +
| Ruby | +✅ | +-- | +✅ | +✅ | +
| Scala | +✅ | +✅ SBT in CLI or CI |
+✅ | +-- | +
| Swift | +✅ | +-- | +✅† | +-- | +
| PHP | +✅ | +-- | +✅ | +-- | +
| Rust | +No reachability analysis. However, Semgrep can compare a package's version against a list of versions with known vulnerabilities. | +-- | +✅ | +✅ | +
| Dart | +-- | +-- | +-- | +|
| Elixir | +-- | +-- | +-- | +
+
+
+
+
+
+_†Supply Chain can treat `requirements.txt` as a lockfile with Pip-compiled output and fully pinned dependencies or as a manifest file with more flexible specifiers. If your `requirements.txt` file doesn't use pinned dependencies exclusively, use the [`--allow-local-builds` flag](/semgrep-supply-chain/getting-started#scan-a-project-without-lockfiles-beta) when invoking your scan. This ensures that the dependencies using non-exact version specifiers, such as `>=`, `>`, `~=`, are included in the dependency graph. Otherwise, Semgrep ingests only pinned (`==`) dependencies._
+
+_‡Supply Chain does not analyze the transitivity of packages for these language and manifest file or lockfile combinations. All dependencies are listed as **No | Language | +Supported package managers | +Manifest file or lockfile | +
|---|---|---|
| C# | +NuGet | +.csproj |
+
| Go | +Go modules (go mod) |
+ go.mod |
+
| Java | +Gradle | +gradle.lockfile or build.gradle or
+ build.gradle.kts through Dynamic
+ Dependency Resolution. |
+
| Maven | +Maven-generated dependency tree (see Setting up SSC scans for Apache Maven for instructions) or pom.xml through Dynamic
+ Dependency Resolution. |
+ |
| JavaScript or TypeScript | +npm | +package-lock.json |
+
| Yarn | +yarn.lock |
+ |
| pnpm | +pnpm-lock.yaml |
+ |
| Kotlin | +Gradle | +gradle.lockfile |
+
| Maven | +Maven-generated dependency tree (See Setting up SSC scans for Apache Maven for instructions.) | +|
| Python | +pip | +A
|
+
| pip-tools | +||
| Pipenv | +Pipfile.lock |
+ |
| Poetry | +poetry.lock |
+ |
| uv | +uv.lock |
+ |
| Ruby | +RubyGems | +Gemfile.lock |
+
| Scala | +Maven | +Maven-generated dependency tree (See Setting up SSC scans for Apache Maven for instructions.) | +
| Swift | +SwiftPM | +Package.swift file and Swift-generated Package.resolved file. (See Swift documentation for instructions.) |
+
| Rust | +Cargo‡ | +cargo.lock |
+
| Dart | +Pub | +pubspec.lock |
+
| Elixir | +Hex | +mix.lock |
+
| PHP | +Composer | +composer.lock |
+
diff --git a/mintlify-docs/semgrep-supply-chain/setup-infrastructure.mdx b/mintlify-docs/semgrep-supply-chain/setup-infrastructure.mdx new file mode 100644 index 0000000000..1c4a18eb75 --- /dev/null +++ b/mintlify-docs/semgrep-supply-chain/setup-infrastructure.mdx @@ -0,0 +1,25 @@ +--- +title: "Set up Semgrep Supply Chain for your infrastructure" +--- + + +
- Upgrade filter for Findings
- Upgrade guidance on the
Finding Details page - Coupled or blocked upgrade information shown on the
Finding Details page - Ability to open a PR to upgrade
- Upgrade filter for Findings
- Upgrade guidance on the
Finding Details page - Coupled or blocked upgrade information shown on the
Finding Details page - Ability to open a PR to upgrade
- Ability to open a PR to upgrade
- Upgrade filter for Findings
- Upgrade guidance on the
Finding Details page - Coupled or blocked upgrade information shown on the
Finding Details page
- Upgrade filter for Findings
- Upgrade guidance on the
Finding Details page - Coupled or blocked upgrade information shown on the
Finding Details page
+“If a developer has to convince their manager to spend a few million dollars on advanced security tools each time they change jobs, the future is bleak.” — see our [introductory blog post](https://semgrep.dev/blog/2020/introducing-semgrep-and-r2c/) for more. It’s important to us (and the community) that Semgrep, Inc. is able to develop a sustainable business around Semgrep to support its development, but we strongly believe the tooling itself must always be free. + +1. **Open-source software**
+Semgrep is [LGPL](https://tldrlegal.com/license/gnu-lesser-general-public-license-v2.1-(lgpl-2.1)) and powered not just by [Semgrep, Inc.](https://semgrep.dev/) but also by community of brilliant external contributors. We welcome feedback and contributions and strive to be a welcoming community for new developers. + +1. **Fast**
+High sloc/sec scanning speed and low startup cost. We’ll never be as fast as ripgrep but we want to get as close as we can. + +1. **Code never leaves your machine**
+Semgrep by default runs entirely locally (unless you set it up yourself in a server/client mode). Code never leaves your machine to be analyzed. + +1. **Support every programming language**
+“If grep supports it, we will too!” This even includes those that aren’t thought of as programming languages, like Bash or Docker. + +1. **Run anywhere**
+Semgrep is small (<100 MB), has minimal runtime dependencies, and should be easily installable via your programming language or operating system package manager. + +1. **Keep easy things easy, and hard things possible.**
+Using Semgrep to scan your code, and writing rules with which to scan, should be easy. Semgrep also smooths the process with delightful defaults and support every step of the way. But it’s also adaptable, and we welcome you using Semgrep in your own custom way. Hey, there are even [examples of scanning cat pictures out there](https://youtu.be/ybWB2Vf2V50?t=1182). + +1. **Beginner-friendly**
+You shouldn’t need a PhD in program analysis, or even to understand what an AST is, to be effective with Semgrep. A novice programmer should be able to write their first Semgrep rule in 60 seconds. + +1. **Human-readable rules**
+Rules should look like code and be easy to read and reason about—hopefully easier than if they were written in grep or a native linter. + +1. **Self-contained rule files**
+You shouldn’t need an additional plugin, dependency, or internet access to run a YAML rule. It should just work. + +1. **Deterministic (implies reproducible, idempotent)**
+Given the same input, Semgrep gives the same output. + +1. **Runs offline**
+Semgrep can run without internet access so developers can write code from airplanes or beaches. + +1. **Rules are safe to run no matter where they came from**
+Rules shouldn’t have the capability to run arbitrary code on your system, only to act as a function that produces a deterministic output message. + +1. **Single-file analysis**
+To stay fast and limit complexity, Semgrep CE draws a line at crossing file boundaries during analysis. It loses the ability to detect certain complex cross-function (interprocedural) issues, but that’s an explicit tradeoff it makes.
+Semgrep CE's goal is to catch what a senior engineer would catch in code review: Semgrep isn’t designed to find a crazy issue that’s 300 calls from start to finish and evaded the team for 20 years. Instead, it’s designed for enforcing best-practices and automating the code review tasks that an excellent senior engineer would be capable of. For a discussion of why expressive creativity is better than a powerful engine, [see this excellent blog post by Devdatta Akhawe](https://devd.me/log/posts/static-analysis/).
+As a corollary: if you design your codebase so that code in a file is safe today, it's still safe after a colleague makes a change twenty function calls away in another file. + +1. **Designed to run while code is being written**
+Semgrep is optimized for running in the IDE, Git commit hooks, or CI—not for at the tail-end of a release process. + +1. **A platform for program analysis**
+We will expose stable internals so that researchers and engineers can develop novel program analysis work off of APIs like Semgrep’s generic AST. diff --git a/mintlify-docs/snippets/faq/comparisons/opengrep.mdx b/mintlify-docs/snippets/faq/comparisons/opengrep.mdx new file mode 100644 index 0000000000..704476ff3e --- /dev/null +++ b/mintlify-docs/snippets/faq/comparisons/opengrep.mdx @@ -0,0 +1,89 @@ +To resolve confusion within security and developer communities when trying to choose between Semgrep and Opengrep, this page highlights some of the key distinctions to help with decision-making. + +
- Verify that your technical stack is supported by Semgrep.
- Begin gathering necessary permissions from your organization for **technical resources** to run the POV.
- Both parties establish success criteria and alignment of the POV goals through a **kickoff call**.
- Semgrep prepares for the POV by creating a dedicated Slack channel and other necessary accounts.
- Semgrep deployment rollout.
- Detection and remediation of findings.
- Analysis of Semgrep ROI.
- A roadmap call with the Semgrep product team.
- A rule-writing session where you can learn how to write custom Semgrep rules.
+ **Then** the finding in the current branch is triaged to that same state. + - **Diff-aware scan**: findings introduced in a diff-aware scan are **not** automatically triaged at scan time, even if there are other instances of that finding on branches that have been triaged. diff --git a/mintlify-docs/snippets/semgrep-ci/packages-in-semgrep-docker.mdx b/mintlify-docs/snippets/semgrep-ci/packages-in-semgrep-docker.mdx new file mode 100644 index 0000000000..d9638ab6b3 --- /dev/null +++ b/mintlify-docs/snippets/semgrep-ci/packages-in-semgrep-docker.mdx @@ -0,0 +1,33 @@ +## Packages + +In addition to the `semgrep` binary, the [`semgrep/semgrep:latest` docker image](https://hub.docker.com/r/semgrep/semgrep/tags) contains the following packages: + +- `bash` +- `jq` +- `curl` +- Python 3.11 (`alpine:3.22` base image) + +The Alpine 3.22 docker image includes additional packages that can change without notice. To review them, run `docker run alpine:3.22 apk list`. + +
/REPOSITORY-ROOT-DIRECTORY/.github/workflows/semgrep.yml.
++ Includes an open source, lightweight SAST scanner and rules in the [Semgrep Registry](https://semgrep.dev/r/) with **open source licenses**. You can also write your own custom rules. Semgrep CE also includes the Visual Studio Code (VS Code) and IntelliJ extensions. The Community Edition is best for small teams or personal projects. + +**Semgrep AppSec Platform (Semgrep)**
+ Refers to a proprietary software suite tailored to support AppSec engineers through the entire software development life cycle (SDLC). Best for deploying security programs throughout their organization. Many of Semgrep's features support the deployment of [secure guardrails](/secure-guardrails/secure-guardrails-in-semgrep). Semgrep includes the following products: + +**Semgrep Code**
+ A SAST scanner that uses cross-file (interfile) and cross-function (intrafile) analysis for improved results over Semgrep Community Edition. Semgrep Code includes rules written by Semgrep's Security Research team, called **Pro Rules**. These rules use cross-file analysis to reduce false positives. + +**Semgrep Supply Chain**
+ A high-signal dependency scanner that detects reachable vulnerabilities in open source third-party libraries and functions across the software development life cycle (SDLC). + +**Semgrep Secrets**
+ A secrets scanner that, in addition to detecting secrets, validates these leaked secrets on a variety of services to help you prioritize active secrets. + +
+ +
+ + + + + +### Triage and remediation + +_Triage is the process of reviewing findings and determining if a finding is a true or false positive, and whether to fix the finding or not. Remediation refers to the steps taken to resolve the finding._ + +_**Ticketing and notification integrations** are included in this workflow to inform developers of fixes and remediation guidance they may need to take to close the finding._ + +
+ + + + + +_**Figure**. The dashboard page. Hover over the charts to view data for that point in time._ + +## Appendix + +This section provides a comprehensive comparison of each offering's features. +### Deployment + +
+ +###### Semgrep Community Edition (SAST) + +- [30+ Community supported languages](/semgrep-ce-languages#semgrep-code-and-community-edition) +- [
Supports 35+ languages | **Semgrep Supply Chain**
Supports 14 languages | +| --- | --- | --- | +| [C#](/languages/csharp) | **Generally available**
• Cross-file dataflow analysis
• Supports up to C# 13
• 170+ Pro rules | **Generally available**
• Reachability analysis
• Can detect open source licenses
• Can detect malicious dependencies | +| [Go](/languages/go) | **Generally available**
• Cross-file dataflow analysis
• 80+ Pro rules | **Generally available**
• Reachability analysis
• Can detect open source licenses
• Can detect malicious dependencies | +| [Java](/languages/java) | **Generally available**
• Cross-file dataflow analysis
• Framework-specific control flow analysis
• 190+ Pro rules | **Generally available**
• Reachability analysis
• Can detect open source licenses | +| [JavaScript](/languages/javascript) | **Generally available**
• Cross-file dataflow analysis
• Framework-specific control flow analysis
• 250+ Pro rules | **Generally available**
• Reachability analysis
• Can detect open source licenses
• Can detect malicious dependencies | +| [Kotlin](/languages/kotlin) | **Generally available**
• Cross-file dataflow analysis
• 60+ Pro rules | **Generally available**
• Reachability analysis
• Can detect open source licenses | +| [Python](/languages/python) | **Generally available**
• Cross-file dataflow analysis
• Framework-specific control flow analysis
• 710+ Pro rules
• See [Python-specific support details](/languages/python) | **Generally available**
• Reachability analysis
• Can detect open source licenses
• Can detect malicious dependencies | +| Typescript | **Generally available**
• Cross-file dataflow analysis
• Framework-specific control flow analysis
• 230+ Pro rules | **Generally available**
• Reachability analysis
• Can detect malicious dependencies
• Can detect open source licenses | +| C / C++ | **Generally available**
• Cross-file dataflow analysis
• 150+ Pro rules | N/a | +| JSX | **Generally available**
• Cross-function dataflow analysis
• 70+ Pro rules | **Generally available**
• Reachability analysis
• Can detect open source licenses | +| [Ruby](/languages/ruby) | **Generally available**
• Cross-function dataflow analysis
• 40+ Pro rules | **Generally available**
• Reachability analysis
• Can detect open source licenses
• Can detect malicious dependencies | +| [Scala](/languages/scala) | **Generally available**
• Cross-function dataflow analysis
• Community rules | **Generally available**
• Reachability analysis
• Can detect open source licenses | +| [Swift](/languages/swift) | **Generally available**
• Cross-function dataflow analysis
• 60+ Pro rules | **Generally available**
• Reachability analysis
• Can detect open source licenses | +| Rust | **Generally available**
• Cross-function dataflow analysis
• 40+ Pro rules | **Generally available**
• Reachability analysis
• Can detect open source licenses
• Can detect malicious dependencies | +| PHP | **Generally available**
• Cross-function dataflow analysis
• 50+ Pro rules | **Generally available**
• Reachability analysis
• Can detect open source licenses | +| Terraform | **Generally available**
• Cross-function dataflow analysis
• Community rules | N/a | +| Generic | **Generally available** | N/a | +| JSON | **Generally available** | N/a | +| Elixir | **Generally available** | **Beta** | +| APEX | **Beta** | -- | +| Dart | **Experimental** | **Beta** | + +
+When running `semgrep ci`, Semgrep fetches rules and any other configurations specific to your CI environment. Setting `SEMGREP_REPO_NAME` is optional, but ensures that: +- Results are sent to the same project (either a repository or folder in a monorepo) in Semgrep AppSec Platform. +- Any project-specific configurations, such as file ignores, are also respected. + +## Troubleshooting GitHub + +The first piece of information that the team at Semgrep uses are the **GitHub Actions logs**. + +To retrieve a log, perform the following steps: + +
+
+ 
+
+ 
+
+
+ - Enable workflows by clicking **I understand my workflows, go ahead and enable them** to allow Semgrep to scan.
+
+### If a project reports a scan 'Never finished'
+
+Most often, this status means that the job started and authenticated correctly, but failed or was canceled before completion. Check your CI provider (such as GitHub Actions) for the log output of the latest Semgrep job execution. In most cases, you will see an error message with detailed instructions on what to do.
+
+Sometimes, this status may be shown when the scan has been running for a long time (more than an hour) and is still in progress. Scans that eventually produce results will be accepted by Semgrep AppSec Platform, even if this message is shown.
+
+#### If the job is aborted due to taking too long
+
+Many CI providers have a time limit for how long a job can run. If your CI scans regularly take too long and fail to complete:
+
+- Please [reach out](/support) to the Semgrep team for help with tracking down the cause. Semgrep scans most projects with hundreds of rules within a few minutes, and long run times are often caused by just one rule or source code file taking too long.
+- To optimize run times, use Semgrep's diff-aware scanning in pull requests and merge requests to skip scanning unchanged files. For more details, see [Semgrep's behavior](/deployment/customize-ci-jobs).
+- Skip scanning large and complex source code files (such as minified JS or generated code) if you know their path by adding a `.semgrepignore` file. See [how to ignore files & directories in Semgrep CI](/ignoring-files-folders-code).
diff --git a/mintlify-docs/troubleshooting/semgrep.mdx b/mintlify-docs/troubleshooting/semgrep.mdx
new file mode 100644
index 0000000000..97430670a5
--- /dev/null
+++ b/mintlify-docs/troubleshooting/semgrep.mdx
@@ -0,0 +1,23 @@
+---
+title: "Troubleshooting the CLI"
+---
+
+## Semgrep exited with code -11 (or -9)
+
+This can happen when Semgrep crashes, usually as a result of memory exhaustion. `-11` and `-9` are the POSIX signals raised to cause the crash.
+
+Review troubleshooting steps for memory exhaustion at [Semgrep scan troubleshooting: Memory usage issues](/kb/semgrep-code/semgrep-scan-troubleshooting/#memory-usage-issues-oom-errors).
+
+## Semgrep is too slow
+
+Semgrep records runtimes for each file and rule. This information is displayed when you include the `--time` flag when running Semgrep. How you choose to interact with the `--time` output depends on your goals.
+
+### I want Semgrep to run faster
+
+Review troubleshooting steps for slow scans at [Semgrep scan troubleshooting: Slow scans](/kb/semgrep-code/semgrep-scan-troubleshooting/#slow-scans).
+
+### I am a contributor who wants to improve Semgrep's engine
+
+Thank you! Check out the [Contributing docs](/contributing/contributing) to get started.
+
+The section [Explore results from a slow run of Semgrep](/contributing/semgrep-core-contributing#explore-results-from-a-slow-run-of-semgrep) is helpful if you haven't previously investigated Semgrep performance.
diff --git a/mintlify-docs/update.mdx b/mintlify-docs/update.mdx
new file mode 100644
index 0000000000..4a257f1b05
--- /dev/null
+++ b/mintlify-docs/update.mdx
@@ -0,0 +1,29 @@
+---
+title: "Update Semgrep"
+description: "Stay up-to-date by running the latest version of Semgrep automatically in CI or your local CLI."
+---
+
+For Docker users, enter the following commands:
+
+```bash
+docker pull semgrep/semgrep:latest
+
+# confirm your Semgrep installation
+docker run --rm semgrep/semgrep semgrep --version
+```
+
+You can also use the following commands in either your CLI or CI environment:
+
+```bash
+# macOS users only, using Homebrew
+brew upgrade semgrep
+
+# macOS, Linux, or Windows users using pipx (recommended)
+pipx upgrade semgrep
+
+# Or, using uv
+uv tool upgrade semgrep
+
+# confirm your Semgrep installation
+semgrep --version
+```
diff --git a/mintlify-docs/usage-and-billing/contributor-count-explained.mdx b/mintlify-docs/usage-and-billing/contributor-count-explained.mdx
new file mode 100644
index 0000000000..4499aef8b0
--- /dev/null
+++ b/mintlify-docs/usage-and-billing/contributor-count-explained.mdx
@@ -0,0 +1,66 @@
+---
+title: "How Semgrep calculates contributor count"
+sidebarTitle: "Calculate Semgrep contributor count"
+---
+
+This page explains how Semgrep calculates contributor count beyond the [basic billing definition](/usage-and-billing/overview#contributor-counts). It is intended to help explain why Semgrep's contributor count may differ from your organization's internal estimate, and how Semgrep reduces double-counting when using repository history.
+
+## Why contributor counts can be hard to calculate
+
+Raw commit history does not always cleanly map to unique people. The same contributor can appear under multiple identities over time, including:
+
+- Multiple company email addresses
+- Email aliases or formatting variations
+- GitHub-generated noreply addresses used in merge commits
+
+Repository history can also include bots and automation accounts that should not count as human contributors. To make contributor counts more accurate, Semgrep applies normalization, deduplication, and filtering steps to the underlying commit data.
+
+## How Semgrep reduces double-counting
+
+Semgrep uses commit metadata from scanned repositories to identify likely duplicate identities and count them once.
+
+This process can include:
+
+- normalizing common email variations
+- matching contributors who appear under multiple company domains
+- resolving GitHub noreply addresses back to known contributor identities when possible
+
+The goal is to better reflect distinct human contributors rather than counting every raw identity in commit history as a separate person.
+
+## How Semgrep handles personal email addresses
+
+Personal email addresses sometimes appear in repository history alongside company-managed identities. Personal emails are weak identifiers and are harder to match reliably across environments. Semgrep applies some filtering rules to reduce overcounting and also keeps a pre-filtered version of the data for auditing and comparison.
+
+- If the primary domain for the deployment is a company domain, Semgrep does not count contributors who appear only with personal email addresses. It still counts contributors who have at least one company email address.
+- If the primary domain for the deployment is a personal email domain, such as gmail.com, Semgrep counts only contributors whose email matches that domain. It does not count contributors who appear only with other personal email domains.
+- If Semgrep cannot identify a primary domain, it does not apply personal email filtering.
+
+## How Semgrep handles bots and automation accounts
+
+Contributor count is intended to measure human contributors, not automated systems. Semgrep excludes known bot and automation accounts from the calculation using maintained exclusion lists informed by bot-related patterns in commit metadata.
+
+## Public and private repositories
+
+Public GitHub repositories that are explicitly set to be visible to everyone are excluded from contributor count calculations.
+
+All GitHub Enterprise Server repositories are treated as private for this purpose, regardless of visibility.
+
+## Why your internal estimate might differ
+
+Your internal estimate of contributors may differ from Semgrep’s for the following reasons:
+
+- One person appears under multiple identities in commit history
+- Bots or service accounts are present in raw repository data
+- Public repositories are excluded
+- Personal email addresses cannot always be matched reliably
+- Limited git history reduces the set of visible contributors
+
+Because of this, contributor count should be understood as a usage metric based on observed repository activity over a defined period.
+
+## Why git history matters
+
+Contributor count depends on the commit history available at scan time. If a checkout includes limited history, Semgrep might not see every contributor active during the full 90-day lookback window.
+
+## Questions about your contributor count
+
+If you have questions about your contributor count, contact [Semgrep support](/support) or your account manager
\ No newline at end of file
diff --git a/mintlify-docs/usage-and-billing/contributors.mdx b/mintlify-docs/usage-and-billing/contributors.mdx
new file mode 100644
index 0000000000..d5de3c9408
--- /dev/null
+++ b/mintlify-docs/usage-and-billing/contributors.mdx
@@ -0,0 +1,64 @@
+---
+title: "How Semgrep calculates contributor count"
+---
+
+This page explains how Semgrep calculates contributor count beyond the [basic billing definition](/usage-and-billing/overview#contributor-counts). It is intended to help explain why Semgrep's contributor count may differ from your organization's internal estimate, and how Semgrep reduces double-counting when using repository history.
+
+## Why contributor counts can be hard to calculate
+
+Raw commit history does not always cleanly map to unique people. The same contributor can appear under multiple identities over time, including:
+- Multiple company email addresses
+- Email aliases or formatting variations
+- GitHub-generated noreply addresses used in merge commits
+
+Repository history can also include bots and automation accounts that should not count as human contributors. To make contributor counts more accurate, Semgrep applies normalization, deduplication, and filtering steps to the underlying commit data.
+
+## How Semgrep reduces double-counting
+
+Semgrep uses commit metadata from scanned repositories to identify likely duplicate identities and count them once.
+
+This process can include:
+- normalizing common email variations
+- matching contributors who appear under multiple company domains
+- resolving GitHub noreply addresses back to known contributor identities when possible
+
+The goal is to better reflect distinct human contributors rather than counting every raw identity in commit history as a separate person.
+
+## How Semgrep handles personal email addresses
+
+Personal email addresses sometimes appear in repository history alongside company-managed identities. Personal emails are weak identifiers and are harder to match reliably across environments. Semgrep applies some filtering rules to reduce overcounting and also keeps a pre-filtered version of the data for auditing and comparison.
+
+- If the primary domain for the deployment is a company domain, Semgrep does not count contributors who appear only with personal email addresses. It still counts contributors who have at least one company email address.
+- If the primary domain for the deployment is a personal email domain, such as gmail.com, Semgrep counts only contributors whose email matches that domain. It does not count contributors who appear only with other personal email domains.
+- If Semgrep cannot identify a primary domain, it does not apply personal email filtering.
+
+
+## How Semgrep handles bots and automation accounts
+
+
+Contributor count is intended to measure human contributors, not automated systems. Semgrep excludes known bot and automation accounts from the calculation using maintained exclusion lists informed by bot-related patterns in commit metadata.
+
+## Public and private repositories
+
+Public GitHub repositories that are explicitly set to be visible to everyone are excluded from contributor count calculations.
+
+All GitHub Enterprise Server repositories are treated as private for this purpose, regardless of visibility.
+
+## Why your internal estimate might differ
+
+Your internal estimate of contributors may differ from Semgrep’s for the following reasons:
+- One person appears under multiple identities in commit history
+- Bots or service accounts are present in raw repository data
+- Public repositories are excluded
+- Personal email addresses cannot always be matched reliably
+- Limited git history reduces the set of visible contributors
+
+Because of this, contributor count should be understood as a usage metric based on observed repository activity over a defined period.
+
+## Why git history matters
+
+Contributor count depends on the commit history available at scan time. If a checkout includes limited history, Semgrep might not see every contributor active during the full 90-day lookback window.
+
+## Questions about your contributor count
+
+If you have questions about your contributor count, contact [Semgrep support](/support) or your account manager
diff --git a/mintlify-docs/usage-and-billing/overview.mdx b/mintlify-docs/usage-and-billing/overview.mdx
new file mode 100644
index 0000000000..7b7f8bb830
--- /dev/null
+++ b/mintlify-docs/usage-and-billing/overview.mdx
@@ -0,0 +1,104 @@
+---
+title: " Usage and billing"
+description: "This document provides information on how Semgrep calculates usage for billing purposes and is intended for users with paid Semgrep Code, Supply Chain, or Secrets licenses."
+---
+
+
+## Contributor definition
+
+A **contributor** is someone who has made at least **one** commit to a Semgrep-scanned **private** repository within the last 90 days, starting from the **date of license purchase** if a license was purchased, or the date of account creation, for accounts using Semgrep within usage limits.
+
+Any Semgrep AppSec Platform scan counts towards the contributor total. This includes:
+
+- Scanning with Semgrep Code, Secrets, or Supply Chain
+- Full scans on a repository or partial scans on a pull request or merge request
+
+Semgrep computes contributor counts for any scan initiated by a logged-in user running `semgrep ci` or `semgrep scan`. The `semgrep scan` command is subject to the usage limit when invoked by a logged-in contributor.
+
+
+
+
+As input, Semgrep workflows take your project code and security context. This includes your organization's risk tolerance, findings triage rules, and other internal security program logic and definitions. The workflow is triggered by actions such as:
+
+- The opening of a pull request (PR) or a merge request (MR)
+- A scheduled scan
+- An API call
+
+Semgrep then runs security tools, such as static analysis, software composition analysis, and secrets detection, and applies LLM-backed analysis on your project. The resulting security findings, triage decisions, research artifacts, and code changes are provided to you in a structured, actionable format.
+
+## Types of workflows
+
+Semgrep provides built-in workflows you can run immediately, or you can define custom ones for your organization's needs. All workflows deploy on Semgrep’s managed infrastructure, minimizing your operational overhead.
+
+Semgrep's **pre-built workflows**, covering common use cases, include:
+
+- **Insecure direct object references (IDORs) and broken authorization**: combine static analysis and AI detection to find broken authorization, authentication bypasses, insecure access patterns, and other business logic issues
+- **Triage**: filter out false positives from your results to help your security teams prioritize real issues
+- **Autofix**: turn dependency findings into actionable remediation guidance, including information on whether the upgrade is safe or requires code modification
+
+You can integrate any of these workflows individually, combine them to implement the functionality you need, or use them all to create an end-to-end security workflow for your organization. Alternatively, you can define **[custom workflows](#custom-workflows)** to meet your organization's needs. You can adapt a pre-built Semgrep workflow for your organization, or create entirely new ones using the Semgrep agent SDK.
+
+## Custom workflows
+
+Semgrep workflows are defined using Python and have a clear structure that includes steps, tool decorators, and standard control flow. This structure makes it straightforward for AI assistants to generate, modify, and extend your workflows -- you can describe what you want your workflow to do in natural language, and the AI assistant presents you with a draft workflow.
+
+You can run workflows locally for testing and iteration, on Kubernetes with a single deploy command, or through CI/CD systems like GitHub Actions or GitLab CI. Semgrep’s managed infrastructure handles orchestration, optimization, and monitoring regardless of deployment method.
+
+Custom workflow patterns include, but aren't limited to, the following:
+
+| Workflow | Description |
+| :--- | :--- |
+| Detection | combine Semgrep with other security tools, project code context, and LLM-assisted reasoning to identify patterns that your organization deems important but can't be categorized neatly into generic, out-of-the-box rules |
+| Policies | encode internal security and compliance logic, then run it across multiple environments and repositories |
+| Remediation | generate upgrade guidance, code change suggestions, and PRs with the context developers need to fix issues safely |
+| Triage | review findings from a scanning tool while using repository context and custom review logic to produce decisions about the validity and priority of the findings |
+| Validation | review suspected issues with additional checks to determine if the issues are exploitable or worth escalating |
+
+## Get started
+
+To get started with your first automated workflows, [+Extract the matched content as raw source code. This is the default value. + +`concat_json_string_array`
+Extract the matched content as a JSON array. Each element of the array correspond to a line the resulting source code. This value is useful in extracting code from JSON formats such as Jupyter Notebooks. + +#### `reduce` + +The `reduce` key is optional in extract mode. The value of this key specifies a method to combine the ranges extracted by a single rule within a file. + +The value of `reduce` key must be one of the following: + +`separate`
+ +Treat all matched ranges as separate units for subsequent queries. This is the **default** value. + +`concat`
+Concatenate all matched ranges together and treat this result as a single unit for subsequent queries. + +### Limitations of extract mode + +Although extract mode supports JSON array decoding with the `json` key, it does not support other additional processing for the extracted text, such as unescaping strings. + +While extract mode can help to enable rules which try and track taint across a language boundary within a file, taint rules cannot have a source and sink split across the original file and extracted text. + +## Turbo Mode + +
+ `server = example.com`. In generic mode, an ellipsis extends until the end of the current block or up to 10 lines below, whichever comes first. To prevent this behavior, continue with the next step. + +2. In the Semgrep rule, specify the following key: + + ```yaml + generic_ellipsis_max_span: 0 + ``` + + This option forces the ellipsis operator to match patterns within a single line. + Example of the [resulting rule](https://semgrep.dev/playground/s/KPzn): + + ```yaml + id: password-in-config-file + pattern: | + password = $...PASSWORD + options: + # prevent ellipses from matching multiple lines + generic_ellipsis_max_span: 0 + message: | + password found in config file: $...PASSWORD + languages: + - generic + severity: WARNING + ``` + +### Ignoring comments + +By default, the generic mode does **not** know about comments or code +that can be ignored. The following example is +scanning for CSS code that sets the text color to blue. The target code +is the following: + +``` +color: /* my fave color */ blue; +``` + +Use the [`options.generic_comment_style`](/writing-rules/rule-syntax/#options) +to ignore C-style comments, as is the case in the example. +The Semgrep rule is: + +```yaml +id: css-blue-is-ugly +pattern: | + color: blue +options: + # ignore comments of the form /* ... */ + generic_comment_style: c +message: | + Blue is ugly. +languages: + - generic +severity: WARNING +``` + +## Command line example + +Sample pattern: `exec(...)` + +Sample target file `exec.txt` contains: +```bash +import exec as safe_function +safe_function(user_input) + +exec("ls") + +exec(some_var) + +some_exec(foo) + +exec (foo) + +exec ( + bar +) + +# exec(foo) + +print("exec(bar)") +``` + +Output: +```bash +$ semgrep -l generic -e 'exec(...)` exec.text +7:exec("ls") +-------------------------------------------------------------------------------- +11:exec(some_var) +-------------------------------------------------------------------------------- +19:exec (foo) +-------------------------------------------------------------------------------- +23:exec ( +24:128 +25: bar +26:129 +27:) +-------------------------------------------------------------------------------- +31:# exec(foo) +-------------------------------------------------------------------------------- +35:print("exec(bar)") +ran 1 rules on 1 files: 6 findings +``` + +## Semgrep Registry rules for generic pattern matching +You can peruse [existing generic rules](https://semgrep.dev/r?lang=generic&sev=ERROR,WARNING,INFO&tag=dgryski.semgrep-go,hazanasec.semgrep-rules,ajinabraham.njsscan,best-practice,security,java-spring,go-stdlib,ruby-stdlib,java-stdlib,js-node,nodejsscan,owasp,dlint,react,performance,compatibility,portability,correctness,maintainability,security,mongodb,experimental,caching,robots-denied,missing-noreferrer,missing-noopener) in the Semgrep registry. In general, short patterns on structured data performs the best. + +## Cheat sheet +Some examples of what matches and what doesn't match on the `generic` tab of the Semgrep cheat sheet below: + + + + + +## Hidden bonus + +In the Semgrep code, the generic pattern matching implementation is called **spacegrep** because it tokenizes based on whitespace (and because it sounds cool 😎). diff --git a/mintlify-docs/writing-rules/glossary.mdx b/mintlify-docs/writing-rules/glossary.mdx new file mode 100644 index 0000000000..71f8cf4416 --- /dev/null +++ b/mintlify-docs/writing-rules/glossary.mdx @@ -0,0 +1,139 @@ +--- +title: "Static analysis and rule-writing glossary" +sidebarTitle: "Glossary" +description: "The definitions provided here are specific to Semgrep." +--- + +## Constant propagation + +Constant propagation is a type of analysis where values known to be constant are substituted in later uses, allowing the value to be used to detect matches. Semgrep can perform constant propagation across files, unless you are running Semgrep Community Edition (CE), which can only propagate within a file. + +Constant propagation is applied to all rules unless [it is disabled](/writing-rules/data-flow/constant-propagation#disable-constant-propagation). + +For example, given the following pattern: +```yaml +... +patterns: +- pattern: console.log(2) +``` +And the following code snippet: +```javascript highlight={2} +const x = 2; +console.log(x); +``` + +The pattern operator `pattern: print(2)` tells Semgrep to match line 2 because it propagates the value `2` from the assignment in line 1 to the `console.log()` function in line. + +Constant propagation is one of the many analyses that differentiate Semgrep from grep. + +## Cross-file analysis + +Cross-file analysis (also known as **interfile analysis**) takes into account how information flows between files. In particular, cross-file analysis includes **cross-file taint analysis**, which tracks unsanitized variables flowing from a source to a sink through arbitrarily many files. Other analyses performed across files include constant propagation and type inference. + +Cross-file analysis is usually used in contrast to intrafile, or per-file analysis, where each file is analyzed as a standalone block of code. + +Within Semgrep, cross-file **and** cross-function analysis is simply referred to as cross-file analysis. + +Semgrep CE is limited to per-file analysis. + +## Cross-function analysis + +Cross-function analysis means that interactions between functions are taken into account. This improves taint analysis, which tracks unsanitized variables flowing from a source to a sink through arbitrarily many functions. + +Within Semgrep documentation, cross-function analysis implies intrafile or per-file analysis. Each file is still analyzed as a standalone block, but within the file it takes into account how information flows between functions. + +Also known as **interprocedural** analysis. + +## Error matrix + +An error matrix is a 2x2 table that visualizes the findings of a Semgrep rule in relation to the vulnerable lines of code it does or doesn't detect. It has two axes: + +- Positive and negative +- True or false + +These yield the following combinations: + +**True positive**
+ The rule detected a piece of code it was intended to find. + +**False positive**
+ The rule detected a piece of code it was not intended to find. + +**True negative**
+ The rule correctly skipped over a piece of code it wasn't meant to find. + +**False negative**
+ The rule failed to detect a piece of code it should have found. + +Not to be confused with **risk matrices**. + +## Finding + +A finding is the core result of Semgrep's analysis. Findings are generated when a Semgrep rule matches a piece of code. Findings can be security issues, bugs, or code that doesn't follow coding conventions. + +## Fully qualified name + +A **fully qualified name** refers to a name which uniquely identifies a class, method, type, or module. Languages such as C# and Ruby use `::` to distinguish between fully qualified names and regular names. + +Not to be confused with **tokens**. + +## l-value (left-, or location-value) + +An expression that denotes an object in memory; a memory location, something that you can use in the left-hand side (LHS) of an assignment. For example, `x` and `array[2]` are l-values, but `2+2` is not. + +## Metavariable + +A metavariable is an abstraction that lets you match something even when you don't know exactly what it is you want to match. It is similar to capture groups in regular expressions. All metavariables begin with a `$` and can only contain uppercase characters, digits, and underscores. + +## Propagator + +A propagator is any code that alters a piece of data as the data moves across the program. This includes functions, reassignments, and so on. + +When you write rules that perform taint analysis, propagators are pieces of code that you specify through the `pattern-propagator` key as code that always passes tainted data. This is especially relevant when Semgrep performs intraprocedural taint analysis, as there is no way for Semgrep to infer which function calls propagate taint. Thus, explicitly listing propagators is the only way for Semgrep to know if tainted data could be passed within your function. + +## Rule (Semgrep rule) + +A rule is a specification of the patterns that Semgrep must match to the code to generate a finding. Rules are written in YAML. Without a rule, the engine has no instructions on how to match code. + +Rules can be run on either Semgrep or its OSS Engine. Only proprietary Semgrep can perform [interfile analysis](#cross-file-analysis). + +There are two types of rules: **search** and **taint**. + + +**Search rules**
+Rules default to this type. Search rules detect matches based on the patterns described by a rule. There are several semantic analyses that search rules perform, such as: + - Interpreting syntactically different code as semantically equivalent + - Constant propagation + - Matching a fully qualified name to its reference in the code, even when not fully qualified + - Type inference, particularly when using typed metavariables + +**Taint rules**
+Taint rules make use of Semgrep's taint analysis in addition to default search functionalities. Taint rules are able to specify sources, sinks, and propagators of data as well as sanitizers of that data. For more information, see [Taint analysis documentation](/writing-rules/data-flow/taint-mode/overview). + +## Sanitizers + +A sanitizer is any piece of code, such as a function or [a cast](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/types/casting-and-type-conversions#explicit-conversions), that can clean untrusted or tainted data. Data from untrusted sources, such as user inputs, may be tainted with unsafe characters. Sanitizers ensure that unsafe characters are removed or stripped from the input. + +An example of a sanitizer is the [
- `c` for traditional C-style comments (`/* ... */`).
- `cpp` for modern C or C++ comments (`// ...` or `/* ... */`).
- `shell` for shell-style comments (`# ...`).
`. |
+
+The complete list of available options can be consulted in the [Semgrep matching engine configuration](https://github.com/semgrep/semgrep/blob/develop/interfaces/Rule_options.atd) module. Please note that options not included in the table above are considered experimental and may change or be removed without notice.
+
+## `fix`
+
+The `fix` top-level key allows simple pattern fixes by suggesting an alternative for each match. Run `semgrep` with `--autofix` to apply the changes to the files.
+
+Example:
+
+```yaml
+rules:
+ - id: use-dict-get
+ patterns:
+ - pattern: $DICT[$KEY]
+ fix: $DICT.get($KEY)
+ message: "Use `.get()` method to avoid a KeyNotFound error"
+ languages: [python]
+ severity: HIGH
+```
+
+For more information about `fix` and `--autofix` see [Rule-defined fix](/writing-rules/rule-defined-fix) documentation.
+
+## `metadata`
+
+Provide additional information for a rule with the `metadata:` key, such as a related CWE, likelihood, or OWASP.
+
+Example:
+
+```yaml
+rules:
+ - id: eqeq-is-bad
+ patterns:
+ - [...]
+ message: "useless comparison operation `$X == $X` or `$X != $X`"
+ metadata:
+ cve: CVE-2077-1234
+ discovered-by: Ikwa L'equale
+ languages:
+ - javascript
+ - python
+ - go
+ severity: MEDIUM
+```
+
+The metadata are also displayed in the output of Semgrep if you’re running it with `--json`.
+Rules with `category: security` have additional metadata requirements. See [Including fields required by security category](/contributing/contributing-to-semgrep-rules-repository/#fields-required-by-the-security-category) for more information.
+
+## `min-version` and `max-version`
+
+Each rule supports optional fields `min-version` and `max-version` specifying
+minimum and maximum Semgrep versions. If the Semgrep
+version being used doesn't satisfy these constraints,
+the rule is skipped without causing a fatal error.
+
+Example rule:
+
+```yaml
+rules:
+ - id: bad-goflags
+ # earlier semgrep versions can't parse the pattern
+ min-version: 1.31.0
+ pattern: |
+ ENV ... GOFLAGS='-tags=dynamic -buildvcs=false' ...
+ languages: [dockerfile]
+ message: "We should not use these flags"
+ severity: MEDIUM
+```
+
+Another use case is when a newer version of a rule works better than
+before but relies on a new feature. In this case, you can use
+`min-version` and `max-version` to ensure that either the older or the
+newer rule is used, but not both. The rules would look like this:
+
+```yaml
+rules:
+ - id: something-wrong-v1
+ max-version: 1.72.999
+ ...
+ - id: something-wrong-v2
+ min-version: 1.73.0
+ # 10x faster than v1!
+ ...
+```
+
+The `min-version`/`max-version` feature has been available since Semgrep 1.38.0. It is intended primarily for publishing rules that rely on
+newly released features without causing errors in older Semgrep
+installations.
+
+
+## `category`
+
+Provide a category for users of the rule. For example: `best-practice`, `correctness`, `maintainability`. For more information, see [Semgrep Registry rule requirements](/contributing/contributing-to-semgrep-rules-repository/#semgrep-registry-rule-requirements).
+
+## `paths`
+
+### Exclude a rule in paths
+
+To ignore a specific rule on specific files, set the `paths:` key with
+one or more filters. The patterns apply to the full file paths
+relative to the project root.
+
+
+Example:
+
+```yaml
+rules:
+ - id: eqeq-is-bad
+ languages:
+ - python
+ - javascript
+ severity: MEDIUM
+ pattern: $X == $X
+ paths:
+ exclude:
+ - "src/**/*.jinja2"
+ - "*_test.go"
+ - "project/tests"
+ - "project/static/*.js"
+```
+
+When invoked with `semgrep -f rule.yaml project/`, the preceding rule runs on files inside `project/`, but no results are returned for:
+
+- any file with a `.jinja2` file extension
+- any file whose name ends in `_test.go`, such as `project/backend/server_test.go`
+- any file inside `project/tests` or its subdirectories
+- any file matching the `project/static/*.js` glob pattern
+
+
+**NOTE**
+
+The glob syntax is from [Python's `wcmatch`](https://pypi.org/project/wcmatch/) and is used to match against the given file and all its parent directories.
+
+
+### Limit a rule to paths
+
+Conversely, to run a rule _only_ on specific files, set a `paths:` key with one or more of these filters:
+
+```yaml
+rules:
+ - id: eqeq-is-bad
+ pattern: $X == $X
+ languages:
+ - python
+ - javascript
+ severity: MEDIUM
+ paths:
+ include:
+ - "*_test.go"
+ - "project/server"
+ - "project/schemata"
+ - "project/static/*.js"
+ - "tests/**/*.js"
+```
+
+When invoked with `semgrep -f rule.yaml project/`, this rule runs on files inside `project/`, but results are returned only for:
+
+- files whose name ends in `_test.go`, such as `project/backend/server_test.go`
+- files inside `project/server`, `project/schemata`, or their subdirectories
+- files matching the `project/static/*.js` glob pattern
+- all files with the `.js` extension, arbitrary depth inside the tests folder
+
+If you are writing tests for your rules, add any test file or directory to the included paths as well.
+
+
+**NOTE**
+
+When mixing inclusion and exclusion filters, the exclusion ones take precedence.
+
+
+Example:
+
+```yaml
+paths:
+ include: "project/schemata"
+ exclude: "*_internal.py"
+```
+
+The preceding rule returns results from `project/schemata/scan.py` but not from `project/schemata/scan_internal.py`.
+
+## Additional examples
+
+This section contains more complex rules that perform advanced code searching.
+
+### Complete useless comparison
+
+```yaml
+rules:
+ - id: eqeq-is-bad
+ languages: [python]
+ severity: MEDIUM
+ patterns:
+ - pattern-not-inside: |
+ def __eq__(...):
+ ...
+ - pattern-not-inside: assert(...)
+ - pattern-not-inside: assertTrue(...)
+ - pattern-not-inside: assertFalse(...)
+ - pattern-either:
+ - pattern: $X == $X
+ - pattern: $X != $X
+ - patterns:
+ - pattern-inside: |
+ def __init__(...):
+ ...
+ - pattern: self.$X == self.$X
+ - pattern-not: 1 == 1
+ message: "useless comparison operation `$X == $X` or `$X != $X`"
+```
+
+The preceding rule makes use of many operators. It utilizes `pattern-either`, `patterns`, `pattern`, and `pattern-inside` to carefully consider different cases, and employs `pattern-not-inside` and `pattern-not` to exclude specific unnecessary comparisons.
+
+## Full specification
+
+The [full configuration-file format](https://github.com/semgrep/semgrep-interfaces/blob/main/rule_schema_v1.yaml) is defined as a [jsonschema](http://json-schema.org/specification.html) object.
diff --git a/mintlify-docs/writing-rules/testing-rules.mdx b/mintlify-docs/writing-rules/testing-rules.mdx
new file mode 100644
index 0000000000..0ab674c1e0
--- /dev/null
+++ b/mintlify-docs/writing-rules/testing-rules.mdx
@@ -0,0 +1,227 @@
+---
+title: "Test rules"
+description: "Semgrep provides a testing mechanism for your rules. You can write code and provide annotations to let Semgrep know where you are or aren't expecting findings. Semgrep provides the following annotations:"
+---
+
+
+- `ruleid: ` for protecting against false negatives
+- `ok: ` for protecting against false positives
+- `todoruleid: ` for future "positive" rule improvements
+- `todook: ` for future "negative" rule improvements
+
+When writing tests, remember that:
+
+1. The `--test` flag tells Semgrep to run tests in the specified directory.
+2. Annotations are specified as a comment immediately preceeding the offending line.
+3. Semgrep looks for tests based on the rule filename and the languages
+ specified in the rule. In other words, `path/to/rule.yaml` searches for
+ `path/to/rule.py`, `path/to/rule.js`, and similar, based on the languages specified in the rule.
+
+
+**INFO**
+
+The `.test.yaml` file extension can also be used for test files. This is necessary when testing YAML language rules.
+
+
+## Test rules with Rule-defined fix
+
+Semgrep's testing mechanism also provides a way to test the behavior of any `fix` values defined in the rules.
+
+To define a test for Rule-defined fix behavior:
+
+
+
+Create a new **Rule-defined fix test file** with the `.fixed` suffix before the file type extension. For example, name the Rule-defined fix test file of a rule with test code in `path/to/rule.py` as `path/to/rule.fixed.py`.
+
+
+Within the Rule-defined fix test file, enter the expected result of applied Rule-defined fix rule to the test code.
+
+
+Run `semgrep --test` to verify that your Rule-defined fix test file is correctly detected.
+
+
+When you use `semgrep --test`, Semgrep applies the Rule-defined fix rule to the original test code (`path/to/rule.py`), then verifies whether this matches the expected outcome defined in the Rule-defined fix test file (`path/to/rule.fixed.py`). If there is a mismatch, the line diffs are printed.
+
+
+**INFO**
+
+**Hint**: Creating a Rule-defined fix test for a rule with Rule-defined fix can take less than a minute with the following flow of commands:
+```sh
+cp rule.py rule.fixed.py
+semgrep --config rule.yaml rule.fixed.py --autofix
+```
+
+These commands apply the Rule-defined fix to the test code. After Semgrep delivers a fix, inspect whether the outcome of this fix is as expected (for example, using `vimdiff rule.py rule.fixed.py`).
+
+
+## Example
+
+Consider the following rule:
+
+```yaml
+rules:
+- id: insecure-eval-use
+ patterns:
+ - pattern: eval($VAR)
+ - pattern-not: eval("...")
+ fix: secure_eval($VAR)
+ message: Calling 'eval' with user input
+ languages: [python]
+ severity: MEDIUM
+```
+
+If the filename with the preceeding rule is `rules/detect-eval.yaml`, you can create `rules/detect-eval.py`:
+
+```python
+from lib import get_user_input, safe_get_user_input, secure_eval
+
+user_input = get_user_input()
+# ruleid: insecure-eval-use
+eval(user_input)
+
+# ok: insecure-eval-use
+eval('print("Hardcoded eval")')
+
+totally_safe_eval = eval
+# todoruleid: insecure-eval-use
+totally_safe_eval(user_input)
+
+# todook: insecure-eval-use
+eval(safe_get_user_input())
+```
+
+Run the tests with the following:
+
+```sh
+semgrep --test rules/
+```
+
+This produces the following output:
+
+```sh
+1/1: ✓ All tests passed
+No tests for fixes found.
+```
+
+Semgrep tests automatically avoid failing on lines marked with `# todoruleid` or `# todook`.
+
+## Store rules and test targets in different directories
+
+Creating different directories for rules and tests helps you manage a growing library of custom rules. To store rules and test targets in different directories, use the `--config` option.
+
+For example, in the directory with the following structure:
+
+```sh
+$ tree tests
+
+tests
+├── rules
+│ └── python
+│ └── insecure-eval-use.yaml
+└── targets
+ └── python
+ └── insecure-eval-use.py
+
+4 directories, 2 files
+```
+
+Use of the following command
+
+```sh
+semgrep --test --config tests/rules/ tests/targets/
+```
+
+Produces the same output as in the previous example.
+
+The subdirectory structure of these two directories must be the same for Semgrep to correctly find the associated files.
+
+To test the Rule-defined fix behavior, add the Rule-defined fix test file `rules/detect-eval.fixed.py` to represent the expected outcome of applying the fix to the test code:
+
+```python
+from lib import get_user_input, safe_get_user_input, secure_eval
+
+user_input = get_user_input()
+# ruleid: insecure-eval-use
+secure_eval(user_input)
+
+# ok: insecure-eval-use
+eval('print("Hardcoded eval")')
+
+totally_safe_eval = eval
+# todoruleid: insecure-eval-use
+totally_safe_eval(user_input)
+
+# todook: insecure-eval-use
+secure_eval(safe_get_user_input())
+```
+
+So that the directory structure is printed as the following:
+
+```sh
+$ tree tests
+
+tests
+├── rules
+│ └── python
+│ └── insecure-eval-use.yaml
+└── targets
+ └── python
+ └── insecure-eval-use.py
+ └── insecure-eval-use.fixed.py
+
+4 directories, 2 files
+```
+
+Use of the following command:
+
+```sh
+semgrep --test --config tests/rules/ tests/targets/
+```
+
+Results in the following outcome:
+
+```sh
+1/1: ✓ All tests passed
+1/1: ✓ All fix tests passed
+```
+
+If the fix does not behave as expected, the output prints a line diff.
+For example, if you replace `secure_eval` with `safe_eval`, you can see that lines 5 and 15 do not render as expected.
+
+```sh
+1/1: ✓ All tests passed
+0/1: 1 fix tests did not pass:
+--------------------------------------------------------------------------------
+ ✖ targets/python/detect-eval.fixed.py <> autofix applied to targets/python/detect-eval.py
+
+ ---
+ +++
+ @@ -5 +5 @@
+ -safe_eval(user_input)
+ +secure_eval(user_input)
+ @@ -15 +15 @@
+ -safe_eval(safe_get_user_input())
+ +secure_eval(safe_get_user_input())
+
+```
+
+## Validating rules
+
+You can run `semgrep --validate --config [filename]` to verify the rule's configuration. This command runs a combination of Semgrep rules and OCaml checks against your rules to search for issues such as duplicate patterns and missing fields. All rules submitted to the Semgrep Registry are validated.
+
+The semgrep rules are pulled from `p/semgrep-rule-lints`.
+
+This feature is still experimental and under active development. Your feedback is welcomed!
+
+## Enable Rule-defined fix in Semgrep Code
+
+To enable Rule-defined fix for all projects in your Semgrep organization:
+
+
+
+In Semgrep AppSec Platform, go to [**Settings > General > Code**](https://semgrep.dev/orgs/-/settings/general/code).
+
+
+Click the **Rule-defined fix** toggle to enable this feature.
+
+