SalsaGate Technical Documentation

1. Abstract

High-level overview of the problem and SalsaGate’s solution.

SalsaGate is a supply-chain security platform that integrates with existing CI/CD pipelines to ensure that software artifacts and infrastructure changes are authenticated, policy-compliant, and auditable from commit to production. The core idea is to treat each build or deployment as a verifiable event backed by cryptographic signatures, SBOMs, and attestations.

This document describes SalsaGate’s architecture, design decisions, security model, and evaluation. It is written for engineers, DevSecOps practitioners, and reviewers who need a deeper technical understanding of the system.

2. Introduction

Background, motivation, and context.

Modern software supply chains rely on a complex mesh of source repositories, build systems, package registries, container registries, and deployment platforms. Compromises at any stage—such as tampered images, malicious dependencies, or misconfigured pipelines—can lead to production incidents and regulatory risk.

Rather than relying on ad-hoc checks and manual approvals, SalsaGate introduces a structured verification layer. Every artifact and configuration must meet a set of machine-readable policies before promotion. Verification results are stored as evidence, enabling both automated gates and human audits.

The design is influenced by principles from SLSA, NIST supply-chain guidance, and real-world DevSecOps workflows, but it focuses on pragmatic integration with tools teams already use.

3. Problem Statement & Goals

What SalsaGate is trying to solve and why.

3.1 Problem Statement

Teams lack a unified way to enforce signing, SBOMs, and test requirements across all pipelines.
Verification logic is often embedded directly in CI scripts, making it inconsistent and hard to audit.
Evidence needed for audits and incident response is fragmented or missing.

3.2 Project Goals

Provide a central verification service that can be called from any CI/CD system.
Offer policy-as-code so teams can express and review security requirements in version control.
Persist verification results and attestations in an evidence store for later analysis and audits.
Keep developer friction low: easy CLI, clear error messages, fast verification.

3.3 Scope

The initial scope covers build artifacts (binaries, containers, bundles) and infrastructure plans (e.g. Terraform). Runtime behavior such as behavior-based anomaly detection is out of scope for this version.

4. System Architecture

Components, interactions, and trust boundaries.

SalsaGate is composed of three main components:

CLI & CI Integrations — Lightweight clients that run in CI to authenticate, register artifacts, and ask SalsaGate to verify them.
Verification Service — A stateless API that performs signature checks, policy evaluation, and logging.
Evidence Store — A durable store for SBOMs, attestations, and verification events.

# Simplified data flow
Developer → CI Build → (sign + attest)
  → SalsaGate Verify API
    → Evidence Store
      → Deploy (K8s admission / release gates)

Component	Responsibility
CLI	Auth, register, verify, attest
Verify API	Signature & policy evaluation
Evidence Store	SBOMs, attestations, logs
Admission Controller	Runtime enforcement

Typical verification flow for a container image:

CI builds an image and pushes it to a container registry.
CI generates an SBOM and vulnerability scan report, then creates an attestation.
CI signs both the image and attestation using Cosign or another signer.
SalsaGate CLI calls the verification API with references to the image and attestations.
The API fetches signatures/metadata, evaluates policy, and records the result in the evidence store.
Deployment tooling or admission controls check SalsaGate before allowing production deployment.

# CI verification step
salsagate verify \
  --artifact ghcr.io/org/app:sha-1234 \
  --policy strict \
  --sbom sbom.spdx.json \
  --attestation vuln-scan.json

Text-based sequence diagram (GitHub Actions + SalsaGate + Kubernetes):

Developer        GitHub Actions        SalsaGate API        Evidence Store        K8s Admission
    |                   |                     |                    |                    |
    |   git push        |                     |                    |                    |
    |------------------>|                     |                    |                    |
    |                   | build, test, scan   |                    |                    |
    |                   |-------------------->|                    |                    |
    |                   | sign image & SBOM   |                    |                    |
    |                   |-------------------->| verify(image,...)  |                    |
    |                   |                     |----policy checks--->|                    |
    |                   |                     |<---store results---|                    |
    |                   |   deploy manifest   |                    | verify admission   |
    |                   |------------------------------------------->|------------------>|
    |                   |                     |                    | allow / deny       |

5. Technology Stack

Languages, frameworks, and infrastructure services.

Core Services

Backend: Go or TypeScript (Node.js), packaged as stateless services.
API: REST + JSON responses, with optional gRPC for internal use.
Storage: PostgreSQL for metadata, object storage (e.g. S3) for large artifacts.
Caching: Redis for hot verification results (optional but recommended).

Integrations

SalsaGate CLI distributed as a single binary.
GitHub Actions / GitLab CI / Jenkins templates.
Kubernetes admission controller for runtime gating.

Security & Identity

OIDC workload identity from GitHub, GitLab, or cloud providers.
Cosign / Sigstore, KMS/HSM, and GPG as signing backends.
mTLS for internal service-to-service communication.

Observability

Structured JSON logs with correlation IDs.
Prometheus metrics for latency, error rate, and throughput.
OpenTelemetry-compatible tracing hooks.

6. Design & Implementation

Key design choices and how they are implemented.

6.1 Policy-as-Code

Policies are stored as versioned YAML files in the same repositories as the services they govern. Each policy can be associated with a project, environment (dev/stage/prod), or artifact type.

# policy.yml
require_signatures: true
allowed_signers:
  - ci-bot@salsagate.dev
  - release-manager@salsagate.dev
enforce_sbom: true
checks:
  - name: unit-tests
    must_pass: true
  - name: vuln-scan
    severity_max: "medium"

6.2 Stateless Verification Service

The verification API is stateless with respect to client sessions. Requests carry all necessary identifiers (artifact URIs, policy name, attestation locations). This simplifies scaling and makes the service easy to deploy in containerized environments.

Stateless design allows horizontal scaling and blue/green deployments without migrating session state.

6.3 CI/CD Integration Pattern

Integration aims to be minimal and tool-agnostic. CI pipelines:

Build artifacts and generate SBOMs and test reports.
Sign artifacts and/or attestations.
Invoke salsagate verify with appropriate flags.

# GitHub Actions example
- name: Build
  run: make build

- name: Sign artifact
  run: cosign sign-blob --key ${{ secrets.COSIGN_KEY }} dist/app.tar.gz

- name: SalsaGate Verify
  run: salsagate verify \
    --artifact dist/app.tar.gz \
    --policy strict

7. Security, Privacy & Ethics

Threat model, mitigations, and ethical considerations.

SalsaGate sits in the critical path of deployments. A compromise could enable malicious releases or block legitimate ones. Hardened deployment and ongoing monitoring are essential.

7.1 Threat Model

Compromised CI agent attempting to publish unsigned or malicious artifacts.
Stolen signing keys used to sign hostile payloads.
MITM attacks between CI systems and SalsaGate services.
Tampering with evidence (SBOMs, logs) to hide vulnerabilities.

7.2 Mitigations

Use OIDC workload identity instead of long-lived secrets in CI.
Store keys in KMS/HSM; enforce strong access controls and rotation.
Enforce mTLS for communication with SalsaGate APIs.
Use append-only or WORM storage for evidence.
Apply RBAC and audit logs around policy changes and evidence exports.

7.3 Privacy & Ethics

SalsaGate primarily manages metadata and security-relevant information (hashes, identities, SBOMs). It is not designed to store personal data. Teams should avoid logging secrets and follow internal data classification guidelines when exporting evidence.

Ethically, SalsaGate aims to increase transparency and accountability in software releases, reducing the risk of harmful incidents caused by unnoticed supply-chain manipulations.

8. Testing & Evaluation

Verification correctness, performance, and integration tests.

8.1 Unit & Integration Tests

Unit tests for policy evaluation and signature verification logic.
Integration tests with local registries and signing tools (Cosign, GPG).
End-to-end tests simulating CI pipelines across multiple repositories.

# Run Go tests
go test ./...

# or language-specific
npm test
pytest

8.2 Performance Evaluation

Key targets for v1:

< 150ms median verification latency for common artifact sizes.
Graceful degradation and backoff when external registries are slow.
Horizontal scaling verified through load tests.

8.3 CI Validation

Reference pipelines exist for:

GitHub Actions: OIDC + Cosign + SalsaGate verify.
GitLab CI: shared runners with environment-based configuration.
Jenkins: credential store and scripted stages using the CLI.

9. Challenges & Limitations

Known constraints and lessons learned.

Diverse signing approaches

Organizations often mix Cosign, GPG, and cloud KMS signing. SalsaGate addresses this through pluggable verification backends, but configuration can still be complex in multi-cloud environments.

Developer experience vs strict policies

If policies are too strict from day one, teams may view SalsaGate as a blocker. To mitigate this, policies support different enforcement modes (observe, warn, enforce) that can be rolled out gradually.

Evidence storage growth

Evidence can grow quickly in high-velocity environments. Retention policies, tiered storage, and export-to-archive workflows are required to keep storage costs manageable.

10. Future Work

Planned enhancements and research directions.

Full Kubernetes admission controller with interactive policy debugging.
IDE plugins to surface policy hints and violations in real time.
Deeper integrations with vulnerability scanners and SBOM generators.
Evidence explorer UI for auditors and compliance officers.
gRPC/streaming verification API for very high-throughput internal use cases.

11. References

Standards, tools, and related work.

Supply-chain security frameworks (e.g. SLSA, NIST guidance on software supply-chain security).
Sigstore / Cosign documentation and examples.
SBOM standards: SPDX, CycloneDX.
Cloud provider docs on OIDC workload identity (AWS, GCP, Azure).
Internal incident response and key management runbooks (if available).