independentid/i2gosignals

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 ***aries:

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

bash
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 ***ary, 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:

bash
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 https://github.com/i2-open/i2gosignals#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.

Project status: active development. Suitable for evaluation, integration testing, and demos. Administration-API security and multi-node coordination are being finalised; not yet recommended for unattended production use.

---

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 https://github.com/i2-open/i2gosignals/blob/master/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 https://github.com/i2-open/i2gosignals/blob/master/docs/adr/0011-environment-variable-taxonomy.md.

---

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 ***ary that probes the server's HTTP health endpoint and exits non-zero on failure. Example Compose snippet:

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

---

Clustering

Multiple i2gosignals containers behind a load *** 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 https://github.com/i2-open/i2gosignals/blob/master/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 ***ly at release time.
• All Go ***aries 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: https://github.com/i2-open/i2gosignals/blob/master/docs/configuration_properties.md
• CLI & login: https://github.com/i2-open/i2gosignals/blob/master/docs/gosignals_tool.md, https://github.com/i2-open/i2gosignals/blob/master/docs/cli_login.md
• Security model: https://github.com/i2-open/i2gosignals/blob/master/docs/security_model.md
• Clustering: https://github.com/i2-open/i2gosignals/blob/master/docs/Cluster.md
• Metrics & observability: https://github.com/i2-open/i2gosignals/blob/master/docs/Metrics.md, https://github.com/i2-open/i2gosignals/blob/master/docs/observability.md
• SPIFFE/SPIRE: https://github.com/i2-open/i2gosignals/blob/master/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 https://github.com/i2-open/i2gosignals.

For commercial licensing, embedding, or the I2 administration server and planned hosted service: <***>.

© Independent Identity Inc.