@zibby/bin-semgrep

Zibby-owned, self-vendored Semgrep OSS engine (semgrep-core) — the supply-chain-hardened way the code-scan skill gets multi-language static analysis (Java, Python, Go, Ruby, PHP, …) into a run container without trusting an upstream package at run time and without baking Semgrep into the agent image.

Why

Semgrep does not publish a standalone static binary on its GitHub releases; the official prebuilt artifact is the PyPI wheel, which bundles the OSS OCaml engine semgrep-core plus a sibling bin/libs/ of shared libraries. Zibby fetches that wheel once — at Zibby's publish time — sha256-verifies it against a pinned digest (fail-closed), extracts semgrep-core + libs/, and vendors them into the per-platform package. Run containers install Zibby's exact, pinned, vendored package and spawn semgrep-core directly. No upstream binary trust, no run-time fetch, no Python, no semgrep CLI, no network — the engine reads a local rules file + a local targets file and emits JSON. There is no telemetry path and no registry fetch in semgrep-core, so it is deterministic + offline by construction.

OSS only (LGPL-2.1)

This vendors and runs only the open-source Semgrep engine (semgrep-core, LGPL-2.1), driven only by Zibby's own open rules and a repo's own local rules. It never bundles, fetches, or invokes Semgrep Pro / Semgrep Code / the Semgrep Registry / any proprietary ruleset (engine_kind = "OSS"). The full LGPL-2.1 text ships in LICENSE.

⚠️ Size

Unlike @zibby/bin-oxlint (a single ~18 MB static file), semgrep-core is a large OCaml binary (~200–250 MB) plus a libs/ directory. Each platform package is ~65–70 MB compressed / ~280 MB unpacked. It is os/cpu-gated, so a run container installs only its one host platform, but it is a meaningful addition to the run container's npm install. This is the cost of one-tool multi-language static scanning with no image bake.

Layout

| Package | Role | |---|---| | @zibby/bin-semgrep (this) | dispatcher — binPath() resolves the host's vendored semgrep-core | | @zibby/bin-semgrep-linux-x64 | vendored semgrep-core + libs/, os:[linux] cpu:[x64] (the prod run container) | | @zibby/bin-semgrep-linux-arm64 | vendored semgrep-core + libs/, os:[linux] cpu:[arm64] | | @zibby/bin-semgrep-darwin-arm64 | vendored semgrep-core + libs/, os:[darwin] cpu:[arm64] (local dev, Apple Silicon) | | @zibby/bin-semgrep-darwin-x64 | vendored semgrep-core + libs/, os:[darwin] cpu:[x64] (local dev, Intel) |

The dispatcher lists the four platform packages as optionalDependencies, so npm installs only the one matching the host os/cpu. The binary rpaths to libs/ via @executable_path/libs (macOS) / $ORIGIN/libs (Linux), so it resolves its shared libs from the sibling dir automatically.

Usage

import { binPath } from '@zibby/bin-semgrep';
const semgrepCore = binPath();   // absolute path to semgrep-core, or null if unsupported/not vendored

Then run offline, e.g.:

semgrep-core -rules <rules.json|yaml> -targets <targets.json> -json

where -targets is the ["Targets",[["CodeTarget",{path,analyzer,products}], …]] JSON that @zibby/skills code-scan.js generates (one entry per changed file, tagged with its Semgrep language). See that file for the exact invocation + parser.

Versioning

Package versions mirror the Semgrep version they vendor — @zibby/[email protected] == Semgrep OSS engine 1.169.0, Zibby-vendored. A dispatcher-only fix carrying the same engine bumps the patch and is noted in the commit/changelog.

Building / publishing (release owner)

Binaries + libs/ are never committed to git (they're large) but do ship in the npm tarball. The per-platform package.json / LICENSE / NOTICE are committed (scaffolded via --templates-only); the binary is fetched + sha-verified at build time:

# from packages/bin-semgrep
npm run build:templates  # write the committed platform templates only (offline, no download)
npm run build            # download the 4 wheels, sha-verify, extract semgrep-core + libs/ (no publish)
npm run build:host       # vendor only this host's platform (fast local check)
node ../scripts/publish-bin-tool.mjs --config ./tool.config.mjs --publish   # release only

tool.config.mjs is the single source of truth for the Semgrep version + the four pinned sha256 digests (of the PyPI wheels). To bump Semgrep: edit it, re-run npm run build, republish.