SDK & Contracts

All inter-platform communication in opensecstack uses the opensecstack/sdk — a set of typed clients and event schemas available in Go, Python, TypeScript, and Rust. Platforms never exchange ad-hoc payloads; every message conforms to a versioned contract defined in the SDK. This means a consumer can trust the shape of data regardless of which platform version produced it.

The SDK

The opensecstack/sdk (Apache 2.0, v1.0.0) ships four language clients that are byte-compatible with each other:

The SDK also includes a shared Argon2id + pepper password hashing module with byte-compatible PHC encoding across Go (sdk/go/password) and Python (sdk/python-password).

Event contracts

The table below lists every typed contract the SDK defines, together with which platform produces it and which platforms consume it.

Go SDK example

The following snippet shows the typical integration flow from an APIGuard scan to the CITADEL WORM log using the Go client. The same pattern is available in Python, TypeScript, and Rust.

import "github.com/opensecstack/sdk/go/opensecstack"

"cm">// Create a client for the APIGuard platform
client := opensecstack.NewAPIGuardClient("https:"cm">//apiguard.example.com", "your-api-key")

"cm">// Kick off a scan against a published OpenAPI spec
scan, _ := client.CreateScan(ctx, "https:"cm">//api.example.com/openapi.json")

"cm">// Retrieve only critical findings once the scan completes
findings, _ := client.GetFindings(ctx, scan.ID, opensecstack.GetFindingsOptions{
    Severity: "critical",
})

"cm">// Emit the scan result to the CITADEL WORM audit chain
entry := &opensecstack.AuditEntry{
    Source:    "apiguard",
    EventType: "scan_completed",
    ProjectID: "your-project-id",
    TsUTC:     scan.CompletedAt,
    Payload: map[string]any{
        "scan_id":          scan.ID,
        "findings_summary": findings,
    },
}
citadel.EmitWORM(ctx, entry)

Signed webhooks

When a platform emits an event to another platform over HTTP, the request is signed with HMAC-SHA256 using a per-source secret. The receiving platform must verify the signature before processing the payload. A ±5-minute replay window is enforced on the timestamp in every request to prevent replay attacks. See Webhooks & Events for the full specification.

IRFlow defines the canonical wire format for signed webhooks; all other platforms follow the same specification. See irflow/docs/webhook-spec.md in the repository for the full header schema and verification algorithm.

Contract versioning

Contracts are versioned by SDK package version. Minor version increments are backward-compatible additions; breaking changes increment the minor SDK version and are announced in sdk/docs/migration.md with a step-by-step upgrade guide. Consumers should pin to a minimum SDK version and upgrade when producers in their deployment do.