Verdicts and outcomes

prediction is the authoritative BENIGN or MALICIOUS verdict. primary_outcome is a forward-compatible string: SDKs expose constants for known labels, but deployments can return additional labels. Treat the constants as routing conveniences rather than a closed verdict enum. The backend wire fields are prediction, primary_outcome, outcome_scores, detector_scores, and detector_counts. Handler functions such as continueNormally and redactAndSuppress in these examples belong to your application.

Prerequisites

Initialize the SDK client for your runtime and classify a boundary.

The SDK examples use the client initialized in the matching setup guide. In Block mode, Python and Go expose an enforced block through its error; the examples retain that verdict for routing. TypeScript returns the verdict directly. The Java example routes a parsed HTTP response using the public wire fields, without an SDK dependency.

Outcome taxonomy

In Block mode, continue only when prediction is benign and no applicable governance policy blocks the request. For malicious results, route the primary outcome using this table of known legacy labels. The table is not exhaustive. Block by default if the outcome is missing or unrecognized.

Outcome	Meaning	Recommended action
`benign`	No harmful outcome detected. Check `prediction` for the verdict.	Continue if governance policy also allows the request.
`information_disclosure`	Exposure of private data, documents, internal context, logs, or other non-secret sensitive information.	Block or require review before returning private data.
`secret_exposure`	Exposure of credentials, tokens, keys, cookies, passwords, or other secrets.	Redact or suppress secret-bearing content.
`control_abuse`	Misuse of authorized tools or user privileges without a stronger outcome.	Deny the action and request explicit confirmation.
`system_compromise`	Privilege escalation, takeover, persistence, lateral movement, or hostile code execution.	Block, record a security event, and escalate.
`service_disruption`	Downtime, lockout, degradation, resource exhaustion, cost spikes, or destructive activity.	Block destructive or disruptive actions.

Route a result in Block mode

This example enforces blocking. For observational behavior, record the verdict and continue according to your effective mode.

import { Firewall, HookLabel, Outcome } from "@silmaril-security/sdk"

async function classifyAndRoute(fw: Firewall, text: string) {
  const result = await fw.classify(text, {
    hook: HookLabel.TOOL_RESPONSE,
    toolName: "read_file",
    mode: "block",
  })

  if (result.governance?.action === "block") {
    return denyByPolicy(result)
  }

  if (result.prediction === "BENIGN") {
    return continueNormally(result)
  }

  switch (result.primaryOutcome) {
    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)
  }
}

from silmaril_security.sdk import FirewallBlockedException, HookLabel

def classify_and_route(fw, text):
    try:
        result = fw.classify(
            text,
            hook=HookLabel.TOOL_RESPONSE,
            tool_name="read_file",
            mode="block",
        )
    except FirewallBlockedException as blocked:
        result = blocked.result

    if result.governance is not None and result.governance.action == "block":
        return deny_by_policy(result)
    if result.prediction == "BENIGN":
        return continue_normally(result)

    match result.primary_outcome:
        case "secret_exposure":
            return redact_and_suppress(result)
        case "information_disclosure":
            return require_review_before_returning_private_data(result)
        case "control_abuse":
            return deny_and_request_explicit_confirmation(result)
        case "system_compromise":
            security_log(result)
            return block_and_escalate(result)
        case "service_disruption":
            return block_destructive_or_disruptive_action(result)
        case _:
            return block_by_default(result)

import (
    "context"
    "errors"
    "github.com/Silmaril-Security/sdk-go/firewall"
)

func classifyAndRoute(ctx context.Context, fw *firewall.Firewall, text string) error {
    result, err := fw.Classify(ctx, text,
        firewall.WithHook(firewall.HookToolResponse),
        firewall.WithToolName("read_file"),
        firewall.WithMode(firewall.ModeBlock),
    )
    if err != nil {
        var blocked *firewall.FirewallBlockedError
        if !errors.As(err, &blocked) {
            return err // A request failure has no verdict to route.
        }
        result = blocked.Result
    }

    if result.Governance != nil && result.Governance.Action == firewall.GovernanceBlock {
        return denyByPolicy(result)
    }
    if result.Prediction == firewall.PredictionBenign {
        return continueNormally(result)
    }

    switch result.PrimaryOutcome {
    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)
    }
}

import java.util.Map;

// Inside your service class; result is the parsed JSON response from /classify.
static String routeInBlockMode(Map<String, Object> result) {
    if (result.get("governance") instanceof Map<?, ?> governance
            && "block".equals(governance.get("action"))) {
        return "deny_by_policy";
    }
    if ("BENIGN".equals(result.get("prediction"))) {
        return "continue_normally";
    }
    if (!(result.get("primary_outcome") instanceof String outcome)) {
        return "block_by_default";
    }
    return switch (outcome) {
        case "secret_exposure" -> "redact_and_suppress";
        case "information_disclosure" -> "require_review_before_returning_private_data";
        case "control_abuse" -> "deny_and_request_explicit_confirmation";
        case "system_compromise" -> "block_and_escalate";
        case "service_disruption" -> "block_destructive_or_disruptive_action";
        default -> "block_by_default";
    };
}

The TypeScript, Python, and Go handlers belong to your application; every handler except continueNormally or continue_normally must stop the event. Go handlers return an error, and securityLog records the event. The Java 17 example accepts a JSON object decoded by your application’s JSON library and returns an action name: dispatch that action before consuming the event, record security events for block_and_escalate, and allow the event only for continue_normally. For a Java SDK block, retain FirewallBlockedException.result() as described in Java errors.

Expected result

A benign prediction invokes your continue handler. A governance-policy block is denied before the prediction is checked. A malicious prediction invokes the matching outcome handler, or the default blocking handler when no outcome matches.

Field names

API response	TypeScript	Python	Go	Java HTTP map
`prediction`	`prediction`	`prediction`	`Prediction`	`get("prediction")`
`primary_outcome`	`primaryOutcome`	`primary_outcome`	`PrimaryOutcome`	`get("primary_outcome")`
`governance.action`	`governance?.action`	`governance.action` when present	`Governance.Action` when present	`get("action")` on the governance map

Read optional governance fields only when the decision is present. See events and conversations for request fields.

Start

Integrations

Guides

Operate

Deployment

SDK reference

Architecture

Prerequisites

Outcome taxonomy

Route a result in Block mode

Expected result

Field names

​Prerequisites

​Outcome taxonomy

​Route a result in Block mode

​Expected result

​Field names

Prerequisites

Outcome taxonomy

Route a result in Block mode

Expected result

Field names