Getting Started with AppSec Kit
AppSec Kit is an excellent tool for monitoring your application dependencies for vulnerabilities. It lets you see details of discovered vulnerabilities. You can record and store your analysis to share with other developers.
This step-by-step guide will show you how to use AppSec Kit in an application.
Add AppSec Kit Dependency
To start, you’ll need to add AppSec Kit as a dependency to your application. To add to a Maven project, you might add something like this to your pom.xml file:
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>appsec-kit-v8</artifactId>
<version>1.0.1</version>
</dependency>|
Note
|
Version Number
See the AppSec Kit releases page for the latest version, or a different version of the dependency.
|
Generating an SBOM
To be able to monitor the application dependencies, AppSec Kit needs a Software Bill of Materials (SBOM) file. This file contains information about the dependencies and their transitives.
To generate the SBOM file, you’ll need to add the cyclonedx-maven-plugin to the plugins in your pom.xml file like so:
<plugin>
<groupId>org.cyclonedx</groupId>
<artifactId>cyclonedx-maven-plugin</artifactId>
<version>2.7.7</version>
<executions>
<execution>
<phase>generate-resources</phase>
<goals>
<goal>makeAggregateBom</goal>
</goals>
</execution>
</executions>
<configuration>
<projectType>library</projectType>
<schemaVersion>1.4</schemaVersion>
<includeBomSerialNumber>true</includeBomSerialNumber>
<includeCompileScope>true</includeCompileScope>
<includeProvidedScope>true</includeProvidedScope>
<includeRuntimeScope>true</includeRuntimeScope>
<includeSystemScope>true</includeSystemScope>
<includeTestScope>false</includeTestScope>
<includeLicenseText>false</includeLicenseText>
<outputReactorProjects>true</outputReactorProjects>
<outputFormat>json</outputFormat>
<outputName>bom</outputName>
<outputDirectory>${project.build.outputDirectory}/resources</outputDirectory>
<verbose>false</verbose>
</configuration>
</plugin>Before starting the application, be sure to run maven install. The SBOM file, bom.json should then be generated in the /resources sub-directory in the project’s output directory. The plugin is configured to do this.
External APIs
AppSec Kit calls external APIs to get vulnerabilities and a vulnerability analysis for Vaadin dependencies. Since these calls are required for a normal operation, they need to be accessible.
OSV (Open Source Vulnerability) API:
https://api.osv.dev/v1/querybatch
https://api.osv.dev/v1/vulns/
GitHub API:
https://api.github.com/repos/vaadin/framework/releases
Vaadin vulnerability analysis:
https://raw.githubusercontent.com/vaadin/vulnerability-analysis/main/analysis.jsonStart the Application
AppSec Kit isn’t enabled in production mode. You’ll need to start your application in debug mode — or in development mode. By default, the Vaadin 8 applications start in debug mode. You don’t need to enable this, explicitly.
Notification Dialog
After the application has started, AppSec Kit analyzes the dependencies, collects new vulnerabilities, and displays a notification dialog. A vulnerability is considered as new if a developer analysis has not yet been added to it. Therefore, vulnerabilities with developer analysis aren’t counted in the found vulnerabilities number. In the screenshot, you’ll see a link labeled Open AppSec Kit that you can click on to open the UI in a new tab.
You can also navigate to the UI using the vaadin-appsec-kit URL parameter. For example, on your localhost, enter something like this in your browser: http://localhost:8080/?vaadin-appsec-kit.
You should configure server push for a UI so you’ll be notified when new vulnerabilities are found. You can do this by adding the @Push annotation to a UI class like so:
@Push
public class ExampleUI extends UI {
// ...
}The server push support in Vaadin, though, requires the separate Vaadin Push library. In Maven, add the following dependency to your pom.xml file:
<dependency>
<groupId>com.vaadin</groupId>
<artifactId>vaadin-push</artifactId>
<version>${vaadin.version}</version>
</dependency>AppSec Kit UI
The AppSec Kit UI has views for seeing vulnerabilities and dependencies of which you should be aware. This section describes these views, which can be found under the two main tabs of the UI.
Vulnerabilities Tab
When you open the UI, you’ll see the Vulnerabilities tab (see screenshot here). Any collected vulnerabilities are listed there. They’re shown in a grid view with columns to help identify each vulnerability, the dependency in which each has been found, the severity, a risk score and some analyses.
You can filter the vulnerabilities by using the Dependency, Developer Analysis, and Severity Level filters. You’d choose these filters from the pull-down menus near the top left, then click the Filter button at the top right. Click on the Clear button next to it to reset the filters.
To run a new scan, click the Scan now button at the top right corner. After it’s finished, the Last Scan date and time is updated — located also at the top right.
If you want to see more details about a vulnerability, select the row containing the vulnerability of interest and then click the Show details button. Or you can just double-click on a row. The Vulnerability Details View is then opened — which is described next.
Vulnerability Details
When you open a listed vulnerability, you can find a more detailed description of it (see screenshot here). You’ll also find there links to other pages to explain the vulnerability and offer some general suggestions to resolve the vulnerability.
If the Vaadin Security Team is reviewing the vulnerability, it will be noted at the top. This includes Vaadin’s specific assessment and recommendations related to the vulnerability.
On the right side of the Details View, there’s a Developer analysis panel. There you can set the Vulnerability status and add your own description and other information you’ve uncovered. Preserve what you enter by clicking the Save button. Note, your analysis will be available to other developers if you commit it to the version control system.
Dependencies Tab
To see your application dependencies, click on the Dependencies tab at the top left of the UI. There you’ll find a list of dependencies shown in a grid view (see screenshot here). They’re listed in columns to help identify each dependency and the group to which it belongs, the version, the severity, and a risk score.
You can filter the list of dependencies based on the Dependency Group and the Security Level. You’d do this by choosing one or both of these two filters from the pull-down menus near the top left, then clicking the Filter button at the top right. Click the Clear button next to it to reset the filters.