Add AppSec Kit documentation for V23

.github/styles/Vaadin/Abbr.yml

@@ -21,6 +21,7 @@ exceptions:
   - CRUD
   - CSS
   - CSV
+  - CVSS
   - DOM
   - DPI
   - DTO
@@ -54,6 +55,7 @@ exceptions:
   - MDN
   - MIME
   - MPR
+  - OSV
   - PATH
   - PDF
   - PHP
@@ -62,6 +64,7 @@ exceptions:
   - POST
   - RAM
   - RFC
+  - SBOM
   - SDK
   - SQL
   - SSH

articles/index.asciidoc

@@ -87,6 +87,13 @@ include::components/app-layout/index.asciidoc[tag=description]
 [.cards.quiet.large]
 == Tools
 
+[.card]
+=== AppSec Kit
+Identify and manage vulnerabilities in third-party dependencies.
+
+[.sr-only]
+<<{articles}/tools/appsec#,See AppSec Kit>>
+
 [.card]
 === Azure Cloud Kit
 image::{articles}/_images/azure-kit.svg[opts=inline, role=icon]

articles/tools/appsec/advanced-topics.adoc

@@ -0,0 +1,97 @@
+---
+title: Advanced Topics
+description: Highlights some advanced topics related to AppSec Kit.
+order: 20
+---
+
+
+= Advanced Topics
+
+This page highlights some advanced topics related to AppSec Kit. For more basic information, see the <</tools/appsec/getting-started#, Getting Started with AppSec>> page.
+
+
+[[appsec-kit-configuration]]
+== AppSec Kit Configuration
+
+This section describes the configuration options and their default values. The AppSec Kit has the `AppSecConfiguration` class. An instance of this class can be set to configure the `AppSecService` like so:
+
+[source,java]
+----
+AppSecConfiguration configuration = new AppSecConfiguration();
+configuration.setAutoScanInterval(Duration.ofDays(2));
+
+AppSecService.getInstance().setConfiguration(appSecConfiguration);
+----
+
+You can set or override the following configuration values in the `AppSecConfiguration`:
+
+`appSecRoute`::
+The route of the AppSec Kit user interface.
+`dataFilePath`::
+The path of the data file for storing information about the vulnerabilities.
+`bomFilePath`::
+The path of the SBOM (Software Bill Of Materials) file used as a source of Maven dependencies.
+`bomNpmFilePath`::
+The path of the SBOM (Software Bill Of Materials) file used as a source of npm dependencies.
+`taskExecutor`::
+The executor used to run asynchronous tasks during the vulnerability scanning.
+`autoScanInterval`::
+The duration of the interval between automatic scanning for vulnerabilities.
+`osvApiRatePerSecond`::
+The rate per second for the OSV (Open Source Vulnerability) API calls.
+`includeNpmDevDependencies`::
+The boolean value to decide if the npm development dependencies should be included during vulnerability scanning.
+`automaticallyActivatePush`::
+The boolean value to decide if the server push should be automatically activated in the application.
+
+
+=== AppSec Kit Route
+
+You can configure the route of the AppSec Kit user interface. The default value is `vaadin-appsec-kit`.
+
+
+=== Path of Data File
+
+In the `Vulnerability Details View`, you can add analysis of the vulnerability. When this analysis is saved with the vulnerability information, it's stored in a data file in JSON format. Its default path is the application's root and the file name is `appsec-data.json`. The path can also be configured with the `vaadin.appsec.data` system property.
+
+
+=== Path of Maven SBOM File
+
+Your application's Maven dependencies in the [guilabel]*Dependencies View* are populated from the Maven SBOM file. It should contain the dependencies in link:https://cyclonedx.org/specification/overview/[CycloneDX JSON schema] format. Its default path is `/resources`; the file name is [filename]`bom.json`. The path can also be configured with the `vaadin.appsec.bom` system property.
+
+
+=== Path of npm SBOM File
+
+Your application's npm dependencies in the [guilabel]*Dependencies View* are populated from the npm SBOM file. It should contain the dependencies in link:https://cyclonedx.org/specification/overview/[CycloneDX JSON schema] format. Its default path is `/resources`; the file name is [filename]`bom-npm.json`. The path can also be configured with the `vaadin.appsec.bom-npm` system property.
+
+
+=== Task Executor
+
+You can set a custom executor for the background and scheduled jobs run by the AppSec Kit. For example, scheduled jobs are run when an automatic or manual vulnerability scan happens. The default task executor is a single-thread executor.
+
+
+=== Auto Scan Interval
+
+You can configure the duration of the interval between automatic scanning for vulnerabilities. The default interval is 1 day.
+
+
+=== OSV Rate per Second
+
+You can configure the rate per second value for the link:https://google.github.io/osv.dev/api/[OSV API] (Open Source Vulnerability) calls. The default value is 25.
+
+
+=== npm Development Dependencies
+
+If applicable, you can configure if the npm development dependencies should be included during vulnerability scanning. The default value is `true`.
+
+
+=== Automatically Activate Push
+
+You can configure whether the <<{articles}/advanced/server-push#, server push>> should be automatically activated if needed. When enabled, which is the default, AppSec Kit automatically activates `PushMode#AUTOMATIC` if neither push nor polling is active for a UI where AppSec Kit is used. When disabled, no automatic changes are made to the application's push configuration.
+
+
+++++
+<style>
+[class^=PageHeader-module--descriptionContainer] {display: none;}
+</style>
+++++

articles/tools/appsec/getting-started.adoc

@@ -0,0 +1,209 @@
+---
+title: Getting Started
+description: Step-by-step guide on how to use AppSec Kit in an application.
+order: 10
+---
+
+
+= Getting Started with AppSec Kit
+
+AppSec Kit is an excellent tool for monitoring application dependencies for vulnerabilities. It lets you see details of what's discovered. And you can record and store your analysis to share with other developers.
+
+
+== Add AppSec Kit Dependency
+
+To start, you'll need to add AppSec Kit as a dependency to your application. To add it to a Maven project, you might include something like this in your [filename]`pom.xml` file:
+
+.pom.xml
+[source,xml,subs="+attributes"]
+----
+<dependency>
+    <groupId>com.vaadin</groupId>
+    <artifactId>appsec-kit-starter</artifactId>
+    <version>2.0.0</version>
+</dependency>
+----
+
+See the https://github.com/vaadin/appsec-kit/releases[AppSec Kit releases page] for the latest version, or for a different version of the dependency.
+
+
+== Generating SBOM Files
+
+To be able to monitor the application dependencies, AppSec Kit needs the Software Bill of Materials (SBOM) files generated from Maven and npm dependencies. These files contain information about the dependencies and their transitives.
+
+
+=== Maven Dependencies
+
+To generate the SBOM file from Maven dependencies, you'll need to add the link:https://github.com/CycloneDX/cyclonedx-maven-plugin[`CycloneDX Maven Plugin`] to the plugins in your [filename]`pom.xml` file like so:
+
+.pom.xml
+[source,xml]
+----
+<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, make sure to run the `maven install`. Then the SBOM file, [filename]`bom.json` should be generated in the `/resources` sub-directory in the project's output directory. The plugin is configured to do this.
+
+
+=== npm Dependencies
+
+To generate the SBOM file from npm dependencies defined in the [filename]`package.json` file, you'll need to run the link:https://www.npmjs.com/package/@cyclonedx/cyclonedx-npm[`@cyclonedx/cyclonedx-npm`] plugin with npx like so:
+
+[source,shell]
+----
+npx --package @cyclonedx/cyclonedx-npm --call exit
+----
+
+The `@cyclonedx/cyclonedx-npm` plugin requires `node >= 14` and `npm >= 6` versions, also, the [filename]`package-lock.json` file and the [filename]`node_modules` folder should be present in order to successfully run.
+
+To add it to the plugins, you would use the `exec-maven-plugin` in your [filename]`pom.xml` file like this:
+
+.pom.xml
+[source,xml]
+----
+<plugin>
+    <groupId>org.codehaus.mojo</groupId>
+    <artifactId>exec-maven-plugin</artifactId>
+    <version>1.3.2</version>
+    <executions>
+        <execution>
+            <id>cyclonedx-npm</id>
+            <goals>
+                <goal>exec</goal>
+            </goals>
+            <phase>generate-resources</phase>
+            <configuration>
+                <executable>npx</executable>
+                <arguments>
+                    <argument>@cyclonedx/cyclonedx-npm</argument>
+                    <argument>--output-file</argument>
+                    <argument>${project.build.outputDirectory}/resources/bom-npm.json</argument>
+                    <argument>--output-format</argument>
+                    <argument>JSON</argument>
+                </arguments>
+            </configuration>
+        </execution>
+    </executions>
+</plugin>
+----
+
+Before starting the application, make sure to run the `npm install` and `mvn install`. Then the SBOM file, [filename]`bom-npm.json` should be generated in the `/resources` sub-directory in the project's output directory. The plugin is configured to do this. AppSec Kit scans this SBOM file for vulnerabilities, if it's available.
+
+
+=== External APIs
+
+AppSec Kit calls external APIs to get vulnerabilities and vulnerability analysis for Vaadin dependencies. Since these calls are required for a normal operation, they need to be accessible.
+
+[source,text]
+----
+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/flow/releases
+
+Vaadin vulnerability analysis:
+https://raw.githubusercontent.com/vaadin/vulnerability-analysis/main/analysis.json
+----
+
+
+== Start the Application
+
+AppSec Kit isn't enabled in production mode. You'll need to start your application in <</configuration/development-mode#, development mode>> -- which is the default starting mode for applications. 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 (see screenshot). You'll see a link labeled _Open AppSec Kit_ that you can click on to open the UI in a new tab.
+
+[[notification-dialog]]
+.AppSec Kit Notification Dialog
+image::images/notification-dialog.png[]
+
+You can also navigate to the UI using the `vaadin-appsec-kit` route. For example, on your localhost enter something like this in your browser: link:http://localhost:8080/vaadin-appsec-kit[http://localhost:8080/vaadin-appsec-kit].
+
+AppSec Kit automatically activates <<{articles}/advanced/server-push#, server push>> if neither push nor polling is active for a UI where AppSec Kit is used. This way you'll be notified when new vulnerabilities are found. You can disable this functionality by overriding the default AppSec Kit <<{articles}/tools/appsec/advanced-topics#appsec-kit-configuration, configuration>>.
+
+
+== AppSec Kit UI
+
+The AppSec Kit UI has views for seeing vulnerabilities and dependencies of which you should be aware. This section describes those views, which can be found under the two main tabs of the UI.
+
+
+=== Vulnerabilities Tab
+
+When you open the UI, you'll see the [guilabel]*Vulnerabilities* tab (see screenshot). Any collected vulnerabilities are listed there. They're shown in a grid view, with columns to help identify each vulnerability, and the ecosystem and dependency in which each has been found. It also includes the severity calculated from the CVSS vector string, a link:https://nvd.nist.gov/vuln-metrics/cvss[CVSS score] and some analyses.
+
+You can filter the vulnerabilities by using the Ecosystem, Dependency, Vaadin analysis, Developer analysis, Severity, and Common Vulnerability Scoring System (i.e., CVSS) score filters. You'd choose these filters from the pull-down menus near the top to apply any of the filters. Click on the [guibutton]*Clear* button next to the filters to reset them.
+
+[[vulnerabilities-tab]]
+.AppSec Kit Vulnerabilities View
+image::images/vulnerabilities-tab.png[]
+
+To run a new scan, click the [guibutton]*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 particular vulnerability, select the row containing it, and then click the [guibutton]*Show details* button. Or you can double-click on the row. The `Vulnerability Details View` is then opened -- which is described next.
+
+
+=== Vulnerability Details
+
+When you open a listed vulnerability, you can see a more detailed description of it (see screenshot here). You'll also find links to other pages to explain the vulnerability and offer some general suggestions to resolve it.
+
+If the Vaadin Security Team is reviewing the vulnerability, it'll be noted at the top. This includes Vaadin's specific assessment and related recommendations.
+
+[[vulnerability-details]]
+.AppSec Kit Vulnerability Details View
+image::images/vulnerability-details-view.png[]
+
+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 [guibutton]*Save* button. Your analysis is made available to other developers if you commit it to the version control system.
+
+
+==== Dependencies Tab
+
+To see your application dependencies, click on the [guilabel]*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, ecosystem and group to which it belongs, and the version. It also lists the _Is development_, which marks if an npm dependency is a development dependency -- for Maven dependencies this is always `false`. And it lists the count of vulnerabilities, the highest severity, and the highest CVSS score.
+
+[[dependencies-tab]]
+.AppSec Kit Dependencies View
+image::images/dependencies-tab.png[]
+
+You can filter the list of dependencies based on the Ecosystem, Dependency group, Is development, Security, and the CVSS score. Choose these filters from the pull-down menus near the top to apply them. Click on the [guibutton]*Clear* button to reset them.
+
+If you want to see the vulnerabilities of a particular dependency, select the row containing it, and then click the [guibutton]*Show vulnerabilities* button. Or you can double-click on a row. The `Vulnerabilities Tab` is then opened with the vulnerabilities for that dependency.
+
+
+++++
+<style>
+[class^=PageHeader-module--descriptionContainer] {display: none;}
+</style>
+++++

articles/tools/appsec/index.adoc

@@ -0,0 +1,46 @@
+---
+title: AppSec Kit
+description: Identify and manage vulnerabilities in third-party dependencies.
+section-nav: commercial
+---
+
+
+= AppSec Kit
+
+:commercial-feature: AppSec Kit
+:kit-trial: true
+include::{articles}/_commercial-banner.asciidoc[opts=optional]
+
+AppSec Kit offers seamless security integration to the development of Vaadin-based applications. It provides comprehensive dependency visibility, earlier remediation of vulnerabilities, and fewer false positives.
+
+
+== Comprehensive Dependency Visibility
+
+Managing dependencies is a crucial aspect of any software project, but it can be a complex and time-consuming task. AppSec Kit provides dependency visibility, generating a Software Bill of Materials (SBOM) that presents a comprehensive view of all direct and transitive dependencies used in your application.
+
+The SBOM is generated automatically each time you perform a development build -- or it can be initiated on-demand. This allows you to have complete visibility of your application's contents.
+
+
+== Earlier Remediation of Vulnerabilities
+
+AppSec Kit further streamlines the remediation process by regularly scanning the SBOM, and cross-referencing it with multiple industry-standard vulnerability databases, including National Vulnerability Database and GitHub Security Advisories. It identifies known vulnerabilities in both direct and transitive dependencies and includes detailed information, such as severity and patch versions.
+
+Reports on the results are displayed in Vaadin Development tools, ensuring smooth integration in your Vaadin application development process. This allows you to address vulnerabilities earlier in the process, ensuring the security of your web applications without compromising development speed.
+
+
+== Fewer False Positives
+
+By identifying and highlighting any false positives associated with Vaadin Flow and its dependencies, AppSec Kit makes it easier for developers to identify the vulnerabilities that actually need addressing.
+
+AppSec Kit flags any _false positive_ vulnerabilities that were identified in the dependencies of the Vaadin platform. It shows the analysis from Vaadin's security team, describing why it was considered a false positive. This allows you to focus on true vulnerabilities, on what matters.
+
+
+== Topics
+
+section_outline::[]
+
+++++
+<style>
+[class^=PageHeader-module--descriptionContainer] {display: none;}
+</style>
+++++