The Problem
Developers need a fast, language‑agnostic way to locate bug patterns, security issues, and style violations without writing complex regular expressions or custom AST walkers. Traditional static analysis tools can be heavyweight, hard to extend, or require deep knowledge of internal representations.
What This Does
semgrep provides a “semantic grep” engine that lets users write search rules that look like ordinary source code. The core CLI lives under cli/src/semgrep/ with entry points such as main.py, cli.py, and main.py. The rule engine (engine.py, corerunner.py) parses code into an AST, matches rule patterns, and outputs results in multiple formats (formatter/json.py, formatter/sarif.py, formatter/gitlabsast.py).
The repository is split into two logical parts: the CLI package (cli/ with its own pyproject.toml and setup.py) and the library code (cli/src/semgrep/). Docker support is provided via the top‑level Dockerfile and a suite of GitHub Actions workflows that build and test the tool on several platforms.
How To Use It
Setup
Build the container (optional) docker build -t semgrep:local .
Install the CLI locally (requires Python 3.9+)
cd cli python -m pip install -e . # editable install pulls deps from pyproject.toml
The pyproject.toml lists runtime dependencies (e.g., click, pyyaml, packaging). The top‑level Makefile defines a make install target that mirrors the pip command above.
Configuration
Environment variables used by the CLI are defined in cli/src/semgrep/env.py (e.g., SEMGREPAPPTOKEN). No default config file is required; flags are exposed via cli/src/semgrep/cli.py.
Running it
Basic scan of a Python project semgrep scan --config=p/r2c-python --verbose path/to/code
Export findings as SARIF
semgrep scan --config=p/r2c-python --output=results.sarif --format=sarif .
The scan command maps to cli/src/semgrep/commands/scan.py, which ultimately invokes cli/src/semgrep/main.py.
Real‑World Use
A CI pipeline can enforce security policies by adding a step: name: Run Semgrep uses: docker://semgrep/semgrep with: args: scan --config=auto --severity=error .
The step fails the build if any rule with severity=error is triggered, providing immediate feedback to developers.
Code Health & Issues
Low – Missing lockfile – Dependencies are declared only in cli/pyproject.toml; no poetry.lock or requirements.txt makes reproducible builds harder. High – Potential secret exposure – cli/src/semgrep/formatter/gitlabsecrets.py contains placeholder logic that may inadvertently embed credentials if misused. Review before production use. Medium – Test coverage gaps – Only 15 test files are present for a codebase of >200 files; many core modules (e.g., engine.py, corerunner.py) lack direct unit tests. Low – Documentation fragmentation – README provides high‑level marketing copy but lacks concrete usage examples for the CLI flags; the docs/ folder is sparse. Medium – CI complexity – Multiple GitHub Actions workflows (build-test-*.yml) increase maintenance overhead; ensure they stay in sync with the Makefile targets.
No license issues are evident (LICENSE present at repo root and under cli/). The project uses pre‑commit hooks (.pre-commit-config.yaml) and has a CI pipeline, indicating a reasonable SDLC process.
The Bottom Line
semgrep offers a practical, extensible static analysis engine with strong language coverage and a straightforward CLI, suitable for integrating into CI/CD pipelines. However, the lack of a lockfile, limited test coverage, and a file that may contain secret‑handling logic warrant caution before adopting it in security‑critical environments. Teams that need fast, rule‑based scanning and can allocate effort to harden the build process will find it valuable.