independentid/i2gosignals repository overview

⁠i2goSignals

A Security Event Router that bridges Push and Poll SET delivery across federation boundaries, with durable storage, replay, and fan-out.

independentid/i2gosignals is the official container image for the community edition of goSignals — a Go-based, horizontally-scalable server that implements the OpenID Shared Signals Framework (SSF) and the IETF Security Event Token (SET) delivery RFCs. Use it to receive, validate, persist, route, and re-emit security signals (CAEP, RISC, SCIM) between identity providers, SaaS receivers, and platforms that live on opposite sides of a firewall or trust boundary.

Source code, issues, and roadmap: https://github.com/i2-open/i2gosignals⁠

⁠What's in the image

The image is a Chainguard-based distroless bash runtime (non-root UID 1000) containing six statically-linked Go binaries:

The image also ships LICENSE.txt (Apache 2.0) and THIRD-PARTY-NOTICES.txt for the Go dependencies it statically links.

⁠Standards implemented

A key value of the router is protocol bridging: poll-only receivers can pull events from push-only transmitters, and inbound SETs can be re-validated, filtered, and re-signed for downstream audiences.

⁠Quick start

⁠Run a single server against MongoDB

docker run -d --name gosignals \
  -p 8888:8888 \
  -e I2SIG_STORE_MONGO_URL=mongodb://mongo:27017 \
  -e I2SIG_STORE_MONGO_DBNAME=gosignals \
  -e I2SIG_ISSUER_DEFAULT=https://signals.example.com \
  -e LOG_LEVEL=INFO \
  independentid/i2gosignals:latest

Then use the admin CLI from inside the container, or download the matching goSignals binary, to register streams.

⁠Full demo (recommended)

The repository ships several docker-compose files that demonstrate two-node clustering, MongoDB, Keycloak SSO, Prometheus/Grafana, and SPIFFE/SPIRE-based mTLS. Clone the repo and bring one up:

git clone https://github.com/i2-open/i2gosignals.git
cd i2gosignals
docker compose up -d           # standard 2-node demo
# or
docker compose -f docker-compose-spiffe.yml up -d   # SPIFFE/mTLS variant
# or
docker compose -f docker-compose-cluster.yml up -d  # Nginx-balanced cluster

See the project README⁠ for the full walk-through, including local DNS, trusting the dev CA, and Grafana SSO.

⁠Image tags

Multi-arch manifest: linux/amd64 and linux/arm64.

⁠Exposed port

Set I2SIG_TLS_ENABLED=true together with I2SIG_TLS_KEY_PATH / I2SIG_TLS_CERT_PATH to terminate TLS in-process; otherwise terminate upstream.

⁠Configuration

i2goSignals is fully environment-variable driven — there is no config file. The taxonomy is I2SIG_<AREA>_<KEY>. The canonical reference, with defaults and behavioural notes, is docs/configuration_properties.md⁠.

The variables you will almost always set:

Tuning knobs worth knowing:

Variables from pre-v0.11.0 releases still work via a compatibility shim (one WARN per process) and will be removed in v0.12.0. See the ADR 0011 taxonomy⁠.

⁠Volumes

The server is largely stateless — durable state lives in MongoDB — but two paths are useful to mount:

⁠Health checks

The image bundles a healthcheck binary that probes the server's HTTP health endpoint and exits non-zero on failure. Example Compose snippet:

services:
  gosignals:
    image: independentid/i2gosignals:latest
    healthcheck:
      test: ["/app/healthcheck"]
      interval: 15s
      timeout: 3s
      retries: 5

⁠Clustering

Multiple i2gosignals containers behind a load balancer form a cluster without any extra coordination service — leases are held in MongoDB (cluster_leases collection) with a 30-second TTL and 10-second heartbeat. Push transmitters and poll receivers each take a per-stream singleton lease; inbound traffic is served by every node. Nodes wake each other for fresh events over an authenticated POST /_cluster/wake-transmitter (shared HMAC via I2SIG_CLUSTER_INTERNAL_TOKEN, or SPIFFE mTLS when enabled).

See docs/Cluster.md⁠ for the design.

⁠Security

• Runs as non-root (UID/GID 1000).
• Built on a Chainguard distroless base; the digest is pinned in the Dockerfile and refreshed deliberately at release time.
• All Go binaries are statically linked; no shared libraries in the image surface.
• A SPDX SBOM is published alongside each release and can be rebuilt locally with make docker-sbom.
• Inbound admin/management API supports OAuth2 bearer tokens (via discovery URLs in I2SIG_AUTH_OAUTH_SERVERS), HMAC, and SPIFFE mTLS.

⁠Documentation

• README & getting started: https://github.com/i2-open/i2gosignals#readme⁠
• Configuration reference: docs/configuration_properties.md⁠
• CLI & login: docs/gosignals_tool.md⁠, docs/cli_login.md⁠
• Security model: docs/security_model.md⁠
• Clustering: docs/Cluster.md⁠
• Metrics & observability: docs/Metrics.md⁠, docs/observability.md⁠
• SPIFFE/SPIRE: docs/spiffe_support.md⁠

⁠License & commercial

The image and source are released under the Apache License 2.0. See LICENSE.txt and THIRD-PARTY-NOTICES.txt inside the image, or on GitHub⁠.

For commercial licensing, embedding, or the I2 administration server and planned hosted service: [email protected]⁠.

© Independent Identity Inc.