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 for API. We believe they're complementary: if you already run ZAP against your API, you'll get substantially deeper coverage using Mayhem for API, and if you already use Mayhem for API, 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 for API. Just add a --zap flag to your existing invocation:

mapi run [...] --zap

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

ZAP Results

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 for API, is driven by an API specification. The full ZAP suite looks at web applications as a whole; ZAP API Scan and Mayhem for API 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 for API in general.

No OpenAPI 3.1 Support

ZAP hasn't yet implemented OpenAPI 3.1 support.

Any other spec format accepted by Mayhem for API (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 for API 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 for API 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 for API "rules") and there are one or more "instances" of each alert. Mayhem for API, 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 for API, 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 for API issue reporting, you can also ingest ZAP result json into a run, instead of having Mayhem for API invoke ZAP for you. This is done with the --zap-import-json-results command-line flag.