AppCheck's API Workspace feature, available if you have purchased an API scanning license, is a powerful tool to prepare API targets for scanning.

API Workspaces enable:

• Validation of the Swagger file.
• Configuration and testing of authentication.
• Parameter mining to discover valid parameter values for use in testing.
• Manual adjustments to provide data that could not be discovered automatically, or to override mistakes in the Swagger file.
• Enabling and disabling of particular endpoints for scanning.

You'll find this feature by clicking API Scans in the main menu option.

What are API Workspaces

An API Workspace is the result of importing a Swagger file and, optionally, enhancing the data with the help of the AppCheck User Interface (UI) as explained in this guide.

By importing, reviewing, and, if necessary, tweaking the API Workspace you can ensure all necessary information is present and correct, and that the scanner will be able to make successful requests to all API endpoints.  These pre-flight checks help run a more accurate scanning test on your API services.

A single workspace can contain up to 128 endpoints.

A saved workspace can be imported into the Web Application Scanner configuration to create an API scan.

Configuring an API Workspace

Creating a New API Workspace using Wizard

New Workspace

Begin by clicking New Workspace, then Import.  Follow the wizard to import your Swagger/OpenAPI file.  Most elements of the wizard should be self-explanatory so this guide will touch lightly on them.

Clicking the red x icon or clicking outside the wizard will close the wizard without saving.

Start

On the Start screen you may wish to change "Scan hubs" to your Private AppCheck Scan Hub if you have one.  If your API is accessible over the internet from AppCheck's IP addresses then you can leave this on "Random external hub".

Import

You can import your swagger file either by uploading it or adding the URL at which it can be found.

Settings

AppCheck will parse your swagger file and populate some key fields,  such as host, Base path and schema. If your API server supports connection on ports 80 and 443, defaulting to HTTPs schema is preferable.

If the swagger file was not parsable you will see an error message. You may be able to find the reason for the Swagger parser failure by loading your Swagger/OpenAPI file in any other API testing tool, such as Swagger Editor.

If the Swagger/OpenAPI file was parsed but some of the values are incorrect you can override them by providing your own values here.

Targets

This stage lists API endpoints, which are documented in the parsed Swagger/OpenAPI file.

By default, AppCheck will add DELETE endpoints to the Excluded Endpoints list.

You can choose which endpoints to include here (this can be changed later once the wizard is complete).  This is useful if your swagger file contains more endpoints than are allowed in a single workspace.

The Config tab includes ways to automate the inclusion/exclusion, for example by specifying a regex for including and/or strings for excluding endpoints that contain it.  Click "Reload Targets" to reset the Targets list based on the options in the Config tab (manual changes you've made to the Targets list will be lost when you do this).

Credentials

Choose authentication method from the drop-down menu, that your API service supports.

• API Key - is used if you need to submit any custom HTTP header to authorize API requests.
• Bearer Token - needs only the value of the token. Bearer prefix will be appended automatically.
• Basic Auth - requires username and password for Basic HTTP authentication. Authorization Basic header will be generated automatically, based on these inputs.
• Auth Automation is used if there is an API endpoint in the Swagger/OpenAPI, where username and password could be submitted automatically.
• API Auth Helper - configuration guidance can be found in this article.

Authentication

This step is reserved for Auth Automation and API Auth Helper only. If authorization process fails at this stage, return back to Credentials and update configuration where necessary.

Miner

At this step, AppCheck begins making requests to your endpoints in order to extract parameters values, which can be used in calls to other endpoints (in addition to default values supplies in the Swagger/OpenAPI file).

Parameters

Here you can see a list of parameters and their values that AppCheck was able to extract during mining, under the 'New Value' heading.

If mining fails, AppCheck would use the example values listed in the Swagger/OpenAPI file, or if there were none, AppCheck has default values for each parameter type (such as "SWAGGER_STRING" for strings).

If you wish to override these values, this can be done after you complete the wizard.

Validation

This step runs final checks based on all the configuration provided to this point.

Result

Complete the wizard and review your workspace.

Save

Give your new workspace a name, and save it.

The workspace is not saved automatically - be sure to save it to avoid having to repeat the setup process.

Testing and Tweaking the API Workspace

Workspace Overview

Workspace Overview offers the following options, represented by the top tabs:

Workspace Overview offers the same actions as the Wizard. We can parse Swagger/OpenAPI file, run Parameter Miner and validate targets. We can manage API targets, add global default parameters values and configure authentication.

Endpoint Details

By selecting an individual API endpoint on the left, we can modify default parameter values and add new headers for this endpoint only:

We can render a raw HTTP request,  to see what is going to be sent from AppCheck's servers (or your Private AppCheck Scan Hub if selected) during scanning phase.  This is where some of the greatest value of this user interface can be realised:

Parameters

Parameter values could be: integers, boolean, strings, arrays.

There are two locations, where default parameter values could be added in the API Workspace configuration:

• Global Default Values in the Workspace Overview:

Parameters, listed here, will be automatically applied to all endpoints, where they are used, in path and/or body.

If you need to exclude parameters in individual API endpoints from being altered by global values, you need to Lock those endpoints in the Settings tab.

• Individual Default Values for specific endpoints (they could be located in path and body):

Only parameters, recorded as Default values for individual endpoints, will be used by the DAST scanner.

Next Steps

Once your workspace is complete to your satisfaction, with a good number of endpoints successfully tested, and you have saved your workspace, you are ready to import your workspace into an API scan.