AppCheck's API Workspace feature, available if you have purchased an API scanning license, is a powerful tool for importing REST API definitions into AppCheck to make them ready for scanning, ensuring maximum coverage of your API's.

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 navigation bar.

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 is able to make successful requests to all endpoints before running a scan.  These pre-flight checks help to maximise the coverage of your API in a way other scanners cannot.

A single workspace can contain up to 128 endpoints.

A saved workspace can be imported into a scan to create an API scan.

Configuring an API Workspace

Creating a New API Workspace

New Workspace

Begin by clicking New Workspace, then Import.  Follow the wizard to import your swagger 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, shown here.

If the swagger file was not parsable you will be notified here.

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

Targets

Here you will see a list of endpoints.

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 string and excluding all 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

Various authentication methods are supported.  Add the details here and click Next to test them.

Authentication

This step will confirm whether the scanner was able to authenticate using the details provided.  If this step fails you can go back to correct the details provided.

Miner

At this step, AppCheck begins making requests to your endpoints in order to extract values which can be used in calls to other endpoints (in addition to default values supplies in the swagger 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.

Without mining, AppCheck would use the example values listed in the swagger 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

If everything has gone well, you should now be able to complete the wizard and review your workspace.

Save

Give your new workspace a name, and click the save icon to 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 Summary

The collection of endpoints within the workspace will be given a name based on the swagger file, in this example it is Swagger Petstore.  By clicking on it we can see a summary of the imported endpoints:

State of Targets

Here we can see how many endpoints AppCheck has been able to make successful requests to, and how many endpoints require attention.  These will be discussed further in Endpoint Details, below.

Include/Exclude

On the Manage Targets tab, you can control which endpoints are included and excluded, as seen during the wizard.

Further Options

The Settings, Authentication and Default Values tabs should be set up correctly already based on the results of the wizard but if changes are required they can be made here.

On the Default values tab you can provide default values for use in all endpoints.  These can be overridden on a per-endpoint basis (see below).

Save

Once again, remember to save your changes frequently.

Endpoint Details

Select and endpoint on the left to see settings specific to that endpoint, and to send test requests to the endpoint from AppCheck's servers (or your Private AppCheck Scan Hub if selected).  This is where some of the greatest value of this user interface can be realised.

In this example, an endpoint marked as Requires Attention is selected:

Send

This triggers a request to the endpoint using the configuration provided.  This can be used to test changes as we attempt to resolve issues with endpoints.

Parameters

The most likely cause of a problem with a specific endpoint is an invalid parameter value.  In the example above we can see from the response that no object is found matching the petId we provided (as a path variable).  This is because the swagger file we imported contained an incorrect "type" attribute for this parameter.

The ultimate fix for this is to correct the swagger file, but in the immediate term we have the option of overriding the value in the endpoint settings in AppCheck.  If we change the value to the number 1, for example, the scanner is now able to make successful requests to the endpoint:

The Params tab lets you configure parameters that appear in the path or query string.  Values used in payload bodies should be specified in the Default values tab.

Further Options

It is possible to provide authentication details for a specific endpoint, if it makes use of a different authentication method from the rest of the endpoints.  In most cases you will only need to configure the authentication at the Workspace level.

Save

Once again, remember to save your changes frequently.

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.