max-sixty · June 19, 2025 17:00
diff --git a/schema.json b/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",
  "properties": {
    "version": {
      "type": "integer",
      "description": "Config file version. Currently must be 0 (no backward compatibility).",
      "default": 0,
      "enum": [0]
    },
    "image": {
      "type": ["string", "null"],
      "description": "The base Docker image to use. Can be null for addon configs that are meant to be combined with base configs.",
      "examples": ["python:3.11-slim", "ubuntu:22.04", "node:20-alpine", null]
    },
    "default-command": {
      "type": "string",
      "description": "Default command to run if none provided at CLI",
      "examples": ["python", "bash", "node"]
    },
    "initialize-command": {
      "oneOf": [
        {
          "type": "string",
          "description": "Single command to run on host before container creation"
        },
        {
          "type": "object",
          "description": "Named commands to run on host before container creation",
          "patternProperties": {
            "^[a-zA-Z0-9._-]+$": {
              "type": "string"
            }
          },
          "additionalProperties": false
        }
      ],
      "description": "Command(s) to run on host machine before building or starting container",
      "examples": [
        "mkdir -p output",
        "wget https://example.com/data.csv",
        {
          "download": "wget https://example.com/data.csv",
          "prepare": "mkdir -p output logs"
        }
      ]
    },
    "on-create-command": {
      "oneOf": [
        {
          "type": "string",
          "description": "Single command to run during docker build"
        },
        {
          "type": "object",
          "description": "Named commands to run during docker build",
          "patternProperties": {
            "^[a-zA-Z0-9._-]+$": {
              "type": "string"
            }
          },
          "additionalProperties": false
        }
      ],
      "description": "Command(s) to run during docker build (RUN instruction)",
      "examples": [
        "apt-get update && apt-get install -y git",
        "pip install --upgrade pip",
        {
          "update": "apt-get update",
          "install": "apt-get install -y git curl"
        }
      ]
    },
    "update-content-command": {
      "oneOf": [
        {
          "type": "string",
          "description": "Single command to run after COPY"
        },
        {
          "type": "object",
          "description": "Named commands to run after COPY",
          "patternProperties": {
            "^[a-zA-Z0-9._-]+$": {
              "type": "string"
            }
          },
          "additionalProperties": false
        }
      ],
      "description": "Command(s) to run after COPY in docker build",
      "examples": [
        "pip install -r requirements.txt",
        "npm install",
        {
          "backend": "pip install -r requirements.txt",
          "frontend": "npm install"
        }
      ]
    },
    "post-create-command": {
      "oneOf": [
        {
          "type": "string",
          "description": "Single command to run before main command"
        },
        {
          "type": "object",
          "description": "Named commands to run before main command",
          "patternProperties": {
            "^[a-zA-Z0-9._-]+$": {
              "type": "string"
            }
          },
          "additionalProperties": false
        }
      ],
      "description": "Command(s) to run synchronously before main command",
      "examples": [
        "echo 'Container ready!'",
        "python setup.py",
        {
          "setup": "python setup.py",
          "cache": "python warm_cache.py"
        }
      ]
    },
    "post-start-command": {
      "oneOf": [
        {
          "type": "string",
          "description": "Single command to run asynchronously"
        },
        {
          "type": "object",
          "description": "Named commands to run asynchronously",
          "patternProperties": {
            "^[a-zA-Z0-9._-]+$": {
              "type": "string"
            }
          },
          "additionalProperties": false
        }
      ],
      "description": "Command(s) 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",
        {
          "server": "code-server --bind-addr 0.0.0.0:8080",
          "jupyter": "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"
        }
      ]
    },
    "forbid-dangerous-mounts": {
      "type": "boolean",
      "default": true,
      "description": "Prevent mounting sensitive paths like /etc, /var/run/docker.sock, etc. that grant system-level access. Set to false ONLY for trusted development environments. When false, containers can mount ANY path including system directories, potentially gaining root access to the host."
    },
    "privileged": {
      "type": "boolean",
      "default": false,
      "description": "Run container in privileged mode. This grants the container almost all capabilities of the host. Required for Docker-in-Docker (DinD) setups. Use with extreme caution as it significantly reduces container isolation."
    },
    "mount-worktree-metadata": {
      "type": "boolean",
      "default": false,
      "description": "Enable git worktree support by mounting git metadata from the main repository. When enabled, Safety Net will detect if running from a worktree and mount the main repository's .git directory to enable git operations inside the container. Only works for sibling worktrees (worktree and main repo in same parent directory)."
    },
    "monitoring": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["claude-code"]
      },
      "default": [],
      "description": "List of monitoring providers to enable. Currently only 'claude-code' is supported. When 'claude-code' is included, runs an OpenTelemetry Collector sidecar to receive and expose metrics for Claude Code sessions."
    }
  },
  "additionalProperties": true
 }
	{
	"$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",
	"properties": {
	"version": {
	"type": "integer",
	"description": "Config file version. Currently must be 0 (no backward compatibility).",
	"default": 0,
	"enum": [0]
	},
	"image": {
	"type": ["string", "null"],
	"description": "The base Docker image to use. Can be null for addon configs that are meant to be combined with base configs.",
	"examples": ["python:3.11-slim", "ubuntu:22.04", "node:20-alpine", null]
	},
	"default-command": {
	"type": "string",
	"description": "Default command to run if none provided at CLI",
	"examples": ["python", "bash", "node"]
	},
	"initialize-command": {
	"oneOf": [
	{
	"type": "string",
	"description": "Single command to run on host before container creation"
	},
	{
	"type": "object",
	"description": "Named commands to run on host before container creation",
	"patternProperties": {
	"^[a-zA-Z0-9._-]+$": {
	"type": "string"
	}
	},
	"additionalProperties": false
	}
	],
	"description": "Command(s) to run on host machine before building or starting container",
	"examples": [
	"mkdir -p output",
	"wget https://example.com/data.csv",
	{
	"download": "wget https://example.com/data.csv",
	"prepare": "mkdir -p output logs"
	}
	]
	},
	"on-create-command": {
	"oneOf": [
	{
	"type": "string",
	"description": "Single command to run during docker build"
	},
	{
	"type": "object",
	"description": "Named commands to run during docker build",
	"patternProperties": {
	"^[a-zA-Z0-9._-]+$": {
	"type": "string"
	}
	},
	"additionalProperties": false
	}
	],
	"description": "Command(s) to run during docker build (RUN instruction)",
	"examples": [
	"apt-get update && apt-get install -y git",
	"pip install --upgrade pip",
	{
	"update": "apt-get update",
	"install": "apt-get install -y git curl"
	}
	]
	},
	"update-content-command": {
	"oneOf": [
	{
	"type": "string",
	"description": "Single command to run after COPY"
	},
	{
	"type": "object",
	"description": "Named commands to run after COPY",
	"patternProperties": {
	"^[a-zA-Z0-9._-]+$": {
	"type": "string"
	}
	},
	"additionalProperties": false
	}
	],
	"description": "Command(s) to run after COPY in docker build",
	"examples": [
	"pip install -r requirements.txt",
	"npm install",
	{
	"backend": "pip install -r requirements.txt",
	"frontend": "npm install"
	}
	]
	},
	"post-create-command": {
	"oneOf": [
	{
	"type": "string",
	"description": "Single command to run before main command"
	},
	{
	"type": "object",
	"description": "Named commands to run before main command",
	"patternProperties": {
	"^[a-zA-Z0-9._-]+$": {
	"type": "string"
	}
	},
	"additionalProperties": false
	}
	],
	"description": "Command(s) to run synchronously before main command",
	"examples": [
	"echo 'Container ready!'",
	"python setup.py",
	{
	"setup": "python setup.py",
	"cache": "python warm_cache.py"
	}
	]
	},
	"post-start-command": {
	"oneOf": [
	{
	"type": "string",
	"description": "Single command to run asynchronously"
	},
	{
	"type": "object",
	"description": "Named commands to run asynchronously",
	"patternProperties": {
	"^[a-zA-Z0-9._-]+$": {
	"type": "string"
	}
	},
	"additionalProperties": false
	}
	],
	"description": "Command(s) 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",
	{
	"server": "code-server --bind-addr 0.0.0.0:8080",
	"jupyter": "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"
	}
	]
	},
	"forbid-dangerous-mounts": {
	"type": "boolean",
	"default": true,
	"description": "Prevent mounting sensitive paths like /etc, /var/run/docker.sock, etc. that grant system-level access. Set to false ONLY for trusted development environments. When false, containers can mount ANY path including system directories, potentially gaining root access to the host."
	},
	"privileged": {
	"type": "boolean",
	"default": false,
	"description": "Run container in privileged mode. This grants the container almost all capabilities of the host. Required for Docker-in-Docker (DinD) setups. Use with extreme caution as it significantly reduces container isolation."
	},
	"mount-worktree-metadata": {
	"type": "boolean",
	"default": false,
	"description": "Enable git worktree support by mounting git metadata from the main repository. When enabled, Safety Net will detect if running from a worktree and mount the main repository's .git directory to enable git operations inside the container. Only works for sibling worktrees (worktree and main repo in same parent directory)."
	},
	"monitoring": {
	"type": "array",
	"items": {
	"type": "string",
	"enum": ["claude-code"]
	},
	"default": [],
	"description": "List of monitoring providers to enable. Currently only 'claude-code' is supported. When 'claude-code' is included, runs an OpenTelemetry Collector sidecar to receive and expose metrics for Claude Code sessions."
	}
	},
	"additionalProperties": true
	}