Fix APIs in VS Code

In Microsoft Visual Studio Code (VS Code), the OpenAPI (Swagger) Editor extension makes creating and navigating OpenAPI definitions quicker and easier, and you can run Security Audit directly from the editor. You can fix the issues that Security Audit found and then upload the updated API definition to 42Crunch Platform.

The issues represent real concerns in your OpenAPI definition, and they may either prevent API Protection completely, or severely impact its quality. We highly recommend that you fix all found issues.

1. Install OpenAPI (Swagger) Editor extension to your VS Code editor.
2. Open the API you want in VS Code in .json or .yaml format.
3. To run Security Audit from VS Code, click the 42C button at the top edge of the editor.

   On the first time, you must provide a token that the extension can use to authenticate to 42Crunch Platform:

   • If you have created an IDE token, select the button for the existing user, and enter the token value you copied and the URL your organization uses to access 42Crunch Platform. For most users, this is https://platform.42crunch.com. If you are not sure what your platform URL is, contact our support.
   • If you do not want to use an IDE token, select the button for new user and enter your email address so we can mail you a token you can use instead.

   Configuring the token is done only once, on subsequent audits you just click the button.

   Security Audit checks your API definition and provides audit score and report on the found issues in the editor just like in the platform. The elements containing issues are also marked in your code. For more details, see Audit report in VS Code.

   

4. Click the icons in the status bar to open the Problems panel, scroll through the issue titles, and click on an issue to jump to view it inline in your API definition. The issues are ordered from most to least severe, so it is easy for fix the worst offenders first. Recommendations are not listed in the Problems panel.
5. Hover on an element marked in your code to see the list of issues in that spot, and click on the list to filter the text panel to show only these issues.
6. Edit your API definition to fix found issues, save your changes, and click the 42C button to re-run the audit.

   If you want to just test how an API operation works, click Try it on that operation to send a single HTTP request to that operation. You can also tweak the parameters, request body, or settings used for that request.

For more details on how OpenAPI (Swagger) Editor helps in creating and editing OpenAPI definitions, see the instructions in the VS Code Marketplace.

If you use external references to schemas that are served by an HTTP service requiring authentication, you must add the list of approved hosts in the settings of the IDE extension. See Configure authentication for external references in OpenAPI files.

For a practical example, check out Tutorial 5: OpenAPI (Swagger) Editor for Visual Studio Code.

Fix multiple issues at one go

Fixing the issues that the audit found one by one can be hard work. If your API has multiple properties with the same name, such as in a schema that is repeated often, and the audit found issues in some of these properties, you can use the quick fix, group fix, and combined fix features in VS Code to speed up the work.

For example, you could have response schemas that all have the numeric property called code, and in some of these schemas code is missing the minimum or maximum values, or both.

1. Go to the issue you want to fix, and click on the quick fix icon next to it.

   

2. Click on the fix you want to apply:
   • Quick fix: Fix one issue in one spot. For example, you could choose to add either the missing minimum or maximum. If at least one other property with the same name in your API definition has the missing property, the extension picks the value of the property from that. You can then change the value if needed.
   • Combined fix: Fix multiple issues in one spot. Combined fix shows all quick fixes that you could apply in that particular spot in your API definition. For example, you could add a quick fix for both the missing minimum and maximum at one go.
   • Group fix: Fix one issue in multiple spots. This bulk update shows only if at least one other property with the same name in your API definition has a value of the missing property defined.
3. If you chose a group fix, select the occurrences of the issue where you want to apply the fix. The fix is applied as shown, so if you want to apply a different value that the suggested in some of the occurrences, do not select them for the group fix.
4. Once you are ready with your fixes, save your changes, and click the 42C button to re-run the audit.

Load audit report from a file

You can open an audit report that has been exported from 42Crunch Platform to view it in VS Code without auditing the API again. This way, you can work on fixing audit issues from an audit report that, for example, someone in a different team shared with you.

1. Obtain the audit report (either from someone else, or download it yourself) from 42Crunch Platform as a JSON file. See Export audit report.
2. Open the API definition that the audit report was for in VS Code, either as .json or .yaml.
3. Go to the command palette in VS Code, and select the command 42Crunch: Load Security Audit report from file.

VS Code loads the exported report from the file and you can now navigate it just as if the audit had been run in VS Code.

If you fix an issue and run Security Audit in VS Code to verify your fix, the audit report your loaded from the file is replaced by the report that the VS Code extension generated.

The exported audit report is a static file: if you reload the exported report file again after fixing an issue in your API, the report still contains the details of that issue and the place you already fixed is highlighted in the editor.

Upload updated APIs to the platform

After you have edited the OpenAPI definition of your API in VS Code, you can upload the updated API definition to 42Crunch Platform without reimporting the API.

Uploading a new API definition for an imported API overwrites the API definition currently stored in 42Crunch Platform. If you have also edited the OpenAPI definition in Security Editor, these changes are lost if you have not included them in the file you are uploading.

1. Go to the API you want to update, and click > Update definition.
2. Select the file to upload.
3. Click Update definition.

The OpenAPI definition of the API you selected in 42Crunch Platform is replaced with the one you uploaded. Security Audit audits the uploaded API definition and recalculates the audit score for the API.

Uploading an API definition changes the format (JSON or YAML) of the API in the platform to match the uploaded file. If you upload a .json file, the API definition in the platform will now be in JSON format. Same applies uploading a YAML file. You can switch between the JSON and YAML format as needed, see Convert APIs.

You can also integrate Security Audit with your CI/CD pipeline so that any changes to APIs in your project are automatically audited for security. For more details, see CI/CD integration.