Explanation

Remotes

Remote adapters enable pushing Evidence Packs to registries for distribution, versioning, and team collaboration.

What are Remotes?

Remotes are external registries where Evidence Packs can be pushed and stored. Think of them like Git remotes or Docker registries, but for compliance evidence. Each remote is backed by an adapter—an external binary that handles communication with the specific registry type.

Key Concepts

  • Remote: A named destination in your config (e.g., locktivity, s3)
  • Adapter: A binary (epack-remote-<name>) implementing the Remote Adapter Protocol
  • Target: Workspace and environment within the remote (e.g., acme/prod)
  • Release: A versioned upload with labels, notes, and metadata

Why Use Remotes?

Centralized Distribution

Push packs to a central registry where customers or internal teams can access them with proper access controls.

Version History

Each push creates a new release. Compare versions, track changes over time, and roll back if needed.

Run Ledger Sync

Automatically sync collector run results after pushing, creating a continuous record of evidence collection.

Authentication Built-in

Adapters handle authentication with the registry, supporting device code, OIDC tokens, and API keys.

The Remote Adapter Protocol

Remote adapters are external binaries that follow a JSON-over-stdin/stdout protocol, similar to Git credential helpers. This plugin architecture allows epack to support any registry type without changes to the core tool.

Adapter naming

Adapters follow the naming convention epack-remote-<name>:

  • epack-remote-locktivity — Locktivity registry
  • epack-remote-s3 — Amazon S3 storage
  • epack-remote-filesystem — Local filesystem (testing)

Protocol commands

Adapters support these commands:

Command Purpose Required
--capabilities Query adapter capabilities and features Yes
push.prepare Get presigned upload URL for pack upload Yes
push.finalize Finalize upload and create release Yes
runs.sync Sync run ledgers to remote No
auth.login Interactive authentication No
auth.whoami Query current identity No

Adapter Discovery

epack executes remotes from explicit configuration:

  1. Managed (source-based): Installed via source: field, verified via Sigstore
  2. External binary: Loaded from an explicit absolute binary: path

Adapter verification status

Verified

Adapter is in the lockfile with a valid digest. Safe to execute.

External

Explicit binary: paths can be pinned in the lockfile and verified before execution.

Configuring Remotes

Remotes are configured in epack.yaml under the remotes: section:

epack.yaml
credential_sets:
  locktivity_push: credset_def456

remotes:
  # Locktivity remote - managed via source
  locktivity:
    source: locktivity/epack-remote-locktivity@^0.1.0
    insecure_endpoint: https://registry.example.com
    target:
      workspace: myorg
      environment: prod
    credentials:
      - locktivity_push
    release:
      labels: [monthly, soc2]
    runs:
      sync: true

  # S3 remote - external binary
  s3:
    binary: /usr/local/bin/epack-remote-s3
    adapter: s3
    target:
      bucket: my-evidence-bucket
    runs:
      sync: false

Configuration fields

Field Type Description
source string Source reference for managed adapter (owner/repo@version)
binary string Path to external adapter binary
adapter string Adapter name (inferred from source if not set)
insecure_endpoint string Optional custom API endpoint override. Must use HTTPS.
auth.insecure_endpoint string Optional custom auth endpoint override. Must use HTTPS.
target object Target workspace/environment within remote
auth object Authentication settings (mode, profile)
release object Release metadata (labels, notes, source info)
runs object Run sync settings

The Push Workflow

When you run epack push, the following steps occur:

  1. 1
    Pack Verification: The pack is verified locally for integrity before upload
  2. 2
    Prepare: Adapter provides a presigned upload URL
  3. 3
    Upload: Pack is uploaded directly to storage
  4. 4
    Finalize: Release is created with labels and metadata
  5. 5
    Run Sync: Collector run results are synced (if enabled)
Terminal
# Push to configured remote
epack push locktivity packs/evidence.epack

# Push with labels
epack push locktivity packs/evidence.epack --label monthly --label soc2

# Push to staging environment
epack push locktivity packs/evidence.epack --env staging

# Push with release notes
epack push locktivity packs/evidence.epack --notes "February release"

# Push without syncing runs
epack push locktivity packs/evidence.epack --no-runs

Authentication

Adapters advertise their own authentication modes. Common current modes include:

Mode Use Case
access_token Short-lived bearer token injected by the runtime or a Locktivity-managed broker
device_code Interactive login via browser (similar to GitHub CLI)
client_credentials Explicit client ID and secret for service-to-service auth

Tokens are typically stored in the OS keychain (os_keychain), encrypted file, or passed via environment variable depending on the adapter.

Per-Environment Overrides

Use the environments: section to override remote settings for different environments:

epack.yaml
remotes:
  locktivity:
    source: locktivity/epack-remote-locktivity@^0.1.0
    target:
      workspace: myorg
      environment: prod

environments:
  staging:
    remotes:
      locktivity:
        target:
          environment: staging
        release:
          labels: [staging]
  prod:
    remotes:
      locktivity:
        release:
          labels: [prod, soc2]

Then push using the --env flag:

epack push locktivity evidence.epack --env staging

Security Considerations

Adapter verification

  • Source-based adapters are verified via Sigstore and lockfile digests
  • External binary adapters have their digest pinned in the lockfile

Authentication security

  • Authentication is handled by the adapter or a Locktivity-managed brokered runtime, not by untrusted components
  • Interactive tokens are stored securely (OS keychain preferred)
  • Brokered access tokens are short-lived and scoped to the current runtime context
Important: Only use adapters from trusted sources. An adapter has access to your credentials and can execute arbitrary code during push operations.

See Also