Using Clayton with VS Code

The Clayton Visual Studio Code extension brings the power of Clayton's security and code quality analysis directly into your VS Code environment.

Instead of switching between apps to check your scan results, you can visualize revision scans, understand policy compliance, and identify issues within your codebase right from your editor.

The extension aims to streamline your development workflow by providing feedback on the code you're working on, helping you and your team maintain high standards for security and quality across your GIT projects linked to Clayton.

This guide will walk you through installing, configuring, and using the Clayton VS Code extension effectively.

Visual Studio Code (VS Code) is a lightweight, open-source code editor developed by Microsoft. It provides powerful features like debugging, syntax highlighting, intelligent code completion, snippets, code refactoring, and built-in Git support. It is widely used by developers for various programming languages and frameworks due to its speed, flexibility, and extensive extension marketplace.

You may see the Clayton Visual Studio Code extension also be referred to as the Clayton IDE plugin.

An IDE, or Integrated Development Environment, enables programmers to consolidate the different aspects of writing a computer program. IDEs increase programmer productivity by combining common activities of writing software into a single application: editing source code, building executables, and debugging.

When you're setting up the Clayton VS Code extension, please ensure these prerequisites are met first:

To install the Clayton VS Code extension you can either search in the VS Code Extensions Marketplace for "Clayton", or simply follow this link.

VSCode version 1.91.0 or higher is required to install the Clayton extension for more information on downloading installing or updating VS code please consult Microsoft's guide on Setting up Visual Studio Code.

Once you have installed the Clayton VS Code extension, you will be presented with a screen like this in VS Code.

Here you will now need to configure the Clayton VS Code extension to enable you to see all the issues detected by Clayton directly into VS Code.

The first step is to setup the OAuth credentials to authorise this connection between VS Code and Clayton.

Once you have these credentials, click on the Add Client ID and Add Client Secret buttons, and when prompted provide the matching OAuth details from your Clayton account.

You will now be asked to login to Clayton in VSCode where you will need to consent and grant permissions for the two applications to work together.

You will now be prompted to Select Workspace. A Visual Studio Code workspace is the collection of one or more folders that are opened in a VS Code window (instance). What is a VS Code workspace?

When asked to Select Project you should select a Clayton project that matches your current local git repository.

That's it, you are now setup and ready to view Clayton revision scans in VS Code. Click on View Scans to move forward.

In the left hand menu in VS Code you will now see the Clayton icon. Click on here to see the history of the latest revisions (scans) in a list for the current branch.

The heading for each item in the list contains the number of issues, the commit reference and the commits message. In the screenshot below you will see 14 - 3901a49 - Empty-..., this indicates there are 14 issues in commit 3901a49.

If you click on this heading the dropdown will display a list of the policies used in this scan. In the screenshot below you will see the list contains the policies Secure, Compliant, Reliable and Automated. Notice how these policies also have a number in brackets indicating the number of issues for that policy.

The related issues are also opened in the SARIF viewer on the right hand side of the screen, presenting a list of all the issues for this revision. These revision issues are also split by Location and Rules.

Clicking on one of the files listed in the SARIF viewer by Location will open a list of the issues, showing you the issue type, line number, and issue description. This will enable you find where the issue is easily, and help you to understand how to fix it.

Clicking on the issues will take you to this file, and also the line number where the issue is found.

After opening a file, within the editor you will see how errors, issues and warning are now highlighted with annotation and decorations to help you find them easily. You can also hover over the line with an issue to see a description inside of the editor as shown in the screenshot below.

When making changes, it is alway best to make a new branch. You can create a new branch inside VS Code using VS Codes build in Source Control functionality, using your Version Control Service extension, or using the terminal.

Before you starting making changes, we recommend that you publish (push) the branch first. This will allow Clayton to see this new branch.

You will then be prompted by VS Code asking if you want to set up branch tracking in Clayton for this branch? Click on Track Branch to set this up.

If you are publishing the branch in the terminal, you may not be prompted to track the branch. To make sure this branch is being tracked in Clayton, find the new branch and ensure the toggle is switched to enable tracking changes in this branch.

With the new branch created, published and tracked you can now make changes to the file and fix these issues.

When you have completed this work and are ready to publish these changes you can do so in VS Code. First add the files you've worked on to staging, make a commit, then publish (push) the changes to the remote branch.

With the Clayton extension open, you will see a button at the top of the revisions section that will allow you to Initiate Clayton Scan.

If you click this, you will see a notification in VS Code:

Shortly after, the scan will begin which is indicated in VS Code with a change in the icon next to the existing revision, or a new revision added to the list:

Already connected Clayton to VS Code using OAuth, but need to find your Client ID and Secret again? No trouble, it's easy to grab them!

You'll then see the Client ID and Client Secret you're looking for!