Security Policy

import {
  createSecurityPolicy,
  createPIIConfig,
  PIIType,
  RedactionAction,
  createInjectionDefenseConfig,
  InjectionSensitivity,
  InjectionAction,
  createNetworkPolicy,
  createTransformationRule,
  TransformDirection,
  createAuditConfig,
  createEnvSecurityConfig,
  createToxicityConfig,
  createCodeSecurityConfig,
  createInvisibleTextConfig,
  createContentGateConfig,
  ALL_TRAFFIC,
} from '@declaw/sdk';
import type {
  SecurityPolicy,
  PIIConfig,
  InjectionDefenseConfig,
  NetworkPolicy,
  TransformationRule,
  AuditConfig,
  AuditEntry,
  EnvSecurityConfig,
  SecureEnvVar,
  ToxicityConfig,
  CodeSecurityConfig,
  InvisibleTextConfig,
  ContentGateConfig,
} from '@declaw/sdk';

A SecurityPolicy is passed to Sandbox.create() via the security option. It composes PII detection, injection defense, network policy, transformation rules, audit logging, and environment variable security.

`createSecurityPolicy()`

Factory function for building a SecurityPolicy with defaults.

import { createSecurityPolicy, createPIIConfig, createInjectionDefenseConfig } from '@declaw/sdk';

const policy = createSecurityPolicy({
  pii: createPIIConfig({ enabled: true, action: 'redact' }),
  injectionDefense: createInjectionDefenseConfig({ enabled: true, action: 'block' }),
  audit: true,
});

const sbx = await Sandbox.create({
  security: policy,
  apiKey: 'key',
  domain: 'host:8080',
});

PIIConfig

default:"createPIIConfig()"

PII detection config. See PIIConfig.

boolean | InjectionDefenseConfig

default:"false"

Injection defense. Pass true for defaults, or an InjectionDefenseConfig for custom settings.

TransformationRule[]

default:"[]"

Regex transformation rules.

NetworkPolicy

Network allowlist/denylist. See NetworkPolicy.

boolean | AuditConfig

default:"false"

Audit logging. Pass true for defaults.

EnvSecurityConfig

default:"createEnvSecurityConfig()"

Environment variable masking config.

ToxicityConfig

Toxicity detection on outbound HTTP bodies. See ToxicityConfig.

CodeSecurityConfig

Code security scanner on outbound HTTP bodies. See CodeSecurityConfig.

InvisibleTextConfig

Invisible-unicode detection on outbound HTTP bodies. See InvisibleTextConfig.

CustomPolicyConfig

Attach OPA/Rego policy — a built-in governance pack via policyRef, or your own rules via inlineRego/inlineModules. See CustomPolicyConfig.

ContentGateConfig

Run the content.scan OPA gate (e.g. an LLM model allowlist / cross-signal rules) on the listed domains. See ContentGateConfig.

Returns SecurityPolicy

`SecurityPolicy` interface

interface SecurityPolicy {
  pii: PIIConfig;
  injectionDefense: boolean | InjectionDefenseConfig;
  transformations: TransformationRule[];
  network?: NetworkPolicy;
  audit: boolean | AuditConfig;
  envSecurity: EnvSecurityConfig;
  toxicity?: ToxicityConfig;
  codeSecurity?: CodeSecurityConfig;
  invisibleText?: InvisibleTextConfig;
  customPolicy?: CustomPolicyConfig;
  contentGate?: ContentGateConfig;
}

Helper functions

Function	Description
`parseSecurityPolicy(data)`	Deserialize a policy from raw JSON.
`securityPolicyToJSON(policy)`	Serialize a policy to a JSON-friendly object.
`requiresTlsInterception(policy)`	Returns `true` if PII, injection defense, or transforms are active.

`createPIIConfig()`

Configure PII detection and redaction on outbound HTTP traffic.

import { createPIIConfig, PIIType, RedactionAction } from '@declaw/sdk';

const pii = createPIIConfig({
  enabled: true,
  types: [PIIType.Email, PIIType.CreditCard, PIIType.SSN],
  action: RedactionAction.Redact,
  rehydrateResponse: false,
});

boolean

default:"false"

Whether PII scanning is active.

string[]

default:"all PIIType values"

PII types to scan for. Accepts PIIType enum values or their string equivalents.

string

default:"RedactionAction.Redact"

Action to take when PII is detected. One of RedactionAction.Redact, RedactionAction.Block, RedactionAction.LogOnly.

boolean

default:"true"

When true, replace redaction tokens in API responses with original values.

`PIIType` enum

enum PIIType {
  SSN         = 'ssn',
  CreditCard  = 'credit_card',
  Email       = 'email',
  Phone       = 'phone',
  PersonName  = 'person_name',
  APIKey      = 'api_key',
  Address     = 'address',
  IPAddress   = 'ip_address',
}

`RedactionAction` enum

enum RedactionAction {
  Redact  = 'redact',    // Replace with a placeholder token
  Block   = 'block',     // Reject the request (HTTP 403)
  LogOnly = 'log_only',  // Log but forward unchanged
}

`PIIConfig` interface

interface PIIConfig {
  enabled: boolean;
  types: string[];
  action: string;
  rehydrateResponse: boolean;
}

`createInjectionDefenseConfig()`

Configure prompt injection detection on outbound HTTP request bodies.

import { createInjectionDefenseConfig, InjectionSensitivity, InjectionAction } from '@declaw/sdk';

const injection = createInjectionDefenseConfig({
  enabled: true,
  sensitivity: InjectionSensitivity.High,
  action: InjectionAction.Block,
});

boolean

default:"false"

Whether injection defense is active.

string

default:"InjectionSensitivity.Medium"

Sensitivity level. One of InjectionSensitivity.Low, Medium, High. Higher sensitivity catches more patterns but may produce false positives.

string

default:"InjectionAction.LogOnly"

Action when injection is detected. One of InjectionAction.Block or InjectionAction.LogOnly.

number

default:"0.8"

Detection threshold (0.0–1.0). Sent to the API alongside sensitivity so the SDK wire format matches the Python SDK’s numeric-threshold form.

string[]

Optional domain allowlist. When omitted, injection defense applies to all outbound destinations.

`InjectionSensitivity` enum

enum InjectionSensitivity {
  Low    = 'low',
  Medium = 'medium',
  High   = 'high',
}

`InjectionAction` enum

enum InjectionAction {
  Block    = 'block',     // Reject the request (HTTP 403)
  LogOnly  = 'log_only',  // Log and forward unchanged
}

`InjectionDefenseConfig` interface

interface InjectionDefenseConfig {
  enabled: boolean;
  sensitivity: string;
  action: string;
  threshold: number;
  domains?: string[];
}

The TypeScript SDK uses sensitivity (low/medium/high) for injection thresholds. The Python SDK uses a numeric threshold (0.0–1.0). The API accepts both representations.

`createNetworkPolicy()`

Define which outbound connections the sandbox is allowed to make.

import { createNetworkPolicy, ALL_TRAFFIC } from '@declaw/sdk';

const network = createNetworkPolicy({
  allowOut: ['api.openai.com', 'pypi.org', '*.github.com'],
  denyOut: [ALL_TRAFFIC],
  allowPublicTraffic: false,
});

string[]

default:"[]"

Destinations to allow. Accepts IP addresses, CIDR blocks, and domain names with optional *. wildcard prefix.

string[]

default:"[]"

Destinations to deny. Accepts IP addresses and CIDR blocks.

boolean

default:"true"

Whether all public traffic is allowed by default. Set to false when using allowOut as an allowlist.

string

Replace the Host header in all outbound requests with this value.

`ALL_TRAFFIC` constant

const ALL_TRAFFIC: string = '0.0.0.0/0';

`NetworkPolicy` interface

interface NetworkPolicy {
  allowOut: string[];
  denyOut: string[];
  allowPublicTraffic: boolean;
  maskRequestHost?: string;
}

`createTransformationRule()`

Create a regex-based transformation rule with validation. The factory checks for ReDoS-vulnerable patterns (nested quantifiers) and validates the regex syntax before returning the rule.

import { createTransformationRule, TransformDirection } from '@declaw/sdk';

const rule = createTransformationRule({
  match: 'Bearer [A-Za-z0-9\\-_\\.]+',
  replace: 'Bearer [REDACTED]',
  direction: TransformDirection.Outbound,
});

string

required

Valid JavaScript regex pattern (max 1000 characters). Must not contain nested quantifiers.

string

required

Replacement string. Supports regex back-references (e.g. $1).

string

default:"TransformDirection.Both"

Direction to apply the rule. One of 'outbound', 'inbound', 'both'.

`TransformDirection` enum

enum TransformDirection {
  Outbound = 'outbound',
  Inbound  = 'inbound',
  Both     = 'both',
}

`TransformationRule` interface

interface TransformationRule {
  match: string;
  replace: string;
  direction: string;
}

`createAuditConfig()`

Toggle whether lifecycle and security events for the sandbox are shipped to Declaw’s audit log.

import { createAuditConfig } from '@declaw/sdk';

// Opt out of audit logging for this sandbox
const audit = createAuditConfig({ enabled: false });

boolean

default:"true"

When true (the default), the orchestrator records the sandbox’s lifecycle events (create, kill, pause, resume, snapshot) and security decisions (egress allow/block) to the audit log. Set to false to suppress all audit events for the sandbox.

Audit log retention is a platform-wide setting (currently a 7-day rolling window) and is not configurable per sandbox. Request and response body logging is not exposed to callers.

`AuditConfig` interface

interface AuditConfig {
  enabled: boolean;
}

`AuditEntry` interface

interface AuditEntry {
  timestamp: Date;
  method: string;
  url: string;
  statusCode: number;
  piiRedactions: number;
  injectionBlocks: number;
  transformationsApplied: number;
  direction: string;
}

`createEnvSecurityConfig()`

Control how environment variable values are masked in audit logs.

import { createEnvSecurityConfig, DEFAULT_MASK_PATTERNS } from '@declaw/sdk';

const envSec = createEnvSecurityConfig({
  maskPatterns: [...DEFAULT_MASK_PATTERNS, '*_PRIVATE_*'],
  autoMaskInAudit: true,
});

string[]

default:"DEFAULT_MASK_PATTERNS"

Glob patterns matched against uppercase variable names. Default: ['*_KEY', '*_SECRET', '*_TOKEN', '*_PASSWORD', '*_CREDENTIALS', 'API_KEY', 'SECRET_KEY'].

boolean

default:"true"

Automatically redact matching variable values in audit logs.

`EnvSecurityConfig` interface

interface EnvSecurityConfig {
  maskPatterns: string[];
  autoMaskInAudit: boolean;
}

`SecureEnvVar` interface

interface SecureEnvVar {
  key: string;
  value: string;
  secret: boolean;
}

`createToxicityConfig()`

Configure toxicity detection on outbound HTTP request bodies.

import { createToxicityConfig } from '@declaw/sdk';

const toxicity = createToxicityConfig({
  enabled: true,
  threshold: 0.9,
  action: 'block',
});

boolean

default:"false"

Whether toxicity detection is active.

number

default:"0.9"

Detection threshold in 0.0–1.0. Higher values fire only on more confident detections.

'block' | 'log_only'

default:"'block'"

Action when toxicity is detected.

string[]

Optional domain allowlist. When omitted, applies to all outbound destinations.

`ToxicityConfig` interface

interface ToxicityConfig {
  enabled: boolean;
  threshold: number;
  action: 'block' | 'log_only';
  domains?: string[];
}

`createCodeSecurityConfig()`

Configure the code-security scanner for outbound HTTP request bodies.

import { createCodeSecurityConfig } from '@declaw/sdk';

const codeSec = createCodeSecurityConfig({
  enabled: true,
  threshold: 0.6,
  excludedLanguages: ['markdown'],
  action: 'log_only',
});

boolean

default:"false"

Whether code-security scanning is active.

number

default:"0.6"

Detection threshold in 0.0–1.0.

string[]

Languages to skip. When omitted, all detected languages are scanned.

'block' | 'log_only'

default:"'log_only'"

Action when a security issue is detected.

string[]

Optional domain allowlist. When omitted, applies to all outbound destinations.

`CodeSecurityConfig` interface

interface CodeSecurityConfig {
  enabled: boolean;
  threshold: number;
  excludedLanguages?: string[];
  action: 'block' | 'log_only';
  domains?: string[];
}

`createInvisibleTextConfig()`

Detect and handle zero-width or otherwise invisible Unicode characters in outbound HTTP bodies.

import { createInvisibleTextConfig } from '@declaw/sdk';

const invisible = createInvisibleTextConfig({
  enabled: true,
  action: 'strip',
});

boolean

default:"false"

Whether invisible-text detection is active.

'block' | 'strip' | 'log_only'

default:"'strip'"

Action when invisible characters are detected.

string[]

Optional domain allowlist. When omitted, applies to all outbound destinations.

`InvisibleTextConfig` interface

interface InvisibleTextConfig {
  enabled: boolean;
  action: 'block' | 'strip' | 'log_only';
  domains?: string[];
}

`CustomPolicyConfig`

Attach OPA/Rego policy — a built-in governance pack via policyRef, or your own rules via inlineRego/inlineModules. Custom rules are evaluated at the enforcement layer alongside the platform defaults and can only tighten policy, never relax it. Set it as a plain object on customPolicy:

// Reference a built-in governance pack
const policy = createSecurityPolicy({
  customPolicy: {
    enabled: true,
    policyRef: 'owasp-llm-top10@v1',
    defaultDeny: false,
  },
});

// Or supply your own Rego
const policy = createSecurityPolicy({
  customPolicy: {
    enabled: true,
    inlineRego: `
      deny_command contains msg if {
        input.action.command in {"rm", "dd"}
        msg := "dangerous command blocked"
      }
    `,
  },
});

boolean

default:"false"

Whether custom policy evaluation is active for the sandbox.

string

A single Rego module string appended to the platform defaults. Use this for a single-package policy.

string[]

A list of independent Rego module strings, each its own package. Use this when your policy spans multiple packages; for a single package use inlineRego instead.

string

Reference a published or built-in policy bundle by name@version (e.g. owasp-llm-top10@v1), sha256:<hex>, or blob:<key>. See Governance Packs for the catalog.

boolean

default:"false"

Fail-closed behavior: when true, an evaluator error or unreachable engine denies the action. Fail-closed is safer for hard security gates; fail-open (false) is acceptable for advisory-only scanners.

`CustomPolicyConfig` interface

interface CustomPolicyConfig {
  enabled: boolean;
  inlineRego?: string;
  inlineModules?: string[];
  policyRef?: string;
  defaultDeny?: boolean;
}

See Custom Policy and Governance Packs for the full guides.

`createContentGateConfig()`

Run the content.scan OPA gate (e.g. an LLM model allowlist / cross-signal rules) on the listed domains. Opts a sandbox into content-gate enforcement without requiring an ML scanner to be enabled.

import { createContentGateConfig } from '@declaw/sdk';

const contentGate = createContentGateConfig({
  enabled: true,
  domains: ['api.openai.com', 'api.anthropic.com'],
});

boolean

default:"false"

Whether the content gate is active.

string[]

Opt-in list of destination hosts to intercept. Omitted or empty means no hosts are intercepted.

`ContentGateConfig` interface

interface ContentGateConfig {
  enabled: boolean;
  domains?: string[];
}

See Custom Policy for details.

Full policy example

import {
  Sandbox,
  createSecurityPolicy,
  createPIIConfig,
  PIIType,
  RedactionAction,
  createInjectionDefenseConfig,
  InjectionSensitivity,
  InjectionAction,
  createNetworkPolicy,
  createTransformationRule,
  TransformDirection,
  createAuditConfig,
  createContentGateConfig,
  ALL_TRAFFIC,
} from '@declaw/sdk';

const policy = createSecurityPolicy({
  pii: createPIIConfig({
    enabled: true,
    types: [PIIType.Email, PIIType.SSN, PIIType.CreditCard],
    action: RedactionAction.Redact,
    rehydrateResponse: true,
  }),
  injectionDefense: createInjectionDefenseConfig({
    enabled: true,
    sensitivity: InjectionSensitivity.High,
    action: InjectionAction.Block,
  }),
  network: createNetworkPolicy({
    allowOut: ['api.openai.com', 'pypi.org'],
    denyOut: [ALL_TRAFFIC],
    allowPublicTraffic: false,
  }),
  transformations: [
    createTransformationRule({
      match: 'sk-[A-Za-z0-9]+',
      replace: 'sk-[REDACTED]',
      direction: TransformDirection.Outbound,
    }),
  ],
  customPolicy: {
    enabled: true,
    policyRef: 'owasp-llm-top10@v1',
  },
  contentGate: createContentGateConfig({
    enabled: true,
    domains: ['api.openai.com'],
  }),
  audit: createAuditConfig({ enabled: true }),
});

const sbx = await Sandbox.create({
  security: policy,
  apiKey: 'your-api-key',
  domain: '104.198.24.180:8080',
});

​createSecurityPolicy()

​SecurityPolicy interface

​Helper functions

​createPIIConfig()

​PIIType enum

​RedactionAction enum

​PIIConfig interface

​createInjectionDefenseConfig()

​InjectionSensitivity enum

​InjectionAction enum

​InjectionDefenseConfig interface

​createNetworkPolicy()

​ALL_TRAFFIC constant

​NetworkPolicy interface

​createTransformationRule()

​TransformDirection enum

​TransformationRule interface

​createAuditConfig()

​AuditConfig interface

​AuditEntry interface

​createEnvSecurityConfig()

​EnvSecurityConfig interface

​SecureEnvVar interface

​createToxicityConfig()

​ToxicityConfig interface

​createCodeSecurityConfig()

​CodeSecurityConfig interface

​createInvisibleTextConfig()

​InvisibleTextConfig interface

​CustomPolicyConfig

​CustomPolicyConfig interface

​createContentGateConfig()

​ContentGateConfig interface

​Full policy example

`createSecurityPolicy()`

`SecurityPolicy` interface

Helper functions

`createPIIConfig()`

`PIIType` enum

`RedactionAction` enum

`PIIConfig` interface

`createInjectionDefenseConfig()`

`InjectionSensitivity` enum

`InjectionAction` enum

`InjectionDefenseConfig` interface

`createNetworkPolicy()`

`ALL_TRAFFIC` constant

`NetworkPolicy` interface

`createTransformationRule()`

`TransformDirection` enum

`TransformationRule` interface

`createAuditConfig()`

`AuditConfig` interface

`AuditEntry` interface

`createEnvSecurityConfig()`

`EnvSecurityConfig` interface

`SecureEnvVar` interface

`createToxicityConfig()`

`ToxicityConfig` interface

`createCodeSecurityConfig()`

`CodeSecurityConfig` interface

`createInvisibleTextConfig()`

`InvisibleTextConfig` interface

`CustomPolicyConfig`

`CustomPolicyConfig` interface

`createContentGateConfig()`

`ContentGateConfig` interface

Full policy example