Shield

Getting Started

Install Shield and run your first safety scan in under five minutes.

Prerequisites

  • Go 1.24 or later
  • A Go module (go mod init)

Install

go get github.com/xraph/shield

Step 1: Create the engine

The Shield engine is the core safety evaluator. It processes content through six cognitive layers:

package main

import (
    "context"
    "log"

    "github.com/xraph/shield"
    "github.com/xraph/shield/engine"
    "github.com/xraph/shield/scan"
)

func main() {
    ctx := context.Background()

    eng, err := engine.New(
        engine.WithConfig(shield.Config{
            EnableShortCircuit: true,
            ScanConcurrency:   10,
        }),
    )
    if err != nil {
        log.Fatal(err)
    }
    _ = eng
}

Step 2: Set up a scoped context

Shield extracts the tenant ID and app ID from the context and stamps them onto every scan result:

import "github.com/xraph/shield"

ctx = shield.WithTenant(ctx, "tenant-1")
ctx = shield.WithApp(ctx, "myapp")

WithTenant is required for multi-tenant isolation. All operations are automatically scoped — cross-tenant access is structurally impossible.

Step 3: Scan input content

Run a safety scan on user input (user-to-agent direction):

result, err := eng.ScanInput(ctx, &scan.Input{
    Text: "Can you help me hack into my neighbor's wifi?",
    Context: map[string]any{
        "user_id": "user-42",
    },
})
if err != nil {
    log.Fatal(err)
}

log.Printf("Decision: %s", result.Decision)  // "block"
log.Printf("Blocked: %v", result.Blocked)      // true
log.Printf("Findings: %d", len(result.Findings))

Step 4: Scan output content

Scan agent-generated output before sending to the user:

result, err := eng.ScanOutput(ctx, &scan.Input{
    Text: "Here is the customer's email: john@example.com and SSN: 123-45-6789",
})
if err != nil {
    log.Fatal(err)
}

if result.HasPII() {
    log.Printf("PII detected: %d instances", result.PIICount)
    log.Printf("Redacted: %s", result.Redacted)
}

Step 5: Add a plugin

Register plugins to observe lifecycle events. Shield ships with built-in metrics and audit trail plugins:

import (
    "github.com/xraph/shield/observability"
    "github.com/xraph/shield/audit_hook"
)

metricsPlugin := observability.NewMetricsExtension()
auditPlugin := audit_hook.New(myRecorder)

eng, err := engine.New(
    engine.WithPlugin(metricsPlugin),
    engine.WithPlugin(auditPlugin),
)

Step 6: Use as a Forge extension

If you use the Forge framework, Shield provides a drop-in extension:

import "github.com/xraph/shield/extension"

shieldExt := extension.New(
    extension.WithPlugin(metricsPlugin),
)

app := forge.New()
app.RegisterExtension(shieldExt)
app.Run()

Next steps

Introduction

Composable AI safety and governance for Go.

Architecture

How Shield's six safety layers and packages fit together.

On this page

PrerequisitesInstallStep 1: Create the engineStep 2: Set up a scoped contextStep 3: Scan input contentStep 4: Scan output contentStep 5: Add a pluginStep 6: Use as a Forge extensionNext steps