API Schema Enforcement
December 2023
Overview
API schema enforcement is the process of ensuring incoming HTTP API calls adhere to a specific
structure or set of constraints defined within a specification file. OpenAPI Specifications (formerly
called Swagger files) are a vendor neutral specification language for HTTP APIs that provides a
standardized means to define an API. Blocking or logging incoming requests that deviate from your
API specification can be a powerful tool in identifying and mitigating malicious actors that are
attempting to abuse an API.
Fastly’s API Schema Enforcement feature exists as a part of the Next-Gen WAF. The feature works
by comparing incoming requests against a user provided OpenAPI v3 specification file. If a request
does not match the specification, the API-SPEC-MISMATCH anomaly signal will be added to the
request with some additional context about the deviation. This allows users to optionally create
rules to block a specific subset, or all requests, that deviate from the specification using the full
power of the Rule Builder.
Requirements
NGWAF Core Deployment
Support for the API Schema Enforcement feature requires the deployment of the Next-Gen WAF
Agent v4.49.0 and above. Currently only core, or on-prem, NGWAF Agent deployments are
supported.
OpenAPI Specification v3
At the moment we are able to support OAS v3 specs only. Customers will need to have an existing
valid OpenAPI v3 spec or the knowledge to create one.
Limitations
If the OAS spec is not supported or properly formatted the agent will exit with an error describing
the issue when it is started. Here are a list of things we do not currently support:
● OAS v2 specs
● OAS v3.1 specs
● Circular schema references
● Extra sibling fields
● The discriminator field or polymorphism
● Invalid regexes that are used in the pattern field
● External references in the schema
See appendix for examples of specification features that we do not support.
User Guide
Loading a Spec File
To enable API Schema inspection, first set the agent open-api-spec-file hidden config option to
point to a OpenAPI v3 specification in either JSON or YAML format.
There are 3 ways we are able to load specs with the open-api-spec-file config option:
1. A simple file path to an OAS yaml file, e.g.
/etc/opt/test-oas.yaml
2. A URL, e.g.
https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v2.0/
yaml/petstore-expanded.yaml
3. An S3 bucket specified in JSON format. You must specify the region, AWS profile and s3
URL. You will need to specify your AWS credentials in your .aws/credentials file for this to
work. E.g.
--open-api-spec-file="'"{"s3url": "s3://sigscidev-testing/stripe-oas.yaml",
"region": "us-west-2", "profile": "021874968854_SuperUser"}"'"'
Creating Rules & Enabling Enforcement (Blocking)
Unless the user creates rules to block the API-SPEC-MISMATCH anomaly signals, requests that
deviate from the specification will not be blocked. The API-SPEC-MISMATCH anomaly signals can
be used within the Requests view and Rule Builder UI. By creating corp or site rules using the
anomaly signal, users can create blocking enforcement actions.
Example Rules
Block every request that deviates from the spec
Only block requests that have deviations for a given endpoint
Only enable enforcement for a specific path ex: /v1/pets. All other paths will not be blocked when
deviations from the spec occur.
Silence (exclude) anomaly signals for a given endpoint
Prevent the API Spec Mismatch signal from being added to certain requests such as for a given path:
Appendix
Examples of unsupported calls
Example of unsupported circular schema references
JavaScript
openapi: 3.0.0
info:
title: Circular Reference Example
version: 1.0.0
paths:
/users:
get:
summary: Get all users
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/User'
components:
schemas:
User:
$ref: '#/components/schemas/Permission'
Permission:
$ref: '#/components/schemas/User'
Example of unsupported extra sibling fields
JavaScript
openapi: 3.0.0
info:
title: Sample API
version: 1.0.0
paths:
/users:
get:
summary: Get a list of users
responses:
'200':
description: Successful response
x-kin-extra-field: Some extra information
Example of discriminator field or polymorphism
JavaScript
components:
schemas:
Pet:
type: object
properties:
type:
type: string
discriminator:
propertyName: type
required:
- type
Cat:
allOf:
- $ref: '#/components/schemas/Pet'
- type: object
properties:
name:
type: string
Dog:
allOf:
- $ref: '#/components/schemas/Pet'
- type: object
properties:
breed:
type: string
Invalid regexes that are used in the pattern field are unsupported.
Below is an example of how the pattern field is normally used.
JavaScript
openapi: 3.0.0
info:
title: Pattern Field Example
version: 1.0.0
paths:
/users/{username}:
parameters:
- name: username
in: path
required: true
schema:
type: string
pattern: '^[a-zA-Z0-9_-]{3,16}$'
description: The username must be 3 to 16 characters long and can
contain letters, numbers, underscores, and hyphens.
get:
summary: Get user by username
responses:
'200':
description: Successful response
Example of unsupported external references in the schema
JavaScript
openapi: 3.0.0
info:
title: My API
version: 1.0.0
paths:
/users:
get:
summary: Get a list of users
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: 'definitions.yaml#/components/schemas/User'
