Integrate 42Crunch Platform with Visual Studio Code

To integrate your IDE with 42Crunch Platform, you must first install the extension OpenAPI (Swagger) Editor to your IDE. After that, you can choose either the free but limited experience, or the full experience for paying customers.

• Paying customers use IDE tokens to configure the IDE extension to access and authenticate to 42Crunch Platform. You can create IDE tokens in 42Crunch Platform, either on the landing page or in your platform account settings. This documentation describes usage for paying customers.
• Free customers can use freemium tokens in their IDEs to configure using the more limited freemium service locally. For more details on the freemium service, see Freemium User FAQ.

For more details on VS Code integration, see VS Code integration.

You can also find a tutorial video on OpenAPI (Swagger) Editor in VS Code here.

Create an IDE token

The extension uses a token to authenticate to 42Crunch Platform, so on the first time, you must provide one that the extension can use. If you already have an account in 42Crunch Platform or want to create one, you can create an IDE token and use that one.

1. Log in or sign up to 42Crunch Platform.
2. Click Create a new IDE token on the landing page.
3. Copy the value of your IDE token and store it securely, you will need it to configure your IDE extension.

If you do not have 42Crunch Platform account and do not want to create one to take advantage of the more advanced integration options, you can also provide your email address when configuring the IDE extension.

Update your token

If you want to use a new IDE token — or change to using IDE tokens to unlock more integration features — you can reconfigure the token that the IDE extension uses.

1. Create an IDE token, and remember to copy the token value and store it securely before closing the configuration window. For security reasons you cannot view the token value later.
2. In VS Code, open the command palette, and select the command 42Crunch: Update platform credentials.
3. Enter 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.
4. Enter the value of the new IDE token.

Your IDE will now use the new token to authenticate to 42Crunch Platform.

Configure VS Code and audit your API definition

You can find OpenAPI (Swagger) Editor on the VS Code Marketplace.

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.

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.

Use Conformance Scan in VS Code

OpenAPI (Swagger) Editor also lets you scan your API operations and work on your scan configuration directly in your IDE.

The scan generates real traffic to the selected API endpoint and could incur costs depending on your setup.

For best results, make sure that your OpenAPI definition is valid and well-formatted before you scan it. The API must be deployed so that the API endpoint is live, and the backend server your API uses must be accessible to Conformance Scan. Otherwise the API cannot be scanned.

Conformance Scan can have potential side effects: APIs can throw exceptions, fail, and data can be affected. As per our terms and conditions, you must only scan APIs that you own, and only against non-production systems and non-production data! Do not use Conformance Scan in production environment!

1. Open the API you want in VS Code in .json or .yaml format.
2. Go to the API operation you want to scan, and click Scan. The IDE extension generates a default scan configuration based on your OpenAPI definition and opens that to a new tab. You can see all operations defined in your OpenAPI definition, listed by their operationId. Clicking on an operationId on the list changes the operation in focus.

   

3. If your API uses authentication, by default the scan in the IDE expects all security requirements to be required in any scan you perform and the scan fails unless you specify all SCAN42C_SECURITY_ environment variables for them. However, if you only want to scan a single operation and do not want to specify other security requirements than what the operation in question uses, you can mark the other security requirements as not required, and switch them back to required when you are done.

   

4. If you want, you can also edit the scan configuration. You can, for example:
   • Create and edit scenarios, global preprocessing and postprocessing block, or custom tests. For more details, see Scan scenarios and playbooks.
   • Populate environment variables used in your scan configuration with data from external sources, such as secrets.
   • Change the scan runtime settings.

     Not all scan settings might be available in the IDE.

   You can find more information on Conformance Scan directly in your IDE on the Help tab.

5. To test that your happy path request for the operation works, click Try. The IDE extension generates and send the happy path request to the operation and you can see the result underneath the settings on the Operations tab. Clicking lets you change some settings for the request.
6. To run a scan, do one of the following on the Operations tab of the scan configuration:
   • To scan just a single API operation, click on the operationId you want, and click Scan. Conformance Scan runs the scan only on the selected API operation, using the current scan configuration and settings.
   • To scan all operations in your API, click Scan all operations. Conformance Scan scans the full API, using the current scan configuration and settings.

     In both cases, Conformance Scan provides a report on the found issues in your editor just like it does in 42Crunch Platform, and you can see how the happy path tests went.

7. To view results from all tests that the scan run, including the ones where no issues were discovered, click Tests. To view results only from the tests that discovered issues, click Issues found. You can also further filter the results, for example, by the endpoint, test, method, or operationId. If filtering by severity, issues of the selected level or more severe are shown.

To fix the found issues, you can either change your API definition or API implementation, depending on what is the outcome you want, and then rerun the scan to verify the fix.

Define authentication methods in your IDE

The most common environment variable that you need for your scan configuration are credentials for authentication. If your API uses authentication, by default the scan in the IDE expects all security requirements to be required in any scan you perform and the scan fails unless you specify all SCAN42C_SECURITY_ environment variables for them. When scanning in your IDE, you can define the credentials as secrets in your IDE.

1. In the scan configuration in your IDE, go to the Environment tab. You can see all environment variables already defined for your scan configuration, such as all security requirements defined in your API.
2. To check which authentication methods you need for the API, check where source environment variables start with SCAN42C_SECURITY_. These mark the credentials your API requires.
3. To define secrets to store the credentials in your IDE, click Manage IDE environment, and go to the Secrets tab.
4. For each SCAN42C_SECURITY_ variable, click onto an empty line (where it says name) and enter the full value of source environment variable, then enter the credential value for it. For secrets, the exact value is automatically hidden.

   

You have now stored the credentials for your API as secrets directly in your IDE. You can also define other environment variables in the same way, if they are not sensitive information, you can define them on the Default tab.

View API collections in the IDE

You can also view and manage API collections available to you in 42Crunch Platform directly in the IDE. The IDE extension uses IDE tokens to access and authenticate to 42Crunch Platform. You can create IDE tokens in 42Crunch Platform, either on the landing page or in your account settings.

Creating IDE tokens requires a user account in 42Crunch Platform. If you have so far just used the token that was mailed to you when you first run Security Audit in the IDE, you must sign up for an account before you can configure the integration for viewing the APIs and API collections in your IDE.

1. If you have not yet done so, change the IDE to use IDE tokens to authenticate to 42Crunch Platform. See Update your token. The IDE extension can now read the API collections available to you and APIs in them when you click the 42C icon in the activity bar.

   

2. To open the API definition in the IDE, click OpenAPI definition. To view the audit report, click Security Audit.
3. To open the API definition in 42Crunch Platform, rename it, or delete it, right-click on the API, and select the action you want.

   Deleting an API permanently removes it from 42Crunch Platform. This action cannot be undone.