From f32322cd41d0bcf32085d28e3ec765bde354c246 Mon Sep 17 00:00:00 2001
From: Alexsander Hamir <alexsanderhamirgomesbaptista@gmail.com>
Date: Wed, 11 Feb 2026 09:39:44 -0800
Subject: [PATCH] chore: improve Semgrep rules documentation and organization
 (#20978)

- Add organizing rules (language/domain structure, naming, metadata)
- Require all rules to fail CI (severity: ERROR, no warn-only)
- Move unbounded-memory.yml to python/reliability/ per structure
- Enhance unbounded-memory rule metadata (tags, confidence, source)
---
 .semgrep/rules/README.md                      | 52 +++++++++++++++----
 .../{ => reliability}/unbounded-memory.yml    |  7 ++-
 2 files changed, 46 insertions(+), 13 deletions(-)
 rename .semgrep/rules/python/{ => reliability}/unbounded-memory.yml (67%)

diff --git a/.semgrep/rules/README.md b/.semgrep/rules/README.md
index 0dbb77cdd4..6cffcc3296 100644
--- a/.semgrep/rules/README.md
+++ b/.semgrep/rules/README.md
@@ -1,22 +1,52 @@
-# Custom Semgrep rules for LiteLLM
+# Custom Semgrep Rules
 
-Add custom rule YAML files here. Semgrep loads all `.yml`/`.yaml` files under this directory.
+All `.yml` files under `.semgrep/rules/` run in CI (CircleCI `semgrep` job).
 
-**Run only custom rules (CI / fail on findings):**
+## Add a Rule
+
+* Add a `.yml` file under `.semgrep/rules/<language>/<domain>/`
+
+
+[Rule syntax →](https://semgrep.dev/docs/writing-rules/rule-syntax/)
+
+## Organizing Rules
+
+### Structure: language → domain
+
+```
+.semgrep/rules/<language>/<domain>/<rule-name>.yml
+```
+
+Examples:
+
+- `python/security/unsafe-yaml-load.yml`
+- `python/reliability/missing-timeout-http.yml`
+- `python/performance/blocking-io-in-async.yml`
+
+### Rule metadata
+
+Match tags to the folder for consistent filtering:
+
+```yaml
+metadata:
+  tags: [python, security]
+```
+
+### Severity expectations
+
+All rules must fail CI on findings. No warn-only rules.
+
+- Use `severity: ERROR` in rule metadata
+- If a rule is noisy → refine until low false positives before adding
+
+## Run Locally
 
 ```bash
 semgrep scan --config .semgrep/rules . --error
 ```
 
-**Run with registry + custom rules:**
+With Semgrep registry:
 
 ```bash
 semgrep scan --config auto --config .semgrep/rules .
 ```
-
-**Layout:**
-
-- `python/` – Python-specific rules (security, patterns)
-- Add more subdirs as needed (e.g. `generic/` for language-agnostic rules)
-
-See [Semgrep rule syntax](https://semgrep.dev/docs/writing-rules/rule-syntax/).
diff --git a/.semgrep/rules/python/unbounded-memory.yml b/.semgrep/rules/python/reliability/unbounded-memory.yml
similarity index 67%
rename from .semgrep/rules/python/unbounded-memory.yml
rename to .semgrep/rules/python/reliability/unbounded-memory.yml
index 811ef68934..f13c38471f 100644
--- a/.semgrep/rules/python/unbounded-memory.yml
+++ b/.semgrep/rules/python/reliability/unbounded-memory.yml
@@ -10,5 +10,8 @@ rules:
       - pattern: asyncio.Queue()
       - pattern: asyncio.Queue(maxsize=0)
     metadata:
-      category: correctness
-      cwe: "CWE-400: Uncontrolled Resource Consumption"
\ No newline at end of file
+      category: reliability
+      cwe: "CWE-400: Uncontrolled Resource Consumption"
+      tags: [python, reliability]
+      confidence: HIGH
+      source: https://docs.python.org/3/library/asyncio-queue.html