> ## Documentation Index
> Fetch the complete documentation index at: https://panopticon-cli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Semgrep (opt-in SAST)

> Opt-in, off-by-default Semgrep CLI managed by Overdeck

# Semgrep (opt-in SAST)

Overdeck can install and manage its own copy of [Semgrep](https://semgrep.dev), 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](#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`:

```yaml theme={null}
security:
  semgrep:
    enabled: true
    mcp: true
    edit_hook: true
    gate: advisory          # off | advisory | blocking
    severity: ERROR         # INFO | WARNING | ERROR
    configs: [p/default]    # registry ids or repo-relative rule paths
    timeout_seconds: 300
```

`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](#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`](https://docs.astral.sh/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](https://docs.astral.sh/uv/getting-started/installation/).

## `pan doctor`

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

| Condition | Row | Status |
| - | - | - |
| Not installed | `Enabled, but not installed at ~/.overdeck/bin/semgrep` | error, fix `pan sync` |
| Installed, version mismatch | `Installed <v>, expected 1.180.0` | warn, fix `pan sync` |
| Installed, pinned version | `1.180.0 (pinned)` | ok |
| `semgrep.dev` reachable | `semgrep.dev reachable` | ok |
| `semgrep.dev` unreachable, non-2xx/3xx, or a 5s timeout | `semgrep.dev unreachable`, followed by a note that registry rule packs such as `p/default` cannot be downloaded | warn |
| Platform is Windows | `Enabled, but Semgrep support is Linux and macOS only` | warn |

## 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.

| `gate` | A counted finding | Semgrep missing or failing |
| - | - | - |
| `off` | No scan runs | No scan runs |
| `advisory` (default) | Recorded in the verification artifact and the review context; the run still passes | The check is marked skipped with the reason; the run still passes |
| `blocking` | Verification fails with `failedCheck: sast`, and the work agent gets the file, line, rule id, message and fix hint | The check is marked skipped with the reason; the run still passes |

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:

```yaml theme={null}
projects:
  myapp:
    verification:
      sast: blocking        # off | advisory | blocking
```

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](https://panopticon-cli.com/integrations/ci.md) for the other CI systems Overdeck reads.

```bash theme={null}
pan semgrep ci-setup myapp --dry-run       # print the target and the workflow; change nothing
pan semgrep ci-setup myapp                 # open the pull request
pan semgrep ci-setup myapp --sarif-upload  # also upload results to GitHub code scanning
```

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`:

```yaml theme={null}
    env:
      OVERDECK_SEMGREP_GATE: advisory
```

| Gate mode | The `semgrep` check |
| - | - |
| `blocking` | A pull request that adds a finding fails the `semgrep` check; the work agent gets the findings with fix and suppression instructions |
| `advisory` or `off` | The check never fails; findings appear as warnings in the job log |

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`:

| Row | Does |
| - | - |
| Semgrep | Turns the feature on or off (`enabled`) |
| Managed install | Shows whether the pinned CLI is installed and, while off, is disabled; otherwise an **Install Semgrep \<version>** button runs the same managed install as `pan sync` (can take several minutes) |
| Gate mode | `off` / `advisory` / `blocking` (`gate`) |
| Minimum severity | `INFO` / `WARNING` / `ERROR` (`severity`) |
| Rule configs | Registry ids or repo-relative rule paths, one per line (`configs`) |
| Scan timeout (seconds) | Wall-clock limit for one repo's scan (`timeout_seconds`) |
| MCP server for agents | Turns the `semgrep` MCP server on or off (`mcp`) |
| Post-edit scan hook | Turns the post-edit scan hook on or off (`edit_hook`) |

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

| Harness | MCP server | Edit hook |
| - | - | - |
| Claude Code | Yes | Yes |
| Codex | Yes | No (#5434) |
| ACP host (Kimi over ACP, OpenCode, Grok Build) | Yes | No |
| pi, oh-my-pi, Kimi Code native, Muse, Prime Agent | No (one launch warning) | No |

## Data egress

| Action | Talks to | Sends code? |
| - | - | - |
| Install (`uv`/`pipx`) | PyPI (`pypi.org`, `files.pythonhosted.org`) | No |
| `pan doctor` registry check | `semgrep.dev` (bare `HEAD` request) | No |
| MCP `semgrep_rule_schema` | `semgrep.dev` | No |
| Post-edit scan | `semgrep.dev` (registry download of `p/default`) | No |
| Verification `sast` scan | `semgrep.dev` (registry download of each registry id in `configs`) | No |
| CI workflow (GitHub Actions) | semgrep.dev (registry download) from GitHub's runner; GitHub code scanning with --sarif-upload | Code stays on GitHub's runner; with --sarif-upload, findings go to GitHub code scanning |
| Version check / metrics | Disabled (`SEMGREP_ENABLE_VERSION_CHECK=0`, `SEMGREP_SEND_METRICS=off`) | n/a |
| Semgrep Platform / Guardian | Not available in this release | n/a |

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](https://semgrep.dev/legal/rules-license/) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.