Skip to main content

Semgrep (opt-in SAST)

Overdeck can install and manage its own copy of Semgrep, a static analysis (SAST) scanner. It is off by default.

What it is

Turning the feature on makes Overdeck install a pinned Semgrep binary and report its health in pan doctor. It also adds in-session tools (#4591): a semgrep MCP server, a post-edit scan hook, and a semgrep skill. The verification gate runs a sast scan of each branch, and its findings go to the security review lane (#4590). pan semgrep ci-setup opens a pull request that adds a Semgrep GitHub Actions workflow (see CI workflow below). A Codex edit hook (#5434) and a Platform/Guardian tier (#4593) are planned but not part of this release. Findings in the dashboard (#5449) are planned.

Turn it on

Add a security: block to ~/.overdeck/config.yaml:
mcp and edit_hook each default to false and do nothing unless enabled is also true. The four gate keys show their defaults; see Verification gate. Then run pan sync (or pan install) to trigger the managed install. A config change reaches new agent sessions only; it does not affect an agent already running. You can also set every key in the dashboard: Settings → Security. Each control saves only its own key, so comments and other settings in config.yaml are kept. A repo-committed .pan.yaml project layer cannot set security; any security: block there is silently ignored. A work agent can commit a .pan.yaml to its own feature branch, so a security setting that controls whether a scanner runs must come only from a file the operator owns, never from a file in the tree being scanned.

What gets installed

Semgrep Community Edition 1.180.0 (pinned), installed via uv (falling back to pipx when uv is not available) into ~/.overdeck/tools/semgrep/, with a launcher symlinked at ~/.overdeck/bin/semgrep, the only path Overdeck ever runs Semgrep from. The install is about 350 MB and happens once per machine; a version check on every pan sync reinstalls only when the pinned version drifts. Your own Semgrep install, wherever it lives (~/.local/bin/semgrep, a different uv tool, pipx, Homebrew, or anywhere else on PATH), is never touched, overwritten, or removed. Overdeck’s installer refuses to replace anything at ~/.overdeck/bin/semgrep that it did not create itself. A regular file or a symlink pointing somewhere else there is left alone, and the install reports failed with a fix telling you to move it out of the way first. If neither uv nor pipx is on the host, the install reports failed with the message “Neither uv nor pipx is installed” and a fix pointing at the uv install docs.

pan doctor

With the feature off, pan doctor prints no Semgrep rows at all. With it on:

In-session tools

No MCP server or edit hook runs in Docker workspaces or on Windows.

semgrep MCP server

With security.semgrep.mcp: true, work agents and the review security lane get a semgrep MCP server. The scan, findings and supply-chain tools are turned off because they fail without a Semgrep login or with metrics off. Scan with the CLI through the semgrep skill. The MCP server is skipped with a warning when the semgrep launcher is missing or not Overdeck’s. The server adds about 100 MB per agent.

Post-edit scan hook

With security.semgrep.edit_hook: true, every Claude Code agent (not a conversation) gets Semgrep’s findings for each file it edits. The hook scans only the edited file with p/default plus the repo’s own .semgrep.yml/.semgrep/ rules, and takes about 2 seconds per edit. It skips files over 1 MiB, files under node_modules/, .git/ or dist/, and non-code extensions such as .md, .svg or .lock. It stays silent when the scan is clean or on any error (it never blocks the edit), and a finding arrives as context for the agent to triage, not as a block.

semgrep skill

The semgrep skill covers triage, a justified nosemgrep, and custom rules. It is hidden at launch while Semgrep is off (security.semgrep.enabled: false).

Verification gate

With enabled: true, every verification run ends with a built-in sast check. It scans the files the branch added, modified or renamed, and counts only findings on lines the branch added at or above severity. It never uses Semgrep’s --baseline-commit mode. A missing binary, a scanner error (an unreachable registry exits 2), a timeout after timeout_seconds, or unreadable output never blocks a merge, in any mode. The skip is visible in the verification artifact and the Test/Lint transcript. In a polyrepo workspace each repo is scanned on its own: a finding in a repo that was scanned still counts, and a repo that could not be scanned is named in the result and in the review context. To set the mode for one project, add verification.sast to that project in ~/.overdeck/projects.yaml, or use the Semgrep gate control in the project’s Project settings:
It overrides security.semgrep.gate for that project only. It cannot turn Semgrep on: with enabled: false no scan runs. A repo’s own .pan.yaml cannot set it. The gate also lists every new suppression in the diff: an added nosemgrep comment, an edit to a .semgrepignore, and a change to a repo-local rule file (a configs path, .semgrep.yml, or .semgrep/). Suppressions never fail the gate. The security review lane receives the findings and the suppressions, and confirms or dismisses each one. If you would rather run your own Semgrep command, a plain quality gate in projects.yaml also works, for example quality_gates.semgrep: { command: "semgrep scan --config p/default --error .", required: true }. Do not name it sast, which is the built-in check’s name. That gate blocks on any finding in the whole tree, and it is not diff-scoped.

CI workflow

pan semgrep ci-setup <project> opens a pull request that adds .github/workflows/semgrep.yml to the project’s GitHub repository. Overdeck never rewrites the file; delete it to stop CI scans. See CI integrations for the other CI systems Overdeck reads.
The command commits in a throwaway worktree under ~/.overdeck/tmp/semgrep-ci-setup/, pushes the branch overdeck/semgrep-ci, and opens the pull request into the base branch (workspace.pr_target, then workspace.default_branch, then origin/HEAD, then main). It never pushes to the base branch and never touches the project’s checkout. If a pull request from overdeck/semgrep-ci is already open, it prints that URL and changes nothing. It refuses, with exit code 1 and a one-line reason, when:
  • security.semgrep.enabled is false;
  • the project is unknown, has no github_repo, or is polyrepo (workspace.repos is set);
  • origin is not the project’s github_repo (a fork, for example);
  • a configs entry is auto, an absolute path, contains a .. segment, or has a character outside A-Z a-z 0-9 . _ / @ : + -;
  • the base branch name has a character outside A-Z a-z 0-9 . _ / -;
  • the base branch already has .github/workflows/semgrep.yml;
  • the branch overdeck/semgrep-ci exists on origin with no open pull request.

What the workflow runs

One job, named semgrep, so GitHub names its check semgrep. It runs semgrep scan in the pinned semgrep/semgrep:1.180.0 image with one --config per configs entry, --metrics off and --sarif-output=semgrep.sarif, with contents: read permission and no Semgrep account or token. A pull request is scanned diff-aware (--baseline-commit at the merge base), so only findings on code the pull request adds are reported. CI uses the same severity threshold as the local gate (ERROR scans with --severity ERROR, WARNING adds --severity WARNING, INFO passes no flag). Dependabot pull requests are scanned too. The job’s OVERDECK_SEMGREP_GATE line holds the gate mode, read once from the project’s verification.sast or from security.semgrep.gate:
The workflow does not follow later config changes. To change the gate, edit the OVERDECK_SEMGREP_GATE line to blocking or advisory. In blocking mode a scanner error (for example an unreachable registry) also fails the pull request check, unlike the local sast gate, which skips on a scanner error. --sarif-upload adds a trigger on pushes to the base branch, an upload-sarif step, and the security-events: write and actions: read permissions. A push run scans the whole tree and never fails the job, and a failed upload never fails it either. GitHub code scanning may then add its own check, governed by the repository’s code-scanning settings, not by OVERDECK_SEMGREP_GATE. The generated commit and push skip repository hooks (--no-verify): the throwaway worktree has no installed dependencies, and the pull request’s CI and review gate the one generated file. Pushing a file under .github/workflows/ needs a credential with the workflow scope. When GitHub refuses the push for that reason, run gh auth refresh -s workflow (HTTPS remotes) or push over SSH, then run the command again.

Dashboard

Settings → Security edits every security.semgrep key without hand-editing ~/.overdeck/config.yaml: Each control writes only its own key, so comments and every other setting in config.yaml survive the save, and an invalid value is rejected without writing anything. A gate mode, severity, rule configs or timeout change applies to the next verification run; the MCP server and edit hook apply to agent sessions started after the change; neither one affects an agent already running. Project settings has a Semgrep gate control (Off / Advisory / Blocking / Global default) that writes verification.sast for that project only. It shows the effective mode and its reason, and says plainly when Semgrep is off for every project. Like the YAML key, it cannot turn Semgrep on.

Harness support

Data egress

MCP tracing is disabled (SEMGREP_MCP_DISABLE_TRACING=true), and every in-session and gate Semgrep process writes its state to ~/.overdeck/tools/semgrep/ instead of the default ~/.semgrep/. The gate also removes SEMGREP_APP_TOKEN and SEMGREP_RULES from the scan’s environment.

Licensing

The Semgrep engine is licensed under LGPL-2.1. Registry rule packs (such as p/default) are licensed under the Semgrep Rules License v1.0 and are downloaded only by your own CLI, on your own machine, when a scan runs. Overdeck never bundles or serves rule packs itself.

Platforms

Linux and macOS. Windows is unsupported: ensureSemgrepInstalled returns unsupported immediately on win32, before any install attempt.