docs: add custom image guide

[lroolle]

• explain how to build local and personal deva images
• document DEVA_DOCKER_IMAGE and DEVA_DOCKER_TAG overrides clearly
• link the guide from the README, docs index, advanced usage, and MkDocs nav

Summary

• what changed
• why it changed

Verification

• ./deva.sh --help
• ./scripts/version-check.sh
• relevant smoke path ran

Risk

• auth / mounts
• installer / release
• docs / site

Issues

Closes #

[claude-yolo]

Claude finished @lroolle's task in 3m 14s —— View job

---

Security Audit: Custom Image Guide PR

Paranoid security audit focusing on container boundaries, auth flows, shell entrypoints, privilege escalation, and permission bypasses.

Security Audit Checklist

• Read and analyze all changed files
• Review custom-images.md for security implications
• Check container boundary preservation
• Analyze authentication flow impacts
• Look for shell injection vectors
• Examine privilege escalation risks
• Identify permission bypass possibilities
• Check for insecure documentation practices
• Verify no secrets exposure
• Document blocking issues and high-risk findings
• Recommend required security tests

CRITICAL SECURITY FINDINGS

🚨 HIGH-RISK: Arbitrary Container Control Without Trust Model

The documentation enables users to inject arbitrary Docker images via DEVA_DOCKER_IMAGE without establishing a clear threat model for custom images.

Key Attack Vectors Identified:

1. Container Boundary Bypass: Custom images completely control the container filesystem, potentially including:

   • Modified /usr/local/bin/docker-entrypoint.sh
   • Compromised agent binaries (claude, codex, gemini CLIs)
   • Malicious init systems or background services
   • Backdoored system utilities

2. Authentication Credential Harvesting: Custom images have full access to mounted auth:

   • ~/.config/deva (agent configs and keys)
   • Docker socket (if mounted) = host root access
   • Workspace-mounted secrets (.env, API keys, etc.)

3. Shell Injection via Image Names: While validate_config_value() prevents backticks and most command substitution, Docker image names are passed unsanitized to shell:

   docker run [...] "${DEVA_DOCKER_IMAGE}:${DEVA_DOCKER_TAG}" [...]

   Potential for shell metacharacter exploitation.

4. Privilege Escalation Paths:

   • Custom images can modify gosu or UID/GID handling
   • Container can exploit Docker socket mount for host escape
   • Malicious entrypoint can bypass intended security controls

🚨 BLOCKING ISSUES

1. Missing Security Guidance

The documentation provides zero guidance on:

• Verifying image authenticity/signatures
• Understanding trust boundaries with custom images
• Secure image building practices
• Credential isolation when using untrusted images

2. Dangerous Documentation Examples

• Lines 76-78: Encourages pushing to personal registries without signature verification
• Lines 120-127: Dockerfile examples don't mention security implications of FROM trust
• Lines 93-98: .deva.local config with custom images but no isolation guidance

3. Authentication Mount Security Gap

Custom images bypass deva's security model by controlling:

• Agent CLI binaries that handle auth tokens
• Container entrypoint that processes mounts
• All system utilities that could exfiltrate credentials

REQUIRED SECURITY MITIGATIONS BEFORE MERGE:

1. Add Security Section to custom-images.md:

   ## Security Considerations
   
   Custom images have full control over the container environment and can:
   - Access all mounted authentication credentials
   - Modify or replace agent binaries
   - Exploit Docker socket mounts for host access
   
   Only use custom images you trust completely.

2. Add Image Verification Guidance:

   • Document image signature verification
   • Recommend using docker trust when available
   • Warn about registry security

3. Shell Injection Hardening:

   • Validate image names against safe charset: [a-zA-Z0-9._/-]+
   • Validate tags against safe charset: [a-zA-Z0-9._-]+
   • Prevent shell metacharacters in image/tag values

4. Required Security Tests:

   • Test with malicious image names containing shell metacharacters
   • Verify auth credential isolation with untrusted images
   • Test Docker socket mount exploitation scenarios
   • Validate image name/tag parsing edge cases

RECOMMENDATION: DO NOT MERGE until security guidance is added and shell injection vectors are hardened.

[Copilot]

Pull request overview

Adds documentation for building and using custom deva Docker images, and wires that guide into the MkDocs site navigation and existing docs entry points.

Changes:

• Add new “Custom Images” guide documenting DEVA_DOCKER_IMAGE / DEVA_DOCKER_TAG overrides and local/personal image workflows.
• Link the new guide from README, docs index, and Advanced Usage.
• Update MkDocs nav to include the new page.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
mkdocs.yml	Adds “Custom Images” to the MkDocs navigation and updates the site description ordering.
docs/index.md	Links the new Custom Images guide from the docs home page.
docs/custom-images.md	Introduces a full guide for local builds, registry images, and .deva / .deva.local overrides.
docs/advanced-usage.md	Adds a pointer to the Custom Images guide from Advanced Usage.
README.md	Links the Custom Images guide from the repo README.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Copilot]

This statement implies deva strictly requires the requested tag to exist, but deva.sh can automatically fall back to another locally-available tag (currently prefers rust then latest) if the requested tag is missing and the pull fails. Please adjust this wording to reflect the fallback + warning behavior, or explicitly note that the requested tag may be substituted when a compatible local image exists.

Suggested change

	that the image exists and that the tag you asked for is real.
	that there is a usable image and tag: it will first try the tag you asked
	for, but if that pull fails and a compatible local image exists, `deva.sh`
	may fall back to another tag (currently preferring `rust` then `latest`)
	and will warn you when it does so.

[Copilot]

The guide says deva "fails fast" when the tag is missing locally and can't be pulled, but deva.sh may instead fall back to another available local tag (and continue) when the pull fails. Please update this gotcha to describe the actual behavior (warn + fallback when rust/latest exists; otherwise error).

Suggested change

	fails fast. Good. Silent nonsense would be worse.
	will warn and fall back to a local `rust` or `latest` tag when one
	exists; if no suitable fallback exists, it errors instead. Silent
	nonsense would be worse.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 72604f83bc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Remove incorrect fail-fast guarantee for missing image tags

This bullet says deva will "fail fast" when the requested tag is missing and cannot be pulled, but check_image() in deva.sh first falls back to any local rust/latest tag (for tag in rust latest and DEVA_DOCKER_TAG="$fallback_tag"). In environments where one fallback tag exists locally, deva proceeds with a different image instead of failing, so this guidance is inaccurate and can mislead users during reproducibility/debugging.

Useful? React with 👍 / 👎.