Why is this new feature important?
In the real world, the parameters defined in a REST API are meant to represent real data, in other words, usernames, asset IDs, query strings, and so on. Using real data for these parameters solicits more realistic logic from your application, and exercises more branches of your code.
For instance, in a password update flow in a REST API, if a username or ID is provided that does not exist within the context of the application, a simple 404 should be returned on the resource lookup, and none of the actual password reset code will be invoked. However, if the resource can be found, all of the password reset code will be exercised with the parameters provided.
This is where Hawkscan’s ‘Custom Test Data for REST APIs’ comes into the picture! This new feature allows users to configure values they want to use in a scan for each defined parameter. For each parameter in a scan, a list of values can be provided, and one of the values will be chosen randomly for each path that parameter belongs to.
How is this new feature configured?
To supply custom values for a REST API’s parameters, some configuration is necessary in the `stackhawk.yml` file. Under the `app.openApiConf` section of the configuration, a new array field called “customVariables” is available, which represents a list of fields and corresponding lists of values for each key. The key represents the parameter in your OpenAPI definition, and HawkScan uses the list of values to choose one on the fly when scanning a REST API. By default, the scanner will NOT use these custom values for DELETE methods. This default behavior is because HawkScan is running real malicious attacks against your application, so to err on the side of safety, DELETEs will not use any custom variables, even if a list of values is provided for that parameter.
To override this default behavior and use custom values for ALL HTTP methods, simply set `includeAllMethods` to true. If you want more control over which methods will use custom values, you can set exactly which methods to use with the `includedMethods` list.
Note: `includeAllMethods` defaults to false, but if set to true, the `includedMethods` will be ignored if provided.
openApiConf:
filePath: "/OpenApi_defn_query_parameters.yaml"
fakerEnabled: true #default false
includeAllMethods: false
includedMethods:
- POST
- PUT
customVariables:
- field: book
values:
- "alpha"
- "beta"
- "charlie"
- field: secret
values:
- "secret1"
- "secret2"
- "secret3"
- field: book_title
values:
- "customBookTitle1"
- "customBookTitle2"I don’t want to supply my own data, but I do want more realistic values.
Sometimes existing data isn’t always necessary and properly formatted values will still be more effective than previous HawkScan default values. Leveraging the Faker library, HawkScan can now generate more realistic data for a REST API using the `format` field on the OpenAPI definition. By using this field along with the type and other schema constraints, HawkScan can generate data that matches your schema on the fly.
For instance, if a request has a phone number as one of its parameters where the type is a string and the format is phone, an actual phone number can be generated rather than a default value string that has no relation to a phone number. Or if a path uses an integer ID parameter but the schema constrains the number to integers from 1-100, HawkScan will generate a random number within this range. To use these faker values, the `fakerEnabled` parameter in the openApiConf section of the `stackhawk.yml` file should be set to `true`. When enabled, HawkScan generates a realistic value for any parameters that have a format or constraints set and don’t have custom values also supplied in the `stackhawk.yml` file.
My spec doesn’t have formats, but I still want to use more realistic values.
If your API definition isn’t quite up to date with formats for each field, you can still leverage the `customVariables` section of the `stackhawk.yml` config file to inject Faker values into your scan. To do this, add a custom variable for each parameter you want to use Faker values for, and in the list of possible values, include `$faker:{format}` as a value.
For example, if the API definition includes an email in a request body, but the definition only defines that parameter as a type string and does not additionally supply the format, then in the `stackhawk.yml` file you can include `$faker:email` as a value for that parameter, and a realistic email will be generated for each path that parameter appears in.
