save progress

devops/tools/sbom-validators/AIRGAP_INSTALL.md

@@ -0,0 +1,199 @@
+# 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:
+```bash
+cd devops/tools/sbom-validators
+```
+
+2. Run the bundle script:
+```bash
+# 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
+
+```bash
+cd /path/to/bundle
+sha256sum -c SHA256SUMS
+```
+
+All files should report `OK`.
+
+### 3. Configure StellaOps
+
+**Option A: Environment Variable**
+```bash
+export STELLAOPS_VALIDATOR_DIR=/path/to/bundle
+```
+
+**Option B: Configuration File** (`appsettings.yaml`)
+```yaml
+Scanner:
+  Validation:
+    BinaryDirectory: /path/to/bundle
+    OfflineMode: true
+    DownloadTimeout: 00:05:00  # Ignored in offline mode
+```
+
+**Option C: Docker Volume**
+```yaml
+services:
+  scanner:
+    volumes:
+      - ./validator-bundle:/opt/stellaops/validators:ro
+    environment:
+      STELLAOPS_VALIDATOR_DIR: /opt/stellaops/validators
+```
+
+### 4. Verify Installation
+
+```bash
+# 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:**
+```bash
+# 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:**
+```bash
+# Download on connected system
+apt download openjdk-11-jre-headless
+
+# Transfer and install
+sudo dpkg -i openjdk-11-jre-headless*.deb
+```
+
+**Alpine:**
+```bash
+# 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:
+```bash
+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.