I have a problem. Not a “my code does not compile” problem. A “I have so many ideas and projects and notes that my brain just gives up and reboots” problem. 😵‍💫

So I did what any reasonable developer would do: I built an AI agent inside Open Claw whose only job is to document everything beautifully in Notion. His name is Escriber.

This is my submission for the Notion MCP Challenge. Let me tell you, building a focused single-purpose agent with 14 Notion tools is exactly as satisfying as it sounds.

What I Built

Escriber is agent #2 of 5 on my OpenClaw multi-agent team.

His SOUL.md says exactly this: “I document. Beautifully. In Notion.” And for anyone who has not used OpenClaw, they give these agents Soul.md files that define who the agent is and give them a small personality.

That is it. Full stop. He cannot debug your code. He cannot give life advice. He has one lane and he stays in it — which, honestly, is more discipline than I have most the time. 😆

He lives in Discord as a bot or I can use the web chat interface to call on him directly. He can be slightly artisanal. Dry wit is baked in by design, because documentation does not have to be soulless. He makes use of my Synap bot to write summaries for projects and clean them up like I would say them, then he will store what Synap sends back.

He is not a Swiss Army knife. He is a scalpel. And sometimes that is exactly what you need.

Video Demo

Show Us the Code

Escriber talks to Notion through mcporter — an MCP relay that proxies tool calls to Notion’s official MCP server. Every Notion interaction looks like this:

mcporter call notion.<tool_name> --args '{ ... }'

Clean. Consistent. One pattern to rule them all.

Here is the full arsenal — 14 tools, one agent, zero excuses for undocumented projects:

Escriber also has workflow rules baked into his instructions. Because tools without discipline are just chaos with an API:

• Search first. Always check if the page already exists before creating a new one.
• Read before writing. Retrieve block children before appending to avoid structural disasters.
• Right block type. Callouts for decisions. Toggles for details. Headings for structure. Not everything is a paragraph.
• Structure intentionally. Measure twice, cut once. 🤣

How I Used Notion MCP

Let me tell you how this actually works.

mcporter connects Escriber to Notion’s official MCP server at https://mcp.notion.com/mcp. Every tool call gets proxied through that relay — no direct API wrangling, no custom request builders. The MCP layer handles it. Escriber just speaks tool.

Here is what that looks like day-to-day:

New project starts?
create_page to spin up the project hub. create_database_item to log it in the master projects database. Done in seconds.

Wrapping up a build session?
append_block_children to the existing project page. Build notes, decisions made, what broke, what did not. Structured. Timestamped. Actually findable later.

JB’s Job Listings
create_page My recruiter agent stored a list of jobs using Esciber every morning. Future-me will be grateful. Past-me was not doing this. These are stored in Notion daily, and sortable ☠️

Let me tell you about the shame moment that made this real.

I went back through my own Notion workspace a few weeks ago. Pages with titles like “ideas v3 FINAL” and “project notes DO NOT DELETE” containing exactly… three bullet points and a YouTube link. That is it. That is the legacy. A graveyard of good intentions. ☠️

Escriber exists because I needed someone with more documentation discipline than me. Turns out that someone is a focused AI agent with a soul file and 14 Notion tools.

One job. One lane. Real personality. And the docs actually get written now.

“Optimization starts with a single point of failure—or a single point of success. Own the lane.”

Also, thanks to Bloggy, for taking the time to help with this post.

Escriber is part of my OpenClaw agent team. If you are curious about building multi-agent setups in openclaw, drop a comment — I am writing more about this whole stack as it comes together.

This didn’t start as a startup idea. I wasn’t trying to build a SaaS product. I just needed a simple way to handle customer support for my own projects without exposing my personal Telegram account or dealing with complex tools.

At first, Telegram felt perfect. Everyone already uses it, there’s no onboarding, no friction, no extra accounts. A client just sends a message and you reply. It’s fast, natural, and works out of the box.

And for a while, it really does work.

The problems don’t show up immediately. In the beginning, you have a few conversations per day, everything is manageable, and you can keep context in your head. Then you launch another project. Then another. Messages start coming in at different times, from different people, about different things.

You reply from your personal account, then maybe create a separate work account, then start forwarding messages to yourself or teammates. Over time, Telegram turns into a mix of personal chats, client conversations, and random forwarded messages. It becomes harder to understand what’s going on at any given moment.

The tricky part is that it doesn’t break in an obvious way. It slowly degrades. Responses get delayed, some messages are missed, sometimes two people reply to the same client, sometimes no one replies because everyone assumes someone else already did. Nothing critical, but enough to hurt the overall experience.

I tried a few workarounds. Multiple accounts, groups, pinned messages, manual labeling, forwarding flows. All of them help a bit, but none of them solve the core issue. Telegram is just a list of chats. There is no structure, no clear overview, no shared context.

Switching to a CRM or helpdesk didn’t feel right either. Not because those tools are bad, but because they’re often overkill for small teams or solo projects. You get dashboards, ticket statuses, workflows, onboarding, and another system you need to constantly keep open. Meanwhile, your actual communication still happens in Telegram, just routed through something else.

At some point it became clear that I didn’t need another tool. I needed a way to make Telegram itself more structured.

The idea ended up being very simple. Instead of clients messaging me directly, they message a bot. Every incoming message is forwarded into a private Telegram group where each client gets their own thread. One client, one thread. All history stays in one place, no forwarding, no confusion.

You reply directly inside that thread, and the bot sends the response back to the client.

Nothing fundamentally changes from the user’s perspective. It still feels like a normal Telegram chat. But internally, everything becomes structured. You can immediately see all active conversations, understand which ones need attention, and multiple people can work in parallel without stepping on each other.

Most importantly, your personal account is no longer part of the support flow at all.

I originally built this just to solve my own problem. But after using it for a while, I realized this pattern applies to a lot of people. Freelancers, small teams, indie projects, small businesses. Many of them rely on Telegram for communication, run into the same limitations, and don’t want to switch to heavy tools.

That’s how it turned into a small product.

If you’re curious how this approach works in practice, I put together a simple explanation here:

👉 https://gramdeskbot.com

It’s not trying to replace a CRM or compete with full helpdesk platforms. It’s just adding a missing layer to Telegram so it can function as a lightweight support system.

And in practice, for small setups, that turned out to be a much better fit than anything more complex.

If you’re already using Telegram as your main communication channel, you’ll likely run into the same issues at some point. The question is whether you keep patching it manually or introduce a bit of structure on top of what you already use.

This is the third post in the series.

In the previous post, we created a pivot table with custom filters. While those filters allowed us to apply constraints such as Equals, Contains, and Between, it would be useful to extend the example further by introducing static and dynamic select lists as filtering options.

In this post, we will enhance the existing solution by integrating these select lists and exploring how they improve the filtering experience.

Below is the link to the previous post:

Getting Started with Seal Report: Creating a Pivot Table with Custom Filters

Vlad Ganușceac

Vlad Ganușceac

Vlad Ganușceac

Follow

Mar 22

Getting Started with Seal Report: Creating a Pivot Table with Custom Filters

#sealreport
#tutorial
#sqlserver
#analytics

1 reaction

Comments

Add Comment

3 min read

Adding a Static Enumeration

In the context of Seal Report, a static enumeration is a collection of key-value pairs defined directly in the report’s XML document definition.

For example, instead of retrieving the distinct values of PayFrequency from the HumanResources.EmployeePayHistory table, it is often more efficient to store these values directly in the data model used for rendering the report. Even executing a hardcoded SQL query each time the report runs would be less efficient than using a predefined collection.

In this case, the static enumeration behaves like a constant list that is already available at runtime and does not require additional database queries.

Select the Add Enum option available under Sources → Data Source → Enumerated Lists. A contextual configuration panel will appear on the right side.

Within the enum definition, provide a meaningful Name, and configure the following options if needed:

• whether the list is dynamically loaded from a SQL Select Statement or from a Load Script

• whether the list should be refreshed before report execution

• whether the list values depend on the connection.

These settings allow you to control how enumeration values are loaded and updated during report execution.

For the current scope, all these options remain set to False, since we are defining a static enumeration.

The SQL Select Statement used to define the enumeration values is the following:

SELECT *
FROM (VALUES
    (1, 'Monthly'),
    (2, 'Biweekly')
) AS PayFrequencyEnum([Key], [Value])

The enum’s configuration looks this way:

Note that the Refresh values option may not appear immediately in the UI. If it is not visible, reopen the enum definition or temporarily enable a dynamic loading option so the two values become available in the final collection.

The enumeration created in the UI is persisted in the report definition as a <MetaEnum> element. A simplified example looks like this:

<MetaEnum>
  <GUID>a90b0ce6-bde8-4199-8869-f2ce0c1218ce</GUID>
  <Name>PayrollFrequency</Name>
  <Sql>SELECT *
FROM (VALUES
    (CAST(1 AS INT), 'Monthly'),
    (CAST(2 AS INT), 'Biweekly')
) AS PayFrequencyEnum([Key], [Value])</Sql>
  <Values>
    <MetaEV>
      <Id>1</Id>
      <Val>Monthly</Val>
    </MetaEV>
    <MetaEV>
      <Id>2</Id>
      <Val>Biweekly</Val>
    </MetaEV>
  </Values>
</MetaEnum>

If the enumeration is configured as static, the actual values used at runtime are stored inside the <Values> section. In this case, the <Sql> element is not required for execution and mainly serves as a definition template.

You can even remove the <Sql> element and keep only the <Values> collection to preserve the same static behavior.

Adding a Dynamic Enumeration

For a dynamic enumeration, let’s select a set of properties directly from the database that are expected to change over time.

For example, the HumanResources.EmployeeDepartmentHistory table references the HumanResources.Shift table. This means that the available shift values may change in the future as new shifts are added or existing ones are modified.

In such scenarios, using a dynamic enumeration ensures that the list of available values is always loaded from the database and reflects the current state of the data.

For this particular case, the list will be dynamically loaded from the SQL Select Statement, and its values will depend on the connection.

I’ve chosen the following SQL Select Statement:

SELECT 
    [ShiftID] AS [KEY],
    CONCAT(
        [Name], 
        ' (',
        FORMAT(CAST([StartTime] AS datetime2), 'HH:mm'),
        ' - ',
        FORMAT(CAST([EndTime] AS datetime2), 'HH:mm'),
        ')'
    ) AS [VALUE]
FROM [AdventureWorks2025].[HumanResources].[Shift]

The configuration looks the following way:

The enumeration will be reflected in the report definition like this:

<MetaEnum>
            <GUID>c107bf33-5f3a-4f26-908d-48a8f768d0d9</GUID>
            <Name>Shifts</Name>
            <IsDynamic>true</IsDynamic>
            <ValuesPerConnection>true</ValuesPerConnection>
            <Sql>SELECT 
    [ShiftID] AS [KEY],
    CONCAT(
        [Name], 
        ' (',
        FORMAT(CAST([StartTime] AS datetime2), 'HH:mm'),
        ' - ',
        FORMAT(CAST([EndTime] AS datetime2), 'HH:mm'),
        ')'
    ) AS [VALUE]
FROM [AdventureWorks2025].[HumanResources].[Shift]</Sql>
          </MetaEnum>

Note that the report definition may also include a key–value collection inside a <Values> section. This typically appears after selecting Refresh values or pressing F9, which materializes the current enumeration entries in the report model.

Applying Enumerations on Restrictions

The process of applying a select-based filter is very similar to the one used for expression-based filters. The key difference is that, within the Advanced section, you must select the appropriate Custom enum.

Drag and drop the PayFrequency property from the HumanResources.EmployeePayHistory table into the Restrictions section. Then click on the newly created [PayFrequency Equals] expression. In the contextual panel on the right side, navigate to the Advanced section and select the PayrollFrequency enumeration.

Execute the report, and you will see the available filters as shown in the screenshot below.

It does not matter whether the enumeration is static or dynamic — both are applied in the same way when configuring a restriction or filter.

Skill Check

Apply the Shifts enumeration to the ShiftID property from the HumanResources.Shift table. The process is similar to the one discussed in the previous section.

Hint: combine restrictions using both the PayrollFrequency and Shifts enumerations.

If you’ve configured it successfully, try answering the following questions:

• How many employees from the Engineering department have agreed to a Biweekly payroll frequency and are working the Day shift (07:00 – 15:00)?

• How many employees with a FirstName starting with Chris are assigned to either the Evening or Night shift?

Dependent select lists allow one enumeration to react dynamically to the selection of another. In one of the following posts, I will show you how to apply dependent select lists.

Quick Summary

Static vs Dynamic Enumerations

Use static enumerations for constant lookup lists and dynamic enumerations when values must reflect the current database state.

Why Semgrep and why now

Semgrep is a fast, open-source static analysis tool that finds bugs and security vulnerabilities by letting you write rules that look like the code you are searching for. Unlike legacy SAST tools that require specialized security expertise to configure and produce overwhelming false positive rates, Semgrep was designed from the ground up for developers. Its pattern syntax mirrors your actual source code, its CLI runs in seconds, and its rule library covers over 30 programming languages with thousands of pre-written checks.

Since its launch by r2c (now Semgrep, Inc.) in 2020, Semgrep has become the default security scanner for thousands of engineering teams – from startups running the free open-source engine to enterprises using the full cloud platform. Dropbox, Figma, Snowflake, and Hashicorp all use Semgrep in their development pipelines. The tool scans over 100 million lines of code daily across its user base.

The reason to set up Semgrep now is straightforward. Every major compliance framework – SOC 2, PCI DSS 4.0, ISO 27001 – requires or strongly recommends static analysis in the development lifecycle. Semgrep gives you that compliance evidence while also catching real vulnerabilities. The open-source engine is free, and the full platform is free for teams of up to 10 contributors. There is no licensing cost barrier to getting started.

This guide walks through every step of setting up Semgrep – from installing the CLI on your local machine to running it in CI/CD pipelines with automatic PR comments. By the end, you will have a production-ready Semgrep configuration that catches security issues before they reach your main branch.

Step 1 – Install the Semgrep CLI

Semgrep provides three installation methods. Choose the one that fits your environment.

Install with pip (all platforms)

The pip installation is the recommended method and works on macOS, Linux, and Windows (via WSL). Semgrep requires Python 3.8 or later.

# Install Semgrep
pip install semgrep

# Verify the installation
semgrep --version

If you prefer to isolate Semgrep from your system Python, use pipx:

# Install with pipx for isolated environment
pipx install semgrep

# Verify
semgrep --version

Install with Homebrew (macOS)

On macOS, Homebrew provides a straightforward installation:

# Install via Homebrew
brew install semgrep

# Verify
semgrep --version

Install with Docker (any platform)

Docker is useful for CI environments or when you do not want to install anything on the host system:

# Pull the Semgrep image
docker pull semgrep/semgrep

# Run a scan using the Docker image
docker run --rm -v "${PWD}:/src" semgrep/semgrep semgrep --config auto /src

The Docker approach mounts your current directory into the container at /src and runs the scan against it. This method ensures a consistent environment regardless of the host operating system.

Verify your installation

After installing through any method, confirm that Semgrep is working:

semgrep --version
# Expected output: semgrep 1.x.x

If you see a version number, the installation was successful. If you encounter a “command not found” error, ensure that the installation directory is in your system PATH. For pip installations, this is typically ~/.local/bin on Linux or ~/Library/Python/3.x/bin on macOS.

Step 2 – Run your first scan

With Semgrep installed, you can run your first scan immediately without any configuration files.

Scan with the default rule set

Navigate to any project directory and run:

cd /path/to/your/project
semgrep --config auto

The --config auto flag tells Semgrep to automatically select rules that are relevant to the languages and frameworks detected in your project. Semgrep downloads the appropriate rules from the Semgrep Registry, runs the scan, and prints findings to your terminal.

Scan with a specific rule set

For more control over which rules run, specify a rule set by name:

# Run the default curated rule set
semgrep --config p/default

# Run security-focused rules
semgrep --config p/security-audit

# Run language-specific rules
semgrep --config p/python
semgrep --config p/javascript
semgrep --config p/golang

Scan a specific file or directory

You do not have to scan your entire project. Target specific paths:

# Scan a single file
semgrep --config p/default src/auth/login.py

# Scan a specific directory
semgrep --config p/default src/api/

# Scan multiple paths
semgrep --config p/default src/auth/ src/api/ src/middleware/

Understand the output

A typical Semgrep finding looks like this:

src/api/users.py
  security.python.sql-injection.sql-injection
    Detected string concatenation in SQL query. Use parameterized queries instead.

    14│ query = "SELECT * FROM users WHERE id = " + user_id

Each finding includes the file path, the rule ID that triggered the match, a human-readable message explaining the issue, and the exact line of code that was matched. The rule ID is important because you will use it later to customize which rules run and to suppress false positives.

Output in different formats

Semgrep supports multiple output formats for integration with other tools:

# JSON output for programmatic processing
semgrep --config p/default --json > results.json

# SARIF output for GitHub Code Scanning integration
semgrep --config p/default --sarif > results.sarif

# JUnit XML for CI/CD integration
semgrep --config p/default --junit-xml > results.xml

# Emacs/Vim compatible output
semgrep --config p/default --emacs

Step 3 – Understand Semgrep rule sets

Rule sets are collections of rules curated for specific use cases. Choosing the right rule sets determines what Semgrep looks for and how many findings you get.

Core rule sets

p/default is the starting point for most teams. It contains high-confidence security and correctness rules curated by the Semgrep team. These rules have low false positive rates and focus on issues that are almost always worth fixing. Start here and expand later.

p/security-audit is a broader security-focused set that includes rules with moderate confidence. It catches more potential issues but produces more findings that may require manual review. Use this when you want comprehensive security coverage and have the bandwidth to triage additional findings.

p/owasp-top-ten maps rules to the OWASP Top 10 vulnerability categories – injection, broken authentication, sensitive data exposure, and so on. This set is useful for compliance-driven teams that need to demonstrate OWASP coverage in their security program.

Language-specific rule sets

Semgrep provides curated rule sets for individual languages and frameworks:

Infrastructure rule sets

For infrastructure-as-code scanning:

Combining multiple rule sets

You can run multiple rule sets in a single scan by passing multiple --config flags:

semgrep --config p/default --config p/security-audit --config p/python

Start with p/default alone, review the findings, and then add additional sets incrementally. Adding too many rule sets at once can generate an overwhelming number of findings that make it hard to prioritize what to fix first.

Step 4 – Write custom Semgrep rules

One of Semgrep’s most powerful features is how easy it is to write custom rules. Unlike tools that require a proprietary query language, Semgrep rules use patterns that look like the code they are matching.

Basic rule structure

Create a file called custom-rules.yaml:

rules:
  - id: no-hardcoded-passwords
    patterns:
      - pattern: password = "$VALUE"
    message: >
      Hardcoded password detected. Use environment variables or a
      secrets manager instead of embedding credentials in source code.
    severity: ERROR
    languages:
      - python
    metadata:
      cwe:
        - "CWE-798: Use of Hard-coded Credentials"
      category: security

Every rule needs five required fields:

• id – a unique identifier for the rule, used in output and for suppression
• pattern or patterns – the code pattern to match, using metavariables like $VALUE as placeholders
• message – a human-readable explanation shown when the rule matches
• severity – one of ERROR, WARNING, or INFO
• languages – an array of languages this rule applies to

Using metavariables

Metavariables are placeholders that match any expression. They start with $ and an uppercase name:

rules:
  - id: insecure-hash-algorithm
    patterns:
      - pattern: hashlib.$ALGO(...)
      - metavariable-regex:
          metavariable: $ALGO
          regex: (md5|sha1)
    message: >
      Insecure hash algorithm '$ALGO' detected. Use SHA-256 or
      stronger for cryptographic hashing.
    severity: WARNING
    languages:
      - python

This rule matches any call to hashlib.md5(...) or hashlib.sha1(...) regardless of the arguments passed.

Combining patterns with pattern-either and pattern-not

Use pattern-either to match multiple patterns and pattern-not to exclude safe patterns:

rules:
  - id: dangerous-eval
    patterns:
      - pattern-either:
          - pattern: eval($INPUT)
          - pattern: exec($INPUT)
      - pattern-not: eval("literal_string")
    message: >
      Use of eval() or exec() with dynamic input is a code injection
      risk. Consider using ast.literal_eval() or a safer alternative.
    severity: ERROR
    languages:
      - python

A more advanced example – detecting SQL injection

rules:
  - id: flask-sql-injection
    patterns:
      - pattern: |
          $CURSOR.execute("..." + $INPUT + "...")
      - pattern-not: |
          $CURSOR.execute("..." + "..." + "...")
    message: >
      SQL query built using string concatenation with variable input.
      Use parameterized queries with placeholders to prevent SQL injection.
      Replace: cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
    severity: ERROR
    languages:
      - python
    metadata:
      cwe:
        - "CWE-89: SQL Injection"
      owasp:
        - "A03:2021 - Injection"

Testing your custom rules

Run your custom rules against your codebase:

# Run a single custom rule file
semgrep --config custom-rules.yaml

# Run custom rules alongside registry rules
semgrep --config custom-rules.yaml --config p/default

# Test a rule against a specific file
semgrep --config custom-rules.yaml src/database/queries.py

Organizing custom rules

For teams with multiple custom rules, organize them in a directory:

.semgrep/
  security/
    sql-injection.yaml
    auth-bypass.yaml
    secrets.yaml
  correctness/
    null-checks.yaml
    error-handling.yaml
  style/
    naming-conventions.yaml

Then scan with the entire directory:

semgrep --config .semgrep/

Step 5 – Set up Semgrep in GitHub Actions

Running Semgrep in CI ensures every pull request is scanned automatically. Here is how to set up a production-ready GitHub Actions workflow.

Basic GitHub Actions workflow

Create .github/workflows/semgrep.yml:

name: Semgrep

on:
  pull_request: {}
  push:
    branches:
      - main

jobs:
  semgrep:
    name: Semgrep Scan
    runs-on: ubuntu-latest
    container:
      image: semgrep/semgrep
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run Semgrep
        run: semgrep ci
        env:
          SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}

This workflow runs Semgrep on every pull request and every push to the main branch. The semgrep ci command is designed for CI environments – it performs diff-aware scanning (only analyzing changed files on PRs), uploads results to Semgrep Cloud if a token is configured, and exits with a non-zero code if blocking findings are detected.

GitHub Actions without Semgrep Cloud

If you do not want to use Semgrep Cloud, you can run the scan using only the CLI with specific rule sets:

name: Semgrep

on:
  pull_request: {}
  push:
    branches:
      - main

jobs:
  semgrep:
    name: Semgrep Scan
    runs-on: ubuntu-latest
    container:
      image: semgrep/semgrep
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run Semgrep
        run: semgrep scan --config p/default --config p/security-audit --error

The --error flag causes Semgrep to exit with a non-zero code when findings are detected, which fails the GitHub Actions check and blocks the PR from merging if branch protection is configured.

Adding SARIF upload for GitHub Code Scanning

To see Semgrep findings in GitHub’s Security tab alongside CodeQL results:

name: Semgrep

on:
  pull_request: {}
  push:
    branches:
      - main

jobs:
  semgrep:
    name: Semgrep Scan
    runs-on: ubuntu-latest
    container:
      image: semgrep/semgrep
    permissions:
      security-events: write
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run Semgrep
        run: semgrep scan --config p/default --sarif --output semgrep-results.sarif

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: semgrep-results.sarif
        if: always()

This uploads Semgrep results in SARIF format so they appear in the GitHub Security tab under “Code scanning alerts.” The if: always() ensures results are uploaded even when Semgrep finds issues and returns a non-zero exit code.

Configuring branch protection

After adding the Semgrep workflow, configure GitHub branch protection to require the scan to pass before merging:

1. Go to your repository Settings, then Branches
2. Edit the branch protection rule for your main branch
3. Enable “Require status checks to pass before merging”
4. Search for and add the “Semgrep Scan” check
5. Save your changes

Now any PR with blocking Semgrep findings will be prevented from merging until the issues are resolved.

Step 6 – Connect Semgrep Cloud

Semgrep Cloud (the Semgrep AppSec Platform) adds a web dashboard, PR comments, AI-powered triage, and cross-file analysis on top of the open-source CLI. It is free for up to 10 contributors.

Create a Semgrep Cloud account

1. Go to semgrep.dev and sign up with your GitHub, GitLab, or email account
2. Create an organization that matches your GitHub organization
3. Navigate to Settings and generate an API token
4. Save this token – you will need it for CI configuration

Add the token to GitHub

1. Go to your repository Settings, then Secrets and variables, then Actions
2. Click “New repository secret”
3. Name it SEMGREP_APP_TOKEN
4. Paste the token from Semgrep Cloud
5. Click “Add secret”

Configure scanning policies in Semgrep Cloud

Semgrep Cloud lets you manage rule configuration from the web dashboard instead of hardcoding rule sets in your CI file:

1. In Semgrep Cloud, go to Policies
2. You will see a default policy with recommended rules enabled
3. Add or remove rule sets based on your needs
4. Set rules to Comment, Block, or Monitor mode

When you use semgrep ci in your workflow (instead of semgrep scan --config ...), Semgrep pulls its configuration from the cloud policy. This means you can change what gets scanned and what severity levels block PRs without modifying your workflow file.

Rule modes in Semgrep Cloud

Semgrep Cloud supports three modes for each rule:

• Block – findings from this rule fail the CI check and block the PR from merging
• Comment – findings are posted as PR comments but do not block merging
• Monitor – findings are tracked in the dashboard but are not surfaced on the PR at all

Most teams start with the majority of rules in Comment mode and only promote rules to Block mode after confirming they produce zero or near-zero false positives in their specific codebase.

Step 7 – Configure PR comments

PR comments are how Semgrep delivers findings to developers in their existing workflow – directly in the pull request where the code was changed.

How PR comments work

When Semgrep Cloud is connected and semgrep ci runs in your CI pipeline, it performs a diff-aware scan that analyzes only the code changed in the pull request. New findings are posted as inline comments on the exact lines of code where the issues were detected. Each comment includes the rule name, severity, a description of the issue, and often a suggested fix.

Install the Semgrep GitHub App

For PR comments to work, you need the Semgrep GitHub App installed:

1. In Semgrep Cloud, go to Settings, then Source Code Managers
2. Click “Add GitHub” and authorize the Semgrep GitHub App
3. Choose which repositories or organizations to grant access to
4. Confirm the installation

Once installed, any repository connected to Semgrep Cloud will receive inline PR comments when semgrep ci detects new findings.

Customizing comment behavior

In Semgrep Cloud under Settings, you can control:

• Whether comments include fix suggestions
• Whether to add a summary comment at the top of the PR
• Whether to leave comments only for blocking findings or for all findings
• Whether to automatically resolve comments when the underlying code is fixed

Example PR comment

A typical Semgrep PR comment looks like:

⚠️ semgrep: python.flask.security.injection.tainted-sql-string

Detected user input flowing into a SQL query without sanitization.
This is a SQL injection vulnerability.

Suggested fix: Use parameterized queries.
- cursor.execute("SELECT * FROM users WHERE id = " + request.args["id"])
+ cursor.execute("SELECT * FROM users WHERE id = %s", (request.args["id"],))

🔗 Rule details | 📘 CWE-89 | Triage in Semgrep Cloud

Developers can respond to findings directly in the PR – fixing the code, marking as false positive, or adding a # nosemgrep comment to suppress the finding with justification.

Step 8 – Set up .semgrepignore

The .semgrepignore file tells Semgrep which files and directories to skip during scans. This is essential for reducing noise from test files, generated code, vendored dependencies, and other paths where findings are not actionable.

Create a .semgrepignore file

Create a .semgrepignore file in your repository root:

# Test files - findings in tests are usually not exploitable
tests/
test/
*_test.go
*_test.py
test_*.py
*.test.js
*.test.ts
*.spec.js
*.spec.ts

# Generated code - cannot be fixed in source
generated/
__generated__/
*.generated.ts
*.gen.go

# Vendored dependencies - managed upstream
vendor/
node_modules/
third_party/

# Build artifacts
dist/
build/
out/
.next/

# Documentation and configuration
docs/
*.md
*.rst

# Migrations - often contain raw SQL by design
migrations/
alembic/

.semgrepignore syntax

The syntax follows .gitignore conventions:

• directory/ ignores an entire directory and its contents
• *.ext ignores all files with that extension
• pattern ignores matching files anywhere in the tree
• !pattern negates a previous ignore (force-includes a file)
• # starts a comment line

When not to ignore

Be cautious about ignoring too much. Some common patterns to avoid ignoring:

• Do not ignore configuration files. Security misconfigurations in Dockerfiles, Terraform files, and Kubernetes manifests are high-value findings.
• Do not ignore migration files entirely. While raw SQL in migrations is expected, injection vulnerabilities can still appear when migrations accept dynamic input.
• Do not ignore scripts/ or tools/ directories. Internal tooling often has weaker security standards and is a common source of vulnerabilities.

Step 9 – Advanced configuration

Beyond the basics, Semgrep supports several configuration options that help you tune scanning behavior for your codebase.

The semgrep.yaml configuration file

Create a .semgrep.yaml file in your repository root to set default scan options:

rules:
  - p/default
  - p/security-audit
  - .semgrep/

options:
  timeout: 30
  max-memory: 5000

Excluding specific rules

If a specific rule from a registry set produces too many false positives in your codebase, exclude it:

# Exclude specific rules by ID
semgrep --config p/default --exclude-rule "generic.secrets.gitleaks.generic-api-key"

Inline suppressions

Suppress individual findings with inline comments:

# nosemgrep: python.flask.security.injection.tainted-sql-string
cursor.execute("SELECT * FROM config WHERE key = " + safe_internal_key)

The nosemgrep comment accepts a rule ID to suppress only that specific rule on the annotated line. This is preferable to broad suppressions because it documents exactly which check was reviewed and accepted.

For other languages, the comment syntax follows the language convention:

// nosemgrep: javascript.express.security.injection.tainted-sql-string
db.query("SELECT * FROM config WHERE key = " + internalKey);

// nosemgrep: go.lang.security.injection.tainted-sql-string
db.Query("SELECT * FROM config WHERE key = " + safeKey)

Setting exit codes for CI

Control how Semgrep’s exit code maps to CI pass/fail behavior:

# Exit 1 only for ERROR severity findings
semgrep --config p/default --severity ERROR --error

# Exit 1 for WARNING and ERROR findings
semgrep --config p/default --severity WARNING --error

This lets you treat ERROR-level findings as blocking while allowing WARNING-level findings to be advisory.

Max target size and timeout

For large repositories, configure limits to prevent scans from hanging:

# Skip files larger than 1MB
semgrep --config p/default --max-target-bytes 1000000

# Set per-rule timeout to 30 seconds
semgrep --config p/default --timeout 30

# Set maximum memory usage
semgrep --config p/default --max-memory 5000

Step 10 – Troubleshooting common issues

Here are the most common problems teams encounter when setting up Semgrep and how to resolve them.

“command not found” after installation

If semgrep is not found after installing via pip, your Python scripts directory is not in your PATH:

# Find where pip installed Semgrep
python -m site --user-base
# Add the bin directory to your PATH
export PATH="$HOME/.local/bin:$PATH"

# Make it permanent by adding to your shell profile
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

On macOS with Homebrew, this issue is rare. If it occurs, run brew link semgrep.

Slow scans on large repositories

If scans are taking too long, there are several optimizations:

# Use diff-aware scanning to only check changed files
semgrep ci  # Automatically diff-aware in CI

# Exclude large directories
semgrep --config p/default --exclude "vendor" --exclude "node_modules"

# Limit concurrency to reduce memory usage
semgrep --config p/default --jobs 2

# Skip large files
semgrep --config p/default --max-target-bytes 500000

Out of memory errors

Semgrep can consume significant memory on very large files or complex rule sets:

# Limit maximum memory usage (in MB)
semgrep --config p/default --max-memory 4000

# Reduce the number of rules being run
semgrep --config p/default  # Instead of p/security-audit which has more rules

# Exclude known large files
# Add to .semgrepignore:
# *.min.js
# *.bundle.js
# package-lock.json

Rules not matching expected code

When a custom rule does not match code that you expect it to match:

# Test with verbose output to see what Semgrep is doing
semgrep --config your-rule.yaml --verbose target-file.py

# Use --debug for detailed matching information
semgrep --config your-rule.yaml --debug target-file.py

# Validate your rule syntax
semgrep --validate --config your-rule.yaml

Common reasons rules fail to match:

• Language mismatch – the languages field in the rule does not include the file’s language
• Whitespace sensitivity – Semgrep normalizes most whitespace, but multiline patterns need to use ... for gaps
• Metavariable scope – a metavariable used across patterns must match the same expression in all occurrences

GitHub Actions workflow not triggering

If the Semgrep workflow does not run on pull requests:

• Verify the workflow file is in .github/workflows/ on the default branch
• Check that the on: trigger includes pull_request
• Ensure the YAML syntax is valid – GitHub silently ignores malformed workflow files
• Check the Actions tab for workflow run errors

SEMGREP_APP_TOKEN errors

If semgrep ci fails with authentication errors:

• Verify the secret is named exactly SEMGREP_APP_TOKEN in GitHub Settings
• Ensure the token has not expired in Semgrep Cloud
• Check that the repository is connected to the correct organization in Semgrep Cloud
• Regenerate the token in Semgrep Cloud and update the GitHub secret

Findings in generated or vendored code

If Semgrep is flagging code you cannot change:

1. Add the paths to .semgrepignore
2. Use inline # nosemgrep comments for individual suppressions
3. In Semgrep Cloud, triage findings as “Ignored” with a reason of “Generated code” or “Vendored dependency”

Recommended setup for different team sizes

The right Semgrep configuration depends on your team’s size, security maturity, and available bandwidth for triaging findings.

Solo developers and small teams (1-5 developers)

Use Semgrep OSS with the default rule set. Install Semgrep locally, run semgrep --config p/default before pushing code, and add a basic GitHub Actions workflow with p/default. This catches the highest-confidence security issues with minimal noise. Total setup time is about 15 minutes.

# Local development workflow
semgrep --config p/default --error

Mid-size teams (5-20 developers)

Use Semgrep Cloud on the free Team tier. Connect your repositories to Semgrep Cloud, enable PR comments, and start with rules in Comment mode. This gives your team automated feedback on every PR without blocking velocity while you learn which rules are most relevant to your codebase. Promote high-confidence rules to Block mode after a few weeks of triage data. Total setup time is about 30 minutes.

Large teams and enterprises (20+ developers)

Use Semgrep Cloud with a dedicated policy per repository or team. Enable Semgrep Assistant for AI-powered triage to reduce false positive noise. Create custom rules for your internal frameworks and patterns. Integrate SARIF output with GitHub Code Scanning for centralized security visibility. Set up separate policies for different service tiers – stricter rules for payment processing code, lighter rules for internal tools. Total setup time is about 2 hours for the initial configuration plus ongoing refinement.

What to do after setup

Once Semgrep is running in your CI pipeline, the work shifts from configuration to maintenance. Here is a practical sequence for the first 30 days:

Week 1 – Run Semgrep with p/default in Comment mode. Review findings as they come in on PRs. Note any rules that produce frequent false positives in your codebase.

Week 2 – Add paths to .semgrepignore for test files, generated code, and vendored dependencies that are generating noise. Suppress any rule IDs that are consistently false positives for your project.

Week 3 – Promote high-confidence rules to Block mode. Start with rules for critical vulnerabilities like SQL injection, command injection, and hardcoded credentials. Add p/security-audit in Monitor mode to evaluate its findings without surfacing them on PRs.

Week 4 – Write your first custom rule targeting a pattern specific to your codebase – an internal API misuse, a deprecated function that should not be called, or an authentication pattern that must be followed. Share the rule with your team and collect feedback.

This gradual rollout ensures that Semgrep becomes a trusted part of your workflow rather than a noisy tool that developers learn to ignore. The goal is not to enable every rule on day one – it is to build a scanning configuration that your team actually reads and acts on.

Frequently Asked Questions

How do I install Semgrep?

Install Semgrep using pip with ‘pip install semgrep’, using Homebrew on macOS with ‘brew install semgrep’, or using Docker with ‘docker run semgrep/semgrep’. The pip method works on all operating systems and is the recommended approach. After installation, verify it works by running ‘semgrep –version’ in your terminal.

Is Semgrep free to use?

Yes, the Semgrep open-source engine is free under the LGPL-2.1 license and includes 2,800+ community rules. The full Semgrep platform – which adds cross-file analysis, SCA, secrets detection, and AI-powered triage – is free for teams of up to 10 contributors. Beyond 10 contributors, the Team plan costs $35 per contributor per month.

What is the difference between Semgrep OSS and Semgrep Cloud?

Semgrep OSS is the open-source CLI engine that performs single-file pattern matching with 2,800+ community rules. Semgrep Cloud (also called Semgrep AppSec Platform) adds cross-file dataflow analysis, 20,000+ Pro rules, AI-powered triage with Semgrep Assistant, a web dashboard for managing findings, and integrations for PR comments. Semgrep Cloud is free for up to 10 contributors.

How do I set up Semgrep in GitHub Actions?

Create a workflow file at .github/workflows/semgrep.yml that triggers on pull_request and push events. Use the ‘semgrep/semgrep-action@v1’ action or run the Semgrep CLI directly. For Semgrep Cloud integration, add your SEMGREP_APP_TOKEN as a GitHub secret and use ‘semgrep ci’ as the scan command to get PR comments and dashboard reporting.

How do I write custom Semgrep rules?

Create a YAML file with a rules array. Each rule needs an id, a pattern or patterns block, a message, a severity level (ERROR, WARNING, or INFO), and a languages array. Semgrep’s pattern syntax mirrors the target language – you write patterns that look like the code you want to match, using metavariables like $X as placeholders. Test rules with ‘semgrep –config your-rule.yaml’ against your codebase.

What languages does Semgrep support?

Semgrep supports over 30 programming languages including Python, JavaScript, TypeScript, Java, Go, Ruby, C, C++, C#, Rust, Kotlin, Swift, PHP, Scala, Terraform, Dockerfile, and Kubernetes YAML. The open-source engine supports all languages. The Pro engine adds deeper cross-file analysis for a subset of these languages.

How do I reduce false positives in Semgrep?

Use several strategies: create a .semgrepignore file to exclude test files, generated code, and vendor directories. Use Semgrep Assistant (available in the Cloud platform) for AI-powered triage that automatically filters noise. Write custom rules with pattern-not clauses to exclude known-safe patterns. Start with high-confidence rule sets like p/default rather than broad sets like p/security-audit.

What are the best Semgrep rule sets to start with?

Start with p/default, which includes high-confidence security and correctness rules curated by the Semgrep team. Add p/security-audit for broader security coverage when you are ready for more findings. For specific languages, use targeted sets like p/python, p/javascript, or p/golang. For infrastructure scanning, add p/terraform or p/docker-compose. You can combine multiple rule sets in a single scan.

How do I configure Semgrep to post comments on pull requests?

Connect your repository to Semgrep Cloud at semgrep.dev, install the Semgrep GitHub App, and add your SEMGREP_APP_TOKEN to your CI environment. When Semgrep runs with ‘semgrep ci’ in your pipeline, it automatically posts inline comments on pull requests for any new findings. Comments include the rule ID, severity, explanation, and remediation guidance.

Can Semgrep scan Docker containers and infrastructure-as-code?

Yes. Semgrep has dedicated rule sets for Dockerfile security (p/dockerfile), Terraform misconfigurations (p/terraform), Kubernetes YAML (p/kubernetes), and Docker Compose files (p/docker-compose). These rules detect issues like running containers as root, exposing unnecessary ports, missing resource limits, and insecure cloud resource configurations.

How fast is Semgrep compared to other SAST tools?

Semgrep is one of the fastest SAST tools available. The median CI scan time is approximately 10 seconds because Semgrep uses diff-aware scanning to analyze only changed files on pull requests. Full repository scans typically complete in under 60 seconds for most codebases. This is significantly faster than tools like SonarQube, Checkmarx, or Veracode, which often take minutes to hours for comparable analysis.

How do I ignore specific Semgrep findings?

Ignore findings at three levels. In code, add a ‘# nosemgrep: rule-id’ comment on the line before the finding. In configuration, add paths or patterns to a .semgrepignore file. In Semgrep Cloud, triage findings as false positives or accepted risks in the dashboard – these triage decisions persist across future scans so the same finding is not reported again.

Does Semgrep work with GitLab CI and other CI platforms?

Yes. Semgrep works with any CI platform that can run a shell command. For GitLab CI, add a Semgrep job to your .gitlab-ci.yml file. Semgrep also has documented integrations for Jenkins, CircleCI, Buildkite, and Azure Pipelines. The ‘semgrep ci’ command handles authentication, diff-aware scanning, and result reporting regardless of which CI platform you use.

Originally published at aicodereview.cc