# 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.