SSF

SSF (protocolsoup-ssf)

Image: ghcr.io/parlesec/protocolsoup-ssf

When To Use

Use SSF service to test security event stream configuration, CAEP/RISC event delivery, and receiver response actions.

Runtime Contract

Property	Value
Primary port	8080 (SSF APIs)
Receiver port	8081 (push delivery listener)
Health	GET /health
SSF discovery	GET /ssf/.well-known/ssf-configuration
Receiver status	GET /ssf/receiver/status

Key Endpoints

Transmitter

• POST|GET|PATCH|DELETE /ssf/stream — stream management
• GET|POST /ssf/status — stream status
• GET|POST /ssf/subjects — subject management
• POST /ssf/actions/{action} — trigger event actions
• POST /ssf/push — push delivery
• GET|POST /ssf/poll — poll delivery
• POST /ssf/ack — acknowledge events

Receiver

• POST /ssf/receiver/push — receive pushed SETs
• GET /ssf/receiver/status — receiver health
• GET /ssf/receiver/events — received event log
• GET /ssf/receiver/actions — response action log

Supporting

• GET /ssf/events/stream — SSE event stream
• GET /ssf/events — event history
• GET /ssf/security-state — all security states
• GET /ssf/security-state/{email} — security state by subject
• POST /ssf/decode — decode SET token
• GET /ssf/event-types — available event types

Supported Event Actions

session-revoked, credential-change, device-compliance-change, credential-compromise, account-disabled, account-enabled, account-purged, identifier-changed, assurance-level-change, token-claims-change, identifier-recycled, account-credential-change-required, sessions-revoked

Configuration

Variable	Required	Default	Description
SHOWCASE_BASE_URL	Yes	http://localhost:8080	External base URL
SSF_DATA_DIR	No	./data	Stream and receiver state directory
SSF_RECEIVER_PORT	No	8081	Standalone receiver listener port
SSF_RECEIVER_TOKEN	No	auto-generated	Bearer token for push delivery authentication

Run

docker run -p 8080:8080 -p 8081:8081 \
  -e SHOWCASE_BASE_URL=http://localhost:8080 \
  -e SSF_DATA_DIR=/app/data \
  -v ssf-data:/app/data \
  ghcr.io/parlesec/protocolsoup-ssf:latest

Operational Notes

• Port 8081 runs the standalone receiver. Keep it private unless you intentionally test external push delivery.
• Push delivery to {baseURL}/ssf/receiver/push is proxied to the internal receiver on port 8081.
• The receiver validates SETs and executes response actions (session revocation, credential compromise, etc.) via the built-in MockIdP action executor.
• Set SSF_RECEIVER_TOKEN explicitly in shared environments.
• Persist SSF_DATA_DIR to keep stream and event state across restarts.