firecrawl-policy-guardrails

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

FireCrawl Policy & Guardrails

FireCrawl 策略与防护机制

Overview

概述

Automated policy enforcement and guardrails for FireCrawl integrations.

为FireCrawl集成提供自动化策略执行与防护机制。

Prerequisites

前置条件

ESLint configured in project
Pre-commit hooks infrastructure
CI/CD pipeline with policy checks
TypeScript for type enforcement

项目中已配置ESLint
具备提交前钩子（Pre-commit hooks）基础设施
带有策略检查的CI/CD流水线
使用TypeScript进行类型校验

ESLint Rules

ESLint规则

Custom FireCrawl Plugin

自定义FireCrawl插件

javascript

// eslint-plugin-firecrawl/rules/no-hardcoded-keys.js
module.exports = {
  meta: {
    type: 'problem',
    docs: {
      description: 'Disallow hardcoded FireCrawl API keys',
    },
    fixable: 'code',
  },
  create(context) {
    return {
      Literal(node) {
        if (typeof node.value === 'string') {
          if (node.value.match(/^sk_(live|test)_[a-zA-Z0-9]{24,}/)) {
            context.report({
              node,
              message: 'Hardcoded FireCrawl API key detected',
            });
          }
        }
      },
    };
  },
};

javascript

// eslint-plugin-firecrawl/rules/no-hardcoded-keys.js
module.exports = {
  meta: {
    type: 'problem',
    docs: {
      description: 'Disallow hardcoded FireCrawl API keys',
    },
    fixable: 'code',
  },
  create(context) {
    return {
      Literal(node) {
        if (typeof node.value === 'string') {
          if (node.value.match(/^sk_(live|test)_[a-zA-Z0-9]{24,}/)) {
            context.report({
              node,
              message: 'Hardcoded FireCrawl API key detected',
            });
          }
        }
      },
    };
  },
};

ESLint Configuration

ESLint配置

javascript

// .eslintrc.js
module.exports = {
  plugins: ['firecrawl'],
  rules: {
    'firecrawl/no-hardcoded-keys': 'error',
    'firecrawl/require-error-handling': 'warn',
    'firecrawl/use-typed-client': 'warn',
  },
};

javascript

// .eslintrc.js
module.exports = {
  plugins: ['firecrawl'],
  rules: {
    'firecrawl/no-hardcoded-keys': 'error',
    'firecrawl/require-error-handling': 'warn',
    'firecrawl/use-typed-client': 'warn',
  },
};

Pre-Commit Hooks

提交前钩子

yaml

undefined

yaml

undefined

.pre-commit-config.yaml

repos:

repo: local hooks:
- id: firecrawl-secrets-check name: Check for FireCrawl secrets entry: bash -c 'git diff --cached --name-only | xargs grep -l "sk_live_" && exit 1 || exit 0' language: system pass_filenames: false
- id: firecrawl-config-validate name: Validate FireCrawl configuration entry: node scripts/validate-firecrawl-config.js language: node files: '.firecrawl.json$'

undefined

repos:

repo: local hooks:
- id: firecrawl-secrets-check name: Check for FireCrawl secrets entry: bash -c 'git diff --cached --name-only | xargs grep -l "sk_live_" && exit 1 || exit 0' language: system pass_filenames: false
- id: firecrawl-config-validate name: Validate FireCrawl configuration entry: node scripts/validate-firecrawl-config.js language: node files: '.firecrawl.json$'

undefined

TypeScript Strict Patterns

TypeScript严格模式规范

typescript

// Enforce typed configuration
interface FireCrawlStrictConfig {
  apiKey: string;  // Required
  environment: 'development' | 'staging' | 'production';  // Enum
  timeout: number;  // Required number, not optional
  retries: number;
}

// Disallow any in FireCrawl code
// @ts-expect-error - Using any is forbidden
const client = new Client({ apiKey: any });

// Prefer this
const client = new FireCrawlClient(config satisfies FireCrawlStrictConfig);

typescript

// 强制类型化配置
interface FireCrawlStrictConfig {
  apiKey: string;  // 必填
  environment: 'development' | 'staging' | 'production';  // 枚举类型
  timeout: number;  // 必填数字，不可选
  retries: number;
}

// 禁止在FireCrawl代码中使用any类型
// @ts-expect-error - Using any is forbidden
const client = new Client({ apiKey: any });

// 推荐写法
const client = new FireCrawlClient(config satisfies FireCrawlStrictConfig);

Architecture Decision Records

架构决策记录

ADR Template

ADR模板

markdown

undefined

markdown

undefined

ADR-001: FireCrawl Client Initialization

ADR-001: FireCrawl客户端初始化

Status

状态

Accepted

已通过

Context

背景

We need to decide how to initialize the FireCrawl client across our application.

我们需要确定在应用中如何初始化FireCrawl客户端。

Decision

决策

We will use the singleton pattern with lazy initialization.

我们将使用单例模式结合延迟初始化。

Consequences

影响

Pro: Single client instance, connection reuse
Pro: Easy to mock in tests
Con: Global state requires careful lifecycle management

优点：单一客户端实例，复用连接
优点：测试中易于模拟
缺点：全局状态需要谨慎的生命周期管理

Enforcement

执行机制

ESLint rule: firecrawl/use-singleton-client
CI check: grep for "new FireCrawlClient(" outside allowed files

undefined

ESLint规则：firecrawl/use-singleton-client
CI检查：在允许的文件外搜索"new FireCrawlClient("

undefined

Policy-as-Code (OPA)

策略即代码（OPA）

rego

undefined

rego

undefined

firecrawl-policy.rego

package firecrawl

Deny production API keys in non-production environments

禁止在非生产环境使用生产环境API密钥

deny[msg] { input.environment != "production" startswith(input.apiKey, "sk_live_") msg := "Production API keys not allowed in non-production environment" }

Require minimum timeout

要求最小超时时间

deny[msg] { input.timeout < 10000 msg := sprintf("Timeout too low: %d < 10000ms minimum", [input.timeout]) }

Require retry configuration

要求配置重试机制

deny[msg] { not input.retries msg := "Retry configuration is required" }

undefined

deny[msg] { not input.retries msg := "Retry configuration is required" }

undefined

CI Policy Checks

CI策略检查

yaml

undefined

yaml

undefined

.github/workflows/firecrawl-policy.yml

name: FireCrawl Policy Check

on: [push, pull_request]

jobs: policy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

  - name: Check for hardcoded secrets
    run: |
      if grep -rE "sk_(live|test)_[a-zA-Z0-9]{24,}" --include="*.ts" --include="*.js" .; then
        echo "ERROR: Hardcoded FireCrawl keys found"
        exit 1
      fi

  - name: Validate configuration schema
    run: |
      npx ajv validate -s firecrawl-config.schema.json -d config/firecrawl/*.json

  - name: Run ESLint FireCrawl rules
    run: npx eslint --plugin firecrawl --rule 'firecrawl/no-hardcoded-keys: error' src/

undefined

name: FireCrawl Policy Check

on: [push, pull_request]

jobs: policy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

  - name: Check for hardcoded secrets
    run: |
      if grep -rE "sk_(live|test)_[a-zA-Z0-9]{24,}" --include="*.ts" --include="*.js" .; then
        echo "ERROR: Hardcoded FireCrawl keys found"
        exit 1
      fi

  - name: Validate configuration schema
    run: |
      npx ajv validate -s firecrawl-config.schema.json -d config/firecrawl/*.json

  - name: Run ESLint FireCrawl rules
    run: npx eslint --plugin firecrawl --rule 'firecrawl/no-hardcoded-keys: error' src/

undefined

Runtime Guardrails

运行时防护机制

typescript

// Prevent dangerous operations in production
const BLOCKED_IN_PROD = ['deleteAll', 'resetData', 'migrateDown'];

function guardFireCrawlOperation(operation: string): void {
  const isProd = process.env.NODE_ENV === 'production';

  if (isProd && BLOCKED_IN_PROD.includes(operation)) {
    throw new Error(`Operation '${operation}' blocked in production`);
  }
}

// Rate limit protection
function guardRateLimits(requestsInWindow: number): void {
  const limit = parseInt(process.env.FIRECRAWL_RATE_LIMIT || '100');

  if (requestsInWindow > limit * 0.9) {
    console.warn('Approaching FireCrawl rate limit');
  }

  if (requestsInWindow >= limit) {
    throw new Error('FireCrawl rate limit exceeded - request blocked');
  }
}

typescript

// 阻止生产环境中的危险操作
const BLOCKED_IN_PROD = ['deleteAll', 'resetData', 'migrateDown'];

function guardFireCrawlOperation(operation: string): void {
  const isProd = process.env.NODE_ENV === 'production';

  if (isProd && BLOCKED_IN_PROD.includes(operation)) {
    throw new Error(`Operation '${operation}' blocked in production`);
  }
}

// 限流保护
function guardRateLimits(requestsInWindow: number): void {
  const limit = parseInt(process.env.FIRECRAWL_RATE_LIMIT || '100');

  if (requestsInWindow > limit * 0.9) {
    console.warn('Approaching FireCrawl rate limit');
  }

  if (requestsInWindow >= limit) {
    throw new Error('FireCrawl rate limit exceeded - request blocked');
  }
}

Instructions

操作步骤

Step 1: Create ESLint Rules

步骤1：创建ESLint规则

Implement custom lint rules for FireCrawl patterns.

实现针对FireCrawl规范的自定义代码检查规则。

Step 2: Configure Pre-Commit Hooks

步骤2：配置提交前钩子

Set up hooks to catch issues before commit.

设置钩子以在提交代码前发现问题。

Step 3: Add CI Policy Checks

步骤3：添加CI策略检查

Implement policy-as-code in CI pipeline.

在CI流水线中实现策略即代码（Policy-as-Code）。

Step 4: Enable Runtime Guardrails

步骤4：启用运行时防护机制

Add production safeguards for dangerous operations.

为危险操作添加生产环境防护措施。

Output

输出结果

ESLint plugin with FireCrawl rules
Pre-commit hooks blocking secrets
CI policy checks passing
Runtime guardrails active

带有FireCrawl规则的ESLint插件
阻止密钥泄露的提交前钩子
通过检查的CI策略
已激活的运行时防护机制

Error Handling

错误处理

Issue	Cause	Solution
ESLint rule not firing	Wrong config	Check plugin registration
Pre-commit skipped	--no-verify	Enforce in CI
Policy false positive	Regex too broad	Narrow pattern match
Guardrail triggered	Actual issue	Fix or whitelist

问题	原因	解决方案
ESLint规则未触发	配置错误	检查插件注册情况
提交前钩子被跳过	使用了--no-verify参数	在CI中强制执行
策略误报	正则表达式范围过宽	缩小匹配模式
防护机制被触发	存在实际问题	修复问题或加入白名单

Examples

示例

Quick ESLint Check

快速ESLint检查

bash

npx eslint --plugin firecrawl --rule 'firecrawl/no-hardcoded-keys: error' src/

bash

npx eslint --plugin firecrawl --rule 'firecrawl/no-hardcoded-keys: error' src/

Resources

参考资源

Next Steps

下一步

For architecture blueprints, see

firecrawl-architecture-variants

如需架构蓝图，请查看

firecrawl-architecture-variants

。