Configuration Reference

This page documents all configuration options for the API-Fence Envoy HTTP filter.

Configuration Format

API-Fence configuration is provided as a JSON object in the Envoy filter configuration:

http_filters:
  - name: envoy.filters.http.dynamic_modules
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.filters.http.dynamic_modules.v3.DynamicModuleFilter
      dynamic_module_config:
        name: api_fence
        do_not_close: true
      filter_name: api_fence
      filter_config:
        "@type": "type.googleapis.com/google.protobuf.StringValue"
        value: |
          {
            "api_name": "my_api",
            "openapi_spec_path": "/etc/envoy/openapi.yaml",
            ...
          }

Top-Level Options

* Either openapi_spec_path or openapi_spec_inline must be provided, but not both.

Cache Configuration

The cache section configures the JSON schema validator cache:

{
  "cache": {
    "max_capacity": 1000,
    "ttl_seconds": 3600
  }
}

The cache stores compiled JSON Schema validators keyed by a hash of the schema content. This avoids re-compiling schemas for repeated requests to the same endpoint.

Validation Configuration

The validation section controls request/response validation behavior:

{
  "validation": {
    "validate_request": true,
    "validate_response": false,
    "fail_on_request_error": true,
    "fail_on_response_error": false,
    "pool": {
      "enabled": false,
      "thread_count": 2,
      "timeout_ms": 50,
      "queue_capacity": 1000,
      "timeout_action": "allow"
    }
  }
}

Validation Options

Validation Pool Options

The validation pool offloads JSON schema validation to a dedicated thread pool, preventing validation from blocking Envoy worker threads:

Mocking Configuration

The mocking section enables mock response generation for API testing:

{
  "mocking": {
    "enabled": true,
    "prefer_examples": true,
    "default_status_code": 200,
    "delay_ms": 100,
    "add_mock_header": true
  }
}

When mocking is enabled, API-Fence generates responses from:

1. Examples in the OpenAPI response definition (if prefer_examples: true)
2. Schema-based generation using fake data matching the response schema

Security Limits

The security section configures input validation limits to prevent resource exhaustion attacks:

{
  "security": {
    "max_path_length": 2048,
    "max_header_value_length": 8192,
    "max_query_string_length": 8192,
    "max_body_size": 10485760,
    "max_json_depth": 32,
    "max_array_items": 1000,
    "max_object_properties": 100,
    "max_schema_depth": 32,
    "max_regex_pattern_length": 1024
  }
}

HTTP Status Codes

Security limit violations return appropriate HTTP status codes:

ModSecurity Configuration

The modsecurity section enables WAF scanning. See ModSecurity Guide for detailed documentation.

{
  "modsecurity": {
    "scan_request": true,
    "scan_response": false,
    "request_action": "block",
    "response_action": "alert",
    "primary_ruleset": {
      "name": "crs",
      "use_bundled_crs": true,
      "bundled_crs_profile": "full"
    }
  }
}

Dynamic Metadata

API-Fence sets Envoy dynamic metadata that can be used in access logs and other filters:

Access Log Example

access_log:
  - name: envoy.access_loggers.file
    typed_config:
      "@type": type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog
      path: /dev/stdout
      log_format:
        text_format_source:
          inline_string: |
            [%START_TIME%] %REQ(:METHOD)% %REQ(:PATH)% %RESPONSE_CODE% verdict=%DYNAMIC_METADATA(api_fence:request.verdict)% errors=%DYNAMIC_METADATA(api_fence:request.errors)%

Metrics

All metrics are scoped under the configured api_name:

Access metrics at: http://localhost:9901/stats/prometheus

Complete Example

{
  "api_name": "users_api",
  "openapi_spec_path": "/etc/envoy/users-api.yaml",
  "cache": {
    "max_capacity": 500,
    "ttl_seconds": 7200
  },
  "validation": {
    "validate_request": true,
    "validate_response": true,
    "fail_on_request_error": true,
    "fail_on_response_error": false,
    "pool": {
      "enabled": true,
      "thread_count": 4,
      "timeout_ms": 100
    }
  },
  "security": {
    "max_body_size": 5242880,
    "max_json_depth": 16
  },
  "modsecurity": {
    "scan_request": true,
    "primary_ruleset": {
      "name": "crs",
      "use_bundled_crs": true,
      "bundled_crs_profile": "minimal"
    }
  }
}