Home

Awesome

Automatic API Attack Tool

Imperva's customizable API attack tool takes an API specification as an input, and generates and runs attacks that are based on it as an output.

The tool is able to parse an API specification and create fuzzing attack scenarios based on what is defined in the API specification. Each endpoint is injected with cleverly generated values within the boundaries defined by the specification, and outside of it, the appropriate requests are sent and their success or failure are reported in a detailed manner. You may also extend it to run various security attack vectors, such as illegal resource access, XSS, SQLi and RFI, that are targeted at the existing endpoints, or even at non-existing ones. No human intervention is needed. Simply run the tool and get the results.

The tool can be easily extended to adapt to meet the various needs, such as for a developer who wants to test their API, or an organization that wants to run regular vulnerability or positive security scans on its public API. It is built with CI/CD in mind.

Requirements

Running

Making a Linux executable

Usage

Required parameters:

-f, --specFile=specFilePath

The API specification file (swagger 2.0) to run on. JSON/YAML format. For better results, make sure responses are well defined for each endpoint.

-n, --hostName=hostName

The host name to connect to. It can also be an IP

-s, --hostScheme=hostScheme

Connection to host will be made using this scheme; e.g: https or http

Optional parameters:

-p, --hostPort=hostPort

The port the host is listening on for API calls, default is: 443

-ph, --proxyHost=proxyHost

Specify the proxy host to send the requests via a proxy

-pp, --proxyPort=proxyPort

The proxy port, default is: 80

-rcn, --addNegativeRC=responseCode[,responseCode...]

Additional response codes to be accepted in negative attacks (e.g. bad value attacks). Multiple values are supported, separated by commas

-rcp, --addPositiveRC=responseCode[,responseCode...]

Additional response codes to be accepted in positive checks (legitimate value attacks). Multiple values are supported, separated by commas

 

Typical usage scenarios:

Conditions for failing checks

Conditions for failing checks

Expected outputs:

Example of a negative check that failed:
***** Testing API Endpoint *****
***** Test ID: 1575128763286-74212
Testing: Bad Property: /username (STRING), value: {, URL encoded: %7B
--> Url: /user/{
--> Method: GET
--> Headers: []
----------**----------
Request was: GET /user/{ [Accept: application/json], Response status code: 200(UNEXPECTED)
Response (non parsed):
{"id":0,"username":"string","firstName":"string","lastName":"string","email":"string","password":"string","phone":"string","userStatus":0}

Why did the check fail? The request got 200, even though didn't contain a legal URL

Another example:
***** Testing API Endpoint *****
***** Test ID: 1575128763286-25078
Testing: Bad Property: /body/quantity (INTEGER), value: 0.4188493, URL encoded: 0.4188493
--> Url: /store/order
--> Method: POST
--> Headers: []
--> Body: {"petId":-2511515111206893939,"quantity":0.4188493,"id":698757161286106823,"shipDate":"�s","complete":"true","status":"approved"}
----------**----------
Request was: POST /store/order [Accept: application/json], Response status code: 200(UNEXPECTED)
Response (non parsed):
{"id":0,"petId":0,"quantity":0,"shipDate":"2019-11-30T15:46:03Z","status":"placed","complete":false}

The server expected to get an integer, but accepted a double value. This might be a good spot to try and exploit some buffer overflow in the server.

Example of a successful check:
***** Testing API Endpoint *****
***** Test ID: 1575128763137-43035
Testing: /user/{username}
--> Url: /user/%E68E97EDB4Oq-(!BbG,Y$p'A-KW%65f9FA6jt5vvDz-cW.QGsLS+AA~RIHC3wgy25lDJsGzcT.;kJ+(
--> Method: GET
--> Headers: []
----------**----------
Request was: GET /user/%E68E97EDB4Oq-(!BbG,Y$p'A-KW%65f9FA6jt5vvDz-cW.QGsLS+AA~RIHC3wgy25lDJsGzcT.;kJ+( [Accept: application/json], Response status code: 404
Response (non parsed):
{"statusCode":404,"error":"Not Found","message":"Not Found"}

We supplied a username that was nonexistent but legal, according to the API specification. The server knew how to handle this request and return a legal error.

Supported Check Scenarios

We will use the term endpoint here, as the endpoint URL and Method tuple.

Positive Scenarios
Negative Scenarios
Ongoing Effort

We are working on migrating our other scenarios to the open-source tool, for the benefit of the community. Stay tuned for updates.

Extensibility

The tool is written in a way that makes it easy to extend its fuzzing and request generation functionality to meet your specific needs. Feel free to suggest any additions that others may benefit from by creating a pull request.

Getting Help

If you have questions about the library, be sure to check out the source code documentation. If you still have questions, reach out to me via email at boris.serebro(at)imperva(dot)com.

Reporting Bugs

Please open a Git Issue and include as much information as possible. If possible, provide a sample code that illustrates the problem you're encountering. If you're experiencing a bug on a specific repository only, provide a link to it, if possible. Do not open a Git Issue for help, only for bug reports.