Deva/chore docs and bug fixes

[lroolle]

No description provided.

[claude-yolo]

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

---

Security Audit Complete

I've performed a thorough security audit of this PR focusing on container boundaries, authentication flows, shell entrypoints, and privilege escalation vectors.

Todo List

• Analyze main deva.sh script for security vulnerabilities
• Review Dockerfile changes for container security issues
• Examine authentication flows in agent scripts
• Check for shell injection vulnerabilities
• Assess privilege escalation vectors
• Review CI/CD workflow security
• Analyze new documentation for security gaps
• Compile findings and risk assessment

🔴 BLOCKING SECURITY ISSUES

1. Command Injection in Volume Hash Computation

File: deva.sh lines 632-636, 2230-2234, 2242-2246
Severity: CRITICAL
Issue: Multiple uses of printf piped to hash commands without proper escaping:

config_hash=$(printf '%s' "$config_hash_source" | md5sum | cut -c1-6)
creds_hash=$(printf '%s' "$CUSTOM_CREDENTIALS_FILE" | md5sum | cut -c1-8)

Impact: User-controlled paths in $CUSTOM_CREDENTIALS_FILE or $config_hash_source could inject commands
Fix Required: Use -- to terminate option parsing: printf -- '%s' "$var"

2. Unsafe Command Substitution Pattern

File: deva.sh lines throughout (160, 245, 309, etc.)
Severity: HIGH
Issue: Extensive use of $(...) command substitution without input validation
Examples:

raw="$(expand_tilde "$raw")"
dir="$(pwd)" 
abs_src=$(cd "$(dirname "$src")" 2>/dev/null && pwd)/$(basename "$src")

Impact: If input paths contain command injection chars, could lead to RCE
Mitigation: The existing validate_config_value() function provides some protection but isn't consistently applied

3. Privileged Docker Socket Access by Default

File: deva.sh line ~770 (auto-mount logic)
Severity: HIGH
Issue: Docker socket (/var/run/docker.sock) auto-mounted when present
Impact: Container gains root-equivalent access to host Docker daemon

• Can start privileged containers
• Can mount any host path
• Effective container escape vector
  Recommendation: Require explicit --enable-docker flag instead of --no-docker opt-out

4. Password-less Sudo in Container

File: Dockerfile lines 180-182
Severity: HIGH
Issue: deva user has NOPASSWD sudo access

echo "$DEVA_USER ALL=(ALL) NOPASSWD: ALL" > "/etc/sudoers.d/$DEVA_USER"

Impact: Any command execution as deva user can escalate to root in container
Justification: Documented as "development convenience" but significantly weakens container security model

🟠 HIGH-RISK FINDINGS

5. Unvalidated Environment Variable Processing

File: deva.sh expand_env_value() function
Issue: Environment variable expansion without sufficient validation
Risk: Could allow injection through carefully crafted env vars

6. Authentication Token Exposure Risk

File: agents/shared_auth.sh lines 95, 89
Issue: GitHub tokens passed as command line arguments:

cmd+=(--github-token "${GH_TOKEN:-${GITHUB_TOKEN}}")

Risk: Tokens visible in process list, docker inspect output

7. Insecure Download in Install Script

File: install.sh lines 44-45
Issue: curl without checksum verification:

curl -fsSL "$GITHUB_RAW/$path" -o "$dest"

Risk: MITM attacks, supply chain compromise (though over HTTPS)

8. Unsafe Copilot API Installation

File: Dockerfile lines 94-101
Issue: Git clone and npm install from external repo without integrity verification
Risk: Supply chain attack vector through compromised upstream

🟡 MEDIUM-RISK FINDINGS

9. Weak File Permission Validation

File: deva.sh should_mount_home_item()
Issue: Blacklist approach for credential files
Risk: May miss new credential file patterns

10. Race Condition in Container Selection

File: deva.sh container picking logic
Issue: TOCTOU between container enumeration and selection
Risk: Could attach to wrong container in rare cases

✅ POSITIVE SECURITY IMPROVEMENTS

Good Security Practices Found:

1. Input validation via validate_config_value() function (lines 1306-1320)
2. Command substitution restrictions - only allows $(pwd)
3. Credential file filtering in should_mount_home_item()
4. Auth environment variable isolation via should_skip_env_for_auth()
5. Tainted credential detection in has_auth_override()
6. Security documentation added in SECURITY.md
7. Set -euo pipefail in install.sh (improved error handling)

REQUIRED TESTS BEFORE MERGE

1. Shell injection tests:

   # Test injection in custom credentials file path
   deva.sh --auth-with './file$(id).json'
   
   # Test injection in volume paths  
   deva.sh -v './path$(whoami):/target'

2. Docker socket privilege tests:

   # Verify container cannot escape via docker socket
   deva.sh -- /bin/sh -c 'docker run --privileged --rm alpine id'

3. Authentication isolation tests:

   # Verify auth tokens don't leak between auth methods
   export ANTHROPIC_API_KEY="test-key" 
   deva.sh claude --auth-with copilot
   # Should not see ANTHROPIC_API_KEY in container

RECOMMENDATIONS

Immediate (Pre-merge):

1. Fix printf injection - add -- flags to all printf calls with user input
2. Document Docker socket risk prominently in README
3. Add integrity checks to install.sh downloads

Short-term:

1. Change Docker socket default to opt-in
2. Implement checksum verification for external dependencies
3. Add process argument sanitization for token passing

Long-term:

1. Implement proper secrets management instead of env vars
2. Consider rootless container runtime option
3. Add security scanning to CI pipeline

Overall Assessment: This PR improves security with better input validation and credential handling, but contains several injection vulnerabilities that must be fixed before merge. The Docker socket auto-mount significantly weakens the "container as sandbox" model.

[Copilot]

Pull request overview

This PR prepares the repo for an OSS-style release by adding a MkDocs documentation site, polishing project metadata (README/license/security/contributing), and tightening auth/config handling in the deva.sh launcher (including --dry-run side-effect fixes and container identity changes).

Changes:

• Add MkDocs configuration, docs pages, and CI/Pages workflows to build and publish the documentation site.
• Update installer + release workflow docs to reflect deva.sh as the primary entrypoint and to install the full agent set.
• Refine deva.sh auth/config behavior (quick mode, credential overlays, container naming, dry-run behavior) and extend agent auth support (e.g., ANTHROPIC_AUTH_TOKEN).

Reviewed changes

Copilot reviewed 25 out of 26 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
workflows/RELEASE.md	Updates release instructions to use deva.sh as version source.
mkdocs.yml	Adds MkDocs Material site config + navigation.
install.sh	Refreshes installer for multi-agent + fallback image behavior.
docs/index.md	Adds docs landing page.
docs/quick-start.md	Adds quick start guide for install + basic usage.
docs/how-it-works.md	Documents startup/config/auth/mount/runtime model.
docs/authentication.md	Documents per-agent auth modes and mounting behavior.
docs/advanced-usage.md	Documents .deva, profiles, risk knobs, advanced workflows.
docs/troubleshooting.md	Adds troubleshooting playbook and diagnostic commands.
docs-requirements.txt	Pins MkDocs + theme dependencies for CI build.
deva.sh	Version bump + quick mode + container identity/auth overlay + dry-run safety improvements.
agents/shared_auth.sh	Extends Anthropic token validation to include ANTHROPIC_AUTH_TOKEN.
agents/claude.sh	Adds ANTHROPIC_AUTH_TOKEN support and avoids proxy start/model probing during --dry-run.
agents/codex.sh	Avoids proxy start/model probing during --dry-run.
agents/gemini.sh	Adjusts gemini mounts + settings writes (now gated by DRY_RUN).
README.md	Rewrites README into concise landing page + docs links.
CHANGELOG.md	Adds 0.9.2 release notes and updates product name.
DEV-LOGS.md	Adds dev log entries describing OSS/docs/auth work.
CONTRIBUTING.md	Adds contribution workflow + local checks guidance.
SECURITY.md	Adds vulnerability reporting policy.
LICENSE	Adds MIT license file.
Dockerfile	Adds locale generation + npm install retry + CLI version sanity checks.
.gitignore	Ignores MkDocs site/ output.
.github/workflows/ci.yml	Adds MkDocs build job to CI.
.github/workflows/pages.yml	Adds GitHub Pages workflow to build/deploy docs.

---

💡 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]

backup_claude_json copies .claude.json into $XDG_STATE_HOME/.../deva/backups but doesn’t enforce restrictive permissions on the backup. Since .claude.json can contain auth/session material, the backup should be written with 0600 (and ideally atomically) to avoid accidentally making it more widely readable than the original.

Suggested change

	mkdir -p "$state_dir"
	cp "$claude_json" "$state_dir/.claude.json.bak"
	local backup_path tmp_backup
	backup_path="$state_dir/.claude.json.bak"
	# Ensure backup directory exists and is owner-only.
	mkdir -p "$state_dir"
	chmod 700 "$state_dir" 2>/dev/null || true
	# Create a temporary file with restrictive permissions, then atomically move.
	tmp_backup="$(mktemp "$state_dir/.claude.json.bak.XXXXXX")"
	chmod 600 "$tmp_backup" 2>/dev/null || true
	if ! cp "$claude_json" "$tmp_backup"; then
	rm -f "$tmp_backup"
	return 1
	fi
	mv -f "$tmp_backup" "$backup_path"

[Copilot]

append_auth_credential_overlay bind-mounts the generated blank overlay file without :ro. Since this file exists on the host under $XDG_STATE_HOME, mounting it read-write allows the container/agent to modify host state. Mount the overlay as read-only (and consider writing it with restrictive perms) so the overlay can’t be mutated from inside the container.

Suggested change

	fi
	DOCKER_ARGS+=("-v" "$overlay_file:$target_path")
	chmod 600 "$overlay_file"
	fi
	DOCKER_ARGS+=("-v" "$overlay_file:$target_path:ro")

[Copilot]

In --auth-with api-key for Gemini, this code still writes to a host-side $HOME/.gemini (mkdir/rm/settings.json) when neither CONFIG_HOME nor CONFIG_ROOT is set. In -Q/--quick bare mode, this means a run can unexpectedly mutate the user’s real home config even though bare mode is intended to avoid host config mounts/state. Consider short-circuiting these writes when QUICK_MODE=true (or require an explicit config home) to keep -Q side-effect-free on the host.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a69ce81b86

ℹ️ 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]

Restrict non-active credential mounts in config-root mode

When --config-home is a root containing multiple agent folders, this loop mounts every agent directory into the container even under non-default auth (for example, claude --auth-with api-key). The new overlay logic only blanks the active agent credential path, so inactive credentials like /home/deva/.codex/auth.json remain mounted and writable, reintroducing credential exposure/corruption risk in the mode that is supposed to isolate from OAuth files.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Skip host Gemini config writes in quick API-key mode

In -Q/--quick runs, deva.sh clears CONFIG_HOME/CONFIG_ROOT, so this fallback resolves to $HOME/.gemini and then writes host config (mkdir, token cleanup, settings.json) for API-key auth. That breaks quick mode’s bare/no-config expectation and the written settings are not mounted into the container anyway, so the auth-mode preparation can be ineffective for the actual run while still mutating host state.

Useful? React with 👍 / 👎.

[claude-yolo]

Claude finished @lroolle's task in 2m 50s —— View job

---

Security Audit Complete

I've performed a thorough security audit of this PR focusing on container boundaries, authentication flows, shell entrypoints, and privilege escalation vectors.

Todo List

• Analyze main deva.sh script for security vulnerabilities
• Review Dockerfile changes for container security issues
• Examine authentication flows in agent scripts
• Check for shell injection vulnerabilities
• Assess privilege escalation vectors
• Review CI/CD workflow security
• Analyze new documentation for security gaps
• Compile findings and risk assessment

🔴 BLOCKING SECURITY ISSUES

1. Command Injection in Volume Hash Computation

File: deva.sh lines 632-636, 2230-2234, 2242-2246
Severity: CRITICAL
Issue: Multiple uses of printf piped to hash commands without proper escaping:

config_hash=$(printf '%s' "$config_hash_source" | md5sum | cut -c1-6)
creds_hash=$(printf '%s' "$CUSTOM_CREDENTIALS_FILE" | md5sum | cut -c1-8)

Impact: User-controlled paths in $CUSTOM_CREDENTIALS_FILE or $config_hash_source could inject commands
Fix Required: Use -- to terminate option parsing: printf -- '%s' "$var"

2. Unsafe Command Substitution Pattern

File: deva.sh lines throughout (160, 245, 309, etc.)
Severity: HIGH
Issue: Extensive use of $(...) command substitution without input validation
Examples:

raw="$(expand_tilde "$raw")"
dir="$(pwd)" 
abs_src=$(cd "$(dirname "$src")" 2>/dev/null && pwd)/$(basename "$src")

Impact: If input paths contain command injection chars, could lead to RCE
Mitigation: The existing validate_config_value() function provides some protection but isn't consistently applied

3. Privileged Docker Socket Access by Default

File: deva.sh line ~770 (auto-mount logic)
Severity: HIGH
Issue: Docker socket (/var/run/docker.sock) auto-mounted when present
Impact: Container gains root-equivalent access to host Docker daemon

• Can start privileged containers
• Can mount any host path
• Effective container escape vector
  Recommendation: Require explicit --enable-docker flag instead of --no-docker opt-out

4. Password-less Sudo in Container

File: Dockerfile lines 180-182
Severity: HIGH
Issue: deva user has NOPASSWD sudo access

echo "$DEVA_USER ALL=(ALL) NOPASSWD: ALL" > "/etc/sudoers.d/$DEVA_USER"

Impact: Any command execution as deva user can escalate to root in container
Justification: Documented as "development convenience" but significantly weakens container security model

🟠 HIGH-RISK FINDINGS

5. Unvalidated Environment Variable Processing

File: deva.sh expand_env_value() function
Issue: Environment variable expansion without sufficient validation
Risk: Could allow injection through carefully crafted env vars

6. Authentication Token Exposure Risk

File: agents/shared_auth.sh lines 95, 89
Issue: GitHub tokens passed as command line arguments:

cmd+=(--github-token "${GH_TOKEN:-${GITHUB_TOKEN}}")

Risk: Tokens visible in process list, docker inspect output

7. Insecure Download in Install Script

File: install.sh lines 44-45
Issue: curl without checksum verification:

curl -fsSL "$GITHUB_RAW/$path" -o "$dest"

Risk: MITM attacks, supply chain compromise (though over HTTPS)

8. Unsafe Copilot API Installation

File: Dockerfile lines 94-101
Issue: Git clone and npm install from external repo without integrity verification
Risk: Supply chain attack vector through compromised upstream

🟡 MEDIUM-RISK FINDINGS

9. Weak File Permission Validation

File: deva.sh should_mount_home_item()
Issue: Blacklist approach for credential files
Risk: May miss new credential file patterns

10. Race Condition in Container Selection

File: deva.sh container picking logic
Issue: TOCTOU between container enumeration and selection
Risk: Could attach to wrong container in rare cases

✅ POSITIVE SECURITY IMPROVEMENTS

Good Security Practices Found:

1. Input validation via validate_config_value() function (lines 1306-1320)
2. Command substitution restrictions - only allows $(pwd)
3. Credential file filtering in should_mount_home_item()
4. Auth environment variable isolation via should_skip_env_for_auth()
5. Tainted credential detection in has_auth_override()
6. Security documentation added in SECURITY.md
7. Set -euo pipefail in install.sh (improved error handling)

REQUIRED TESTS BEFORE MERGE

1. Shell injection tests:

   # Test injection in custom credentials file path
   deva.sh --auth-with './file$(id).json'
   
   # Test injection in volume paths  
   deva.sh -v './path$(whoami):/target'

2. Docker socket privilege tests:

   # Verify container cannot escape via docker socket
   deva.sh -- /bin/sh -c 'docker run --privileged --rm alpine id'

3. Authentication isolation tests:

   # Verify auth tokens don't leak between auth methods
   export ANTHROPIC_API_KEY="test-key" 
   deva.sh claude --auth-with copilot
   # Should not see ANTHROPIC_API_KEY in container

RECOMMENDATIONS

Immediate (Pre-merge):

1. Fix printf injection - add -- flags to all printf calls with user input
2. Document Docker socket risk prominently in README
3. Add integrity checks to install.sh downloads

Short-term:

1. Change Docker socket default to opt-in
2. Implement checksum verification for external dependencies
3. Add process argument sanitization for token passing

Long-term:

1. Implement proper secrets management instead of env vars
2. Consider rootless container runtime option
3. Add security scanning to CI pipeline

Overall Assessment: This PR improves security with better input validation and credential handling, but contains several injection vulnerabilities that must be fixed before merge. The Docker socket auto-mount significantly weakens the "container as sandbox" model.