devcontainer-validator
Validate devcontainer.json files for VS Code Dev Containers, GitHub Codespaces, and DevPod.
What it does
Checks your devcontainer.json (JSONC — comments and trailing commas supported) for common mistakes across six areas:
- Structure — required fields, conflicts between image/dockerFile/dockerComposeFile, unknown keys
- Features — OCI reference format, duplicates, empty options
- Ports & networking — forwardPorts format, port ranges, portsAttributes consistency
- Lifecycle scripts — command types, empty commands, shell injection patterns
- Customizations — VS Code extensions format, settings type, extension ID validation
- Best practices — remoteUser, privileged mode, workspaceFolder, dangerous capabilities
Rules (24+)
| Category | Rules | Examples |
|---|---|---|
| Structure (6) | Invalid JSONC syntax, missing image source, unknown top-level keys, empty name, image+dockerFile conflict, dockerFile+compose conflict | "image": "...", "dockerFile": "..." both set |
| Features (4) | Invalid features format, feature ID not valid OCI ref, empty feature options, duplicate features | "features": ["go"] (should be object) |
| Ports & networking (4) | forwardPorts not array, invalid port numbers, port out of range, portsAttributes referencing unlisted ports | "forwardPorts": [99999] |
| Lifecycle scripts (4) | Invalid command type, empty commands, shell injection patterns, onCreateCommand usage hints | "postCreateCommand": "" |
| Customizations (3) | extensions not array of strings, invalid extension ID format, settings not object | "extensions": [123] |
| Best practices (3+) | Missing remoteUser (root warning), privileged: true, missing workspaceFolder, dangerous capAdd entries | "capAdd": ["SYS_ADMIN"] |
Output formats
- text — human-readable with severity tags ([E] [W] [I])
- json — structured with summary counts
- summary — one-line PASS/WARN/FAIL
Exit codes
0— no errors (warnings/info allowed)1— errors found (or--strictwith any issue)2— file not found or parse error
Commands
validate
Full validation of all rules.
python3 scripts/devcontainer_validator.py validate devcontainer.json
python3 scripts/devcontainer_validator.py validate --format json .devcontainer/devcontainer.json
python3 scripts/devcontainer_validator.py validate --strict devcontainer.json
structure
Validate only structure rules (required fields, conflicts, unknown keys).
python3 scripts/devcontainer_validator.py structure devcontainer.json
features
Validate only the features section.
python3 scripts/devcontainer_validator.py features devcontainer.json
security
Validate only security-related rules (privileged, capAdd, shell injection, remoteUser).
python3 scripts/devcontainer_validator.py security --strict devcontainer.json
Options
| Option | Values | Default | Description |
|---|---|---|---|
--format | text, json, summary | text | Output format |
--min-severity | error, warning, info | info | Filter by minimum severity |
--strict | flag | off | Exit 1 on any issue |
Requirements
- Python 3.8+ (pure stdlib, no dependencies)
Examples
# Quick check
python3 scripts/devcontainer_validator.py validate devcontainer.json
# CI pipeline
python3 scripts/devcontainer_validator.py validate --strict --format summary devcontainer.json
# Security audit only
python3 scripts/devcontainer_validator.py security --format json devcontainer.json
# Filter noise
python3 scripts/devcontainer_validator.py validate --min-severity warning devcontainer.json