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 inpan 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 asecurity: 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 viauv
(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
Withsecurity.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
Withsecurity.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
Thesemgrep skill covers triage, a justified nosemgrep, and custom rules. It is hidden at
launch while Semgrep is off (security.semgrep.enabled: false).
Verification gate
Withenabled: 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:
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.
~/.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.enabledis false;- the project is unknown, has no
github_repo, or is polyrepo (workspace.reposis set); originis not the project’sgithub_repo(a fork, for example);- a
configsentry isauto, an absolute path, contains a..segment, or has a character outsideA-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-ciexists onoriginwith no open pull request.
What the workflow runs
One job, namedsemgrep, 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 everysecurity.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 asp/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.