Semgrep CI

Semgrep CI (aka Semgrep Action or semgrep-agent) is a specialized Docker image for running Semgrep in CI environments. It can also optionally connect to Semgrep App for centralized rule and findings management.

• Scan every commit. Semgrep CI rapidly scans modified files on pull and merge requests, protecting developer productivity. Longer full project scans are configurable on merges to specific branches.
• Block new bugs. You shouldn’t have to fix existing bugs just to adopt a tool. Semgrep CI reports newly introduced issues on pull and merge requests, scanning them at their base and HEAD commits to compare findings. Developers are signficantly more likely to fix the issues they introduced themselves on PRs and MRs.
• Get findings where you work. Semgrep CI can connect to Semgrep App to present findings in Slack, on PRs and MRs via inline comments, email, and through 3rd party services.

Semgrep CI runs fully in your build environment: code is never sent anywhere.

Getting started

Semgrep CI behaves like other static analysis and linting tools: it runs a set of user-configured rules and returns a non-zero exit code if there are findings, resulting in its job showing a ✅ or ❌.

Find a relevant template for your CI provider through these links:

• GitHub Actions
• GitLab CI/CD
• Other CI providers (Buildkite, CircleCI, Jenkins, and more)

Read through the comments in the template to adjust when and what Semgrep CI scans, selecting pull and merge requests, merges to branches, or both.

Once Semgrep CI is running, explore the Semgrep Registry to find and add more project-specific rules.

Configuration

See Advanced Configuration documentation for further customizations, such as scanning with custom rules, ignoring files, and tuning performance.

Metrics

Semgrep CI collects opt-out non-identifiable aggregate metrics for improving the user experience, guiding Semgrep feature development, and identifying regressions.

The PRIVACY.md file describes the principles that guide our data-collection decisions, the breakdown of the data that are and are not collected, and how to opt-out of Semgrep CI’s metrics.

Semgrep CI never sends your source code anywhere.

Technical details

Packaging

Semgrep CI is published under the name semgrep-agent.

• The semgrep_agent Python package uses this name.
• The semgrep-agent Docker image also uses this name.
• The semgrep-action GitHub Marketplace listing runs the above Docker image.
• The semgrep-action repository holds the code for Semgrep CI, the Docker image, and the GitHub Marketplace manifest.

New versions of Semgrep CI and the Docker image above are released by Semgrep maintainers on a regular basis. To run all jobs with the latest releases, use returntocorp/semgrep-action@v1 in your GitHub Actions workflow, or the returntocorp/semgrep-agent:v1 Docker image with other providers.

The Python package itself is not published to PyPI, or any other package index, but you can still use it by cloning the GitHub repository.

Usage outside CI

While Semgrep CI is designed for integrating with various CI providers, it's versatile enough to be used locally to scan a repository with awareness of its git history.

To locally scan issues in your current branch that are not found on the main branch, run the following command:

docker run -v $(pwd):/src --workdir /src returntocorp/semgrep-agent:v1 semgrep-agent --config p/ci --baseline-ref main

Another use case is when you want to scan only commits from the past weeks for new issues they introduced. This can be done by using a git command that gets the tip of the current branch two weeks earlier:

docker run -v $(pwd):/src --workdir /src returntocorp/semgrep-agent:v1 semgrep-agent --config p/ci --baseline-ref $(git rev-parse '@{2.weeks.ago}')

To compare two commits and find the issues added between them, checkout the more recent commit of the two before running Semgrep CI:

git checkout $RECENT_SHA
docker run -v $(pwd):/src --workdir /src returntocorp/semgrep-agent:v1 semgrep-agent --config p/ci --baseline-ref $OLDER_SHA

The above commands all require docker to be installed on your machine. They also use Docker volumes to make your working directory accessible to the container. --config p/ci is the Semgrep rule configuration, which can be changed to any value that semgrep itself understands.

Contributing

See CONTRIBUTING.md