From d0a09df0d183038573c826e49924b76a9b5cb1fe Mon Sep 17 00:00:00 2001 From: Flavio Soibelmann Glock Date: Thu, 19 Mar 2026 09:29:18 +0100 Subject: [PATCH 01/11] Add SBOM (Software Bill of Materials) design document This document outlines the plan to add CycloneDX SBOM generation for PerlOnJava, covering both Java dependencies (via Gradle/Maven plugins) and bundled Perl modules (via SBOM::CycloneDX). Key points: - Phase 1: Add CycloneDX plugins to Gradle and Maven builds - Phase 2: Generate Perl module SBOM using SBOM::CycloneDX - Phase 3: Optional combined SBOM merging - CI/CD integration for automated SBOM generation - Compliance with NTIA minimum elements and CISA guidelines No code changes yet - this is a planning document only. Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin --- dev/design/sbom.md | 451 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 451 insertions(+) create mode 100644 dev/design/sbom.md diff --git a/dev/design/sbom.md b/dev/design/sbom.md new file mode 100644 index 000000000..f7b9f668e --- /dev/null +++ b/dev/design/sbom.md @@ -0,0 +1,451 @@ +# SBOM (Software Bill of Materials) for PerlOnJava + +## Status: Planned + +**Author:** Devin AI +**Date:** 2026-03-19 +**Related:** US Executive Order 14028, CISA SBOM Guidelines, CycloneDX ECMA-424 + +--- + +## Overview + +This document describes the plan to add CycloneDX SBOM generation to PerlOnJava, covering both: +1. **Java dependencies** (automatically via build tools) +2. **Bundled Perl modules** (via custom script using SBOM::CycloneDX) + +The goal is to produce a unified or complementary SBOM that documents the complete software supply chain of PerlOnJava releases. + +--- + +## Background + +### What is SBOM? + +A **Software Bill of Materials (SBOM)** is a nested inventory - a list of ingredients that make up software components. SBOMs are increasingly required for: + +- **US Government contracts** (Executive Order 14028, May 2021) +- **Supply chain security** and vulnerability management +- **License compliance** tracking +- **Security auditing** and incident response +- **Regulatory compliance** (FDA, EU Cyber Resilience Act) + +### CycloneDX Standard + +**CycloneDX** is the recommended SBOM standard for PerlOnJava because: + +1. **Security-focused** - Designed by OWASP for application security contexts +2. **Lightweight** - Simple JSON/XML format, easy to generate and consume +3. **Well-supported** - Extensive tooling for Java (Gradle, Maven) and Perl +4. **Standardized** - ECMA-424 international standard +5. **Comprehensive** - Supports dependencies, licenses, vulnerabilities (VEX) + +Alternative: **SPDX** (Linux Foundation) is more focused on license compliance but has less mature Java tooling. + +--- + +## PerlOnJava Component Inventory + +### Java Dependencies (from pom.xml / build.gradle) + +| Dependency | Version | License | Purpose | +|------------|---------|---------|---------| +| org.ow2.asm:asm | 9.9.1 | BSD-3-Clause | Bytecode manipulation | +| org.ow2.asm:asm-util | 9.9.1 | BSD-3-Clause | ASM utilities | +| com.ibm.icu:icu4j | 78.2 | ICU License | Unicode support | +| com.alibaba.fastjson2:fastjson2 | 2.0.61 | Apache-2.0 | JSON processing | +| org.snakeyaml:snakeyaml-engine | 3.0.1 | Apache-2.0 | YAML processing | +| org.tomlj:tomlj | 1.1.1 | Apache-2.0 | TOML processing | +| org.apache.commons:commons-csv | 1.14.1 | Apache-2.0 | CSV processing | +| com.github.jnr:jnr-posix | 3.1.19 | LGPL-2.1+ | Native POSIX access | + +Test dependencies (not in runtime SBOM): +- org.junit.jupiter (JUnit 5) - test scope only + +### Bundled Perl Modules (511 files in src/main/perl/lib/) + +Categories of bundled Perl modules: + +| Category | Examples | License | Notes | +|----------|----------|---------|-------| +| Core modules | strict.pm, warnings.pm | Perl Artistic-2.0 | Re-implemented for PerlOnJava | +| CPAN modules | CPAN.pm, CPAN::Meta | Various | Ported from CPAN | +| Pod modules | Pod::Text, Pod::Man | GPL-1.0+ OR Artistic-1.0 | Documentation tools | +| Test modules | Test::More, Test::Builder | Perl Artistic-2.0 | Testing infrastructure | +| Utility modules | File::Spec, Cwd | Perl Artistic-2.0 | Standard utilities | + +--- + +## Implementation Plan + +### Phase 1: Java SBOM Generation + +Add CycloneDX plugins to both Gradle and Maven builds. + +#### Gradle Configuration + +Add to `gradle/libs.versions.toml`: +```toml +[plugins] +cyclonedx = "org.cyclonedx.bom:3.2.2" +``` + +Add to `build.gradle`: +```groovy +plugins { + id 'org.cyclonedx.bom' version '3.2.2' +} + +// Configure CycloneDX +tasks.cyclonedxBom { + projectType = "application" + schemaVersion = "1.6" + includeLicenseText = false + includeBomSerialNumber = true + includeBuildSystem = true + + // Output configuration + destination = file("$buildDir/reports/sbom") + outputName = "perlonjava-java" + outputFormat = "all" // json and xml + + // Component metadata + componentName = "perlonjava" + componentVersion = project.version + + // Organization metadata + organizationalEntity { + name = "PerlOnJava Project" + urls = ["https://github.com/fglock/PerlOnJava"] + } +} +``` + +#### Maven Configuration + +Add to `pom.xml`: +```xml + + org.cyclonedx + cyclonedx-maven-plugin + 2.9.1 + + + package + + makeAggregateBom + + + + + application + 1.6 + true + false + all + perlonjava-java + + +``` + +**Output:** `build/reports/sbom/perlonjava-java.json` (Gradle) or `target/perlonjava-java.json` (Maven) + +### Phase 2: Perl SBOM Generation + +Use **SBOM::CycloneDX** (v1.07) to generate SBOM for bundled Perl modules. + +#### Option A: Use Native Perl (if available) + +```bash +# Install SBOM::CycloneDX +cpanm SBOM::CycloneDX +``` + +Create `dev/tools/generate-perl-sbom.pl`: +```perl +#!/usr/bin/env perl +use strict; +use warnings; +use SBOM::CycloneDX; +use SBOM::CycloneDX::Enum qw(COMPONENT_TYPE); +use File::Find; +use JSON::PP; + +my $bom = SBOM::CycloneDX->new; + +# Root component +my $root = SBOM::CycloneDX::Component->new( + type => COMPONENT_TYPE->APPLICATION, + name => 'perlonjava-perl-modules', + version => '5.42.0', + licenses => [SBOM::CycloneDX::License->new('Artistic-2.0')], + bom_ref => 'perlonjava-perl' +); + +$bom->metadata->component($root); +$bom->metadata->tools->add(SBOM::CycloneDX::cyclonedx_tool()); + +# Scan Perl modules +my @modules; +find(sub { + return unless /\.pm$/; + my $path = $File::Find::name; + my $module = $path; + $module =~ s{.*/lib/}{}; + $module =~ s{/}{::}g; + $module =~ s{\.pm$}{}; + + # Extract version from module if available + my $version = extract_version($path); + + push @modules, { + name => $module, + version => $version // 'bundled', + path => $path, + }; +}, 'src/main/perl/lib'); + +# Add components +for my $mod (@modules) { + my $component = SBOM::CycloneDX::Component->new( + type => COMPONENT_TYPE->LIBRARY, + name => $mod->{name}, + version => $mod->{version}, + bom_ref => "perl:$mod->{name}", + purl => URI::PackageURL->new( + type => 'cpan', + name => $mod->{name}, + version => $mod->{version}, + ), + ); + $bom->components->add($component); + $bom->add_dependency($root, [$component]); +} + +# Validate and output +my @errors = $bom->validate; +die "Validation errors: @errors" if @errors; + +print $bom->to_string; + +sub extract_version { + my ($path) = @_; + open my $fh, '<', $path or return; + while (<$fh>) { + if (/(?:our\s+)?\$VERSION\s*=\s*['"]?([0-9._]+)/) { + return $1; + } + } + return; +} +``` + +#### Option B: Use PerlOnJava (self-hosting) + +Once SBOM::CycloneDX is ported to PerlOnJava: +```bash +./jperl dev/tools/generate-perl-sbom.pl > build/reports/sbom/perlonjava-perl.json +``` + +#### Option C: Static JSON Generation + +For initial implementation, generate a static inventory: +```bash +# Create a simple inventory script +perl dev/tools/generate-perl-sbom-simple.pl > build/reports/sbom/perlonjava-perl.json +``` + +### Phase 3: Combined SBOM (Optional) + +Merge Java and Perl SBOMs into a unified document using CycloneDX CLI: + +```bash +# Install CycloneDX CLI +npm install -g @cyclonedx/cyclonedx-cli + +# Merge SBOMs +cyclonedx merge \ + --input-files build/reports/sbom/perlonjava-java.json \ + build/reports/sbom/perlonjava-perl.json \ + --output-file build/reports/sbom/perlonjava-complete.json +``` + +Alternatively, keep them separate: +- `perlonjava-java.json` - Java dependencies (automatically updated by build) +- `perlonjava-perl.json` - Perl modules (manually curated) + +--- + +## CI/CD Integration + +### GitHub Actions + +Add to `.github/workflows/ci.yml`: +```yaml +- name: Generate SBOM + run: ./gradlew cyclonedxBom + +- name: Upload SBOM + uses: actions/upload-artifact@v4 + with: + name: sbom + path: build/reports/sbom/ + retention-days: 90 + +# Optional: Upload to Dependency-Track or similar +- name: Upload to Dependency-Track + if: github.ref == 'refs/heads/master' + run: | + curl -X POST "$DT_URL/api/v1/bom" \ + -H "X-Api-Key: $DT_API_KEY" \ + -H "Content-Type: application/json" \ + -d @build/reports/sbom/perlonjava-java.json +``` + +### Release Artifacts + +Include SBOM in GitHub releases: +```yaml +- name: Create Release + uses: softprops/action-gh-release@v1 + with: + files: | + target/perlonjava-*-all.jar + build/reports/sbom/perlonjava-*.json +``` + +--- + +## SBOM::CycloneDX Module Details + +### Module Information + +- **CPAN:** https://metacpan.org/pod/SBOM::CycloneDX +- **Version:** 1.07 (as of 2026-01-21) +- **Author:** Giuseppe Di Terlizzi (GDT) +- **License:** Artistic-2.0 +- **Perl Version:** v5.16.0+ + +### Dependencies + +Core dependencies required: +- Cpanel::JSON::XS +- JSON::Validator +- List::Util (core) +- Moo +- Type::Tiny +- URI::PackageURL +- UUID::Tiny +- namespace::autoclean + +### Supported CycloneDX Versions + +- 1.7 (latest) +- 1.6 +- 1.5 +- 1.4 +- 1.3 +- 1.2 + +### Key Features + +- Full CycloneDX model support +- Built-in validation against official schemas +- JSON output format +- Support for PURL (Package URL) specification +- VEX (Vulnerability Exploitability eXchange) support +- License expression parsing + +--- + +## Makefile Integration + +Add SBOM generation to the Makefile: +```makefile +.PHONY: sbom sbom-java sbom-perl sbom-clean + +sbom: sbom-java sbom-perl + @echo "SBOM generated in build/reports/sbom/" + +sbom-java: + ./gradlew cyclonedxBom + +sbom-perl: + perl dev/tools/generate-perl-sbom.pl > build/reports/sbom/perlonjava-perl.json + +sbom-clean: + rm -rf build/reports/sbom/ +``` + +--- + +## Verification + +### Validate Generated SBOM + +```bash +# Using CycloneDX CLI +cyclonedx validate --input-file build/reports/sbom/perlonjava-java.json + +# Using online validator +# https://cyclonedx.github.io/sbom-validator/ +``` + +### Check NTIA Minimum Elements + +The generated SBOM must include: +- [x] Supplier name +- [x] Component name +- [x] Component version +- [x] Unique identifier (PURL/CPE) +- [x] Dependency relationship +- [x] Author of SBOM data +- [x] Timestamp + +--- + +## Open Questions + +1. **Perl module licensing:** Should we manually curate licenses for all 511 bundled modules, or use a default? + +2. **Version tracking:** How to handle Perl modules that don't have explicit `$VERSION`? + +3. **Separate vs. merged SBOM:** Should we ship one unified SBOM or separate Java/Perl SBOMs? + +4. **SBOM::CycloneDX porting:** Is it worth porting SBOM::CycloneDX to run under PerlOnJava for self-hosting? + +5. **VEX integration:** Should we include vulnerability status (VEX) in the SBOM? + +--- + +## Progress Tracking + +### Current Status: Phase 0 - Planning + +### Completed Phases +- [x] Phase 0: Research and design document (2026-03-19) + +### Next Steps +1. Add CycloneDX plugin to build.gradle +2. Add CycloneDX plugin to pom.xml +3. Create Perl SBOM generation script +4. Add Makefile targets +5. Add CI/CD workflow +6. Verify SBOM compliance + +### Open Questions to Resolve +- Decide on separate vs. merged SBOM approach +- Determine Perl module version/license extraction strategy + +--- + +## References + +- [CycloneDX Specification](https://cyclonedx.org/specification/overview/) +- [CycloneDX Gradle Plugin](https://github.com/CycloneDX/cyclonedx-gradle-plugin) +- [CycloneDX Maven Plugin](https://github.com/CycloneDX/cyclonedx-maven-plugin) +- [SBOM::CycloneDX Perl Module](https://metacpan.org/pod/SBOM::CycloneDX) +- [CISA SBOM Resources](https://www.cisa.gov/sbom) +- [NTIA SBOM Minimum Elements](https://www.ntia.gov/files/ntia/publications/sbom_minimum_elements_report.pdf) +- [US Executive Order 14028](https://www.whitehouse.gov/briefing-room/presidential-actions/2021/05/12/executive-order-on-improving-the-nations-cybersecurity/) +- [CycloneDX Tool Center](https://cyclonedx.org/tool-center/) From a8fe26c9eb682eb0175acc73d7838317344786c6 Mon Sep 17 00:00:00 2001 From: Flavio Soibelmann Glock Date: Thu, 19 Mar 2026 09:41:49 +0100 Subject: [PATCH 02/11] Add SBOM storage locations section to design document Documents where SBOM files will be stored in: - Build output (build/reports/sbom/ for Gradle, target/ for Maven) - JAR distribution (META-INF/sbom/) - DEB package (/opt/perlonjava/share/sbom/) - GitHub release artifacts (standalone files) Includes configuration snippets for embedding SBOM in JAR and DEB. Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin --- dev/design/sbom.md | 121 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) diff --git a/dev/design/sbom.md b/dev/design/sbom.md index f7b9f668e..479364b79 100644 --- a/dev/design/sbom.md +++ b/dev/design/sbom.md @@ -276,6 +276,127 @@ Alternatively, keep them separate: --- +## SBOM Storage Locations + +### Build Output (Development) + +During build, SBOMs are generated to: + +| Build System | Location | Files | +|--------------|----------|-------| +| Gradle | `build/reports/sbom/` | `bom.json`, `bom.xml` | +| Maven | `target/` | `bom.json`, `bom.xml` | + +### Distribution: JAR File + +SBOMs should be embedded inside the JAR following CycloneDX conventions: + +``` +perlonjava-5.42.0.jar +├── META-INF/ +│ ├── MANIFEST.MF +│ └── sbom/ +│ ├── bom.json # CycloneDX JSON format +│ └── bom.xml # CycloneDX XML format (optional) +└── ... (other contents) +``` + +To include SBOM in JAR, add to `build.gradle`: +```groovy +// Copy SBOM into JAR's META-INF/sbom/ +shadowJar { + from("$buildDir/reports/sbom") { + into 'META-INF/sbom' + include '*.json', '*.xml' + } +} + +// Ensure SBOM is generated before JAR +shadowJar.dependsOn cyclonedxBom +``` + +For Maven, add to `pom.xml`: +```xml + + org.apache.maven.plugins + maven-resources-plugin + + + copy-sbom + package + copy-resources + + ${project.build.outputDirectory}/META-INF/sbom + + + ${project.build.directory} + + bom.json + bom.xml + + + + + + + +``` + +### Distribution: DEB Package + +For Debian packages, SBOMs go in the standard documentation directory: + +``` +/opt/perlonjava/ +├── bin/ +│ └── jperl +├── lib/ +│ └── perlonjava-5.42.0.jar +└── share/ + └── sbom/ + ├── bom.json + └── bom.xml +``` + +Alternative location (Debian convention): +``` +/usr/share/doc/perlonjava/ +├── copyright +├── changelog.gz +└── sbom/ + ├── bom.json + └── bom.xml +``` + +To include in DEB package, update `build.gradle`: +```groovy +ospackage { + // ... existing config ... + + // Include SBOM in package + from("$buildDir/reports/sbom") { + into '/opt/perlonjava/share/sbom' + include '*.json', '*.xml' + } +} +``` + +### GitHub Release Artifacts + +SBOMs should also be attached as separate release artifacts: + +``` +Release v5.42.0 +├── perlonjava-5.42.0.jar +├── perlonjava_5.42.0_amd64.deb +├── perlonjava-5.42.0-sbom.json # Standalone SBOM +└── perlonjava-5.42.0-sbom.xml # Standalone SBOM (XML) +``` + +This allows consumers to inspect the SBOM without downloading/extracting the full package. + +--- + ## CI/CD Integration ### GitHub Actions From 55a970e65a2ea7e54b36baedb7d1e2544d71771e Mon Sep 17 00:00:00 2001 From: Flavio Soibelmann Glock Date: Thu, 19 Mar 2026 09:45:27 +0100 Subject: [PATCH 03/11] Add component hashes section to SBOM design document Documents hash support in CycloneDX: - Supported algorithms: MD5, SHA-1, SHA-256, SHA-384/512, SHA3-*, BLAKE2b/3 - Java dependencies: hashes are automatically included by plugins - Perl modules: need manual SHA-256 computation using Digest::SHA - Hash verification enables integrity checking Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin --- dev/design/sbom.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/dev/design/sbom.md b/dev/design/sbom.md index 479364b79..ef0fb1037 100644 --- a/dev/design/sbom.md +++ b/dev/design/sbom.md @@ -525,6 +525,84 @@ The generated SBOM must include: --- +## Component Hashes + +### Supported Hash Algorithms + +CycloneDX supports these hash algorithms: +- **MD5** (legacy, included for compatibility) +- **SHA-1** (legacy, included for compatibility) +- **SHA-256** (recommended) +- **SHA-384**, **SHA-512** +- **SHA3-256**, **SHA3-384**, **SHA3-512** +- **BLAKE2b-256**, **BLAKE2b-384**, **BLAKE2b-512** +- **BLAKE3** + +### Java Dependencies (Automatic) + +The CycloneDX Gradle and Maven plugins **automatically include hashes** for all dependencies: + +1. Hashes are retrieved from Maven Central repository metadata +2. SHA-256 is computed from downloaded artifacts +3. Multiple hash algorithms are included (MD5, SHA-1, SHA-256) + +Example output: +```json +{ + "type": "library", + "name": "asm", + "version": "9.9.1", + "group": "org.ow2.asm", + "purl": "pkg:maven/org.ow2.asm/asm@9.9.1", + "hashes": [ + {"alg": "MD5", "content": "..."}, + {"alg": "SHA-1", "content": "..."}, + {"alg": "SHA-256", "content": "..."} + ] +} +``` + +**No additional configuration needed** - hashes are included by default. + +### Perl Modules (Manual) + +For bundled Perl modules, hashes must be computed manually. Update the SBOM generation script: + +```perl +use Digest::SHA qw(sha256_hex); +use SBOM::CycloneDX::Hash; + +sub compute_hash { + my ($path) = @_; + open my $fh, '<:raw', $path or return; + local $/; + my $content = <$fh>; + close $fh; + return sha256_hex($content); +} + +# When creating component: +my $hash = SBOM::CycloneDX::Hash->new( + alg => 'SHA-256', + content => compute_hash($path) +); +$component->hashes->add($hash); +``` + +### Hash Verification + +Consumers can verify component integrity by: +1. Downloading the component from its source (PURL) +2. Computing the hash locally +3. Comparing with the hash in the SBOM + +This enables detection of: +- Tampered dependencies +- Man-in-the-middle attacks +- Compromised build artifacts + +--- + ## Open Questions 1. **Perl module licensing:** Should we manually curate licenses for all 511 bundled modules, or use a default? From bb3f1a997dcd0d5508affccb63a425bd9c99e983 Mon Sep 17 00:00:00 2001 From: Flavio Soibelmann Glock Date: Thu, 19 Mar 2026 09:46:46 +0100 Subject: [PATCH 04/11] Clarify hash strategy for shaded JAR distribution PerlOnJava ships as a single uber JAR with all dependencies shaded in. Updated hash strategy: - Java deps: automatic per-component hashes (pre-shading artifacts) - Perl modules: skip individual hashes (version/license sufficient) - Distribution: single .sha256 file alongside JAR/DEB releases This simplifies the Perl SBOM generation - no need to compute 511 individual hashes for bundled modules. Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin --- dev/design/sbom.md | 101 +++++++++++++++++++++++++-------------------- 1 file changed, 56 insertions(+), 45 deletions(-) diff --git a/dev/design/sbom.md b/dev/design/sbom.md index ef0fb1037..aa6a9b7a1 100644 --- a/dev/design/sbom.md +++ b/dev/design/sbom.md @@ -527,32 +527,32 @@ The generated SBOM must include: ## Component Hashes -### Supported Hash Algorithms +### PerlOnJava Distribution Model -CycloneDX supports these hash algorithms: -- **MD5** (legacy, included for compatibility) -- **SHA-1** (legacy, included for compatibility) -- **SHA-256** (recommended) -- **SHA-384**, **SHA-512** -- **SHA3-256**, **SHA3-384**, **SHA3-512** -- **BLAKE2b-256**, **BLAKE2b-384**, **BLAKE2b-512** -- **BLAKE3** +PerlOnJava ships as a **shaded/uber JAR** containing everything: +``` +perlonjava-5.42.0.jar +├── org/perlonjava/... (PerlOnJava Java classes) +├── org/ow2/asm/... (shaded ASM library) +├── com/ibm/icu/... (shaded ICU4J library) +├── lib/*.pm (511 bundled Perl modules) +└── META-INF/sbom/bom.json (embedded SBOM) +``` -### Java Dependencies (Automatic) +### Hash Strategy -The CycloneDX Gradle and Maven plugins **automatically include hashes** for all dependencies: +#### 1. Java Dependencies → **Automatic (per-component)** -1. Hashes are retrieved from Maven Central repository metadata -2. SHA-256 is computed from downloaded artifacts -3. Multiple hash algorithms are included (MD5, SHA-1, SHA-256) +The CycloneDX plugins automatically include hashes for Java dependencies: +- These are hashes of the **original Maven artifacts** (before shading) +- Used to identify exact versions and match against CVE databases +- Hashes are retrieved from Maven Central metadata -Example output: ```json { "type": "library", "name": "asm", "version": "9.9.1", - "group": "org.ow2.asm", "purl": "pkg:maven/org.ow2.asm/asm@9.9.1", "hashes": [ {"alg": "MD5", "content": "..."}, @@ -562,44 +562,55 @@ Example output: } ``` -**No additional configuration needed** - hashes are included by default. +#### 2. Perl Modules → **Optional (skip individual hashes)** -### Perl Modules (Manual) +For the 511 bundled Perl modules, individual hashes are **not required** because: +- They are internal bundled files, not external dependencies +- No CPAN hash database exists for vulnerability matching +- Version tracking via `$VERSION` is sufficient for identification -For bundled Perl modules, hashes must be computed manually. Update the SBOM generation script: +The Perl SBOM should include: +- Module name and version +- License information +- PURL (e.g., `pkg:cpan/Test::More@1.302195`) +- **Hashes: omitted** (or optionally included for strict compliance) -```perl -use Digest::SHA qw(sha256_hex); -use SBOM::CycloneDX::Hash; +#### 3. Distribution Artifacts → **Single hash file** -sub compute_hash { - my ($path) = @_; - open my $fh, '<:raw', $path or return; - local $/; - my $content = <$fh>; - close $fh; - return sha256_hex($content); -} +The final distribution artifacts should have accompanying hash files: -# When creating component: -my $hash = SBOM::CycloneDX::Hash->new( - alg => 'SHA-256', - content => compute_hash($path) -); -$component->hashes->add($hash); +``` +Release v5.42.0/ +├── perlonjava-5.42.0.jar +├── perlonjava-5.42.0.jar.sha256 # echo "abc123... perlonjava-5.42.0.jar" +├── perlonjava_5.42.0_amd64.deb +├── perlonjava_5.42.0_amd64.deb.sha256 +└── perlonjava-5.42.0-sbom.json # SBOM (contains component hashes) ``` -### Hash Verification +Generate with: +```bash +sha256sum perlonjava-5.42.0.jar > perlonjava-5.42.0.jar.sha256 +``` + +### Supported Hash Algorithms + +CycloneDX supports: +- **MD5**, **SHA-1** (legacy, for compatibility) +- **SHA-256** (recommended) +- **SHA-384**, **SHA-512** +- **SHA3-256**, **SHA3-384**, **SHA3-512** +- **BLAKE2b-256**, **BLAKE2b-384**, **BLAKE2b-512** +- **BLAKE3** -Consumers can verify component integrity by: -1. Downloading the component from its source (PURL) -2. Computing the hash locally -3. Comparing with the hash in the SBOM +### Summary -This enables detection of: -- Tampered dependencies -- Man-in-the-middle attacks -- Compromised build artifacts +| What | Individual Hashes? | Notes | +|------|-------------------|-------| +| Java dependencies | ✅ Yes (automatic) | Pre-shading artifact hashes from Maven Central | +| Perl modules | ❌ No (optional) | Version/license is sufficient | +| Final JAR | ✅ Yes (single file) | `.sha256` file alongside release | +| Final DEB | ✅ Yes (single file) | `.sha256` file alongside release | --- From 220769ed6362c56742e81ce2bec761b2b4b385d7 Mon Sep 17 00:00:00 2001 From: Flavio Soibelmann Glock Date: Thu, 19 Mar 2026 09:48:49 +0100 Subject: [PATCH 05/11] Remove author line from SBOM design document Attribution is tracked in git history. Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin --- dev/design/sbom.md | 1 - 1 file changed, 1 deletion(-) diff --git a/dev/design/sbom.md b/dev/design/sbom.md index aa6a9b7a1..60c4aeff1 100644 --- a/dev/design/sbom.md +++ b/dev/design/sbom.md @@ -2,7 +2,6 @@ ## Status: Planned -**Author:** Devin AI **Date:** 2026-03-19 **Related:** US Executive Order 14028, CISA SBOM Guidelines, CycloneDX ECMA-424 From fa5fd47b68c836eba7324c6c10b56ee4e92ee90c Mon Sep 17 00:00:00 2001 From: Flavio Soibelmann Glock Date: Thu, 19 Mar 2026 09:57:07 +0100 Subject: [PATCH 06/11] Review and improve SBOM design document for accuracy and clarity Accuracy fixes: - Correct Gradle version catalog plugin syntax - Fix output paths to match actual CycloneDX defaults (build/reports/cyclonedx/) - Remove biased claim about SPDX tooling maturity - Fix "re-implemented" claim for Perl pragmas - Remove hallucinated version date for SBOM::CycloneDX - Correct claim about CPAN checksums Clarity improvements: - Add glossary explaining SBOM, CycloneDX, PURL, VEX, shaded JAR, Maven Central, CPAN - Better explain "why SBOM matters" with concrete use cases - Simplify Phase 2 options to single recommended approach - Add context for both Java and Perl developers - Improve code examples with comments Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin --- dev/design/sbom.md | 255 +++++++++++++++++++++------------------------ 1 file changed, 119 insertions(+), 136 deletions(-) diff --git a/dev/design/sbom.md b/dev/design/sbom.md index 60c4aeff1..c02ab85f9 100644 --- a/dev/design/sbom.md +++ b/dev/design/sbom.md @@ -17,29 +17,50 @@ The goal is to produce a unified or complementary SBOM that documents the comple --- +## Glossary + +| Term | Definition | +|------|------------| +| **SBOM** | Software Bill of Materials - a formal inventory of software components | +| **CycloneDX** | An OWASP standard for SBOM format (JSON/XML), now ECMA-424 | +| **SPDX** | Alternative SBOM standard from Linux Foundation, focused on licensing | +| **PURL** | Package URL - a standard format for identifying software packages (e.g., `pkg:maven/org.ow2.asm/asm@9.9.1`) | +| **VEX** | Vulnerability Exploitability eXchange - documents whether vulnerabilities affect a product | +| **Shaded/Uber JAR** | A JAR file that bundles all dependencies into a single archive | +| **Maven Central** | The primary repository for Java libraries (like CPAN for Perl) | +| **CPAN** | Comprehensive Perl Archive Network - the primary repository for Perl modules | + +--- + ## Background ### What is SBOM? -A **Software Bill of Materials (SBOM)** is a nested inventory - a list of ingredients that make up software components. SBOMs are increasingly required for: +A **Software Bill of Materials (SBOM)** is a formal, machine-readable inventory of all components in a software product. Think of it as a "ingredients list" for software. +**Why it matters:** +- **Security teams** can quickly check if a product contains vulnerable components +- **Legal/compliance teams** can verify license obligations +- **Procurement** can assess supply chain risk before adoption + +SBOMs are increasingly required for: - **US Government contracts** (Executive Order 14028, May 2021) - **Supply chain security** and vulnerability management - **License compliance** tracking - **Security auditing** and incident response -- **Regulatory compliance** (FDA, EU Cyber Resilience Act) +- **Regulatory compliance** (FDA for medical devices, EU Cyber Resilience Act) -### CycloneDX Standard +### Why CycloneDX? **CycloneDX** is the recommended SBOM standard for PerlOnJava because: 1. **Security-focused** - Designed by OWASP for application security contexts 2. **Lightweight** - Simple JSON/XML format, easy to generate and consume -3. **Well-supported** - Extensive tooling for Java (Gradle, Maven) and Perl -4. **Standardized** - ECMA-424 international standard -5. **Comprehensive** - Supports dependencies, licenses, vulnerabilities (VEX) +3. **Well-supported** - Mature plugins for Gradle, Maven; Perl library available on CPAN +4. **Standardized** - ECMA-424 international standard (December 2024) +5. **Comprehensive** - Supports dependencies, licenses, and vulnerability status (VEX) -Alternative: **SPDX** (Linux Foundation) is more focused on license compliance but has less mature Java tooling. +**Alternative:** SPDX (Linux Foundation) is another respected standard, more focused on license compliance. Both have good tooling; CycloneDX is chosen here for its security focus and simpler format. --- @@ -47,9 +68,11 @@ Alternative: **SPDX** (Linux Foundation) is more focused on license compliance b ### Java Dependencies (from pom.xml / build.gradle) +These are external libraries downloaded from Maven Central during build: + | Dependency | Version | License | Purpose | |------------|---------|---------|---------| -| org.ow2.asm:asm | 9.9.1 | BSD-3-Clause | Bytecode manipulation | +| org.ow2.asm:asm | 9.9.1 | BSD-3-Clause | JVM bytecode generation | | org.ow2.asm:asm-util | 9.9.1 | BSD-3-Clause | ASM utilities | | com.ibm.icu:icu4j | 78.2 | ICU License | Unicode support | | com.alibaba.fastjson2:fastjson2 | 2.0.61 | Apache-2.0 | JSON processing | @@ -58,20 +81,20 @@ Alternative: **SPDX** (Linux Foundation) is more focused on license compliance b | org.apache.commons:commons-csv | 1.14.1 | Apache-2.0 | CSV processing | | com.github.jnr:jnr-posix | 3.1.19 | LGPL-2.1+ | Native POSIX access | -Test dependencies (not in runtime SBOM): +Test dependencies (excluded from runtime SBOM): - org.junit.jupiter (JUnit 5) - test scope only ### Bundled Perl Modules (511 files in src/main/perl/lib/) -Categories of bundled Perl modules: +These are Perl modules bundled with PerlOnJava to provide standard library functionality: | Category | Examples | License | Notes | |----------|----------|---------|-------| -| Core modules | strict.pm, warnings.pm | Perl Artistic-2.0 | Re-implemented for PerlOnJava | -| CPAN modules | CPAN.pm, CPAN::Meta | Various | Ported from CPAN | -| Pod modules | Pod::Text, Pod::Man | GPL-1.0+ OR Artistic-1.0 | Documentation tools | -| Test modules | Test::More, Test::Builder | Perl Artistic-2.0 | Testing infrastructure | -| Utility modules | File::Spec, Cwd | Perl Artistic-2.0 | Standard utilities | +| Pragmas | strict.pm, warnings.pm | Perl Artistic-2.0 | Compile-time behavior controls | +| CPAN client | CPAN.pm, CPAN::Meta | Various | Module installation tools | +| Pod modules | Pod::Text, Pod::Man | GPL-1.0+ OR Artistic-1.0 | Documentation processing | +| Test modules | Test::More, Test::Builder | Perl Artistic-2.0 | Testing framework | +| Utility modules | File::Spec, Cwd | Perl Artistic-2.0 | Cross-platform utilities | --- @@ -79,40 +102,34 @@ Categories of bundled Perl modules: ### Phase 1: Java SBOM Generation -Add CycloneDX plugins to both Gradle and Maven builds. +Add CycloneDX plugins to both Gradle and Maven builds. These plugins automatically scan dependencies and generate compliant SBOMs. #### Gradle Configuration Add to `gradle/libs.versions.toml`: ```toml [plugins] -cyclonedx = "org.cyclonedx.bom:3.2.2" +cyclonedx = { id = "org.cyclonedx.bom", version = "3.2.2" } ``` Add to `build.gradle`: ```groovy plugins { - id 'org.cyclonedx.bom' version '3.2.2' + id 'org.cyclonedx.bom' } -// Configure CycloneDX -tasks.cyclonedxBom { +// Configure CycloneDX (optional - defaults are sensible) +cyclonedxBom { projectType = "application" schemaVersion = "1.6" includeLicenseText = false includeBomSerialNumber = true - includeBuildSystem = true - - // Output configuration - destination = file("$buildDir/reports/sbom") - outputName = "perlonjava-java" - outputFormat = "all" // json and xml // Component metadata componentName = "perlonjava" componentVersion = project.version - // Organization metadata + // Organization metadata organizationalEntity { name = "PerlOnJava Project" urls = ["https://github.com/fglock/PerlOnJava"] @@ -120,9 +137,13 @@ tasks.cyclonedxBom { } ``` +Run with: `./gradlew cyclonedxBom` + +**Output:** `build/reports/cyclonedx/bom.json` and `bom.xml` + #### Maven Configuration -Add to `pom.xml`: +Add to `pom.xml` in the `` section: ```xml org.cyclonedx @@ -142,96 +163,92 @@ Add to `pom.xml`: true false all - perlonjava-java + bom ``` -**Output:** `build/reports/sbom/perlonjava-java.json` (Gradle) or `target/perlonjava-java.json` (Maven) +Run with: `mvn package` (SBOM generated automatically) or `mvn cyclonedx:makeAggregateBom` + +**Output:** `target/bom.json` and `bom.xml` ### Phase 2: Perl SBOM Generation -Use **SBOM::CycloneDX** (v1.07) to generate SBOM for bundled Perl modules. +Generate SBOM for the 511 bundled Perl modules. Since these aren't downloaded from a package manager, we need a custom approach. -#### Option A: Use Native Perl (if available) +**Recommended approach:** Use native Perl with the `SBOM::CycloneDX` module from CPAN. + +#### Prerequisites ```bash -# Install SBOM::CycloneDX +# Install from CPAN (requires native Perl) cpanm SBOM::CycloneDX ``` +#### Generation Script + Create `dev/tools/generate-perl-sbom.pl`: ```perl #!/usr/bin/env perl use strict; use warnings; use SBOM::CycloneDX; -use SBOM::CycloneDX::Enum qw(COMPONENT_TYPE); +use SBOM::CycloneDX::Component; +use SBOM::CycloneDX::License; +use SBOM::CycloneDX::Enum qw(:component_type); use File::Find; -use JSON::PP; -my $bom = SBOM::CycloneDX->new; +my $bom = SBOM::CycloneDX->new(spec_version => '1.6'); -# Root component +# Define the root component (PerlOnJava itself) my $root = SBOM::CycloneDX::Component->new( - type => COMPONENT_TYPE->APPLICATION, + type => COMPONENT_TYPE_APPLICATION, name => 'perlonjava-perl-modules', - version => '5.42.0', - licenses => [SBOM::CycloneDX::License->new('Artistic-2.0')], + version => $ENV{VERSION} // '5.42.0', + licenses => [SBOM::CycloneDX::License->new(id => 'Artistic-2.0')], bom_ref => 'perlonjava-perl' ); $bom->metadata->component($root); -$bom->metadata->tools->add(SBOM::CycloneDX::cyclonedx_tool()); -# Scan Perl modules -my @modules; +# Scan and add all Perl modules find(sub { return unless /\.pm$/; my $path = $File::Find::name; + + # Convert path to module name: lib/Foo/Bar.pm -> Foo::Bar my $module = $path; $module =~ s{.*/lib/}{}; $module =~ s{/}{::}g; $module =~ s{\.pm$}{}; - # Extract version from module if available - my $version = extract_version($path); + # Try to extract version from module + my $version = extract_version($path) // 'bundled'; - push @modules, { - name => $module, - version => $version // 'bundled', - path => $path, - }; -}, 'src/main/perl/lib'); - -# Add components -for my $mod (@modules) { my $component = SBOM::CycloneDX::Component->new( - type => COMPONENT_TYPE->LIBRARY, - name => $mod->{name}, - version => $mod->{version}, - bom_ref => "perl:$mod->{name}", - purl => URI::PackageURL->new( - type => 'cpan', - name => $mod->{name}, - version => $mod->{version}, - ), + type => COMPONENT_TYPE_LIBRARY, + name => $module, + version => $version, + bom_ref => "perl:$module", ); + $bom->components->add($component); - $bom->add_dependency($root, [$component]); -} + $bom->dependencies->add($root->bom_ref, $component->bom_ref); + +}, 'src/main/perl/lib'); # Validate and output my @errors = $bom->validate; -die "Validation errors: @errors" if @errors; +die "SBOM validation failed: @errors\n" if @errors; -print $bom->to_string; +print $bom->to_json; sub extract_version { my ($path) = @_; open my $fh, '<', $path or return; while (<$fh>) { - if (/(?:our\s+)?\$VERSION\s*=\s*['"]?([0-9._]+)/) { + # Match: our $VERSION = '1.23'; or $VERSION = "1.23"; + if (/\$VERSION\s*=\s*['"]?([0-9][0-9._]*)/) { return $1; } } @@ -239,20 +256,14 @@ sub extract_version { } ``` -#### Option B: Use PerlOnJava (self-hosting) - -Once SBOM::CycloneDX is ported to PerlOnJava: +Run with: ```bash -./jperl dev/tools/generate-perl-sbom.pl > build/reports/sbom/perlonjava-perl.json +perl dev/tools/generate-perl-sbom.pl > build/reports/cyclonedx/perl-bom.json ``` -#### Option C: Static JSON Generation +#### Alternative: Simpler Static Approach -For initial implementation, generate a static inventory: -```bash -# Create a simple inventory script -perl dev/tools/generate-perl-sbom-simple.pl > build/reports/sbom/perlonjava-perl.json -``` +If `SBOM::CycloneDX` dependencies are problematic, generate a minimal compliant SBOM using core Perl modules only. See `dev/tools/generate-perl-sbom-simple.pl` (to be created). ### Phase 3: Combined SBOM (Optional) @@ -283,20 +294,20 @@ During build, SBOMs are generated to: | Build System | Location | Files | |--------------|----------|-------| -| Gradle | `build/reports/sbom/` | `bom.json`, `bom.xml` | +| Gradle | `build/reports/cyclonedx/` | `bom.json`, `bom.xml` | | Maven | `target/` | `bom.json`, `bom.xml` | +| Perl script | `build/reports/cyclonedx/` | `perl-bom.json` | ### Distribution: JAR File -SBOMs should be embedded inside the JAR following CycloneDX conventions: +SBOMs can be embedded inside the JAR for easy discovery: ``` perlonjava-5.42.0.jar ├── META-INF/ │ ├── MANIFEST.MF │ └── sbom/ -│ ├── bom.json # CycloneDX JSON format -│ └── bom.xml # CycloneDX XML format (optional) +│ └── bom.json # CycloneDX JSON format └── ... (other contents) ``` @@ -304,9 +315,9 @@ To include SBOM in JAR, add to `build.gradle`: ```groovy // Copy SBOM into JAR's META-INF/sbom/ shadowJar { - from("$buildDir/reports/sbom") { + from("$buildDir/reports/cyclonedx") { into 'META-INF/sbom' - include '*.json', '*.xml' + include 'bom.json' } } @@ -314,32 +325,7 @@ shadowJar { shadowJar.dependsOn cyclonedxBom ``` -For Maven, add to `pom.xml`: -```xml - - org.apache.maven.plugins - maven-resources-plugin - - - copy-sbom - package - copy-resources - - ${project.build.outputDirectory}/META-INF/sbom - - - ${project.build.directory} - - bom.json - bom.xml - - - - - - - -``` +For Maven, the shade plugin can include the SBOM automatically if it's in the resources directory during build. ### Distribution: DEB Package @@ -373,9 +359,9 @@ ospackage { // ... existing config ... // Include SBOM in package - from("$buildDir/reports/sbom") { + from("$buildDir/reports/cyclonedx") { into '/opt/perlonjava/share/sbom' - include '*.json', '*.xml' + include 'bom.json' } } ``` @@ -436,27 +422,24 @@ Include SBOM in GitHub releases: --- -## SBOM::CycloneDX Module Details +## SBOM::CycloneDX Perl Module + +The `SBOM::CycloneDX` module on CPAN provides a full implementation of the CycloneDX specification for Perl. ### Module Information - **CPAN:** https://metacpan.org/pod/SBOM::CycloneDX -- **Version:** 1.07 (as of 2026-01-21) -- **Author:** Giuseppe Di Terlizzi (GDT) - **License:** Artistic-2.0 -- **Perl Version:** v5.16.0+ +- **Minimum Perl:** v5.16.0 -### Dependencies +### Key Dependencies -Core dependencies required: -- Cpanel::JSON::XS -- JSON::Validator -- List::Util (core) -- Moo -- Type::Tiny -- URI::PackageURL -- UUID::Tiny -- namespace::autoclean +- Cpanel::JSON::XS (fast JSON encoding) +- JSON::Validator (schema validation) +- Moo (object system) +- Type::Tiny (type constraints) +- URI::PackageURL (PURL support) +- UUID::Tiny (serial number generation) ### Supported CycloneDX Versions @@ -485,16 +468,17 @@ Add SBOM generation to the Makefile: .PHONY: sbom sbom-java sbom-perl sbom-clean sbom: sbom-java sbom-perl - @echo "SBOM generated in build/reports/sbom/" + @echo "SBOM generated in build/reports/cyclonedx/" sbom-java: ./gradlew cyclonedxBom sbom-perl: - perl dev/tools/generate-perl-sbom.pl > build/reports/sbom/perlonjava-perl.json + @mkdir -p build/reports/cyclonedx + perl dev/tools/generate-perl-sbom.pl > build/reports/cyclonedx/perl-bom.json sbom-clean: - rm -rf build/reports/sbom/ + rm -rf build/reports/cyclonedx/ ``` --- @@ -504,8 +488,8 @@ sbom-clean: ### Validate Generated SBOM ```bash -# Using CycloneDX CLI -cyclonedx validate --input-file build/reports/sbom/perlonjava-java.json +# Using CycloneDX CLI (install via npm: npm install -g @cyclonedx/cyclonedx-cli) +cyclonedx validate --input-file build/reports/cyclonedx/bom.json # Using online validator # https://cyclonedx.github.io/sbom-validator/ @@ -564,15 +548,14 @@ The CycloneDX plugins automatically include hashes for Java dependencies: #### 2. Perl Modules → **Optional (skip individual hashes)** For the 511 bundled Perl modules, individual hashes are **not required** because: -- They are internal bundled files, not external dependencies -- No CPAN hash database exists for vulnerability matching +- They are bundled source files, not downloaded artifacts +- CPAN does publish checksums, but there's no standard vulnerability database keyed by hash - Version tracking via `$VERSION` is sufficient for identification The Perl SBOM should include: - Module name and version -- License information -- PURL (e.g., `pkg:cpan/Test::More@1.302195`) -- **Hashes: omitted** (or optionally included for strict compliance) +- License information (where known) +- **Hashes: omitted** (simplifies generation; can be added later if needed) #### 3. Distribution Artifacts → **Single hash file** From b55f1ddc31a4f60bb79a2b07b7cd4ce8129c753b Mon Sep 17 00:00:00 2001 From: Flavio Soibelmann Glock Date: Thu, 19 Mar 2026 10:00:15 +0100 Subject: [PATCH 07/11] Fix remaining path inconsistencies in SBOM design document - Update Phase 3 merge example to use correct paths - Update CI/CD section to use build/reports/cyclonedx/ - Remove speculative Dependency-Track integration (can be added later) - Simplify release artifacts example Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin --- dev/design/sbom.md | 23 +++++++---------------- 1 file changed, 7 insertions(+), 16 deletions(-) diff --git a/dev/design/sbom.md b/dev/design/sbom.md index c02ab85f9..8d47a8c33 100644 --- a/dev/design/sbom.md +++ b/dev/design/sbom.md @@ -275,14 +275,14 @@ npm install -g @cyclonedx/cyclonedx-cli # Merge SBOMs cyclonedx merge \ - --input-files build/reports/sbom/perlonjava-java.json \ - build/reports/sbom/perlonjava-perl.json \ - --output-file build/reports/sbom/perlonjava-complete.json + --input-files build/reports/cyclonedx/bom.json \ + build/reports/cyclonedx/perl-bom.json \ + --output-file build/reports/cyclonedx/combined-bom.json ``` Alternatively, keep them separate: -- `perlonjava-java.json` - Java dependencies (automatically updated by build) -- `perlonjava-perl.json` - Perl modules (manually curated) +- `bom.json` - Java dependencies (automatically updated by build) +- `perl-bom.json` - Perl modules (generated separately) --- @@ -395,17 +395,8 @@ Add to `.github/workflows/ci.yml`: uses: actions/upload-artifact@v4 with: name: sbom - path: build/reports/sbom/ + path: build/reports/cyclonedx/ retention-days: 90 - -# Optional: Upload to Dependency-Track or similar -- name: Upload to Dependency-Track - if: github.ref == 'refs/heads/master' - run: | - curl -X POST "$DT_URL/api/v1/bom" \ - -H "X-Api-Key: $DT_API_KEY" \ - -H "Content-Type: application/json" \ - -d @build/reports/sbom/perlonjava-java.json ``` ### Release Artifacts @@ -417,7 +408,7 @@ Include SBOM in GitHub releases: with: files: | target/perlonjava-*-all.jar - build/reports/sbom/perlonjava-*.json + build/reports/cyclonedx/bom.json ``` --- From 42f88248b38fe1e7b8182accf850136d11bd5fa6 Mon Sep 17 00:00:00 2001 From: Flavio Soibelmann Glock Date: Thu, 19 Mar 2026 10:02:10 +0100 Subject: [PATCH 08/11] Expand references section with categorized links - Add SBOM standards: ECMA-424, SPDX, PURL, VEX specs - Add CycloneDX tooling: CLI, online validator - Add Java/Perl resources: Maven Central, CPAN - Add EU Cyber Resilience Act - Add inline links to glossary terms Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin --- dev/design/sbom.md | 42 ++++++++++++++++++++++++++++++------------ 1 file changed, 30 insertions(+), 12 deletions(-) diff --git a/dev/design/sbom.md b/dev/design/sbom.md index 8d47a8c33..ad4a4a84e 100644 --- a/dev/design/sbom.md +++ b/dev/design/sbom.md @@ -22,13 +22,13 @@ The goal is to produce a unified or complementary SBOM that documents the comple | Term | Definition | |------|------------| | **SBOM** | Software Bill of Materials - a formal inventory of software components | -| **CycloneDX** | An OWASP standard for SBOM format (JSON/XML), now ECMA-424 | -| **SPDX** | Alternative SBOM standard from Linux Foundation, focused on licensing | -| **PURL** | Package URL - a standard format for identifying software packages (e.g., `pkg:maven/org.ow2.asm/asm@9.9.1`) | -| **VEX** | Vulnerability Exploitability eXchange - documents whether vulnerabilities affect a product | +| **[CycloneDX](https://cyclonedx.org/)** | An OWASP standard for SBOM format (JSON/XML), now ECMA-424 | +| **[SPDX](https://spdx.dev/)** | Alternative SBOM standard from Linux Foundation, focused on licensing | +| **[PURL](https://github.com/package-url/purl-spec)** | Package URL - a standard format for identifying software packages (e.g., `pkg:maven/org.ow2.asm/asm@9.9.1`) | +| **[VEX](https://cyclonedx.org/capabilities/vex/)** | Vulnerability Exploitability eXchange - documents whether vulnerabilities affect a product | | **Shaded/Uber JAR** | A JAR file that bundles all dependencies into a single archive | -| **Maven Central** | The primary repository for Java libraries (like CPAN for Perl) | -| **CPAN** | Comprehensive Perl Archive Network - the primary repository for Perl modules | +| **[Maven Central](https://central.sonatype.com/)** | The primary repository for Java libraries (like CPAN for Perl) | +| **[CPAN](https://metacpan.org/)** | Comprehensive Perl Archive Network - the primary repository for Perl modules | --- @@ -624,11 +624,29 @@ CycloneDX supports: ## References -- [CycloneDX Specification](https://cyclonedx.org/specification/overview/) +### SBOM Standards +- [CycloneDX Specification](https://cyclonedx.org/specification/overview/) - OWASP SBOM standard +- [CycloneDX ECMA-424](https://ecma-international.org/publications-and-standards/standards/ecma-424/) - International standard (Dec 2024) +- [SPDX Specification](https://spdx.dev/specifications/) - Linux Foundation SBOM standard +- [PURL Specification](https://github.com/package-url/purl-spec) - Package URL format +- [VEX Specification](https://cyclonedx.org/capabilities/vex/) - Vulnerability Exploitability eXchange + +### CycloneDX Tooling - [CycloneDX Gradle Plugin](https://github.com/CycloneDX/cyclonedx-gradle-plugin) - [CycloneDX Maven Plugin](https://github.com/CycloneDX/cyclonedx-maven-plugin) -- [SBOM::CycloneDX Perl Module](https://metacpan.org/pod/SBOM::CycloneDX) -- [CISA SBOM Resources](https://www.cisa.gov/sbom) -- [NTIA SBOM Minimum Elements](https://www.ntia.gov/files/ntia/publications/sbom_minimum_elements_report.pdf) -- [US Executive Order 14028](https://www.whitehouse.gov/briefing-room/presidential-actions/2021/05/12/executive-order-on-improving-the-nations-cybersecurity/) -- [CycloneDX Tool Center](https://cyclonedx.org/tool-center/) +- [CycloneDX CLI](https://github.com/CycloneDX/cyclonedx-cli) - Merge, validate, convert SBOMs +- [CycloneDX Tool Center](https://cyclonedx.org/tool-center/) - Full list of tools +- [CycloneDX Online Validator](https://cyclonedx.github.io/sbom-validator/) + +### Perl Resources +- [SBOM::CycloneDX on CPAN](https://metacpan.org/pod/SBOM::CycloneDX) +- [CPAN](https://metacpan.org/) - Comprehensive Perl Archive Network + +### Java Resources +- [Maven Central](https://central.sonatype.com/) - Primary Java package repository + +### Regulatory & Government +- [US Executive Order 14028](https://www.whitehouse.gov/briefing-room/presidential-actions/2021/05/12/executive-order-on-improving-the-nations-cybersecurity/) - Improving the Nation's Cybersecurity (May 2021) +- [CISA SBOM Resources](https://www.cisa.gov/sbom) - US guidance and tools +- [NTIA SBOM Minimum Elements](https://www.ntia.gov/files/ntia/publications/sbom_minimum_elements_report.pdf) - Required fields +- [EU Cyber Resilience Act](https://digital-strategy.ec.europa.eu/en/policies/cyber-resilience-act) - European regulation From 91a92157c14c9099adf98d36a6c69d5a4d4be2ab Mon Sep 17 00:00:00 2001 From: Flavio Soibelmann Glock Date: Thu, 19 Mar 2026 10:02:44 +0100 Subject: [PATCH 09/11] Add CPAN Security Advisory Database to references Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin --- dev/design/sbom.md | 1 + 1 file changed, 1 insertion(+) diff --git a/dev/design/sbom.md b/dev/design/sbom.md index ad4a4a84e..4c6898bca 100644 --- a/dev/design/sbom.md +++ b/dev/design/sbom.md @@ -641,6 +641,7 @@ CycloneDX supports: ### Perl Resources - [SBOM::CycloneDX on CPAN](https://metacpan.org/pod/SBOM::CycloneDX) - [CPAN](https://metacpan.org/) - Comprehensive Perl Archive Network +- [CPAN Security Advisory Database](https://security.metacpan.org/) - Vulnerability database for Perl modules ### Java Resources - [Maven Central](https://central.sonatype.com/) - Primary Java package repository From 186889ff65cdd223b5e838684c67953b7ab04a49 Mon Sep 17 00:00:00 2001 From: Flavio Soibelmann Glock Date: Thu, 19 Mar 2026 10:05:55 +0100 Subject: [PATCH 10/11] Add CPAN Security Group (CPANSec) section - Document CPANSec as the CVE Numbering Authority for Perl/CPAN - Add cpansa-feed for machine-readable security advisories - Add perl-SBOM-Examples for SBOM best practices - Document integration opportunity for vulnerability checking - Expand Perl Resources in references section Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin --- dev/design/sbom.md | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/dev/design/sbom.md b/dev/design/sbom.md index 4c6898bca..da18eaaea 100644 --- a/dev/design/sbom.md +++ b/dev/design/sbom.md @@ -452,6 +452,44 @@ The `SBOM::CycloneDX` module on CPAN provides a full implementation of the Cyclo --- +## CPAN Security Group (CPANSec) + +The [CPAN Security Group](https://security.metacpan.org/) is a community effort for supporting and responding to security incidents in the Perl/CPAN ecosystem. + +### Why CPANSec Matters for SBOM + +1. **CVE Numbering Authority (CNA)**: As of February 2025, CPANSec is the official [CVE Numbering Authority](https://www.cve.org/PartnerInformation/ListofPartners) for Perl and CPAN. This means: + - All CPAN-related CVEs go through CPANSec + - Vulnerability IDs in SBOMs can be traced to authoritative sources + - Security advisories are coordinated through proper channels + +2. **CPANSA Feed**: The [cpansa-feed](https://github.com/CPAN-Security/cpansa-feed) provides automatically updated security advisory data for CPAN modules in a structured JSON format. This can be used to: + - Check bundled Perl modules against known vulnerabilities + - Generate VEX (Vulnerability Exploitability eXchange) data + - Integrate with vulnerability scanning tools + +3. **SBOM Guidelines**: CPANSec maintains [perl-SBOM-Examples](https://github.com/CPAN-Security/perl-SBOM-Examples) with guidance on: + - When to create/update SBOM files + - Required metadata fields for Perl distributions + - Handling vendored (bundled) dependencies + +### CPANSec Resources + +| Resource | Description | +|----------|-------------| +| [Security Advisory Database](https://security.metacpan.org/) | Main website, CVE announcements | +| [cpansa-feed](https://github.com/CPAN-Security/cpansa-feed) | Machine-readable security advisory data | +| [perl-SBOM-Examples](https://github.com/CPAN-Security/perl-SBOM-Examples) | SBOM best practices for Perl | +| [Test-CVE](https://metacpan.org/pod/Test::CVE) | Test distributions for CVE vulnerabilities | +| [Net-CVE](https://metacpan.org/pod/Net::CVE) | Fetch CVE data from cve.org | +| [CVE Announcements](https://lists.security.metacpan.org/cve-announce/) | Mailing list archive | + +### Integration Opportunity + +Future enhancement: Integrate CPANSA feed checking into CI/CD to automatically flag if any bundled Perl modules have known vulnerabilities. This would complement the SBOM by providing actionable security status. + +--- + ## Makefile Integration Add SBOM generation to the Makefile: @@ -641,7 +679,10 @@ CycloneDX supports: ### Perl Resources - [SBOM::CycloneDX on CPAN](https://metacpan.org/pod/SBOM::CycloneDX) - [CPAN](https://metacpan.org/) - Comprehensive Perl Archive Network -- [CPAN Security Advisory Database](https://security.metacpan.org/) - Vulnerability database for Perl modules +- [CPAN Security Group (CPANSec)](https://security.metacpan.org/) - CVE Numbering Authority for Perl/CPAN +- [CPANSA Feed](https://github.com/CPAN-Security/cpansa-feed) - Machine-readable security advisories +- [perl-SBOM-Examples](https://github.com/CPAN-Security/perl-SBOM-Examples) - SBOM best practices for Perl +- [CPANSec CVE Announcements](https://lists.security.metacpan.org/cve-announce/) - Mailing list archive ### Java Resources - [Maven Central](https://central.sonatype.com/) - Primary Java package repository From 0342573bb41c2f3ab59bc9e03821b0bdfa47bcb0 Mon Sep 17 00:00:00 2001 From: Flavio Soibelmann Glock Date: Thu, 19 Mar 2026 10:07:34 +0100 Subject: [PATCH 11/11] Improve SECURITY.md with CPANSec references and timelines - Add email as alternative reporting channel - Add section for bundled Perl module vulnerabilities with CPANSec contact - Add response timeline targets (7/14/90 days) - Expand dependency vulnerabilities section with CPANSA feed reference - Add TODO placeholder for future SBOM reference - Add Related Resources section with security links Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin --- SECURITY.md | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 3636933d2..8da78edca 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -8,7 +8,15 @@ Only the latest release of PerlOnJava receives security fixes. We recommend alwa If you discover a security vulnerability in PerlOnJava, please **do not** open a public GitHub issue. Instead, use one of the following private disclosure channels: -- **GitHub Private Advisory**: [Report a vulnerability](https://github.com/fglock/PerlOnJava/security/advisories/new) via GitHub's Security Advisories feature. +- **GitHub Private Advisory** (preferred): [Report a vulnerability](https://github.com/fglock/PerlOnJava/security/advisories/new) via GitHub's Security Advisories feature. + +- **Email**: Contact the maintainer directly (see [GitHub profile](https://github.com/fglock)). + +### For Bundled Perl Module Vulnerabilities + +If the vulnerability is in a Perl module bundled with PerlOnJava (rather than PerlOnJava itself), you may also contact the [CPAN Security Group](https://security.metacpan.org/) at [cpan-security@security.metacpan.org](mailto:cpan-security@security.metacpan.org). CPANSec is the CVE Numbering Authority for Perl and CPAN. + +### What to Include Please include as much of the following as possible: @@ -17,7 +25,14 @@ Please include as much of the following as possible: - The version of PerlOnJava affected - Any suggested mitigations, if known -We will do our best to respond promptly, but cannot guarantee a specific response timeline. We appreciate your patience and your effort in responsible disclosure. +### Response Timeline + +We aim to: +- **Acknowledge** your report within **7 days** +- **Provide an initial assessment** within **14 days** +- **Coordinate disclosure** within **90 days** (or sooner if a fix is available) + +These are targets, not guarantees. Complex issues may take longer. We appreciate your patience and your effort in responsible disclosure. ## Security Considerations @@ -59,7 +74,15 @@ PerlOnJava supports calling Java classes and methods from Perl (JSR-223). This s ### Dependency Vulnerabilities -PerlOnJava depends on third-party Java libraries. These dependencies may themselves contain vulnerabilities. Keep your dependencies up to date and monitor them with tools such as [OWASP Dependency-Check](https://owasp.org/www-project-dependency-check/) or GitHub's Dependabot. +PerlOnJava depends on third-party Java libraries and bundles Perl modules. These dependencies may themselves contain vulnerabilities. + +**Java dependencies**: Keep your dependencies up to date and monitor them with tools such as [OWASP Dependency-Check](https://owasp.org/www-project-dependency-check/) or GitHub's Dependabot. + +**Bundled Perl modules**: Check the [CPAN Security Advisory Database](https://security.metacpan.org/) and the [CPANSA feed](https://github.com/CPAN-Security/cpansa-feed) for known vulnerabilities in Perl modules. + + ## Recommendations for Safe Deployment @@ -82,3 +105,10 @@ The following are generally not considered security vulnerabilities for this pro We are grateful to security researchers who responsibly disclose vulnerabilities. Confirmed reporters will be credited in the release notes for the fixing version, unless they prefer to remain anonymous. +## Related Resources + +- [CPAN Security Group](https://security.metacpan.org/) - CVE Numbering Authority for Perl/CPAN +- [Perl Security Policy](https://perldoc.perl.org/perlsecpolicy) - Security handling for Perl itself +- [OWASP Dependency-Check](https://owasp.org/www-project-dependency-check/) - Vulnerability scanner for Java dependencies +- [GitHub Security Advisories](https://github.com/fglock/PerlOnJava/security/advisories) - Published advisories for this project +