GoTestWAF Documentation

You can define custom attack simulations using YAML files. Each test case consists of four main components:

• payload: Malicious attack samples. Since YAML strings are required, payloads must be encoded as binary data.
• encoder: The encoding applied to the payload before injection. Supported values: Base64, Base64Flat, JSUnicode, URL, Plain, and XML Entity.
• placeholder: The location in the HTTP request where the payload is placed. Supported values include gRPC, Header, UserAgent, RequestBody, JSONRequest, JSONBody, HTMLForm, HTMLMultipartForm, SOAPBody, XMLBody, URLParam, URLPath, and RawRequest.
• type: An arbitrary name describing the attack group (e.g., SQL Injection).

Using the RawRequest placeholder

RawRequest allows for arbitrary HTTP request construction. You must include a method field. The payload is substituted by replacing the string {{payload}} within the provided structure.

Fields for RawRequest:

• method (Required)
• path
• headers
• body

payload:
  - test
encoder:
  - Plain
placeholder:
  - RawRequest:
      method: "POST"
      path: "/"
      headers:
        Content-Type: "multipart/form-data; boundary=boundary"
      body: |
        --boundary
        Content-disposition: form-data; name="field1"
        
        Test
        --boundary
        Content-disposition: form-data; name="field2"
        Content-Type: text/plain; charset=utf-7
        
        Knock knock.
        {{payload}}
        --boundary--
type: RawRequest test

GoTestWAF can be run using several methods depending on your environment:

Using Docker (Pre-built image)

docker pull wallarm/gotestwaf
docker run --rm --network="host" -v ${PWD}/reports:/app/reports \
    wallarm/gotestwaf --url=<EVALUATED_SECURITY_SOLUTION_URL>

Note: Use --network="host" if the target WAF is running on 127.0.0.1 on your host machine.

Building from Source (Docker)

git clone https://github.com/wallarm/gotestwaf.git
cd gotestwaf
DOCKER_BUILDKIT=1 docker build --force-rm -t gotestwaf .
docker run --rm --network="host" -it -v ${PWD}/reports:/app/reports \
    gotestwaf --url=<EVALUATED_SECURITY_SOLUTION_URL>

Running Natively with Go

git clone https://github.com/wallarm/gotestwaf.git
cd gotestwaf
# Run directly
go run ./cmd --url=<EVALUATED_SECURITY_SOLUTION_URL>

# Or build as a Go module
go build -mod vendor -o gotestwaf ./cmd

To improve scanning accuracy, GoTestWAF can use an OpenAPI 3.0 specification to construct valid application requests instead of simple, unstructured requests.

Workflow:

1. Template Construction: GoTestWAF loads the OpenAPI file and creates request templates. Templates are grouped by the placeholders they support (e.g., URLPath).
2. Vector Substitution: A malicious vector is selected from the queue. GoTestWAF finds compatible templates, substitutes the vector into the placeholder, and sends the request.
3. Bypass Detection: GoTestWAF uses the response codes and schemes defined in the OpenAPI file to determine if a request was blocked by the WAF or passed to the application. If the response matches the OpenAPI spec, it is marked as bypassed; otherwise, it is marked as blocked. If the response status code matches a WAF block code but is also a valid application response, it is marked as unresolved.

Supported Features:

• Numeric and string parameters in headers, paths, query parameters, and bodies.
• Content-types: application/json, application/xml, application/x-www-form-urlencoded, text/plain.
• XML modifiers: name, wrapped, attribute, prefix, namespace.
• Length limits (minLength, maxLength) and numeric restrictions (minimum, maximum, etc.).
• Array length restrictions (minItems, maxItems).
• Combination schemes (oneOf, anyOf, allOf).

Note: You must mount the OpenAPI file into the container using a volume.

Example Command:

docker run --rm --network="host" -it -v ${PWD}/reports:/app/reports -v ${PWD}/api.yaml:/app/api.yaml wallarm/gotestwaf --wafName your_waf_name --url=https://example.com/v1 --openapiFile api.yaml

Follow these steps to run GoTestWAF using Docker with minimal configuration.

1. Pull the image:

   docker pull wallarm/gotestwaf

2. Run the container: Use --network="host" to allow interaction with containers running on 127.0.0.1. Replace ${PWD}/reports with your desired local report directory.

   Standard run (prompts for email):

   docker run --rm --network="host" -it -v ${PWD}/reports:/app/reports \
       wallarm/gotestwaf --url=<EVALUATED_SECURITY_SOLUTION_URL>

   Run without email prompt:

   docker run --rm --network="host" -v ${PWD}/reports:/app/reports \
       wallarm/gotestwaf --url=<EVALUATED_SECURITY_SOLUTION_URL> --noEmailReport

   Run gRPC tests: You must provide a working endpoint and specify the port using --grpcPort.

   docker run --rm --network="host" -it -v ${PWD}/reports:/app/reports \
       wallarm/gotestwaf --grpcPort 9000 --url=http://my.grpc.endpoint

3. Check your email for the generated report.

GoTestWAF outputs evaluation results via STDOUT and STDERR. The results are presented in three main sections:

1. True-Positive Tests: Measures how effectively the WAF blocks actual attacks. It categorizes tests by TEST SET (e.g., community, owasp, owasp-api) and TEST CASE. Key metrics include:
   • PERCENTAGE , %: The percentage of successful blocks.
   • BLOCKED: Number of requests successfully blocked.
   • BYPASSED: Number of malicious requests that successfully bypassed the WAF.
   • UNRESOLVED: Requests where the outcome was indeterminate.
   • SENT: Total number of requests sent for that test case.
   • FAILED: Number of requests that failed due to technical errors (not WAF bypasses).
2. True-Negative Tests: Measures the WAF's ability to allow legitimate traffic without false positives (using the false-pos test set).
3. Summary: Provides an aggregated score for API Security, Application Security, and an overall Score.

Note: A high True-Positive Score is desirable (meaning more attacks are blocked), and a high True-Negative Score is desirable (meaning fewer legitimate requests are incorrectly blocked).

True-Positive Tests:
┌────────────┬───────────────────────────┬──────────────────────┬─────────────────────┬──────────────────────┬────────────────────┬─────────────┬─────────────────┐
│  TEST SET  │         TEST CASE         │    PERCENTAGE , %    │       BLOCKED       │       BYPASSED       │     UNRESOLVED     │     SENT     │     FAILED      │
├────────────┼───────────────────────────┼──────────────────────┼─────────────────────┼──────────────────────┼────────────────────┼─────────────┼─────────────────┐
│ community  │ community-128kb-rce       │ 0.00                 │ 0                   │ 0                    │ 1                  │ 1           │ 0               │
└────────────┴───────────────────────────┴──────────────────────┴─────────────────────┴──────────────────────┴────────────────────┴─────────────┴─────────────────┘