From 604b291236d6a98ca8d192f8525a8f24987eaf81 Mon Sep 17 00:00:00 2001
From: Dawid Myslak <dawid.myslak@gmail.com>
Date: Mon, 23 Mar 2026 16:04:17 +0100
Subject: [PATCH] docs: Add security fix hygiene guidelines for public
 artifacts (#27441)

---
 .claude/skills/create-pr/SKILL.md | 26 +++++++++++++++++++++++---
 AGENTS.md                         | 26 +++++++++++++++++++++++++-
 2 files changed, 48 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/create-pr/SKILL.md b/.claude/skills/create-pr/SKILL.md
index 977d41609c7..3ddc67faf55 100644
--- a/.claude/skills/create-pr/SKILL.md
+++ b/.claude/skills/create-pr/SKILL.md
@@ -53,17 +53,20 @@ Creates GitHub PRs with titles that pass n8n's `check-pr-title` CI validation.
    git log origin/master..HEAD --oneline
    ```
 
-2. **Analyze changes** to determine:
+2. **If this is a security fix**, audit every public-facing artifact before
+   proceeding (see Security Fixes below).
+
+3. **Analyze changes** to determine:
    - Type: What kind of change is this?
    - Scope: Which package/area is affected?
    - Summary: What does the change do?
 
-3. **Push branch if needed**:
+4. **Push branch if needed**:
    ```bash
    git push -u origin HEAD
    ```
 
-4. **Create PR** using gh CLI with the template from `.github/pull_request_template.md`:
+5. **Create PR** using gh CLI with the template from `.github/pull_request_template.md`:
    ```bash
    gh pr create --draft --title "<type>(<scope>): <summary>" --body "$(cat <<'EOF'
    ## Summary
@@ -152,3 +155,20 @@ Key validation rules:
 - Exclamation mark for breaking changes goes before the colon
 - Summary must start with capital letter
 - Summary must not end with a period
+
+## Security Fixes
+
+**This repo is public.** Never expose the attack vector in any public artifact.
+Describe **what the code does**, not what threat it prevents.
+
+| Artifact | BAD | GOOD |
+|---|---|---|
+| Branch | `fix-sql-injection-in-webhook` | `fix-webhook-input-validation` |
+| PR title | `fix(core): Prevent SSRF` | `fix(core): Validate outgoing URLs` |
+| Commit msg | `fix: prevent denial of service` | `fix: add payload size validation` |
+| PR body | *"attacker could trigger SSRF…"* | *"validates URL protocol and host"* |
+| Linear ref | URL with slug (leaks title) | URL without slug or ticket ID only |
+| Test name | `'should prevent SQL injection'` | `'should sanitize query parameters'` |
+
+**Before pushing a security fix, verify:** no branch name, commit, PR title,
+PR body, Linear URL, test name, or code comment hints at the vulnerability.
diff --git a/AGENTS.md b/AGENTS.md
index 705ad5d28f7..be623018ec3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -16,7 +16,8 @@ frontend, and extensible node-based workflow engine.
 - When starting to work on a new ticket – create a new branch from fresh
   master with the name specified in Linear ticket
 - When creating a new branch for a ticket in Linear - use the branch name
-  suggested by linear
+  suggested by Linear, **unless it is a security fix** (see Security Fix
+  Hygiene below)
 - Use mermaid diagrams in MD files when you need to visualise something
 
 ## Essential Commands
@@ -190,6 +191,29 @@ handling), apply these checks:
   are not trade-offs. They're both required. If a design forces a choice
   between them, the design needs more work.
 
+### Security Fix Hygiene
+
+**This is a public repository.** When working on security fixes, never expose
+the attack vector or vulnerability type in any public-facing artifact. Attackers
+monitor open-source repos for signals like branch names, commit messages, PR
+titles, test descriptions, and Linear URLs.
+
+**Rules for security fixes:**
+
+- **Branch names:** Do NOT use the Linear-suggested branch name if it reveals
+  the vulnerability. Rename to describe the fix neutrally
+  (e.g. `node-1234-improve-request-handling`, not
+  `node-1234-fix-ddos-vulnerability`).
+- **Commit messages:** Describe what the code now does, not the threat it
+  prevents (e.g. `fix: add payload size validation`, not
+  `fix: prevent denial of service`).
+- **Test descriptions:** Use neutral, functional language
+  (e.g. `'should sanitize query parameters'`, not
+  `'should prevent SQL injection'`).
+- **Code comments:** Do not describe the attack scenario in comments.
+- **Linear references:** Never include the URL slug
+  (e.g. `.../N8N-1234/fix-ssrf-vulnerability`).
+
 ## Github Guidelines
 - When creating a PR, use the conventions in
   `.github/pull_request_template.md` and