Devcontainer Validator

Validate devcontainer.json files for syntax, structure, features, ports, lifecycle scripts, customizations, and security best practices in VS Code Dev Contai...

Security Scan

The skill is internally coherent: a local, pure-Python devcontainer.json validator that asks for no credentials, installs nothing, and its instructions align with its code — however the provided source was truncated so a full line-by-line audit couldn't be completed.

Purpose & Capability

The name/description (devcontainer.json validation) matches the included SKILL.md and the Python script: the validator implements structure, features, ports, lifecycle, customizations, and best-practice checks. Required binaries/env/configs are none, which is proportionate for a local linter.

Instruction Scope

Runtime instructions only tell the agent to run the included script against a devcontainer.json file and to use flags like --format/--strict; SKILL.md does not direct reading unrelated files, collecting secrets, or posting results to external endpoints.

Install Mechanism

No install spec (instruction-only plus an included Python script). The script targets Python 3.8+ and uses only stdlib imports (argparse, json, os, re, sys), which matches the SKILL.md claim; nothing is downloaded or written outside running the script.

Credentials

The skill declares no required environment variables, credentials, or config paths and the visible code does not access external secrets. This is appropriate for a local validation tool.

Persistence & Privilege

The skill is not force-included (always: false) and does not request persistent or cross-skill configuration. Autonomous invocation is allowed by default but not combined with other privilege concerns.

Assessment

This skill appears to be a straightforward, local devcontainer.json validator implemented in pure Python and is coherent with its documentation. Before installing or running it in sensitive environments: (1) review the complete scripts/devcontainer_validator.py file (the provided source was truncated here) to confirm there are no unexpected network calls, subprocess.exec calls, or telemetry; (2) run it on sample files locally or in an isolated CI container; and (3) if you plan to give it access to repositories or pipeline artifacts, ensure those environments have least privilege. If you can provide the missing portion of the script, I can raise the confidence to high after reviewing it in full.

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 --strict with 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