We have updated our OpenAPI extension to version 2.0. This is a major release with the Security Audit getting to where we wanted it to be for its initial scope and a few other improvements.
OpenAPI Security Audit is a static analysis of OpenAPI files. The service does not call the actual API endpoint. It simply looks at the OpenAPI file itself and checks if it is following industry security best practices.
The checks that are run are derived from the API Security Encyclopedia at APISecurity.io.
To run Security Audit for the currently opened OpenAPI file:
- Click the 42c button at the upper right of the OpenAPI file you are editing.
Note:
- To run Security Audit from VS Code, you need a token. On the first time, you are asked to provide your email address. When you supply the address, the extension requests the token to be sent to your mailbox. Once you get the token, paste it in the prompt in VS Code, and you are all set. From now on, all you need to do is to click the button to run the audit.
After the audit finishes, you get the audit report directly in the VS Code view, side by side with your code. Depending on your API definition, the report might be long, so here are some handy ways to navigate the found issues.
- To scroll through all issues and their details, use the text panel on the right.
- Hover on an element that is underlined or marked with three dots (recommendations) in your code to see what the issues in that spot are. If you click on view the descriptions of only these issues, the rest of details are filtered out from the text panel, so you have less to scroll through.
- For a quick overall look, check the counts in the Status Bar. The different icons match the severity of the issue:
- Error: critical or high
- Warning: medium
- Info: low
- Click the icons in the Status Bar to open the PROBLEMS panel and scroll through the issue titles. The issues are ordered from most to least severe, so it is easy for fix the worst offenders first. Note that recommendations are not listed in the PROBLEMS panel.
- Click on an issue in the PROBLEMS panel to jump to view it inline in your API definition.
We have added the ability to jump to the specific place in the API definition for each error. To do this, simply click the hyperlink in the report.
When you are reading Security Audit information for a particular issue, you can now jump back to the full security audit report by clicking the Go back to full report link at the bottom of the article.
Security Audits can be tricky. If you believe that the static analysis misinterpreted your API definition, missed something, or provided a description or mitigation advice that can be improved, click the Please submit your feedback for the security audit here link at the top of the full report and submit a GitHub ticket.
API navigation tree used to only go 2 levels deep: to paths and operations. You can now go down two levels more: to specific parameters and responses.
As you edit OpenAPI files they temporarily become invalid from OpenAPI schema requirements perspective. In the past, this temporarily removed the API navigation tree entirely.
We have now improved the usability and keep the current tree even when the schema is temporarily wrong. This means that you still see which elements your API has.
Note: we still remove the ability to add new elements from the API navigation pane menu until your OpenAPI file becomes a proper JSON/YAML file again and we can build the live navigation model.