> ## Documentation Index
> Fetch the complete documentation index at: https://silmaril.security/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Verdicts and outcomes

> Use prediction as the benign or malicious verdict, then route optional malicious detail with typed outcome constants.

`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.

* [TypeScript](https://silmaril.security/docs/sdk/typescript.md)
* [Python](https://silmaril.security/docs/sdk/python.md)
* [Go](https://silmaril.security/docs/sdk/go.md)
* [Java](https://silmaril.security/docs/sdk/java.md)

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](https://silmaril.security/docs/guides/enforcement.md).

```typescript TypeScript theme={"theme":"github-light-default"}
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)
  }
}
```

```python Python theme={"theme":"github-light-default"}
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)
```

```go Go theme={"theme":"github-light-default"}
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)
    }
}
```

```java Java theme={"theme":"github-light-default"}
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](https://silmaril.security/docs/sdk/java.md#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](https://silmaril.security/docs/guides/events.md) for request fields.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.