Go SDK

Prerequisites

Use Go 1.22 or later. Set SILMARIL_API_KEY and SILMARIL_API_URL from your deployment access.

Install

go get github.com/Silmaril-Security/sdk-go/firewall@v0.6.1

Classify your first request

Create one client per protected system and reuse it. Label each call with the boundary it checks, and check each call’s error before making the next one.

package main

import (
	"context"
	"errors"
	"log"
	"os"

	"github.com/Silmaril-Security/sdk-go/firewall"
)

func main() {
	fw, err := firewall.New(firewall.Options{
		APIKey: os.Getenv("SILMARIL_API_KEY"),
		APIURL: os.Getenv("SILMARIL_API_URL"),
	})
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()

	result, err := fw.Classify(ctx, "Summarize this release note.",
		firewall.WithHook(firewall.HookUserInput),
	)
	if err != nil {
		var blocked *firewall.FirewallBlockedError
		if errors.As(err, &blocked) {
			log.Printf("block score=%.4f threshold=%.4f", blocked.Score, blocked.Threshold)
			return
		}
		log.Fatalf("classify failed: %v", err)
	}

	log.Printf("prediction=%s score=%.4f", result.Prediction, result.Score)
}

In a service, pass the request context instead of context.Background(). For tool output, pass the tool name as well, and handle its error the same way.

result, err = fw.Classify(ctx, toolOutput,
	firewall.WithHook(firewall.HookToolResponse),
	firewall.WithToolName("read_file"),
)

Expected result

A benign request logs prediction=BENIGN and its score. When the effective mode is block, a malicious request returns *firewall.FirewallBlockedError. Its Result field holds the full verdict. In shadow or warn mode the call returns the result instead, so route on result.Prediction. Your deployment sets the mode unless the client or call sets Mode. Outcome meanings and recommended actions are in the outcome taxonomy. Any other error means the call did not produce a verdict. That includes *firewall.APIError for a non-2xx API response, and a network, timeout, or context error. Decide whether that boundary fails open or closed.

Concurrent requests

Reuse one client across goroutines. Each Classify or ClassifyBatch call takes a context, so canceling one call also stops its retry wait. Caller-owned metadata, callbacks, and custom transports must be safe for concurrent access.

Shadow mode

Shadow mode returns results instead of blocking errors, so you can measure would-block decisions while traffic continues. Per-call options can enforce one boundary before you change the client default.

fw, err := firewall.New(firewall.Options{
	APIKey:     os.Getenv("SILMARIL_API_KEY"),
	APIURL:     os.Getenv("SILMARIL_API_URL"),
	ShadowMode: true,
	OnClassify: func(event firewall.ClassifyEvent) {
		if event.Blocked && event.ShadowMode {
			log.Printf("would block %s score=%.4f", event.Hook, event.Result.Score)
		}
	},
})
if err != nil {
	log.Fatal(err)
}

_, err = fw.Classify(ctx, text,
	firewall.WithHook(firewall.HookToolResponse),
	firewall.WithShadowMode(false),
)

The classify call passes WithShadowMode(false), so that call enforces. OnClassify can run on overlapping calls. Synchronize any shared state it touches.

Errors

Enforced blocks return *firewall.FirewallBlockedError, which carries Score, Threshold, and Result.

var blocked *firewall.FirewallBlockedError
if errors.As(err, &blocked) {
	log.Printf("blocked score=%.4f threshold=%.4f", blocked.Score, blocked.Threshold)
	return
}

Read blocked.Result for the verdict, or use shadow mode when you need the result without a blocking error. Outcome meanings and recommended actions are in the outcome taxonomy.

Start

Concepts

SDKs

AI gateways

Integrations

Deployment

MacOS

Prerequisites

Install

Classify your first request

Expected result

Concurrent requests

Shadow mode

Errors

​Prerequisites

​Install

​Classify your first request

​Expected result

​Concurrent requests

​Shadow mode

​Errors

Prerequisites

Install

Classify your first request

Expected result

Concurrent requests

Shadow mode

Errors