Redsf/n8n-workflow-linter

# n8n-workflow-linter [](https://github.com/Redsf/n8n-workflow-linter/actions/workflows/ci.yml) [](https://www.python.org/) [](LICENSE) 针对 [n8n](https://n8n.io) workflow 导出文件的静态分析工具。可在 CI 中捕获泄露的凭据、硬编码的机密信息、缺失的错误处理以及其他问题——在有缺陷或存在泄露风险的 workflow 合并到 `main` 分支之前进行拦截。 将 n8n workflow 作为 JSON 进行版本控制现在已很普遍。但对它们进行 Lint 检查却并非如此。 workflow 的 JSON 导出文件会轻易携带有效的 API key、来自您私有实例的 credential ID、作为测试数据的真实客户记录，或者是没有重试机制的 HTTP 调用——并且在它进入代码库或在凌晨 2 点运行失败之前，没有任何机制会提醒您。这就是缺失的那道检查关卡。 ``` $ n8n-lint workflows/ workflows/cold_email.json :12 error openAiApi credential uses a real instance ID (8gccIj…aoEr); replace with REPLACE_WITH_CREDENTIAL_ID (Personalize Email) :40 warning HTTP Request has retryOnFail disabled — a transient error will fail the run (Send) warning workflow ships pinned data for: Get Leads — remove it before publishing; it commonly contains real records Checked 1 workflow file(s): 1 error(s), 2 warning(s), 0 info. ``` **零运行时依赖。** 整个 linter 完全基于 Python 标准库运行，因此它可以在任何仅有 `python` 环境的 CI 作业中运行，无需其他依赖。 ## 安装 ``` pip install n8n-workflow-linter ``` 或者无需安装直接运行最新版本： ``` pipx run n8n-workflow-linter workflows/ ``` ## 快速开始 ``` # Lint 一个目录（递归进入子文件夹） n8n-lint workflows/ # Lint 单个文件 n8n-lint workflows/cold_email.json # 遇到 warnings 也会失败，而不仅仅是 errors n8n-lint workflows/ --strict # 查看所有 rule n8n-lint --list-rules ``` ## 规则说明 | 规则 | 默认级别 | 捕获内容 | |---|---|---| | `real-credential-id` | **error** | 凭据引用了来自真实 n8n 实例的 ID，而不是占位符。这会泄露私有实例所使用的 credential，并导致其他任何人无法导入——credential ID 无法在不同账户间转移。 | | `hardcoded-secret` | **error** | 文件中任意位置嵌入了有效的 API key、token 或私钥（OpenAI、Anthropic、AWS、Google、Slack、Stripe、Twilio、GitHub、JWTs、PEM 数据块）。已记录的占位符将被忽略。 | | `hardcoded-resource-id` | warning | 节点中硬编码了 Google Drive/Sheets 的文件 ID 或 Gmail 的标签 ID。这会泄露真实部署中所使用的资源，并破坏可复用性。 | | `no-error-trigger` | warning | 没有激活的 **Error Trigger** 节点——workflow 运行失败时将无法通知任何人。 | | `missing-retry` | warning | 向外部服务发起的 **HTTP Request** 关闭了 `retryOnFail`——瞬时的网络错误会导致整个运行过程失败。 | | `orphan-node` | warning | 画布上存在未连接到任何部分的节点。这些节点永远不会运行，通常意味着连线被误删了。 | | `pinned-data` | warning | 导出文件中遗留了 pinned 的测试数据。这会使文件变得臃肿，且经常包含真实的客户记录。 | | `unauthenticated-webhook` | warning | 没有身份验证的 **Webhook** 触发器——任何拥有此 URL 的人都可以触发它。 | | `disabled-node` | info | 画布上遗留的已禁用节点。| 每一个默认值都是根据真实的 workflow 进行校准的，以将误报率保持在接近零的水平。`real-credential-id` 和 `hardcoded-secret` 被设为 error 是因为它们应当阻止合并；除非您选择启用 `--strict`，否则其余规则仅作为建议。 ## 在 CI 中使用 ### GitHub Actions ``` name: lint-workflows on: [push, pull_request] jobs: n8n-lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: Redsf/n8n-workflow-linter@v1 with: path: workflows/ strict: "false" # set "true" to fail on warnings ``` 检查结果会以内联注释的形式显示在 pull request 上——该 action 会发出 GitHub workflow 命令，因此每个结果都会精确定位到其对应的文件和行号。 ### pre-commit ``` # .pre-commit-config.yaml repos: - repo: https://github.com/Redsf/n8n-workflow-linter rev: v0.1.0 hooks: - id: n8n-lint args: ["--strict"] ``` ### 其他任何 CI 这是一个带有明确退出码的常规 CLI 工具： ``` pip install n8n-workflow-linter n8n-lint workflows/ --strict ``` ## 配置 在您的代码库根目录下放置一个 `.n8nlintrc.json` 文件，以更改严重级别或关闭规则。每个规则都可以设置为 `error`、`warning`、`info` 或 `off`： ``` { "rules": { "disabled-node": "off", "hardcoded-resource-id": "error", "missing-retry": "warning" } } ``` 使用 `--config path/to/config.json` 指向不同的配置文件，或者从命令行临时禁用规则： ``` n8n-lint workflows/ --disable missing-retry --disable disabled-node ``` ## 输出格式 | `--format` | 用途 | |---|---| | `text` (默认) | 面向人类阅读。输出到终端时带有颜色；使用 `--no-color` 可禁用。 | | `github` | 用于 GitHub Actions。发出 `::error`/`::warning` workflow 命令，用于在 PR 上生成内联注释。 | | `json` | 用于脚本和仪表盘。稳定的 schema：`{summary, findings[]}`。 | ## 退出码 | 代码 | 含义 | |---|---| | `0` | 没有阻塞性的检查结果。（存在 warning，但未开启 `--strict`。） | | `1` | 至少有一个 error——或在 `--strict` 模式下出现任何 warning。 | | `2` | 使用错误：配置错误、未知规则或未找到 workflow 文件。 | ## 特意不处理的内容 ## 添加规则 规则非常小巧且独立。请在 [`src/n8n_linter/rules/`](src/n8n_linter/rules/) 中实现一个 `Rule` 子类，将实例添加到 [`rules/__init__.py`](src/n8n_linter/rules/__init__.py) 的 `ALL_RULES` 中，并在 [`tests/fixtures/`](tests/fixtures/) 下添加一对通过/未通过的测试夹具（fixture）。引擎、配置系统和 `--list-rules` 都会从注册表中读取信息，因此无需更改其他任何内容。详情请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## License MIT — 详见 [LICENSE](LICENSE)。

标签：Blue Team, DevSecOps, Linux安全, n8n, Python, 上游代理, 云安全监控, 前端框架, 开源框架, 持续集成, 无后门, 逆向工具, 静态分析