N8n Security Governance

n8n Security Governance

Use this skill as the production gate for AI Coding and Code2n8n work. A working demo is not automatically safe, traceable, or reversible.

Required outputs

Produce all applicable artifacts:

1. SECURITY-REVIEW.md: scope, trust boundaries, checks, evidence, findings, and decision.
2. SECURITY-CAVEATS.md: unresolved findings that block or limit deployment.
3. CHANGELOG.md entry: user-visible security or workflow behavior changes.
4. Workflow change-history sticky note: internal version, date, and plain-language change.
5. Release traceability: source commit SHA, workflow version/tag, validation result, and rollback target.

Never include real secrets, tokens, passwords, credential values, or sensitive customer data.

Security review

1. Establish scope and trust boundaries

Inventory:

• Public and internal entry points: webhook, REST, form, queue, schedule, CLI.
• Identities: user, admin, service account, n8n credential, worker.
• Sensitive data: secrets, PII, files, prompts, database records, logs.
• Side effects: writes, deletes, notifications, external calls, privileged actions.
• Trust transitions: internet to webhook, workflow to worker, worker to database, AI agent to tool.

2. Run mandatory checks

Use deterministic scanners when supported: dependency audit, secret scan, SAST, container scan, and n8n instance audit. Record tool versions and commands. Scanner results never replace manual auth and trust-boundary review.

3. Record findings

Each finding must contain:

markdownCopy code
## SEC-001: Short title
- Severity: Critical | High | Medium | Low | Informational
- Status: Open | Mitigated | Accepted | False positive
- Evidence: file:line, workflow/node, request/response, or reproducible command
- Impact:
- Reproduction:
- Required fix:
- Validation:
- Owner:
- Target version:

Do not call an issue fixed without a regression test or repeatable validation.

4. Make a deployment decision

• PASS: no unresolved Critical/High findings; validation and rollback evidence exist.
• CONDITIONAL: only documented Medium/Low risks remain with owner and due date.
• BLOCKED: unresolved Critical/High finding, fake/missing auth, exposed secret, injection, or no rollback path.

If the decision is not PASS, publish SECURITY-CAVEATS.md and remove "production-ready" or "enterprise-ready" claims.

Version control and change governance

Security without traceability is incomplete. Apply these controls to source, workflow JSON, and operational configuration.

Source control

• Work from a named branch; protect the release branch with review and CI.
• Commit workflow JSON, SDD, field mapping, security review, tests, and migration notes together.
• Keep credentials, .env, execution data, and local backups out of Git.
• Add a security-impact note when auth, permissions, credentials, data access, or webhook behavior changes.
• Tag approved releases using the repository convention and record the commit SHA.

Workflow versioning

• Maintain SemVer in the first sticky note: v<major.minor.patch> YYYY-MM-DD: summary.
• Major: breaking contract or behavior change.
• Minor: backward-compatible capability or node path.
• Patch: fix, hardening, documentation, or non-breaking refactor.
• Export the exact reviewed workflow JSON after validation.
• Apply an n8n tag containing the release/version identifier; keep import separate from production activation.

CI/CD gate

Require:

1. JSON/static lint.
2. Secret scan.
3. Dependency/container scan when applicable.
4. n8n REST import/schema validation.
5. Security regression tests for changed trust boundaries.
6. Artifact hash or commit SHA in release evidence.
7. Explicit approval before production activation.

Rollback

Document:

• Previous known-good Git tag/commit.
• Previous exported workflow JSON and n8n workflow ID.
• Database/config migration reversibility.
• Credential compatibility and rotation impact.
• Owner and rollback command/procedure.

Do not claim production readiness when the change cannot be traced to a commit or rolled back.

Observability minimum

Security review without runtime visibility is incomplete: an undetected silent failure is functionally equivalent to a missing control. Every production workflow must expose at least the following.

Required runtime signals

Required alert routes

At minimum, three escalation channels with documented owners:

1. High-volume soft signal (latency, queue depth) → a chat channel; reviewed daily.
2. Single-event hard signal (auth failure spike, credential rotation lag, repeated 5xx) → on-call paging.
3. Security incident (signature failure, identifier-injection attempt, secret exfil pattern in logs) → security on-call; auto-create incident ticket.

Dashboard targets

Pack-agnostic. Pick one and document the link in the workflow's sticky note:

• n8n Insights (Cloud and self-hosted Pro feature)
• Grafana + Prometheus, scraping the n8n metrics endpoint and Postgres execution data
• Datadog / New Relic / Honeycomb if already adopted

A dashboard does not exist until a link is in the sticky note. "Available via Grafana" is not enough.

Honesty rule

Workflows whose risk profile demands monitoring but ship without it must publish that absence in SECURITY-CAVEATS.md exactly as auth/injection findings would. Lack of observability is itself a finding.

Code2n8n integration

1. Run this skill after source inventory and before partition/design.
2. Carry findings into the SDD and partition decision.
3. Re-run affected checks after workflow generation.
4. Include the final security decision and release traceability in validation results.

§10 — V&V two-layer gate (added v0.28.0 after the einvoice-n8n incident)

📜 Why this exists: in Pack v0.27.0 the first external-SDK case study (examples/einvoice-n8n/) shipped with claims of "validated" backed only by scripts/security-scan.mjs (regex pass on workflow JSON) and scripts/live-roundtrip.mjs (n8n import/export round-trip). An adversarial review by a second AI immediately found 5 blocking-severity runtime bugs (broken HTTP status check, orphan dead-letter nodes, wrong resume URL variable name, timezone off-by-one for daily/monthly schedulers, missing CSV binary conversion) plus a package.json with non-existent dependency versions. Root cause: equating Layer 1 (structural / import-time) with validation. This section enforces both layers from now on.

Rule: before any text in a commit, release note, README, or sticky note may say "validated" / "tested" / "verified", the case MUST pass both layers below. Layer 1 alone is necessary but never sufficient.

Layer 1 — Structural / import-time (must pass, does not count as validation)

• scripts/security-scan.mjs — 0 errors on workflow JSON.
• scripts/live-roundtrip.mjs — every workflow JSON imports / GET / DELETE round-trips cleanly.
• Workflow JSON parses; manifest consistency holds.

Layer 2 — Compile / runtime / cross-document (required for the "validated" claim)

• Dependency reality: npm install (or equivalent) succeeds without --force; npm audit --omit=dev reports 0 high+ CVEs.
• Compile: tsc --noEmit (or equivalent) exits 0.
• Service starts: /healthz returns 200; authn enforced on protected paths (curl /protected/* without bearer → 401).
• Negative tests: oversized body → 413; prototype-pollution payload to dynamic dispatch endpoints → 400; unknown enum → 400.
• Workflow runtime contract (each of these is a Pack v0.27.0 failure):
  • HTTP nodes branching on status MUST set options.response.response.fullResponse = true. Otherwise $json.statusCode is undefined and || 200 defaults true → silent failures with corrupted audit log.
  • Wait + resume uses $execution.resumeUrl (NOT $resumeUrl — that is a hallucination).
  • Every node a sticky note or README promises is actually graph-connected (open the canvas and trace each dead-letter / notification edge).
  • Webhook responseMode = responseNode with a fixed-schema respondToWebhook node (NOT lastNode, which leaks whatever the final node returned).
  • Schedule triggers MUST have settings.timezone set; Code-node date math MUST use Intl.DateTimeFormat({ timeZone }) instead of UTC toISOString().slice(0,10).
  • Email / file attachments preceded by Convert to File node when the source is a string.
• Cross-document parity: every README claim points at the file/line that implements it; sticky notes do not promise behavior the JSON omits.
• At least one end-to-end smoke per pattern (real svc + real workflow + real Sheet row).

Required output

• AI agents: follow docs/code2n8n-vv-a2a.md — the A2A directive with exact tool invocations, mandatory evidence schema, forbidden phrases, and skip behavior.
• Human reviewers: tick every box in docs/code2n8n-vv-checklist.md explicitly. No aggregated "all good".
• Release notes / READMEs must distinguish ✅ what was tested · ❌ what was NOT tested · 🟡 what is known-partial (with target version).
• Forbidden phrases unless backed by Layer 2 evidence: "Tested", "X/X ok", "Validated", "Production-ready". Use the substitutes in the A2A directive / checklist.

Worked example

examples/einvoice-n8n/SECURITY-REVIEW.md is the retroactive application of this gate to the v0.27.0 case. 13 structured SEC-### findings (SEC-001 … SEC-013) — SEC-011 / SEC-012 / SEC-013 are the exact failure modes this gate exists to catch (broken status check, orphan dead-letter, timezone trap). The gate would have blocked v0.27.0.

Completion checklist

• Trust boundaries and sensitive data are documented.
• Auth, authorization, injection, webhook, secret, file, AI-agent, and audit controls were reviewed.
• Findings have evidence, severity, status, owner, and target version.
• Unresolved risks are disclosed in SECURITY-CAVEATS.md.
• Workflow sticky-note version and repository changelog were updated.
• Reviewed JSON maps to a Git commit SHA and n8n release tag.
• CI validation and rollback evidence exist.
• Deployment decision is PASS, CONDITIONAL, or BLOCKED.
• §10 V&V two-layer gate: Layer 1 + Layer 2 both pass per docs/code2n8n-vv-checklist.md. Every checklist box ticked explicitly, not aggregated.