xkiian/awswaf

Purpose and Entry Points

This repository is an unofficial AWS WAF challenge solver implemented in parallel Go and Python libraries. It targets token/invisible challenges and CAPTCHA challenges, returning an aws-waf-token cookie.

Primary runnable examples are:

• Go: main.go

• Python: python/main.py

The Go library is rooted at internal/aws/aws.go; the Python equivalent is python/awswaf/aws.py.

Challenge Session Orchestration

AwsWaf is the central orchestration boundary in both implementations. It accepts challenge properties extracted from an initial protected-site response, the WAF endpoint/host, target domain, browser user agent, and optionally proxy configuration. It selects and executes the applicable challenge path, then exposes the resulting WAF token.

Grounding:

• internal/aws/aws.go

• internal/aws/structs.go

• python/awswaf/aws.py

Initial Challenge Parsing and Protocol Models

The solver consumes AWS WAF bootstrap data (“goku”/gokuProps) from a protected response. Go models protocol inputs and challenge/session state in dedicated structs, while the Python implementation carries corresponding parsing and workflow logic.

Grounding:

• internal/aws/structs.go

• internal/aws/aws.go

• python/awswaf/aws.py

Browser Fingerprint Construction

AWS WAF validation depends on browser-like fingerprint material. The repository generates or packages fingerprint attributes and includes a WebGL data source, likely used to make requests consistent with the supplied browser identity.

Grounding:

• internal/aws/fingerprint.go

• python/awswaf/fingerprint.py

• webgl.json

Cryptographic Payload Processing

Challenge request and response fields require AWS-specific cryptographic processing. Both language implementations isolate encryption/decryption or payload transformation from the transport orchestration, preserving a clear protocol boundary.

Grounding:

• internal/aws/crypto.go

• python/awswaf/crypto.py

• deobf.js

Proof-of-Work Challenge Stage

For invisible/token flows, the solver computes AWS WAF proof-of-work data before submitting the challenge completion request. This is a CPU-bound stage separate from network request handling.

Grounding:

• internal/aws/pow.go

• internal/aws/aws.go

• python/awswaf/verify.py

CAPTCHA Resolution Path

CAPTCHA flows are handled by a distinct Go subpackage and use Gemini AI according to the README. The CAPTCHA subsystem contains image/answer handling and its own request/response models, then feeds the solution back into the broader WAF verification workflow.

Grounding:

• internal/aws/captcha/captcha.go

• internal/aws/captcha/ai.go

• internal/aws/captcha/structs.go

External Boundaries and Runtime Dependencies

Go is managed through go.mod and provides the primary package API; Python provides a parallel package under python/awswaf. The system communicates with AWS WAF/protected-site HTTP endpoints, may route through a caller-provided proxy, and invokes Gemini for CAPTCHA solving. Generated output is the aws-waf-token cookie, intended for use by an upstream HTTP client rather than a web UI.

Grounding:

• go.mod

• package.json

• python/awswaf/aws.py