git.stella-ops.org/devops/tools/sbom-validators/AIRGAP_INSTALL.md

SBOM Validator Air-Gap Deployment

This guide explains how to deploy SBOM validators in air-gapped environments.

Overview

StellaOps Scanner uses two external validators for SBOM validation:

Validator	Purpose	Runtime
sbom-utility	CycloneDX JSON/XML validation	Native binary
spdx-tools	SPDX JSON/RDF/Tag-Value validation	Java (JRE 11+)

Creating the Bundle

On a Connected System

1. Navigate to the tools directory:

cd devops/tools/sbom-validators

2. Run the bundle script:

# Bundle for current platform
./bundle.sh

# Bundle for specific platform
./bundle.sh --platform linux-amd64

# Bundle for all platforms
./bundle.sh --all-platforms

3. The bundle will be created in ./bundle/<platform>/

Bundle Contents

bundle/
├── linux-amd64/
│   ├── sbom-utility/
│   │   └── 0.17.0/
│   │       └── sbom-utility
│   ├── spdx-tools/
│   │   └── 1.1.9/
│   │       └── tools-java-1.1.9-jar-with-dependencies.jar
│   ├── SHA256SUMS
│   ├── manifest.json
│   └── README.md
└── ...

Installation on Air-Gapped System

1. Transfer Bundle

Transfer the appropriate platform bundle to your air-gapped system.

2. Verify Integrity

cd /path/to/bundle
sha256sum -c SHA256SUMS

All files should report OK.

3. Configure StellaOps

Option A: Environment Variable

export STELLAOPS_VALIDATOR_DIR=/path/to/bundle

Option B: Configuration File (appsettings.yaml)

Scanner:
  Validation:
    BinaryDirectory: /path/to/bundle
    OfflineMode: true
    DownloadTimeout: 00:05:00  # Ignored in offline mode

Option C: Docker Volume

services:
  scanner:
    volumes:
      - ./validator-bundle:/opt/stellaops/validators:ro
    environment:
      STELLAOPS_VALIDATOR_DIR: /opt/stellaops/validators

4. Verify Installation

# Check sbom-utility
/path/to/bundle/sbom-utility/0.17.0/sbom-utility --version

# Check spdx-tools (requires Java)
java -jar /path/to/bundle/spdx-tools/1.1.9/tools-java-1.1.9-jar-with-dependencies.jar --version

Java Runtime Requirement

spdx-tools requires Java Runtime Environment (JRE) 11 or later.

Installing Java in Air-Gap

Red Hat / CentOS / Rocky:

# Download on connected system
yum download --downloadonly --downloaddir=/tmp/java java-11-openjdk-headless

# Transfer and install
sudo rpm -ivh /tmp/java/*.rpm

Debian / Ubuntu:

# Download on connected system
apt download openjdk-11-jre-headless

# Transfer and install
sudo dpkg -i openjdk-11-jre-headless*.deb

Alpine:

# Download on connected system
apk fetch openjdk11-jre-headless

# Transfer and install
apk add --allow-untrusted openjdk11-jre-headless-*.apk

Updating Validators

1. On a connected system, update version numbers in bundle.sh
2. Run the bundle script to download new versions
3. Verify the bundle integrity
4. Transfer to air-gapped system
5. Update configuration if paths changed

Troubleshooting

Validator Not Found

ValidatorBinaryException: Validator 'sbom-utility' not found and offline mode is enabled

Solution: Verify STELLAOPS_VALIDATOR_DIR points to the bundle directory.

Hash Mismatch

ValidatorBinaryException: Downloaded file hash mismatch

Solution: Re-download the bundle or verify file integrity with sha256sum -c SHA256SUMS.

Java Not Found

SpdxValidator: Java runtime not found

Solution: Install JRE 11+ and ensure java is in PATH.

Permission Denied

Permission denied: /path/to/sbom-utility

Solution: Set executable permission:

chmod +x /path/to/bundle/sbom-utility/*/sbom-utility

Security Considerations

1. Verify bundle source - Only use bundles from trusted sources
2. Check signatures - Verify SHA256SUMS against known good values
3. Principle of least privilege - Run validators with minimal permissions
4. Audit trail - Log all validation operations

Version Pinning

The bundle uses pinned versions for reproducibility:

Validator	Version	SHA-256
sbom-utility	0.17.0	See SHA256SUMS
spdx-tools	1.1.9	See SHA256SUMS

To use different versions, modify bundle.sh and regenerate the bundle.