AI-SDLC
AI-SDLC
API Reference

Security

Security

Enterprise security primitives: sandboxed execution, JIT credential issuance, kill switches, and approval workflows.

Import

import {
  // Interfaces
  type NetworkPolicy,
  type SandboxConstraints,
  type SandboxStatus,
  type Sandbox,
  type SecretStore,
  type JITCredential,
  type JITCredentialIssuer,
  type KillSwitch,
  type ApprovalTier,
  type ApprovalStatus,
  type ApprovalRequest,
  type ApprovalWorkflow,

  // Approval classification
  classifyApprovalTier,
  compareTiers,
  type ApprovalClassificationInput,

  // Stubs (for testing)
  createStubSandbox,
  createStubJITCredentialIssuer,
  createStubKillSwitch,
  createStubApprovalWorkflow,

  // GitHub implementations
  createGitHubSandbox,
  createGitHubJITCredentialIssuer,
  type GitHubSandboxConfig,
  type GitHubJITConfig,

  // Docker sandbox
  createDockerSandbox,
  type DockerSandboxConfig,

  // OpenShell sandbox
  createOpenShellSandbox,
  isOpenShellAvailable,
  buildSandboxExecPrefix,
  generateOpenShellPolicy,
  serializePolicy,
  type OpenShellSandboxConfig,
  type OpenShellPolicy,
  type ProviderCredential,

  // Secret store
  createEnvSecretStore,
} from '@ai-sdlc/reference';

Interfaces

Sandbox

Sandboxed execution environment for agent code.

interface Sandbox {
  create(constraints: SandboxConstraints): Promise<SandboxStatus>;
  destroy(id: string): Promise<void>;
  getStatus(id: string): Promise<SandboxStatus>;
  execute(id: string, command: string): Promise<{ stdout: string; stderr: string; exitCode: number }>;
}

JITCredentialIssuer

Just-in-time credential issuance with automatic expiration.

interface JITCredentialIssuer {
  issue(scope: string[], ttl: string): Promise<JITCredential>;
  revoke(credentialId: string): Promise<void>;
}

KillSwitch

Emergency stop mechanism for agent operations.

interface KillSwitch {
  activate(reason: string): Promise<void>;
  deactivate(): Promise<void>;
  isActive(): Promise<boolean>;
  getReason(): Promise<string | undefined>;
}

ApprovalWorkflow

Multi-tier approval workflow for sensitive operations.

interface ApprovalWorkflow {
  request(request: ApprovalRequest): Promise<string>;  // returns request ID
  approve(requestId: string, approver: string): Promise<ApprovalStatus>;
  reject(requestId: string, approver: string, reason: string): Promise<ApprovalStatus>;
  getStatus(requestId: string): Promise<ApprovalStatus>;
}

SecretStore

interface SecretStore {
  get(name: string): Promise<string | undefined>;
  set(name: string, value: string): Promise<void>;
  delete(name: string): Promise<void>;
  list(): Promise<string[]>;
}

Functions

classifyApprovalTier(input)

Classify an operation into an approval tier based on its characteristics.

function classifyApprovalTier(input: ApprovalClassificationInput): ApprovalTier;

Tiers: 'auto', 'peer-review', 'team-lead', 'security-review'.

compareTiers(a, b)

Compare two approval tiers. Returns negative if a < b, zero if equal, positive if a > b.

Implementations

createGitHubSandbox(config)

Create a Sandbox backed by GitHub Codespaces.

function createGitHubSandbox(config: GitHubSandboxConfig): Sandbox;

createGitHubJITCredentialIssuer(config)

Create a JITCredentialIssuer backed by GitHub repository secrets.

function createGitHubJITCredentialIssuer(config: GitHubJITConfig): JITCredentialIssuer;

createDockerSandbox(config)

Create a Sandbox backed by Docker containers.

function createDockerSandbox(config: DockerSandboxConfig): Sandbox;

createOpenShellSandbox(exec, config)

Create a Sandbox backed by NVIDIA OpenShell for kernel-level agent isolation using Landlock LSM, seccomp, and network policy enforcement. Security is enforced at the infrastructure layer — agents cannot override policies even if compromised.

function createOpenShellSandbox(exec: ShellExec, config?: OpenShellSandboxConfig): Sandbox;

Config options:

FieldTypeDescription
blockedPathsstring[]Paths the agent is blocked from accessing
workDirstringWorking directory to mount into the sandbox
networkEndpointsRecord<string, ...>Named network endpoints to allow
providersstring[]Pre-existing OpenShell providers to attach
autoProvidersProviderCredential[]Credentials to auto-create as providers
binaryPathstringPath to openshell binary (default: 'openshell')

Example:

import { createOpenShellSandbox, isOpenShellAvailable } from '@ai-sdlc/reference';
import { exec } from 'node:child_process';
import { promisify } from 'node:util';

const execAsync = (cmd: string) => promisify(exec)(cmd).then(r => r.stdout);

if (await isOpenShellAvailable(execAsync)) {
  const sandbox = createOpenShellSandbox(execAsync, {
    workDir: '/home/runner/work/repo',
    blockedPaths: ['.github/workflows/**', '.ai-sdlc/**'],
    autoProviders: [
      { name: 'claude', type: 'claude' },
      { name: 'github', type: 'github' },
    ],
    networkEndpoints: {
      anthropic: [{ host: 'api.anthropic.com', port: 443, access: 'full' }],
      github: [{ host: 'api.github.com', port: 443, access: 'read-write' }],
    },
  });

  const id = await sandbox.isolate('task-42', {
    maxMemoryMb: 512,
    maxCpuPercent: 80,
    networkPolicy: 'egress-only',
    timeoutMs: 1_800_000,
    allowedPaths: ['/home/runner/work/repo'],
  });

  // Agent runs inside sandbox via: openshell sandbox connect <id> -- claude ...
  // ...

  await sandbox.destroy(id); // downloads results, deletes sandbox, purges credentials
}

generateOpenShellPolicy(options)

Generate an OpenShell policy YAML structure from AI-SDLC configuration.

function generateOpenShellPolicy(options: PolicyGenerationOptions): OpenShellPolicy;

Maps SandboxConstraints, blockedPaths, and networkEndpoints to OpenShell policy format. The autonomyLevel parameter controls policy strictness:

LevelLandlockNetwork
0 (Observer)hard_requirementNo network (deny all)
1 (Junior)best_effortConfigured endpoints only
2+best_effortFull configured network

serializePolicy(policy)

Serialize an OpenShellPolicy object to YAML string.

isOpenShellAvailable(exec)

Check if the openshell CLI is available on the system. Returns true if openshell --version succeeds.

buildSandboxExecPrefix(sandboxName, binaryPath?)

Build the command prefix array for executing a command inside an OpenShell sandbox. Used by runners to spawn agents within isolated environments.

const prefix = buildSandboxExecPrefix('my-sandbox');
// ['openshell', 'sandbox', 'connect', 'my-sandbox', '--']

createEnvSecretStore()

Create a SecretStore backed by environment variables. Secret names are converted from kebab-case to UPPER_SNAKE_CASE.

Stubs (Testing)

FactoryReturns
createStubSandbox()In-memory Sandbox
createStubJITCredentialIssuer()In-memory JITCredentialIssuer
createStubKillSwitch()In-memory KillSwitch
createStubApprovalWorkflow()In-memory ApprovalWorkflow
import { createStubKillSwitch } from '@ai-sdlc/reference';

const ks = createStubKillSwitch();
console.log(await ks.isActive()); // false
await ks.activate('Security incident detected');
console.log(await ks.isActive()); // true
console.log(await ks.getReason()); // 'Security incident detected'
await ks.deactivate();

Telemetry

Previous Page

Compliance

Next Page

On this page

SecurityImportInterfacesSandboxJITCredentialIssuerKillSwitchApprovalWorkflowSecretStoreFunctionsclassifyApprovalTier(input)compareTiers(a, b)ImplementationscreateGitHubSandbox(config)createGitHubJITCredentialIssuer(config)createDockerSandbox(config)createOpenShellSandbox(exec, config)generateOpenShellPolicy(options)serializePolicy(policy)isOpenShellAvailable(exec)buildSandboxExecPrefix(sandboxName, binaryPath?)createEnvSecretStore()Stubs (Testing)