Overview
Static application security testing (SAST) catches bugs such as SQL injection, command injection and hardcoded secrets before code ships. Semgrep Community Edition (CE) is an open-source (LGPL 2.1) scanner that matches code patterns instead of regexes, so rules read like the code they find. It supports many languages, runs in seconds, and needs no account.
In this project you will build a complete pipeline:
- A repo-local ruleset that mixes the public registry rules with your own custom rules.
- Rule unit tests, so a rule change cannot silently stop matching.
- A pre-commit hook for fast local feedback.
- A GitHub Actions workflow that fails pull requests only on new findings and uploads SARIF to the Security tab.
CE has no hosted dashboard, triage UI or PR comments (those need the paid platform and semgrep ci). We use semgrep scan and GitHub's own code scanning for triage instead.
Architecture
developer ──commit──▶ pre-commit (semgrep, p/default + .semgrep/)
│
└──push/PR──▶ GitHub Actions
├─ semgrep --test (rule unit tests)
├─ semgrep scan --baseline-commit <base> --error (gate: new findings only)
└─ semgrep scan --sarif ──▶ upload-sarif ──▶ Security tab
Design decisions:
- Rules live in the repo under
.semgrep/, reviewed like code. - Baseline scanning (
--baseline-commit) avoids failing every PR on legacy findings. Existing issues are tracked through SARIF instead. - Two scan steps: one gates the PR, one produces the full report. The report step must run even when the gate fails.
Prerequisites
- A GitHub repository with application code (the examples use Python and JavaScript)
- Python 3.9+ and
piplocally, or Docker - Permission to enable code scanning (free on public repos; private repos need GitHub Code Security)
Step 1: Install and run a first scan
python3 -m venv .venv && source .venv/bin/activate
pip install semgrep pre-commit
# Registry ruleset, no account needed
semgrep scan --config p/default .Or use the container with no local install:
docker run --rm -v "$PWD:/src" semgrep/semgrep \
semgrep scan --config p/default /srcExpect noise on a first run. Note the count; it is your baseline.
Step 2: Write custom rules
Create .semgrep/rules.yml. These rules encode house standards that generic rulesets do not know about.
rules:
- id: no-shell-true-subprocess
languages: [python]
severity: ERROR
message: >-
subprocess called with shell=True. Pass an argument list instead to
avoid command injection.
pattern: subprocess.$FUNC(..., shell=True, ...)
metadata:
cwe: "CWE-78"
category: security
- id: sql-string-formatting
languages: [python]
severity: ERROR
message: >-
SQL built with string formatting. Use parameterized queries.
pattern-either:
- pattern: $CUR.execute(f"...{$X}...")
- pattern: $CUR.execute("..." % $X)
- pattern: $CUR.execute("...".format(...))
metadata:
cwe: "CWE-89"
category: security
- id: dangerously-set-inner-html
languages: [javascript, typescript]
severity: WARNING
message: >-
dangerouslySetInnerHTML used. Sanitize with DOMPurify first and
justify with a nosemgrep comment.
pattern: <$EL dangerouslySetInnerHTML={{...}} />
metadata:
cwe: "CWE-79"
category: security
- id: hardcoded-internal-admin-token
languages: [generic]
severity: ERROR
message: Possible hardcoded admin token. Load it from the environment.
pattern-regex: (?i)admin[_-]?token\s*[:=]\s*["'][A-Za-z0-9_\-]{20,}["']
paths:
exclude:
- "*.test.*"
- "tests/"Tip: use semgrep --dump-ast and the playground when a pattern will not match, and prefer pattern-either with several concrete shapes over one clever pattern.
Step 3: Unit-test the rules
Semgrep tests are annotated source files placed beside the rule file. ruleid: marks a line that must match; ok: marks one that must not. Create .semgrep/rules.py, named to match rules.yml:
import subprocess
def bad(user_input, cur):
# ruleid: no-shell-true-subprocess
subprocess.run("ls " + user_input, shell=True)
# ruleid: sql-string-formatting
cur.execute(f"SELECT * FROM users WHERE name = '{user_input}'")
def good(user_input, cur):
# ok: no-shell-true-subprocess
subprocess.run(["ls", user_input])
# ok: sql-string-formatting
cur.execute("SELECT * FROM users WHERE name = ?", (user_input,))Run them:
semgrep --test .semgrep/A passing run reports every rule's expected matches. Wire this into CI so a bad rule edit fails the build.
Step 4: Local pre-commit hook
Create .pre-commit-config.yaml:
repos:
- repo: https://github.com/semgrep/pre-commit
rev: v1.100.0 # pin to the latest release tag you have vetted
hooks:
- id: semgrep
args:
- "--config"
- "p/default"
- "--config"
- ".semgrep/"
- "--error"
- "--skip-unknown-certs"Drop --skip-unknown-certs unless you are behind a TLS-inspecting proxy. Install it:
pre-commit install
pre-commit run --all-filesCheck the actual latest tag on the hook repository before pinning, and let a dependency bot keep it current.
Step 5: GitHub Actions workflow
Create .github/workflows/semgrep.yml:
name: Semgrep
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
jobs:
rule-tests:
runs-on: ubuntu-latest
container: semgrep/semgrep
steps:
- uses: actions/checkout@v4
- run: semgrep --test .semgrep/
gate:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
container: semgrep/semgrep
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # baseline scan needs the base commit
- name: Mark workspace safe
run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
- name: Fail only on new findings
run: |
semgrep scan \
--config p/default --config .semgrep/ \
--baseline-commit "${{ github.event.pull_request.base.sha }}" \
--error --metrics=off
report:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
container: semgrep/semgrep
steps:
- uses: actions/checkout@v4
- name: Full scan to SARIF
run: |
semgrep scan \
--config p/default --config .semgrep/ \
--sarif --output semgrep.sarif --metrics=off
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: semgrep.sarifNotes:
- The default shallow checkout lacks the base commit, which is why
fetch-depth: 0matters for baseline scans. security-events: writeis only granted to the report job, keeping the gate job least-privilege.--metrics=offdisables anonymous usage telemetry.- Pin third-party actions to commit SHAs for stricter supply-chain hygiene.
- Fork PRs get a read-only token, so SARIF upload will fail there. Restrict
reporttopushevents if you accept outside contributions.
Step 6: Handle false positives
Suppress a single line with a justified comment:
subprocess.run(cmd, shell=True) # nosemgrep: no-shell-true-subprocess -- cmd is a constantExclude paths in a .semgrepignore file (gitignore syntax):
tests/
vendor/
*.min.js
Require that every nosemgrep includes a reason; a simple CI grep for bare nosemgrep with no explanation keeps suppressions honest.
Testing
- Rule tests:
semgrep --test .semgrep/passes locally and in CI. - Local hook: add a deliberate
subprocess.run(x, shell=True)to a file,git commit, and confirm the hook blocks it. - PR gate: open a PR containing that line. The
gatejob should fail and name the rule. Open another PR with only a pre-existing finding touched elsewhere: it should pass. - SARIF: after the
reportjob, open Security → Code scanning and confirm alerts appear with rule IDs and CWE metadata. - Negative control: fix the line and confirm the PR goes green.
Deployment
- Make
rule-testsandgaterequired status checks in branch protection so findings cannot be merged around. - Roll out in stages: begin with the report job only (informational), triage the backlog in the Security tab, then enable the gate once the noise is understood.
- Centralize rules by moving
.semgrep/into a sharedsecurity-rulesrepository and checking it out in each workflow, so one rule fix protects every repo. - Run a scheduled full scan weekly (
on: schedule) because registry rules improve over time and may flag old code.
Extensions and next steps
- Taint tracking: Semgrep CE supports
mode: taintrules with sources, sinks and sanitizers for intra-file flows (cross-file analysis is a paid feature). - Autofix: add a
fix:key to rules for mechanical corrections, and apply withsemgrep scan --autofix. - Secrets and dependencies: pair this with a secret scanner and a dependency scanner such as Trivy or OSV-Scanner; SAST does not cover either.
- Metrics: export SARIF counts to your monitoring stack to track findings over time.
- Triage workflow: route high-severity code scanning alerts to your ticketing or chat tool.