canonical: https://jentic.com/apis/amazonaws.com/waf

# AWS WAF Classic

Jentic publishes the only available OpenAPI specification for AWS WAF Classic, keeping it validated and agent-ready. AWS WAF Classic protects CloudFront distributions and Application Load Balancers from common web exploits by matching incoming requests against rules built from byte-match, IP-set, geo-match, regex, size-constraint, SQL-injection, and XSS conditions. The 77 operations cover full CRUD on every match-condition type, on rules and rate-based rules, on rule groups, and on Web ACLs, along with the change-token workflow that AWS WAF Classic uses for consistency. Note: AWS recommends WAFv2 for new deployments; this API covers the original (Classic) version.

## For AI agents

Manage AWS WAF Classic Web ACLs, rules, and match conditions so an agent can block bad IPs, geo-restrict traffic, and add SQLi/XSS protection to CloudFront and ALB.

## Scope

Does not handle DDoS mitigation, network-layer firewall rules, or modern WAFv2 rule groups - use for managing AWS WAF Classic match conditions, rules, and Web ACLs only.

## Capabilities

- Build IP, geo, byte, regex, size, SQL injection, and XSS match conditions
- Compose match conditions into rules and rate-based rules
- Group rules into reusable rule groups
- Assemble Web ACLs and order rules with explicit priority
- Manage the change-token workflow that AWS WAF Classic uses for consistent updates
- Enumerate Web ACLs, rules, and conditions across the account
- Migrate Classic Web ACLs into WAFv2 stacks via CreateWebACLMigrationStack

## Use cases

### IP Blocklist Automation

Automate response to abuse by syncing a threat-intel IP feed into an AWS WAF Classic IPSet. UpdateIPSet (with a change token from GetChangeToken) adds and removes /32 or /24 entries without recreating the set, and the IPSet is referenced by a rule in a Web ACL attached to CloudFront or an ALB. End-to-end, an agent can react to abuse signals in seconds without touching the underlying L7 protection layer.

Example prompt: Call GetChangeToken, then UpdateIPSet with IPSetId, ChangeToken, and Updates listing IPSetDescriptors with Action INSERT for each malicious /32 IP.

### Rate-Based Throttling for Login Abuse

Create a RateBasedRule that triggers when a single IP exceeds a threshold (e.g. 2000 requests in 5 minutes) and pair it with byte-match conditions on /login. CreateRateBasedRule sets the RateLimit and RateKey; UpdateWebACL inserts the rule with a BLOCK action above other rules. This is the standard AWS WAF Classic pattern for stopping credential-stuffing without rolling your own rate limiter.

Example prompt: Call CreateRateBasedRule with Name 'login-rate-limit', MetricName 'loginRateLimit', RateKey 'IP', RateLimit 2000, then UpdateWebACL to add the new rule with Action BLOCK at Priority 1.

### Migrating to WAFv2

AWS recommends migrating from WAF Classic to WAFv2 for richer rule constructs, managed rule groups, and JSON-based configuration. CreateWebACLMigrationStack generates a CloudFormation template that recreates an existing Classic Web ACL as a v2 ACL in a target S3 bucket; deploying that stack gives you a WAFv2 equivalent you can iterate on. List operations on Classic resources help inventory what still needs migrating.

Example prompt: Call CreateWebACLMigrationStack with WebACLId of the Classic ACL, S3BucketName for the generated CloudFormation, and IgnoreUnsupportedType=false.

### Agent-Driven Web ACL Updates via Jentic

A security agent ingesting threat-intel events can update WAF Classic IP sets and rules through Jentic without ever holding AWS keys. The agent submits an intent like 'block these ten IPs in production WAF'; Jentic loads GetChangeToken, then UpdateIPSet, executes them in sequence, and returns the new ChangeToken status. All keys stay vaulted and the agent's context never sees a SecretAccessKey.

Example prompt: Through Jentic, search for 'add ips to an aws waf classic ip set', load GetChangeToken and UpdateIPSet, and execute the pair to insert a list of IPs.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /#X-Amz-Target=AWSWAF_20150824.CreateIPSet | Create an IP set used by a rule |
| POST | /#X-Amz-Target=AWSWAF_20150824.CreateRateBasedRule | Create a rate-based rule |
| POST | /#X-Amz-Target=AWSWAF_20150824.CreateWebACL | Create a Web ACL |
| POST | /#X-Amz-Target=AWSWAF_20150824.GetChangeToken | Fetch a change token before mutating resources |
| POST | /#X-Amz-Target=AWSWAF_20150824.CreateWebACLMigrationStack | Generate a CloudFormation stack to migrate to WAFv2 |

## Key resources

- **Match conditions** — ByteMatchSet, GeoMatchSet, IPSet, RegexMatchSet, RegexPatternSet, SizeConstraintSet, SqlInjectionMatchSet, XssMatchSet - full CRUD
- **Rules** — Rule and RateBasedRule with Update operations to add or remove predicates
- **Rule groups** — RuleGroup, ListActivatedRulesInRuleGroup, UpdateRuleGroup
- **Web ACLs** — WebACL CRUD, UpdateWebACL for ordered rule changes, CreateWebACLMigrationStack
- **Change tokens** — GetChangeToken, GetChangeTokenStatus for the consistency workflow Classic requires

## Why Jentic

- **Setup:** Wiring AWS WAF Classic by hand means computing SigV4 signatures, managing the GetChangeToken concurrency step, and routing calls through the X-Amz-Target action header yourself. Through Jentic you install once, import WAF Classic from the API Directory, store the access keys once, and your agent calls it.
- **Permission scoping:** WAF Classic routes its actions through one endpoint by X-Amz-Target rather than resource ids in the path, so scope the agent to the operations it needs, such as GetChangeToken and CreateIPSet. You choose the operations it may call, so a web ACL delete is not included unless you add it.
- **Credential handling:** Your AWS access keys are stored once, encrypted, by your own Jentic One instance and used to sign each WAF Classic request with SigV4 at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'add IPs to a WAF Classic IP set' or 'create a rate-based rule', and Jentic returns the matching WAF Classic operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Amazon GuardDuty** — GuardDuty surfaces malicious IPs and behaviour that you can block by adding them to a WAF IP set.
- **AWS Security Hub** — Security Hub aggregates findings - including WAF metrics - into a single posture view.
- **AWS CloudTrail** — CloudTrail records every WAF management API call, giving you an audit trail of rule changes.

## FAQ

### Why is there no official OpenAPI spec for AWS WAF Classic?

AWS does not publish an OpenAPI specification for AWS WAF Classic; it ships Smithy models and language-specific SDKs instead. Jentic generates and maintains this OpenAPI spec so that AI agents and developers can call AWS WAF Classic via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does AWS WAF Classic use?

AWS WAF Classic uses AWS SigV4 with X-Amz-Target identifying the action (e.g. AWSWAF_20150824.UpdateIPSet). It also requires the change-token workflow: every mutating call must include a fresh ChangeToken obtained from GetChangeToken. Through Jentic, your AWS keys remain in the vault and Jentic signs each request.

### Can I block traffic by country with AWS WAF Classic?

Yes. Create a GeoMatchSet with GeoMatchConstraints listing ISO country codes, attach it to a rule via UpdateRule, and add the rule to a Web ACL with a BLOCK action. Combine with byte-match conditions to scope the block to specific paths or hosts.

### What are the rate limits for AWS WAF Classic?

Management API throughput is modest - a few transactions per second per account - because most calls require a fresh change token. The data-plane (request inspection) is independent and scales with the protected service. Most quotas (rules per Web ACL, IP entries per set) are increasable via AWS Support.

### How do I add IPs to a WAF IP set through Jentic?

Search Jentic with 'add ips to an aws waf classic ip set', load GetChangeToken, then UpdateIPSet, and execute the pair: GetChangeToken returns a ChangeToken, then UpdateIPSet uses it together with IPSetId and Updates listing IPSetDescriptors to insert.

### Should I use WAF Classic or WAFv2 for new deployments?

AWS recommends WAFv2 for new work; it offers managed rule groups, JSON-style rule statements, and CloudFront and Regional integrations under one API. Use this Classic API when working with existing Classic Web ACLs or running CreateWebACLMigrationStack to upgrade them.

### Can I attach a WAF Classic Web ACL to an Application Load Balancer?

Yes. Create the Web ACL with this API, then call AssociateWebACL to attach it to the ALB or CloudFront distribution. The Web ACL evaluates inbound requests in priority order and applies the matched rule's action (ALLOW, BLOCK, or COUNT).

### Can I limit what my agent is allowed to do with the AWS WAF Classic API?

Yes. Because you run Jentic One yourself, your own rules decide which AWS WAF Classic operations and credentials the agent may use. AWS WAF Classic routes every action through a single endpoint by X-Amz-Target rather than by resource ids in the path, so you scope the agent to just the operations it needs, such as GetChangeToken and CreateIPSet. You choose the operations it may call, so a Web ACL delete is not available to the agent unless you explicitly add it.