# Semgrep

{% hint style="info" %}
Cortex connects to many third-party vendors whose system interfaces frequently change. As a result, integration behavior or configuration steps may shift without notice. If you encounter unexpected issues, check with your system administrator or refer to the vendor's documentation for the most current information. Additionally, integration sync times vary and are subject to scheduling overrides and timing variance.
{% endhint %}

[Semgrep](https://semgrep.dev/) is static application security testing (SAST) tool that includes software composition analysis (SCA). It detects security vulnerabilities in your code and analyzes your open-source dependencies for vulnerabilities. You can use it to scan local repositories or integrate it into your CI/CD pipeline.

Integrating Semgrep with Cortex allows you to:

* Display the latest scans and vulnerability data [on entity details pages in Cortex](#viewing-semgrep-information-in-cortex)
* Create [Scorecards](#scorecards-and-cql) that track progress and drive alignment on projects involving Semgrep security data, allowing you to address and remediate vulnerabilities more efficiently

## How to configure Semgrep with Cortex

### Prerequisites

Before getting started:

* Create an [API token in Semgrep](https://semgrep.dev/api/v1/docs/#section/Introduction) with [`GET scan details`](https://semgrep.dev/api/v1/docs/#tag/Scan/operation/semgrep_app.foundations.scan.handlers.scan.openapi_get_scan) and [`GET List code or supply chain findings`](https://semgrep.dev/api/v1/docs/#tag/Finding) permissions.

### Configure the integration in Cortex

1. In Cortex, navigate to the [Semgrep settings page](https://app.getcortexapp.com/admin/integrations/semgrep):
   * Click **Integrations** from the main nav. Search for and select **Semgrep**.
2. Click **Add configuration**.
3. Configure the Semgrep integration form:
   * **Alias**: Enter an alias for this integration.
   * **API key**: Enter the value of the API token you created in Semgrep.
   * **Organization ID**: Enter your organization ID for Semgrep.
   * **Organization slug**: Enter your organization slug for Semgrep.
4. Click **Save**.

After saving your configuration, you are redirected to the Semgrep integration settings page in Cortex. In the upper right corner of the page, click **Test configuration** to ensure Semgrep was configured properly.

## How to connect Cortex entities to Semgrep

### Match entity names to Semgrep projects

By default, Cortex will use the [Cortex tag](https://docs.cortex.io/entities#cortex-tag) (e.g. `my-service`) as the "best guess" for Semgrep projects. For example, if your entity name is "My Service" or your tag is `my-service`, then the corresponding project name in Semgrep should also be "My Service" or `my-service`.

If your Semgrep project names don’t cleanly match the Cortex entity name or tag, you can override this in the Cortex entity descriptor.

### Editing the entity descriptor

Under the `x-cortex-semgrep` block in an [entity's YAML](https://docs.cortex.io/entities#defining-entities-via-yaml-file), you can define the projects you want based on the Semgrep project ID. For example:

```yaml
x-cortex-semgrep:
  projects:
  - alias: my_org 
    projectId: 1234567
  - alias: other_org
    projectId: 7654321
```

## Using the Semgrep integration

### Viewing Semgrep information in Cortex

Semgrap vulnerabilities and scans appear on [entity details pages](https://docs.cortex.io/ingesting-data-into-cortex/entities/details):

* in the **Code & security** block in the entity's overview:\\

  <div align="left"><figure><img src="https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-e46d8071830d28166bca2d0e39a057d9f5708b78%2Fsemgrep-entity-overview.jpg?alt=media" alt="See Semgrep data on an entity&#x27;s overview." width="563"><figcaption></figcaption></figure></div>
* in the entity's sidebar in **Code & security.**

  * This page contains scan results and vulnerability metrics from Semgrep. Click **Filter** at the top of the vulnerability list to filter by severity.

  <div align="left"><figure><img src="https://826863033-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FJW7pYRxS4dHS3Hv6wxve%2Fuploads%2Fgit-blob-0497bec10b502cf23b0eded8c570a8fc6e2dad53%2Fsemgrep-entity-details.jpg?alt=media" alt="On an entity, click Code &#x26; security > Semgrep to view vulnerability details from Semgrep." width="563"><figcaption></figcaption></figure></div>

### Scorecards and CQL

With the Semgrep integration, you can create Scorecard rules and write CQL queries based on Semgrep projects.

See more examples in the [CQL Explorer](https://app.getcortexapp.com/admin/cql-explorer) in Cortex.

<details>

<summary>Check if Semgrep project is set</summary>

Check if entity has a registered Semgrep project in its entity descriptor.

**Definition:** `semgrep (==/!=) null: Boolean`

**Example**

An initial level in a security Scorecard might include a rule to make sure entities are associated with a Semgrep project:

```
semgrep != null
```

Setting a `semgrep != null` rule can also serve as a secondary check to confirm an entity is synced properly with Semgrep and is reporting frequently.

</details>

<details>

<summary>List vulnerabilities</summary>

List of Semgrep vulnerabilities by severity or type.

**Definition:** `semgrep.vulnerabilities()`

**Example**

You can write a rule to verify an entity has fewer than 10 vulnerabilities:

```
semgrep.vulnerabilities().length < 10
```

</details>

<details>

<summary>Get scan results for an entity</summary>

Get Semgrep scan results for an entity.

**Definition**: `semgrep.scans()`

You could write a Scorecard rule to ensure an entity has fewer than 10 scans:

```
semgrep.scans().length < 10
```

You could write a rule to ensure an entity has had fewer than 10 new scans in the last week:

```
semgrep.scans("firstSeen:-1w") <= 10
```

</details>

### View integration logs <a href="#still-need-help" id="still-need-help"></a>

## Still need help?[​](https://docs.cortex.io/docs/reference/integrations/aws#still-need-help) <a href="#still-need-help" id="still-need-help"></a>

The following options are available to get assistance from the Cortex Customer Engineering team:

* **Email**: <help@cortex.io>, or open a support ticket in the in app Resource Center
* **Slack**: Users with a connected Slack channel will have a workflow added to their account. From here, you can either @CortexTechnicalSupport or add a `:ticket:` reaction to a question in Slack, and the team will respond directly.

Don’t have a Slack channel? Talk with your Customer Success Manager.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortex.io/ingesting-data-into-cortex/integrations/semgrep.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.