Skip to content

security.md

Latest commit

 

History

History
83 lines (57 loc) · 5.23 KB

security.md

File metadata and controls

83 lines (57 loc) · 5.23 KB

Security

This project ships workflow files that other people will run. That makes security part of the contract, not an afterthought.

Credentials

  • No real credentials in workflow files. Ever. Not in parameters, not in notes, not in description, not in a base64 blob "just for testing."
  • Use the framework's credential reference mechanism (in n8n: the credentials block referencing a credential ID; in others: equivalent).
  • Use clearly fake placeholders in examples — YOUR_API_KEY, REPLACE_ME, or framework-specific reference syntax such as {{ $secrets.OPENAI_API_KEY }}.
  • If you ever paste a real key by accident, rotate it immediately — assume any committed key is public.

Secret scanning

tools/audit_workflows.py runs a conservative secret scan on every JSON file and writes findings to reports/workflow-audit.json under secretFindings. Matched values are replaced with [REDACTED] before anything is written to disk.

The scan is not a guarantee. It catches common, well-shaped patterns (OpenAI keys, AWS access key IDs, GitHub tokens, JWT-like strings, etc.) but it will miss things that don't match the patterns. Treat a clean report as "nothing obvious found", not "this is safe."

If a report ever includes anything that looks like a real secret, open an issue immediately and treat it as a leak until proven otherwise.

Webhooks

  • Workflows that expose webhooks must validate the source. Either by signature (Stripe, GitHub, Shopify all support this) or by a shared secret in a header — never by IP allow-list alone.
  • Do not commit real webhook URLs containing tenant IDs or other identifying components. Genericise them in examples.
  • Webhooks that have side effects must be idempotent. See wiki/patterns/.

PII

  • Workflows that process user data must declare it. Tag with pii in workflow metadata.
  • Do not commit example inputs that contain real names, emails, addresses, phone numbers, or any other personal data. Use clearly synthetic placeholders.
  • Logging in workflows: prefer hashes or coarse counts over raw values when the workflow handles PII.

Generated workflows

The current generators are deterministic:

  • The Expansion Pack V0 generator produces 420 template workflows under workflows/generated/open-workflow-library-v0/ with placeholder credentials and placeholder URLs only.
  • The prompt-to-n8n MVP under tools/prompt_to_n8n.py writes output to reports/runtime-proof/<slug>/ with the same placeholder rules. It is a deterministic keyword-rule pipeline, not an LLM.

Rules that apply now and that will continue to apply when the LLM-backed generator lands:

  • Generated workflows are reviewed before being promoted into the curated catalog. Generation does not bypass the contribution standards.
  • Generators never have access to real credentials and cannot embed them. Generated workflows reference credentials by symbolic name; the operator supplies the actual values at deployment time.
  • Generators must not produce real secret values in placeholders. If a future LLM-backed generator returns something that matches the audit tool's secret patterns, the generator must reject the output.
  • The static n8n validator (tools/validate_n8n_workflow.py) enforces the placeholder rule for any URL host outside the safe allow-list and refuses credential-like fields with non-placeholder values.

Regulated industries

This library is general-purpose automation tooling. It is not a substitute for industry-specific compliance work.

  • Healthcare / homecare. Do not use workflows from this library as a replacement for clinical decision-making, diagnosis, triage, or medication management. They are not safety-rated for that, they are not validated for that, and no LLM step in any workflow here should be treated as a clinician.
  • Finance, legal, regulated communications. Workflows here are starting points, not compliant systems. Compliance (KYC, AML, audit trails, retention) is the operator's responsibility.
  • Children / vulnerable populations. Apply the same caution as healthcare: extra review, extra opt-in, no automated decisions that affect a person without a human in the loop.

If a workflow's purpose touches one of these areas, mark it explicitly in metadata and notes, and link to the relevant compliance considerations the operator must handle themselves.

Contribution standards

When contributing a workflow:

  1. Strip all real credentials. Re-export from a clean workspace if needed.
  2. Run python tools/audit_workflows.py locally and confirm there are no new entries under secretFindings.
  3. Replace identifying webhook URLs and emails with placeholders.
  4. Document required credentials in the workflow's notes field using symbolic names.
  5. Note any PII handling explicitly.
  6. Flag if the workflow targets a regulated domain.

PRs that contain anything matching the audit tool's secret patterns will be flagged in review and not merged until cleaned.

Reporting a security issue

If you find a leaked secret in this repository, or a workflow that has a security problem you don't want to disclose publicly, open a private issue or contact the maintainers directly — do not file a public issue with the problem in it.