0
# Software Bill of Materials (SBOM) Generation
1

2
The SBOM generation goals create standardized CycloneDX Software Bill of Materials files for both backend (Maven) and frontend (npm) dependencies, supporting security compliance and vulnerability analysis.
3

4
## Goals Overview
5

6
```xml { .api }
7
<goal>generate-maven-sbom</goal>  <!-- Backend dependencies SBOM -->
8
<goal>generate-npm-sbom</goal>    <!-- Frontend dependencies SBOM -->
9
<!-- Default phase: process-resources -->
10
<!-- Dependency resolution: compile -->
11
```
12

13
Both goals generate CycloneDX-compliant SBOM files for comprehensive dependency tracking.
14

15
## Maven SBOM Generation
16

17
### Purpose
18

19
The `generate-maven-sbom` goal creates SBOM files focused on backend Java dependencies using the CycloneDX Maven plugin.
20

21
### Configuration Parameters
22

23
```xml { .api }
24
<configuration>
25
  <!-- Component metadata -->
26
  <projectType>application</projectType>
27
  <schemaVersion>1.4</schemaVersion>
28
  <includeBomSerialNumber>true</includeBomSerialNumber>
29

30
  <!-- Scope inclusion -->
31
  <includeCompileScope>true</includeCompileScope>
32
  <includeProvidedScope>true</includeProvidedScope>
33
  <includeRuntimeScope>true</includeRuntimeScope>
34
  <includeTestScope>false</includeTestScope>
35
  <includeSystemScope>true</includeSystemScope>
36

37
  <!-- Output configuration -->
38
  <outputFormat>json</outputFormat>
39
  <outputName>bom</outputName>
40
  <outputDirectory>${project.build.outputDirectory}/resources</outputDirectory>
41

42
  <!-- Additional options -->
43
  <includeLicenseText>false</includeLicenseText>
44
  <outputReactorProjects>true</outputReactorProjects>
45
  <verbose>false</verbose>
46
</configuration>
47
```
48

49
### Parameter Reference
50

51
```xml { .api }
52
<!-- Component type for SBOM metadata -->
53
<projectType>application|library|framework|device|firmware|container</projectType>
54

55
<!-- CycloneDX schema version -->
56
<schemaVersion>1.3|1.4|1.5</schemaVersion>
57

58
<!-- Include unique BOM serial number -->
59
<includeBomSerialNumber>true|false</includeBomSerialNumber>
60

61
<!-- Dependency scope inclusion -->
62
<includeCompileScope>true|false</includeCompileScope>
63
<includeProvidedScope>true|false</includeProvidedScope>
64
<includeRuntimeScope>true|false</includeRuntimeScope>
65
<includeTestScope>true|false</includeTestScope>
66
<includeSystemScope>true|false</includeSystemScope>
67

68
<!-- Output format options -->
69
<outputFormat>json|xml|all</outputFormat>
70
<outputName>string</outputName>
71
<outputDirectory>path</outputDirectory>
72

73
<!-- Advanced options -->
74
<includeLicenseText>true|false</includeLicenseText>
75
<outputReactorProjects>true|false</outputReactorProjects>
76
<excludeTypes>type1,type2,...</excludeTypes>
77
<excludeArtifactId>artifact1,artifact2,...</excludeArtifactId>
78
<excludeGroupId>group1,group2,...</excludeGroupId>
79
<excludeTestProject>true|false</excludeTestProject>
80
<verbose>true|false</verbose>
81
```
82

83
## NPM SBOM Generation
84

85
### Purpose
86

87
The `generate-npm-sbom` goal creates SBOM files focused on frontend npm dependencies using the CycloneDX npm tool.
88

89
### Configuration Parameters
90

91
```xml { .api }
92
<configuration>
93
  <!-- NPM analysis options -->
94
  <ignoreNpmErrors>false</ignoreNpmErrors>
95
  <packageLockOnly>false</packageLockOnly>
96
  <omit>dev</omit>
97

98
  <!-- Output formatting -->
99
  <flattenComponents>false</flattenComponents>
100
  <shortPURLs>false</shortPURLs>
101
  <outputReproducible>false</outputReproducible>
102
  <validate>true</validate>
103

104
  <!-- Component metadata -->
105
  <mcType>application</mcType>
106
  <productionMode>false</productionMode>
107

108
  <!-- File paths -->
109
  <outputFormat>json</outputFormat>
110
  <outputFilePath>${project.build.outputDirectory}/resources/bom-npm.json</outputFilePath>
111
  <packageManifest>./package.json</packageManifest>
112
  <specVersion>1.4</specVersion>
113
</configuration>
114
```
115

116
### Parameter Reference
117

118
```xml { .api }
119
<!-- NPM behavior options -->
120
<ignoreNpmErrors>true|false</ignoreNpmErrors>              <!-- Ignore NPM installation errors -->
121
<packageLockOnly>true|false</packageLockOnly>              <!-- Use only lock file, not node_modules -->
122
<omit>dev|optional|peer</omit>                             <!-- Dependency types to omit -->
123

124
<!-- Output formatting -->
125
<flattenComponents>true|false</flattenComponents>          <!-- Flatten component hierarchy -->
126
<shortPURLs>true|false</shortPURLs>                        <!-- Omit PURL qualifiers -->
127
<outputReproducible>true|false</outputReproducible>        <!-- Make output reproducible -->
128
<validate>true|false</validate>                            <!-- Validate generated SBOM -->
129

130
<!-- Component type -->
131
<mcType>application|library|firmware</mcType>              <!-- Main component type -->
132
<productionMode>true|false</productionMode>                <!-- Mark as production -->
133

134
<!-- File configuration -->
135
<outputFormat>json|xml</outputFormat>                      <!-- Output format -->
136
<outputFilePath>path/to/output/file</outputFilePath>       <!-- Output file path -->
137
<packageManifest>path/to/package.json</packageManifest>    <!-- package.json location -->
138
<specVersion>1.3|1.4|1.5</specVersion>                    <!-- CycloneDX spec version -->
139
```
140

141
## Usage Examples
142

143
### Basic SBOM Generation
144

145
```xml
146
<plugin>
147
  <groupId>com.vaadin</groupId>
148
  <artifactId>vaadin-maven-plugin</artifactId>
149
  <version>24.9.0</version>
150
  <executions>
151
    <execution>
152
      <goals>
153
        <goal>generate-maven-sbom</goal>
154
        <goal>generate-npm-sbom</goal>
155
      </goals>
156
    </execution>
157
  </executions>
158
</plugin>
159
```
160

161
### Custom Maven SBOM Configuration
162

163
```xml
164
<plugin>
165
  <groupId>com.vaadin</groupId>
166
  <artifactId>vaadin-maven-plugin</artifactId>
167
  <version>24.9.0</version>
168
  <configuration>
169
    <!-- Maven SBOM settings -->
170
    <projectType>library</projectType>
171
    <schemaVersion>1.5</schemaVersion>
172
    <outputFormat>xml</outputFormat>
173
    <outputName>security-bom</outputName>
174
    <includeTestScope>true</includeTestScope>
175
    <includeLicenseText>true</includeLicenseText>
176
    <verbose>true</verbose>
177
  </configuration>
178
  <executions>
179
    <execution>
180
      <goals>
181
        <goal>generate-maven-sbom</goal>
182
      </goals>
183
    </execution>
184
  </executions>
185
</plugin>
186
```
187

188
### Custom NPM SBOM Configuration
189

190
```xml
191
<plugin>
192
  <groupId>com.vaadin</groupId>
193
  <artifactId>vaadin-maven-plugin</artifactId>
194
  <version>24.9.0</version>
195
  <configuration>
196
    <!-- NPM SBOM settings -->
197
    <productionMode>true</productionMode>
198
    <omit>dev,optional</omit>
199
    <outputReproducible>true</outputReproducible>
200
    <flattenComponents>false</flattenComponents>
201
    <outputFilePath>target/security/frontend-bom.json</outputFilePath>
202
    <mcType>library</mcType>
203
  </configuration>
204
  <executions>
205
    <execution>
206
      <goals>
207
        <goal>generate-npm-sbom</goal>
208
      </goals>
209
    </execution>
210
  </executions>
211
</plugin>
212
```
213

214
### Security-Focused Configuration
215

216
```xml
217
<configuration>
218
  <!-- Maven SBOM for security analysis -->
219
  <includeCompileScope>true</includeCompileScope>
220
  <includeRuntimeScope>true</includeRuntimeScope>
221
  <includeTestScope>false</includeTestScope>
222
  <includeLicenseText>true</includeLicenseText>
223
  <outputFormat>all</outputFormat>  <!-- Generate both JSON and XML -->
224

225
  <!-- NPM SBOM for security analysis -->
226
  <omit>dev</omit>                 <!-- Exclude dev dependencies from security analysis -->
227
  <validate>true</validate>        <!-- Ensure SBOM validity -->
228
  <outputReproducible>true</outputReproducible>  <!-- Consistent builds -->
229
</configuration>
230
```
231

232
## Command Line Execution
233

234
```bash
235
# Generate both SBOMs
236
mvn flow:generate-maven-sbom vaadin:generate-npm-sbom
237

238
# Generate Maven SBOM only
239
mvn flow:generate-maven-sbom
240

241
# Generate NPM SBOM only
242
mvn flow:generate-npm-sbom
243

244
# Custom output directory
245
mvn flow:generate-maven-sbom -Dvaadin.outputDirectory=target/security
246

247
# Include test dependencies
248
mvn flow:generate-maven-sbom -Dvaadin.includeTestScope=true
249

250
# Verbose NPM SBOM generation
251
mvn flow:generate-npm-sbom -Dvaadin.validate=true -X
252
```
253

254
## Generated SBOM Files
255

256
### Maven SBOM Output
257

258
Default location: `target/classes/resources/bom.json`
259

260
```json
261
{
262
  "bomFormat": "CycloneDX",
263
  "specVersion": "1.4",
264
  "serialNumber": "urn:uuid:12345678-1234-1234-1234-123456789012",
265
  "version": 1,
266
  "metadata": {
267
    "timestamp": "2024-01-01T00:00:00Z",
268
    "component": {
269
      "type": "application",
270
      "name": "my-vaadin-app",
271
      "version": "1.0.0"
272
    }
273
  },
274
  "components": [
275
    {
276
      "type": "library",
277
      "group": "com.vaadin",
278
      "name": "vaadin-core",
279
      "version": "24.9.0",
280
      "purl": "pkg:maven/com.vaadin/vaadin-core@24.9.0",
281
      "licenses": [...]
282
    }
283
  ]
284
}
285
```
286

287
### NPM SBOM Output
288

289
Default location: `target/classes/resources/bom-npm.json`
290

291
```json
292
{
293
  "bomFormat": "CycloneDX",
294
  "specVersion": "1.4",
295
  "serialNumber": "urn:uuid:87654321-4321-4321-4321-210987654321",
296
  "version": 1,
297
  "metadata": {
298
    "component": {
299
      "type": "application",
300
      "name": "my-frontend",
301
      "version": "1.0.0"
302
    }
303
  },
304
  "components": [
305
    {
306
      "type": "library",
307
      "name": "lit",
308
      "version": "2.8.0",
309
      "purl": "pkg:npm/lit@2.8.0",
310
      "licenses": [...]
311
    }
312
  ]
313
}
314
```
315

316
## Integration with Security Tools
317

318
### Vulnerability Scanning
319

320
SBOM files can be used with security tools:
321

322
```bash
323
# Using OWASP Dependency Check
324
dependency-check --project myapp --scan target/classes/resources/bom.json
325

326
# Using Snyk
327
snyk test --file=target/classes/resources/bom.json
328

329
# Using Grype
330
grype sbom:target/classes/resources/bom.json
331
```
332

333
### CI/CD Integration
334

335
```bash
336
#!/bin/bash
337
# CI/CD security pipeline
338
mvn flow:generate-maven-sbom vaadin:generate-npm-sbom
339
vulnerability-scanner --sbom target/classes/resources/bom.json
340
vulnerability-scanner --sbom target/classes/resources/bom-npm.json
341
```
342

343
## Troubleshooting
344

345
### NPM SBOM Generation Issues
346

347
```
348
Error: node_modules not found
349
Solution: Run mvn flow:prepare-frontend first or ensure npm install completed
350
```
351

352
```
353
Error: CycloneDX tool not available
354
Solution: Ensure npx and @cyclonedx/cyclonedx-npm are accessible
355
```
356

357
### Maven SBOM Generation Issues
358

359
```
360
Error: CycloneDX plugin execution failed
361
Solution: Check Maven repository access, verify plugin version compatibility
362
```
363

364
### Output Directory Issues
365

366
```
367
Error: Cannot write to output directory
368
Solution: Ensure directory exists and has write permissions, create directory structure
369
```
370

371
## Advanced Configuration
372

373
### Multi-Module Projects
374

375
For Maven multi-module projects:
376

377
```xml
378
<!-- In parent pom.xml -->
379
<plugin>
380
  <groupId>com.vaadin</groupId>
381
  <artifactId>vaadin-maven-plugin</artifactId>
382
  <version>24.9.0</version>
383
  <configuration>
384
    <outputReactorProjects>true</outputReactorProjects>  <!-- Include all modules -->
385
    <excludeTestProject>true</excludeTestProject>        <!-- Exclude test modules -->
386
  </configuration>
387
</plugin>
388
```
389

390
### Custom Exclusions
391

392
```xml
393
<configuration>
394
  <!-- Exclude internal/test artifacts -->
395
  <excludeGroupId>com.example.internal,org.test</excludeGroupId>
396
  <excludeArtifactId>mock-*,test-*</excludeArtifactId>
397
  <excludeTypes>test-jar,javadoc</excludeTypes>
398
</configuration>
399
```
400

401
### Corporate Environment Settings
402

403
```xml
404
<configuration>
405
  <!-- NPM SBOM in corporate environment -->
406
  <ignoreNpmErrors>true</ignoreNpmErrors>  <!-- Handle corporate proxy issues -->
407
  <packageLockOnly>true</packageLockOnly>  <!-- Use only lock file if node_modules problematic -->
408
  <validate>false</validate>               <!-- Skip validation if network restricted -->
409
</configuration>
410
```