# Silmaril Public Docs

Silmaril Firewall protects AI applications and agentic systems from prompt injection, tool abuse, context poisoning, confused deputy behavior, and unsafe execution chains.

Access is not self-serve yet. Book a call to provision credentials, choose a managed or self-hosted deployment path, and receive the endpoint used by the examples below.

Demo URL: https://cal.com/silmaril/15min
Book a call: https://cal.com/silmaril/15min
Website: https://silmaril.dev
Updated: June 2, 2026

## Public Routes

- Home: https://silmaril.dev/
- Docs overview: https://silmaril.dev/docs
- Privacy: https://silmaril.dev/privacy
- Terms: https://silmaril.dev/terms
- Status: https://silmaril.dev/status

## TypeScript SDK

Current SDK version: 0.4.2
Package: @silmaril-security/sdk
Updated: June 2, 2026

Install the core SDK in the service that owns inference, tool execution, or orchestration boundaries.

```bash
npm install @silmaril-security/sdk@0.4.2
```

```ts
import { Firewall, HookLabel } from "@silmaril-security/sdk";

const fw = new Firewall({
  apiKey: process.env.SILMARIL_API_KEY!,
  apiUrl: process.env.SILMARIL_API_URL!,
});

const result = await fw.classify(userInput, {
  hook: HookLabel.USER_INPUT,
});

await fw.classify(toolOutput, {
  hook: HookLabel.TOOL_RESPONSE,
  toolName: "read_file",
});
```

## Python SDK

Current SDK version: 0.4.2
Package: silmaril-security-sdk
Updated: June 2, 2026

Install the Python SDK in services that own inference, tool execution, or orchestration boundaries.

```bash
pip install silmaril-security-sdk==0.4.2
```

```py
import os
from silmaril_security.sdk import Firewall, HookLabel

fw = Firewall(
    api_key=os.environ["SILMARIL_API_KEY"],
    api_url=os.environ["SILMARIL_API_URL"],
)

result = fw.classify(
    user_input,
    hook=HookLabel.USER_INPUT,
)

fw.classify(
    tool_output,
    hook=HookLabel.TOOL_RESPONSE,
    tool_name="read_file",
)
```

## Go SDK

Current SDK version: v0.4.1
Package: github.com/Silmaril-Security/sdk-go
Updated: June 2, 2026

Install the Go module and classify boundaries with explicit hook metadata.

```bash
go get github.com/Silmaril-Security/sdk-go@v0.4.1
```

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

result, err := fw.Classify(ctx, userInput,
    firewall.WithHook(firewall.HookUserInput),
)
```

## Firewall Outcomes

TypeScript, Python, Go, and Java SDKs expose typed outcome constants on `BlockResult` so application code can route different classes of firewall decisions without stringly-typed branching. The backend wire fields remain `primary_outcome`, `outcome_scores`, `detector_scores`, `detector_counts`.

- `benign`: No harmful firewall outcome detected.
- `information_disclosure`: Private data, documents, internal context, logs, traces, customer data, SQL rows, topology, or similar non-secret sensitive information.
- `secret_exposure`: Credentials, tokens, API keys, cookies, passwords, signing keys, OAuth secrets, session material, or webhook secrets.
- `control_abuse`: Misuse of authorized tools or user privileges to send, change, approve, delete, operate, or bypass policy/RBAC without a stronger outcome.
- `system_compromise`: Privilege escalation, account takeover, hostile integration/plugin takeover, persistence, lateral movement, attacker webhook registration, or code/plugin execution.
- `service_disruption`: Downtime, lockout, degradation, alert suppression, destructive loops, resource exhaustion, cost spikes, or hidden outage evidence.

### TypeScript outcome handling

```ts
import { HookLabel, Outcome } from "@silmaril-security/sdk";

const result = await fw.classify(text, {
  hook: HookLabel.TOOL_RESPONSE,
  toolName: "read_file",
});

switch (result.primaryOutcome) {
  case Outcome.Benign:
    return continueNormally(result);
  case Outcome.SecretExposure:
    return redactAndSuppress(result);
  case Outcome.InformationDisclosure:
    return requireReviewBeforeReturningPrivateData(result);
  case Outcome.ControlAbuse:
    return denyAndRequestExplicitConfirmation(result);
  case Outcome.SystemCompromise:
    securityLog(result);
    return blockAndEscalate(result);
  case Outcome.ServiceDisruption:
    return blockDestructiveOrDisruptiveAction(result);
  default:
    return blockByDefault(result);
}
```

### Python outcome handling

```py
from silmaril_security.sdk import (
    HookLabel,
    OUTCOME_BENIGN,
    OUTCOME_CONTROL_ABUSE,
    OUTCOME_INFORMATION_DISCLOSURE,
    OUTCOME_SECRET_EXPOSURE,
    OUTCOME_SERVICE_DISRUPTION,
    OUTCOME_SYSTEM_COMPROMISE,
)

result = fw.classify(
    text,
    hook=HookLabel.TOOL_RESPONSE,
    tool_name="read_file",
    shadow_mode=True,
)

if result.primary_outcome == OUTCOME_BENIGN:
    continue_normally(result)
elif result.primary_outcome == OUTCOME_SECRET_EXPOSURE:
    redact_and_suppress(result)
elif result.primary_outcome == OUTCOME_INFORMATION_DISCLOSURE:
    require_review_before_returning_private_data(result)
elif result.primary_outcome == OUTCOME_CONTROL_ABUSE:
    deny_and_request_explicit_confirmation(result)
elif result.primary_outcome == OUTCOME_SYSTEM_COMPROMISE:
    security_log(result)
    block_and_escalate(result)
elif result.primary_outcome == OUTCOME_SERVICE_DISRUPTION:
    block_destructive_or_disruptive_action(result)
else:
    block_by_default(result)
```

### Go outcome handling

```go
result, err := fw.Classify(ctx, text,
    firewall.WithHook(firewall.HookToolResponse),
    firewall.WithToolName("read_file"),
    firewall.WithShadowMode(true),
)
if err != nil {
    return err
}

switch result.PrimaryOutcome {
case firewall.OutcomeBenign:
    return continueNormally(result)
case firewall.OutcomeSecretExposure:
    return redactAndSuppress(result)
case firewall.OutcomeInformationDisclosure:
    return requireReviewBeforeReturningPrivateData(result)
case firewall.OutcomeControlAbuse:
    return denyAndRequestExplicitConfirmation(result)
case firewall.OutcomeSystemCompromise:
    securityLog(result)
    return blockAndEscalate(result)
case firewall.OutcomeServiceDisruption:
    return blockDestructiveOrDisruptiveAction(result)
default:
    return blockByDefault(result)
}
```

### Java outcome handling

```java
BlockResult result = fw.classify(
    text,
    ClassifyOptions.builder()
        .hook(HookLabel.TOOL_RESPONSE)
        .toolName("read_file")
        .shadowMode(true)
        .build()
);

switch (result.primaryOutcome()) {
  case Outcome.BENIGN:
    return continueNormally(result);
  case Outcome.SECRET_EXPOSURE:
    return redactAndSuppress(result);
  case Outcome.INFORMATION_DISCLOSURE:
    return requireReviewBeforeReturningPrivateData(result);
  case Outcome.CONTROL_ABUSE:
    return denyAndRequestExplicitConfirmation(result);
  case Outcome.SYSTEM_COMPROMISE:
    securityLog(result);
    return blockAndEscalate(result);
  case Outcome.SERVICE_DISRUPTION:
    return blockDestructiveOrDisruptiveAction(result);
  default:
    return blockByDefault(result);
}
```

Recommended routing:
- `benign`: continue normally.
- `information_disclosure`: block or require review before returning private data.
- `secret_exposure`: redact or suppress secret-bearing content.
- `control_abuse`: deny the action and request explicit confirmation.
- `system_compromise`: block, security-log, and escalate.
- `service_disruption`: block destructive or disruptive actions.

## Java SDK

Current SDK version: 0.3.1
Package: com.silmaril.security:silmaril-security-sdk
Updated: June 2, 2026

Add the JVM SDK dependency and build one firewall client per protected system.

```kotlin
dependencies {
    implementation("com.silmaril.security:silmaril-security-sdk:0.3.1")
}
```

```java
Firewall fw = Firewall.builder()
    .apiKey(System.getenv("SILMARIL_API_KEY"))
    .apiUrl(System.getenv("SILMARIL_API_URL"))
    .build();

BlockResult result = fw.classify(
    userInput,
    ClassifyOptions.builder()
        .hook(HookLabel.USER_INPUT)
        .build()
);

fw.classify(
    toolOutput,
    ClassifyOptions.builder()
        .hook(HookLabel.TOOL_RESPONSE)
        .toolName("read_file")
        .build()
);
```

### Java shadow mode

```java
Firewall fw = Firewall.builder()
    .apiKey(System.getenv("SILMARIL_API_KEY"))
    .apiUrl(System.getenv("SILMARIL_API_URL"))
    .shadowMode(true)
    .onClassify(event -> {
        if (event.blocked() && event.shadowMode()) {
            telemetry.track("firewall.would_block", event.hook(), event.result().score());
        }
    })
    .build();

fw.classify(
    text,
    ClassifyOptions.builder()
        .hook(HookLabel.TOOL_RESPONSE)
        .shadowMode(false)
        .build()
);
```

### Java block handling

```java
try {
    fw.classify(userInput, options);
} catch (PromptBlockedException blocked) {
    audit(blocked.score(), blocked.threshold());
    return;
}
```

## Vercel AI SDK and Gateway

Use Silmaril middleware around the model object when Vercel owns model execution. Gateway routing and middleware can share the same firewall client.

```bash
npm install ai@^5 @ai-sdk/openai
```

```ts
import { gateway, generateText, wrapLanguageModel } from "ai";

const model = wrapLanguageModel({
  model: gateway("anthropic/claude-sonnet-4.6"),
  middleware: fw.asMiddleware({ scanOutput: true }),
});

await generateText({
  model,
  prompt: userInput,
  providerOptions: {
    gateway: { tags: ["surface:assistant"] },
  },
});
```

## LiteLLM Guardrails

Configure Silmaril as a LiteLLM generic guardrail with pre-call and post-call checks.

```yaml
guardrails:
  - guardrail_name: silmaril-firewall
    litellm_params:
      guardrail: generic_guardrail_api
      mode: [pre_call, post_call]
      api_base: os.environ/SILMARIL_GUARDRAIL_URL
      headers:
        x-api-key: os.environ/SILMARIL_API_KEY
      default_on: true
      unreachable_fallback: fail_open
      additional_provider_specific_params:
        on_error: warn
```

## Self-hosting

For customer-controlled deployments, run the firewall service and model as containers in the cloud account that holds the protected workload. SDKs use the deployed classify endpoint. LiteLLM uses the guardrail endpoint from the same stage.

Supported deployment targets include AWS ECS/EKS, Google Cloud Run/GKE, Azure Container Apps/AKS, and Oracle Cloud OKE.