6a299d231f
- Implemented tests for RouterConfig, RoutingOptions, StaticInstanceConfig, and RouterConfigOptions to ensure default values are set correctly. - Added tests for RouterConfigProvider to validate configurations and ensure defaults are returned when no file is specified. - Created tests for ConfigValidationResult to check success and error scenarios. - Developed tests for ServiceCollectionExtensions to verify service registration for RouterConfig. - Introduced UdpTransportTests to validate serialization, connection, request-response, and error handling in UDP transport. - Added scripts for signing authority gaps and hashing DevPortal SDK snippets.
125 lines
5.0 KiB
Markdown
125 lines
5.0 KiB
Markdown
# Cosign binaries (runtime/signals signing)
|
||
|
||
## Preferred (system)
|
||
- Version: `v3.0.2`
|
||
- Path: `/usr/local/bin/cosign` (installed on WSL Debian host)
|
||
- Breaking change: v3 requires `--bundle <file>` when signing blobs; older `--output-signature`/`--output-certificate` pairs are deprecated.
|
||
|
||
## Offline fallback (repo-pinned)
|
||
- Version: `v2.6.0`
|
||
- Binary: `tools/cosign/cosign` → `tools/cosign/v2.6.0/cosign-linux-amd64`
|
||
- SHA256: `ea5c65f99425d6cfbb5c4b5de5dac035f14d09131c1a0ea7c7fc32eab39364f9`
|
||
- Check: `cd tools/cosign/v2.6.0 && sha256sum -c cosign_checksums.txt --ignore-missing`
|
||
|
||
## Usage examples
|
||
- v3 DSSE blob: `cosign sign-blob --key cosign.key --predicate-type stella.ops/confidenceDecayConfig@v1 --bundle confidence_decay_config.sigstore.json decay/confidence_decay_config.yaml`
|
||
- v3 verify: `cosign verify-blob --bundle confidence_decay_config.sigstore.json decay/confidence_decay_config.yaml`
|
||
- To force offline fallback, export `PATH=./tools/cosign:$PATH` (ensures v2.6.0 is used).
|
||
|
||
## CI Workflow: signals-dsse-sign.yml
|
||
|
||
The `.gitea/workflows/signals-dsse-sign.yml` workflow automates DSSE signing for Signals artifacts.
|
||
|
||
### Required Secrets
|
||
| Secret | Description | Required |
|
||
|--------|-------------|----------|
|
||
| `COSIGN_PRIVATE_KEY_B64` | Base64-encoded cosign private key | Yes (for production) |
|
||
| `COSIGN_PASSWORD` | Password for the private key | If key is encrypted |
|
||
| `CI_EVIDENCE_LOCKER_TOKEN` | Token for Evidence Locker upload | Optional |
|
||
|
||
### Trigger Options
|
||
1. **Automatic**: On push to `main` when signals artifacts change
|
||
2. **Manual**: Via workflow_dispatch with options:
|
||
- `out_dir`: Output directory (default: `evidence-locker/signals/2025-12-01`)
|
||
- `allow_dev_key`: Set to `1` for testing with dev key
|
||
|
||
### Setting Up CI Secrets
|
||
```bash
|
||
# Generate production key pair (do this once, securely)
|
||
cosign generate-key-pair
|
||
|
||
# Base64 encode the private key
|
||
cat cosign.key | base64 -w0 > cosign.key.b64
|
||
|
||
# Add to Gitea secrets:
|
||
# - COSIGN_PRIVATE_KEY_B64: contents of cosign.key.b64
|
||
# - COSIGN_PASSWORD: password used during key generation
|
||
```
|
||
|
||
## CI / secrets (manual usage)
|
||
- CI should provide a base64-encoded private key via secret `COSIGN_PRIVATE_KEY_B64` and optional password in `COSIGN_PASSWORD`.
|
||
- Example bootstrap in jobs:
|
||
```bash
|
||
echo "$COSIGN_PRIVATE_KEY_B64" | base64 -d > /tmp/cosign.key
|
||
chmod 600 /tmp/cosign.key
|
||
COSIGN_PASSWORD="${COSIGN_PASSWORD:-}" cosign version
|
||
```
|
||
- For local dev, copy your own key to `tools/cosign/cosign.key` or export `COSIGN_PRIVATE_KEY_B64` before running signing scripts. Never commit real keys; only `cosign.key.example` lives in git.
|
||
|
||
## Development signing key
|
||
|
||
A development key pair is provided for local testing and smoke tests:
|
||
|
||
| File | Description |
|
||
|------|-------------|
|
||
| `tools/cosign/cosign.dev.key` | Private key (password-protected) |
|
||
| `tools/cosign/cosign.dev.pub` | Public key for verification |
|
||
|
||
### Usage
|
||
```bash
|
||
# Sign signals artifacts with dev key
|
||
COSIGN_ALLOW_DEV_KEY=1 COSIGN_PASSWORD=stellaops-dev \
|
||
OUT_DIR=docs/modules/signals/dev-test \
|
||
tools/cosign/sign-signals.sh
|
||
|
||
# Verify a signature
|
||
cosign verify-blob \
|
||
--key tools/cosign/cosign.dev.pub \
|
||
--bundle docs/modules/signals/dev-test/confidence_decay_config.sigstore.json \
|
||
docs/modules/signals/decay/confidence_decay_config.yaml
|
||
```
|
||
|
||
### Security Notes
|
||
- Password: `stellaops-dev` (do not reuse elsewhere)
|
||
- **NOT** for production or Evidence Locker ingestion
|
||
- Real signing requires the Signals Guild key via `COSIGN_PRIVATE_KEY_B64` (CI) or `tools/cosign/cosign.key` (local drop-in)
|
||
- `sign-signals.sh` requires `COSIGN_ALLOW_DEV_KEY=1` to use the dev key; otherwise it refuses
|
||
- The signing helper disables tlog upload (`--tlog-upload=false`) and auto-accepts prompts (`--yes`) for offline runs
|
||
|
||
## Signing Scripts
|
||
|
||
### sign-signals.sh
|
||
Signs decay config, unknowns manifest, and heuristics catalog with DSSE envelopes.
|
||
|
||
```bash
|
||
# Production (CI secret or cosign.key drop-in)
|
||
OUT_DIR=evidence-locker/signals/2025-12-01 tools/cosign/sign-signals.sh
|
||
|
||
# Development (dev key)
|
||
COSIGN_ALLOW_DEV_KEY=1 COSIGN_PASSWORD=stellaops-dev \
|
||
OUT_DIR=docs/modules/signals/dev-test \
|
||
tools/cosign/sign-signals.sh
|
||
```
|
||
|
||
### Key Resolution Order
|
||
1. `COSIGN_KEY_FILE` environment variable
|
||
2. `COSIGN_PRIVATE_KEY_B64` (decoded to temp file)
|
||
3. `tools/cosign/cosign.key` (production drop-in)
|
||
4. `tools/cosign/cosign.dev.key` (only if `COSIGN_ALLOW_DEV_KEY=1`)
|
||
|
||
### sign-authority-gaps.sh
|
||
Signs Authority gap artefacts (AU1–AU10, RR1–RR10) under `docs/modules/authority/gaps/artifacts/`.
|
||
|
||
```
|
||
# Production (Authority key via CI secret or cosign.key drop-in)
|
||
OUT_DIR=docs/modules/authority/gaps/dsse/2025-12-04 tools/cosign/sign-authority-gaps.sh
|
||
|
||
# Development (dev key, smoke only)
|
||
COSIGN_ALLOW_DEV_KEY=1 COSIGN_PASSWORD=stellaops-dev \
|
||
OUT_DIR=docs/modules/authority/gaps/dev-smoke/2025-12-04 \
|
||
tools/cosign/sign-authority-gaps.sh
|
||
```
|
||
|
||
- Outputs bundles or dsse signatures plus `SHA256SUMS` in `OUT_DIR`.
|
||
- tlog upload disabled (`--tlog-upload=false`) and prompts auto-accepted (`--yes`) for offline use.
|