Zed Attack Proxy (ZAP) Integration

The OWASP Zed Attack Proxy, or ZAP, is an open-source web app scanner, and the de-facto industry standard for automated security scanning of web applications.

ZAP's priorities and approach are quite different from Mayhem. We believe they're complementary: if you already run ZAP against your API, you'll get substantially deeper coverage using Mayhem, and if you already use Mayhem, ZAP is likely to report lots of potential problems, especially configuration and operational problems.

The tools complement each other so well, in fact, that we built a super-easy way to run ZAP's API Scan tool alongside Mayhem's API testing. Just add a --zap flag to your existing invocation:

mapi run [...] --zap

And you should see ZAP issues reported alongside discovered Mayhem API testing issues, like so:

Read on if you want some of the technical details, or more advanced options, but really: that's it. Go try it!

The Fine Print

ZAP vs. ZAP API Scan

It's worth pointing out that the tool we've integrated with, ZAP API Scan, isn't the full ZAP suite: it is a subset of the ZAP suite which, like Mayhem, is driven by an API specification. The full ZAP suite looks at web applications as a whole; ZAP API Scan and Mayhem are more narrowly focused on API back-ends.

Docker Required!

Our integration with ZAP relies on a working Docker environment (it's just the easiest way, by far, for us to manage all of the transitive dependencies of the ZAP toolchain.) This dependency is specific to the --zap flag, i.e. it's not a requirement for running Mayhem in general.

No OpenAPI 3.1 Support

ZAP hasn't yet implemented OpenAPI 3.1 support.

Any other spec format accepted by Mayhem (OpenAPI 2.x, OpenAPI 3.0, Postman and HAR) should work, but if your spec is using OAS 3.1 features, ZAP won't work with it until they update their support.

Only Header Auth Supported

While Mayhem supports several authentication methods, only --header-auth is currently propagated correctly to ZAP.

Transformations of the Raw ZAP Results

In order to fit the Mayhem data model, we transform and filter the raw ZAP results in a couple of ways.

First, ZAP issues are organized differently: there are alerts (roughly analogous to Mayhem "rules") and there are one or more "instances" of each alert. Mayhem, being API-oriented, likes to organize issues by endpoint. To map ZAP results into our model, therefore, we create an endpoint-associated issue for each distinct "instance" of each ZAP alert.

Second, in our experience, the lowest-risk ZAP alerts had a terrible signal-to-noise ratio when applied specifically to an API. As a result, by default, we filter these out! You can use the --zap_min_risk_code flag to adjust the default, if it's not what you want.

Why isn't --zap the default?

We're committed to making Mayhem, out of the box, a tool API developers are happy to use every day, and happy to add as a gating step in their CI/CD pipelines. This means we work very hard only to report issues which we are certain are genuine and resolveable.

ZAP, on the other hand, reports on everything it finds that might be an issue. Their results—while interesting and useful!—tend to require developer triage, which (usually) makes them unusable as a CI/CD gate.

So: we don't include ZAP results by default, but we make it easy for you to get them periodically.

Ingest your own

If you're already running ZAP, and just want to unify your ZAP and Mayhem API testing issue reporting, you can also ingest ZAP result json into a run, instead of having Mayhem invoke ZAP for you. This is done with the --zap-import-json-results command-line flag.