# GoTestWAF Review: API Security and WAF Attack Simulation

> GoTestWAF is a Go-based evaluator for API security products, web application firewalls, IPS systems, and API gateways. It generates encoded malicious requests across REST, GraphQL, gRPC, SOAP, XMLRPC, and other HTTP request locations, then records how the evaluated product responds.

**wallarm/gotestwaf** — An open-source project in Golang to asess different API Security tools and WAF for detection logic and bypasses

- Repository: https://github.com/wallarm/gotestwaf
- Website: https://lab.wallarm.com/test-your-waf-before-hackers/
- Stars: 1,816 · Forks: 260
- Language: Go
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/wallarm-gotestwaf

## GoTestWAF's API and WAF Evaluation Scope

GoTestWAF solves the problem of comparing the detection behavior of application security products without manually constructing every request variation. The README identifies its audience as teams evaluating web application security solutions, including API security proxies, web application firewalls, IPS products, and API gateways. It supports REST, GraphQL, gRPC, SOAP, XMLRPC, and other API protocols. The tool is therefore aimed at security engineers, QA specialists, and product evaluators who need repeatable traffic generation against a controlled endpoint. It does not describe itself as a general scanner for finding vulnerabilities in arbitrary applications. Its focus is on sending known malicious request patterns and recording whether the security solution blocks, detects, or allows them.

This distinction matters when selecting the tool. A WAF evaluation asks whether security middleware recognizes a specified request as malicious. An application security assessment may also need authenticated workflows, object-level authorization checks, business-logic abuse cases, and assertions about actions taken by the backend. GoTestWAF documents request simulation and product evaluation, not complete application penetration testing. Treating its results as a product certification would therefore exceed what the documented mechanism establishes.

## Encoded Payloads and HTTP Placement

The request-generation mechanism combines payloads, encoders, and placeholders. A YAML testcase names a payload group, lists encoders such as `Base64`, `Base64Flat`, `JSUnicode`, `URL`, `Plain`, or `XML Entity`, and selects destinations such as `Header`, `RequestBody`, `JSONBody`, `URLParam`, `URLPath`, `SOAPBody`, or `RawRequest`. The number of requests is the product of those three dimensions. With two payloads, three encoders, and one placeholder, the documented calculation is `2x3x1 = 6` requests. This makes coverage easy to reason about, but it also means that a small testcase can expand into a substantial request set. Payload values must be encoded as YAML binary data according to the README. `RawRequest` provides lower-level control through `method`, `path`, `headers`, and `body`, with `method` required.

The documented placement options also include `gRPC`, `UserAgent`, `HTMLForm`, `HTMLMultipartForm`, `XMLBody`, and `JSONRequest`. This is more flexible than a scanner that sends one fixed attack format. It also shifts part of the test-design burden to the operator. A syntactically valid generated request does not necessarily match the target's required media type, authentication model, schema, or endpoint routing. Based on the repository design, coverage depends directly on the selected payloads, encoders, placeholders, and target behavior.

## Installing GoTestWAF and Running the First Scan

The quickest documented workflow uses Docker Hub. The command below downloads the `wallarm/gotestwaf` image into the local Docker image cache.

```bash
docker pull wallarm/gotestwaf
```

Start the container with the URL of the evaluated security solution. The `${PWD}/reports` mount makes the report directory available under `/app/reports`.

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

The reader should see the interactive container output and later find the generated report in the mounted local directory. The README also documents an optional email prompt. Use `--noEmailReport` to skip it when no email report is needed.

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

For a native build, the repository Makefile provides the following target. It compiles `./cmd/gotestwaf` and injects a version derived from `git describe --tags`.

```bash
make gotestwaf_bin
```

Native execution requires Go, and the module declares Go 1.25. The README also says Chrome is required to generate PDF reports. Without Chrome, it says an HTML report can be created. Before either run, the source IP must be whitelisted by the evaluated security solution. If the target runs locally on `127.0.0.1`, retain the documented host-network setting unless the operator has another reachable arrangement.

## Protocol Coverage and gRPC Configuration

GoTestWAF is broader than an HTTP form scanner, but its breadth should not be confused with protocol fidelity. The README names REST, GraphQL, gRPC, SOAP, XMLRPC, and other API protocols. Placeholder types let testcases place an encoded payload in a JSON body, XML body, SOAP body, form, URL, header, or raw HTTP request. For gRPC, the project expects an existing working endpoint rather than deriving a service schema from the target.

The README gives this command for a gRPC endpoint listening on port 9000:

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

This should not be read as a universal gRPC configuration. The target endpoint, port, authentication, and service behavior must already be suitable for receiving the generated requests. The documentation does not explain how GoTestWAF discovers gRPC methods or verifies application-level success, so teams should confirm that the endpoint accepts the generated traffic and that a blocked response is distinguishable from a routing or protocol failure.

For OWASP Core Rule Set regression testing, the README points to a dedicated section. The Makefile also contains targets named `modsec_crs_regression_tests_convert` and `modsec_stat`. These entries show repository support for CRS-related workflows, but the documentation does not describe every generated file or conversion decision.

## Reports, Logs, and Evaluation Interpretation

Evaluation results are written to a report file on the machine running GoTestWAF and also appear through `STDOUT` and `STDERR`. The Docker workflow mounts `${PWD}/reports` into `/app/reports`, which gives the operator a predictable place to retrieve generated output. The README includes a sample startup log showing the version and testcase loading, but the excerpt does not specify the complete report schema or the exact classification rules used to label every outcome.

That missing detail affects interpretation. A request may be blocked by the WAF, rejected by the origin, fail because its media type is invalid, or return a response that the product's reporting logic classifies according to configurable behavior. The excerpt does not provide enough information to explain those classifications in full. Reviewers should therefore compare log output with the actual HTTP responses and the expected behavior of the endpoint under test. GoTestWAF can expose differences between security products, but only if transport errors and target-side rejections are not counted as meaningful detection results.

The repository Makefile also provides `modsec_stat`, which builds the container image before running `misc/modsec_stat.sh`. The README and repository files do not document the script's inputs or output fields, so this target should not be treated as a general reporting interface without reading that file.

## Custom Testcases and Maintenance Boundaries

Custom coverage is defined through YAML files and selected with the `testCasePath` configuration option. The repository contains `testcases/`, `config.yaml`, `docs/`, `tests/`, and command and internal packages. GoTestWAF also embeds OWASP Top-10 and OWASP-API selections, giving operators a starting point when they do not want to supply a corpus immediately.

A testcase combines four documented fields: `payload`, `encoder`, `placeholder`, and `type`. Payload strings must use YAML's binary-data representation. Encoder and placeholder lists drive a Cartesian expansion, which makes test volume easy to predict but can create unexpectedly large runs. Operators also need to consider whether each transformation is appropriate for the chosen destination. Applying a payload where the destination does not expect it may test parser behavior rather than the intended inspection path.

The project is not archived, and the last push was on 2026-09-25. Release history includes `v0.5.10` on 2026-09-25, `v0.5.9` on 2026-09-25, and `v0.5.8` on 2025-07-31. This is recent repository activity, but upgrade cost still depends on Go, Docker, browser availability, target configuration, and compatibility between custom YAML cases and the selected release. The module uses Go 1.25, while the Dockerfile builds with `golang:1.25-alpine` and installs Chromium in the runtime image. The MIT license permits use, modification, and redistribution under its terms, although license compliance remains the user's responsibility.

## GoTestWAF Compared with Application-Specific Tests

The closest practical alternative is a hand-built HTTP client test suite, such as Go tests that construct requests for one API and assert specific response behavior. GoTestWAF takes a different approach: it multiplies reusable attack payloads across encoders and named request locations, then uses an embedded or user-supplied YAML corpus for traffic generation. That design is useful when comparing several security products against a consistent request stream. A hand-built suite is better when assertions depend on business logic, authenticated user state, workflow order, or a narrow set of application-specific vulnerabilities.

GoTestWAF is also not a replacement for authorization testing, general fuzzing, dependency analysis, or source review. None of those capabilities is documented in the repository. Its request multiplication can create broad syntactic coverage, but breadth does not guarantee meaningful application coverage. Conversely, a custom Go test suite requires more implementation work yet can express exact endpoint expectations that the YAML fields do not describe.

The choice turns on the evaluation question. Use GoTestWAF when the objective is to compare security products against a shared malicious-request corpus across supported protocols and locations. Use an application-specific suite when the correct outcome depends on the target's schema, identity, resources, or workflow. For product comparisons, first confirm that both approaches define how transport failures, origin rejections, and WAF detections are distinguished.

## Conclusion

GoTestWAF fits security engineers who need a repeatable comparison of API gateways, WAFs, IPS products, and related controls against an existing test corpus. It is a poor substitute for application-specific security testing because its cases are generated from configurable payloads and placeholders rather than a complete model of a production API. Verify first that the target can receive every request format you intend to test, that its IP is whitelisted, and that the selected `testcases` cover the protocols and attack classes relevant to your deployment. The project is not archived, its last push was on 2026-09-25, and its MIT license permits modification and redistribution subject to the license terms.

## FAQ

### How do I install and run GoTestWAF with Docker?

Pull the `wallarm/gotestwaf` image, then run it with the evaluated service URL and a mounted reports directory. The README documents `--url` and `--noEmailReport` for this basic workflow.

### What does GoTestWAF test?

It generates malicious requests using YAML-defined payloads, encoders, and HTTP request placeholders. The documentation lists REST, GraphQL, gRPC, SOAP, XMLRPC, headers, bodies, URLs, forms, and raw requests as supported areas.

### Can I use custom attack cases with GoTestWAF?

Yes. The `testCasePath` configuration option selects custom testcases. YAML entries define the `payload`, `encoder`, `placeholder`, and `type` fields used to generate requests.

### Does GoTestWAF generate PDF reports?

The README says native runs require Chrome to generate PDF reports. If Chrome is unavailable, it says an HTML report can be created instead.

### How do I run gRPC tests?

The target must provide a working gRPC endpoint. The documented Docker example adds `--grpcPort 9000` and supplies `--url=http://my.grpc.endpoint`.

## Sources

- [License: MIT](https://github.com/wallarm/gotestwaf/blob/master/LICENSE)
- [Project website](https://lab.wallarm.com/test-your-waf-before-hackers/)
- [README](https://github.com/wallarm/gotestwaf/blob/master/README.md)
- [Releases](https://github.com/wallarm/gotestwaf/releases)
- [wallarm/gotestwaf on GitHub](https://github.com/wallarm/gotestwaf)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wallarm-gotestwaf