API Armor

Overview

API Armor provides GraphQL query analysis, JSON schema validation, JWT/API-key auth validation, multi-dimensional behavioral profiling, and per-endpoint rate limiting. It is gated behind the api_armor_enabled feature flag.

GraphQL Analysis

API Armor parses GraphQL queries and extracts:

  • Operation type (query, mutation, subscription)
  • Depth
  • Complexity
  • Field count
  • Alias count
  • Fragment count
  • Query hash

These metrics are available in Security Rule expressions and used by preset rules to block abusive queries.

JSON Schema Validation

API Armor validates request bodies against JSON schemas:

  • OpenAPI spec import — parse JSON or YAML OpenAPI specs, extract per-endpoint schemas, resolve $ref references
  • Schema inference — learn schemas from observed traffic
  • Schema merging — merge inferred schemas with imported schemas
  • Validation rules: type, properties, required, items, minLength/maxLength, minimum/maximum, enum, pattern, additionalProperties

Auth Validation

API Armor validates authentication on API requests:

Auth TypeDescription
JWTHS256/HS384/HS512 with issuer, audience, and expiry checks
API KeyValidate against configured API key lists
BearerExtract and validate bearer tokens

Auth type is auto-detected and exposed as auth.type in Security Rules. The auth.valid boolean indicates whether validation passed.

Behavioral Profiling

API Armor tracks 7 dimensions per endpoint:

DimensionDescription
Body structureJSON shape of the request body
GraphQL metricsDepth, complexity, field count, etc.
Content typeRequest Content-Type
Auth typeDetected auth type
Request fingerprintJA4 and request fingerprint subfields
Param keysQuery parameter names
Param typesQuery parameter value types

Profiles are marked “learned” after min_samples observations (default 100). When a request deviates from a learned profile, an anomaly is detected and available in Security Rule expressions.

Preset Rules

coreX Manager ships preset GraphQL security rules:

  • Depth limit
  • Complexity limit
  • Field count limit
  • Alias count limit
  • Query length limit

These can be enabled with a single click and tuned per listener.

Per-Endpoint Rate Limiting

The RateLimit model has path_pattern, method, and api_armor_scoped columns for scoping rate limits to specific endpoints. This integrates with the Rate Limiting feature.

Security Rules Integration

The following fields from API Armor are available in Security Rule expressions:

  • Request fingerprint subfields
  • GraphQL fields (depth, complexity, field count, etc.)
  • Schema validation fields
  • Auth fields (auth.valid, auth.type)
  • Profile anomaly fields

Conditional Body Buffering

When API Armor is enabled, http-request buffer-request and lua.api_body_parse are emitted on every listener. API_ARMOR_MAX_BODY_BYTES caps the buffer size to prevent memory exhaustion from large payloads.

Profiling Log

A Rust module writes one JSON line per request to profiling.log. The ApiArmorProfiler sampler tails the log and upserts ApiProfile rows for behavioral profiling.

Frontend

The API Armor page has 8 tabs:

TabDescription
SettingsEnable/disable, configure min_samples, body size limits
Preset RulesEnable and configure GraphQL security presets
OpenAPI SpecsImport and manage OpenAPI specs
SchemasView and edit JSON schemas per endpoint
Auth PoliciesConfigure JWT and API key validation
API Key ListsManage API key lists
ProfilesView learned behavioral profiles
AnomaliesView detected anomalies

Step-by-Step: Enable API Armor

  1. Navigate to Protection > API Armor > Settings
  2. Toggle Enable API Armor on
  3. Set min_samples to 100 (or lower for faster learning)
  4. Set API_ARMOR_MAX_BODY_BYTES to an appropriate value (default 1MB)
  5. Click Save and Apply Changes

Step-by-Step: Import an OpenAPI Spec

  1. Navigate to Protection > API Armor > OpenAPI Specs
  2. Click Import Spec
  3. Upload a JSON or YAML file, or paste the URL
  4. coreX Manager parses the spec, extracts per-endpoint schemas, and resolves $refs
  5. Review the extracted schemas in the Schemas tab

Step-by-Step: Create an Auth Policy

  1. Navigate to Protection > API Armor > Auth Policies
  2. Click Add Policy
  3. Select auth type: JWT
  4. Configure:
    • Algorithm: HS256
    • Secret: your HMAC secret
    • Issuer: https://auth.example.com
    • Audience: api.example.com
  5. Save and Apply

Step-by-Step: Apply Preset Rules

  1. Navigate to Protection > API Armor > Preset Rules
  2. Enable Depth Limit and set max depth to 10
  3. Enable Complexity Limit and set max complexity to 1000
  4. Save and Apply

Step-by-Step: Finalize a Profile

  1. Send representative traffic to your API endpoints
  2. Navigate to Protection > API Armor > Profiles
  3. Wait for profiles to reach “learned” status (min_samples observations)
  4. Review the learned dimensions
  5. Once learned, anomalies will be detected for deviating requests

Verification

  1. Check profiling log:

    tail -f /app/data/profiling.log

    Each request should produce one JSON line.

  2. Test schema validation:

    # Valid request
curl -k -X POST https://localhost/api/users -H "Content-Type: application/json" -d '{"name":"test"}'

# Invalid request (wrong type)
curl -k -X POST https://localhost/api/users -H "Content-Type: application/json" -d '{"name":123}'

  3. Test GraphQL depth limit:

    curl -k -X POST https://localhost/graphql -H "Content-Type: application/json" -d '{"query":"{ user { posts { comments { user { posts { comments { user { posts } } } } } } } }"}'

    Expect a rejection if depth exceeds the preset limit.

  4. Check anomalies:

    • Navigate to Protection > API Armor > Anomalies
    • Send a request that deviates from learned profiles
    • Verify it appears in the anomalies list

Next Steps

← Previous CAPTCHA Next → Page Protect