safety net schema

schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/max-sixty/safety-net/main/sn/schema.json",
  "title": "Safety Net Configuration",
  "description": "Configuration schema for Safety Net secure sandboxing tool",
  "$comment": "This schema is descriptive, not prescriptive. The actual Safety Net implementation is the source of truth. If discrepancies are found, update this schema to match the implementation.",
  "type": "object",
  "required": ["image"],
  "properties": {
    "image": {
      "type": "string",
      "description": "The base Docker image to use",
      "examples": ["python:3.11-slim", "ubuntu:22.04", "node:20-alpine"]
    },
    "default-command": {
      "type": "string",
      "description": "Default command to run if none provided at CLI",
      "examples": ["python", "bash", "node"]
    },
    "on-create-command": {
      "type": "string",
      "description": "Command to run during docker build (RUN instruction)",
      "examples": [
        "apt-get update && apt-get install -y git",
        "pip install --upgrade pip"
      ]
    },
    "update-content-command": {
      "type": "string",
      "description": "Command to run after COPY in docker build",
      "examples": ["pip install -r requirements.txt", "npm install"]
    },
    "post-create-command": {
      "type": "string",
      "description": "Command to run synchronously before main command",
      "examples": ["echo 'Container ready!'", "python setup.py"]
    },
    "post-start-command": {
      "type": "string",
      "description": "Command to run asynchronously via docker exec after container starts",
      "examples": [
        "code-server --bind-addr 0.0.0.0:8080",
        "jupyter lab --ip=0.0.0.0"
      ]
    },
    "copy-files": {
      "type": "array",
      "description": "Files to COPY before update-content command",
      "items": {
        "type": "string"
      },
      "examples": [["requirements.txt"], ["package.json", "package-lock.json"]]
    },
    "mounts": {
      "type": "object",
      "description": "Volume mount configurations",
      "properties": {
        "ro": {
          "type": "array",
          "description": "Read-only mounts",
          "items": {
            "type": "string"
          },
          "examples": [["src", "config:/app/config", "~/.gitconfig"]]
        },
        "rw": {
          "type": "array",
          "description": "Read-write mounts",
          "items": {
            "type": "string"
          },
          "examples": [[".", "data", "/tmp/cache:/cache"]]
        }
      },
      "additionalProperties": false
    },
    "network": {
      "type": "object",
      "description": "Network configuration",
      "properties": {
        "mode": {
          "type": "string",
          "enum": ["none", "limited", "all"],
          "default": "all",
          "description": "Network access mode: none (no network), limited (allowlist), all (unrestricted)"
        },
        "domains-allowed": {
          "type": "array",
          "description": "Allowed domains when mode is 'limited'",
          "items": {
            "type": "string",
            "format": "hostname"
          },
          "examples": [["github.com", "pypi.org", "npmjs.com"]]
        },
        "forward-ports": {
          "type": "array",
          "description": "Port forwarding configurations",
          "items": {
            "oneOf": [
              {
                "type": "integer",
                "minimum": 1,
                "maximum": 65535
              },
              {
                "type": "string",
                "pattern": "^\\d{1,5}(:\\d{1,5})?(/[a-z]+)?$"
              }
            ]
          },
          "examples": [[8080, "3000", "8080:80", "53:53/udp"]]
        }
      },
      "additionalProperties": false
    },
    "limits": {
      "type": "object",
      "description": "Resource limits",
      "properties": {
        "cpu": {
          "type": "string",
          "pattern": "^\\d+(\\.\\d+)?$",
          "default": "2",
          "description": "CPU limit (number of cores)",
          "examples": ["1", "2", "0.5", "4"]
        },
        "mem": {
          "type": "string",
          "pattern": "^\\d+(\\.\\d+)?[kmgKMG][bB]?$",
          "default": "4g",
          "description": "Memory limit with unit suffix",
          "examples": ["512m", "2g", "4gb", "8G"]
        },
        "pids": {
          "type": "integer",
          "minimum": 1,
          "default": 512,
          "description": "Maximum number of processes"
        }
      },
      "additionalProperties": false
    },
    "features": {
      "type": "object",
      "description": "DevContainer features to install",
      "patternProperties": {
        "^[a-zA-Z0-9._/-]+$": {
          "oneOf": [
            {
              "type": "string",
              "description": "Feature version"
            },
            {
              "type": "object",
              "description": "Feature with options",
              "additionalProperties": true
            }
          ]
        }
      },
      "examples": [
        {
          "ghcr.io/devcontainers/features/python:1": "latest",
          "ghcr.io/devcontainers/features/node:1": {
            "version": "20",
            "installYarnUsingApt": false
          }
        }
      ]
    },
    "envs": {
      "type": "object",
      "description": "Static environment variables (replaces all defaults)",
      "patternProperties": {
        "^[A-Za-z_][A-Za-z0-9_]*$": {
          "type": "string"
        }
      },
      "examples": [
        {
          "PYTHONUNBUFFERED": "1",
          "NODE_ENV": "development",
          "DEBUG": "true"
        }
      ]
    },
    "envs-extend": {
      "type": "object",
      "description": "Environment variables that extend defaults (supports templates)",
      "patternProperties": {
        "^[A-Za-z_][A-Za-z0-9_]*$": {
          "type": "string"
        }
      },
      "examples": [
        {
          "USER_NAME": "${USER:-developer}",
          "HOME_DIR": "${HOME:-/home/user}",
          "CUSTOM_VAR": "value"
        }
      ]
    }
  },
  "additionalProperties": true
}