Introducing a new way to review your PRs.

Read the announcement

semgrep / semgrep

Lightweight static analysis for many languages. Find bug variants with patterns that look like source code.

View on GitHub

13 documents · Updated Nov 16, 2026

overview

Knowledge Base updated: 2026-11-16

Knowledge Base Index

Orientation

This repository is Semgrep: a static-analysis scanner with Python CLI surfaces and an OCaml analysis core. The highest-level flow is a scan request that starts in cli/ or src/osemgrep/, resolves rules and targets, runs the OCaml parsing/matching/analysis pipeline, then reports findings and optional fixes.

Main parts:

  • Python CLI (cli/) — user-facing command package, output, Semgrep Core invocation, dependency-aware helpers, RPC/MCP hooks.
  • OCaml CLI (src/main/, src/core_cli/, src/osemgrep/) — native command entrypoints and subcommand orchestration.
  • OCaml core engine (src/core_scan/, src/engine/, src/matching/, src/analyzing/, src/tainting/) — target scheduling, parsing, matching, semantic/dataflow analysis, and taint mode.
  • Language frontends (languages/, parsing libs, src/ast_generic/) — per-language parsers and the generic AST consumed by the engine.
  • Reporting and integrations (src/reporting/, src/fixing/, src/rpc/, src/lsp_legacy/) — output formats, autofix, RPC, editor/server integrations.
  • Shared libraries and build infra (libs/, scripts/, bin/, Nix/opam/Dune files) — reusable OCaml utilities and development/package tooling.

Critical state is mostly file-based rather than service-backed: rule/config files become internal rule models, target trees become scan target sets, manifests/lockfiles feed SCA, and CLI/runtime settings or metrics are local process/file state. There is no repository-owned database, queue, or object store in this codebase.

Architecture diagrams

flowchart LR
  subgraph Inputs
    Rules[Rule/config files]
    Targets[Source targets]
    Deps[Manifests and lockfiles]
  end

  subgraph CLI
    PyCLI[cli Python package]
    OCLI[osemgrep OCaml CLI]
  end

  subgraph Core
    Targeting[src/targeting]
    Parsing[languages + src/parsing]
    AST[src/ast_generic]
    Scan[src/core_scan]
    Match[src/engine + src/matching]
    Analysis[src/analyzing + src/tainting]
    SCA[src/sca + semdep]
    Output[src/reporting + src/fixing]
  end

  subgraph Integrations
    RPC[src/rpc]
    LSP[src/lsp_legacy]
    MCP[cli MCP/RPC hooks]
  end

  Shared[libs + build infra]

  Rules --> PyCLI
  Rules --> OCLI
  Targets --> PyCLI
  Targets --> OCLI
  Deps --> SCA
  PyCLI --> Scan
  OCLI --> Scan
  Scan --> Targeting
  Scan --> Parsing
  Parsing --> AST
  AST --> Match
  Match --> Analysis
  SCA --> Match
  Match --> Output
  Analysis --> Output
  RPC --> Scan
  LSP --> Scan
  MCP --> PyCLI
  Shared --> Core
flowchart TD
  Entry[CLI scan command] --> Config[Resolve rules and options]
  Config --> Targets[Discover and filter targets]
  Targets --> Jobs[Build language jobs]
  Jobs --> Parse[Parse target files]
  Parse --> Match[Run matching engine]
  Match --> Taint[Taint and dataflow modes]
  Match --> Results[Core match results]
  Taint --> Results
  Results --> Report[JSON/text output]
  Results --> Fix[Autofix output]
flowchart TD
  RuleFile[Rule file] --> ParseRule[src/parsing]
  ParseRule --> RuleModel[src/rule]
  RuleModel --> Pattern[Pattern/formula/xpattern]
  Pattern --> Matcher[src/engine + src/matching]
  TargetFile[Target source file] --> LangParser[languages + parsing libs]
  LangParser --> GenericAST[src/ast_generic]
  GenericAST --> Matcher
  Matcher --> Findings[Findings with metavars]
flowchart LR
  Editor[Editor/tool client] --> LSP[src/lsp_legacy]
  Tool[External RPC caller] --> RPC[src/rpc]
  LSP --> Helpers[scan helpers]
  RPC --> CoreScan[src/core_scan]
  Helpers --> CoreScan
  CoreScan --> Results[Results]
  Results --> LSP
  Results --> RPC

Glossary

  • osemgrep — OCaml-native Semgrep CLI implementation under src/osemgrep/.
  • semdep — Python dependency/SCA support package under cli/src/semdep/.
  • SCA — software composition/dependency analysis, centered on manifests, lockfiles, packages, and dependency rules.
  • nosemgrep — inline suppression mechanism handled in reporting/output paths.
  • xpattern — extended pattern abstraction used by matching engines beyond normal AST patterns.

Codebase-wide invariants

  • Dune is the primary OCaml build graph: the repo has dune-project, top-level dune, and subsystem dune files such as src/core_scan/dune, src/engine/dune, and src/reporting/dune.
  • OCaml subsystems commonly expose implementation/interface pairs where APIs are public, evidenced by pairs such as src/core_scan/Core_scan.ml + src/core_scan/Core_scan.mli, src/targeting/Find_targets.ml + src/targeting/Find_targets.mli, and src/reporting/Core_json_output.ml + src/reporting/Core_json_output.mli.
  • The Python CLI is packaged separately under cli/, evidenced by cli/pyproject.toml, cli/setup.py, cli/Makefile, and package code under cli/src/semgrep/ and cli/src/semdep/.
  • Language support is organized as per-language directories under languages/ plus shared parsing/generic AST layers (libs/lib_parsing/**, libs/lib_parsing_tree_sitter/**, src/ast_generic/**).

Routing table