Semgrep

Semgrep integration allows your product to connect with Semgrep's security analysis platform to fetch scan results, findings, rules, and project metadata. This integration is ideal for source code analysis, static application security testing (SAST), and continuous vulnerability management workflows, enabling your product to ingest security findings directly from Semgrep scans. Semgrep supports both cloud-based (Semgrep App) and self-hosted (Semgrep CI) environments, with authentication via an API token.

Credentials Needed

To integrate with Semgrep's API, you need:

Required credentials:

• Semgrep API Token (organization-level or user-level)
• (Optional) Organization ID (for multi-org setups in Semgrep Cloud)

The API Token provides access to your organization's Semgrep Cloud data. Use organization-scoped tokens when available.

Permissions Needed / API Scopes

Semgrep API tokens inherit permissions from the associated user or organization. There are no granular OAuth scopes — permissions are role-based.

Permission	Description
Read Scans	Required to read scan results and findings
Read Rules	Required to fetch rule metadata
Read Projects	Required to list repositories or projects
Trigger Scans (optional)	Allows initiating scans remotely (CI/CD automation)

Minimum Required Permissions: Read access to Scans, Findings, and Projects

Creating Users / Access Tokens

Step 1: Generate a Semgrep API Token

1. Log in to your Semgrep Cloud account: https://semgrep.dev/login
2. Go to your Organization Settings → API Tokens
3. Click Create API Token
4. Enter a descriptive name (e.g., PlatformIntegrationToken)
5. Copy the generated token — e.g.: sgp_123456789abcdef...
6. Store it securely in your product's encrypted vault

Organization owners can also generate org-wide tokens to allow integrations across multiple projects.

Test Connectivity

You can validate the token by listing Semgrep projects or scans.

Example: Test API Token

curl -X GET "https://semgrep.dev/api/v1/me" \
  -H "Authorization: Bearer <SEMGREP_API_TOKEN>"

Example Response:

{
  "user": {
    "id": "user_12345",
    "email": "security@company.com",
    "organizations": [
      {"id": "org_67890", "name": "Security Team"}
    ]
  }
}

List Projects (Repositories)

curl -X GET "https://semgrep.dev/api/v1/orgs/<ORG_ID>/projects" \
  -H "Authorization: Bearer <SEMGREP_API_TOKEN>"

Example Response:

{
  "projects": [
    {
      "id": "proj_123",
      "name": "backend-api",
      "provider": "github",
      "url": "https://github.com/company/backend-api"
    }
  ]
}

List Recent Scans

curl -X GET "https://semgrep.dev/api/v1/orgs/<ORG_ID>/scans" \
  -H "Authorization: Bearer <SEMGREP_API_TOKEN>"

Example Response:

{
  "scans": [
    {
      "id": "scan_456",
      "project_id": "proj_123",
      "started_at": "2025-10-13T09:00:00Z",
      "status": "success",
      "findings_count": 24
    }
  ]
}

Fetch Findings for a Specific Scan

curl -X GET "https://semgrep.dev/api/v1/orgs/<ORG_ID>/scans/<SCAN_ID>/findings" \
  -H "Authorization: Bearer <SEMGREP_API_TOKEN>"

Example Response:

{
  "findings": [
    {
      "check_id": "python.lang.security.audit.os-system-injection.os-system-injection",
      "severity": "HIGH",
      "message": "Detected use of os.system() which may allow command injection.",
      "path": "app/main.py",
      "line": 42,
      "fixable": true,
      "cwe": "CWE-78"
    }
  ]
}

Save the Results in the Platform and Create Connection

1. In your platform's integration setup, securely store:
   • SEMGREP_API_TOKEN
   • (Optional) SEMGREP_ORG_ID
2. Label the connection as Semgrep Integration
3. Test the connection by listing organizations or projects
4. Once verified, enable workflows such as:
   • Pulling scan results and mapping them to your vulnerability records
   • Linking findings to repository metadata
   • Aggregating results across Semgrep projects for risk dashboards

Best Practices

• Use organization-level API tokens for shared integrations
• Store tokens securely in your platform's secret vault
• Rotate tokens every 90 days
• Schedule incremental fetches of new scans (e.g., every 6–12 hours)
• Implement rate limiting (default API limit: ~60 requests/minute)
• Use pagination (?page=<n>&per_page=<n>) for large result sets
• Map findings to CWE and OWASP categories for standardized analysis
• Track project URLs to link Semgrep findings with source repositories
• Handle HTTP 401 (unauthorized) and 429 (rate-limit) responses gracefully

Useful Semgrep API Endpoints

Resource	Method	Endpoint	Description
Get user info	GET	/api/v1/me	Validate API token and get user/org info
List orgs	GET	/api/v1/orgs	List all organizations the token has access to
List projects	GET	/api/v1/orgs/{org_id}/projects	Retrieve all linked repositories
List scans	GET	/api/v1/orgs/{org_id}/scans	List recent Semgrep scans
Get scan details	GET	/api/v1/orgs/{org_id}/scans/{scan_id}	Retrieve scan metadata
List findings	GET	/api/v1/orgs/{org_id}/scans/{scan_id}/findings	Retrieve findings from a specific scan
List rules	GET	/api/v1/rules	Get available Semgrep rules
Trigger scan	POST	/api/v1/orgs/{org_id}/projects/{project_id}/scans	Trigger a new scan (if supported)

Official Docs: https://semgrep.dev/docs/api

Example: Unified Finding Schema for Your Platform

{
  "tool": "semgrep",
  "project": "backend-api",
  "path": "app/main.py",
  "line": 42,
  "severity": "HIGH",
  "title": "os.system() command injection",
  "cwe": "CWE-78",
  "fixable": true,
  "rule": "python.lang.security.audit.os-system-injection.os-system-injection",
  "description": "Detected use of os.system() which can lead to command injection.",
  "link": "https://semgrep.dev/s/python.lang.security.audit.os-system-injection"
}

Webhook Integration (Optional)

Semgrep Cloud allows webhook notifications for new scan results.

Setup Steps

1. Go to Organization Settings → Webhooks
2. Click Add Webhook
3. Set Target URL = your platform's webhook listener (e.g., https://yourplatform.com/webhooks/semgrep)
4. Choose event types:
   • scan_completed
   • project_added
   • finding_created
5. Save and test the webhook

Your system will now receive JSON payloads when new Semgrep scans finish or findings are created.

Example Webhook Payload

{
  "event": "scan_completed",
  "org_id": "org_67890",
  "project_id": "proj_123",
  "scan_id": "scan_456",
  "findings_count": 12,
  "timestamp": "2025-10-13T10:45:00Z"
}

Example Workflow

1. Detect new scan event via webhook
2. Call /findings API to fetch detailed results
3. Normalize and ingest vulnerabilities into your platform
4. Correlate findings with developer repositories (GitHub, GitLab, etc.)
5. Provide links back to Semgrep dashboard for remediation