feat: add Dockerfile and docker-compose for local development

[zeel2104]

Description

Add a root Docker-based local development workflow for the monorepo.

This PR adds:

• a root multi-stage Dockerfile
• a root docker-compose.yml with dev, test, and optional dashboard services
• a root .dockerignore
• Docker helper scripts under scripts/docker/
• Docker quickstart documentation in CONTRIBUTING.md

The setup uses Python 3.11 and Node.js 22, installs the repo’s editable packages explicitly from packages/, mounts the source into /workspace, and runs tests package-by-package to match the existing CI behavior.

Type of Change

• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Maintenance (dependency updates, CI/CD, refactoring)
• Security fix

Package(s) Affected

• agent-os-kernel
• agent-mesh
• agent-runtime
• agent-sre
• agent-governance
• docs / root

Checklist

• My code follows the project style guidelines (ruff check)
• I have added tests that prove my fix/feature works
• All new and existing tests pass (pytest)
• I have updated documentation as needed
• I have signed the Microsoft CLA

Related Issues

Closes #322

Test Verification

• docker compose build
• docker compose up -d dev
• docker compose exec dev bash
• python --version -> Python 3.11.15
• node --version -> v22.22.0
• docker compose run --rm test

docker compose run --rm test completed successfully across:

• packages/agent-os (2817 passed, 30 skipped)
• packages/agent-mesh (1900 passed, 38 skipped)
• packages/agent-hypervisor (584 passed, 60 skipped)
• packages/agent-sre (1258 passed)
• packages/agent-compliance (160 passed)

[github-actions]

Welcome to the Agent Governance Toolkit! Thanks for your first pull request.
Please ensure tests pass, code follows style (ruff check), and you have signed the CLA.
See our Contributing Guide.

[github-actions]

🤖 AI Agent: code-reviewer

Review Summary

This pull request introduces a Docker-based local development workflow for the monorepo. While it provides a convenient way to set up and manage development environments, there are several areas that require attention to ensure security, maintainability, and compliance with the project's goals. Below are the detailed findings:

---

🔴 CRITICAL

1. Unrestricted docker-compose Volumes:

   • The docker-compose.yml file mounts the entire repository (.:/workspace) into the container. This could lead to accidental exposure of sensitive files (e.g., .env, .git, .ssh) or host system files if the repository root contains unintended files.
   • Recommendation: Use a more restrictive volume configuration. Explicitly specify which directories or files should be mounted into the container.

2. Potential Sandbox Escape via bash Entrypoint:

   • The dev service uses bash as its entrypoint (ENTRYPOINT ["bash", "/workspace/scripts/docker/dev-entrypoint.sh"]). This could allow a malicious actor to execute arbitrary commands within the container if they gain access to the container runtime.
   • Recommendation: Use a more restrictive entrypoint and avoid exposing a shell unless absolutely necessary. Consider using a dedicated script with limited functionality.

3. Unverified Node.js Installation:

   • The Dockerfile installs Node.js via an external script (https://deb.nodesource.com/setup_${NODE_MAJOR}.x). This script is fetched without verification, which could lead to supply chain attacks if the script is compromised.
   • Recommendation: Verify the integrity of the script using checksums or use a trusted package manager like nvm or apt with signed packages.

4. Lack of User Isolation:

   • The Dockerfile does not create a non-root user for running the application. Running processes as root inside containers increases the risk of privilege escalation if the container is compromised.
   • Recommendation: Create a non-root user in the Dockerfile and switch to that user for running the application.

---

🟡 WARNING

1. Backward Compatibility:

   • The Dockerfile explicitly installs packages using editable mode (pip install -e). If the package structure changes or dependencies are updated, this could cause compatibility issues across environments.
   • Recommendation: Ensure that the Dockerfile is updated whenever the package structure or dependencies change. Consider adding automated tests to verify the Docker-based setup.

2. Python Version Hardcoding:

   • The Dockerfile uses ARG PYTHON_VERSION=3.11. While this is fine for now, the project supports Python 3.9–3.12. Hardcoding a single version may lead to compatibility issues for developers using other Python versions.
   • Recommendation: Allow developers to specify the Python version dynamically or provide separate Dockerfiles for each supported Python version.

---

💡 SUGGESTIONS

1. Documentation Improvements:

   • The CONTRIBUTING.md file mentions the Docker setup but does not explain how to troubleshoot common issues (e.g., permission errors, volume mounting issues). Adding a troubleshooting section would improve developer experience.

2. Streamlit Dashboard Security:

   • The dashboard service exposes the Streamlit app on 0.0.0.0:8501. This could be a security risk if the container is run in a production-like environment.
   • Recommendation: Add authentication or restrict access to the dashboard service. For development, consider binding to 127.0.0.1 instead of 0.0.0.0.

3. Testing Script Enhancements:

   • The run-tests.sh script runs tests package-by-package but does not provide detailed logs or exit codes for failed tests.
   • Recommendation: Enhance the script to capture and report detailed test results, including error messages and exit codes.

4. Use of Multi-Stage Builds:

   • The Dockerfile uses multi-stage builds effectively but could benefit from further optimization. For example, the test stage could be streamlined to avoid redundant installations.
   • Recommendation: Refactor the test stage to reuse layers from the dev stage wherever possible.

5. Environment Variable Management:

   • The Dockerfile and docker-compose.yml do not provide a mechanism for managing environment variables securely (e.g., .env files).
   • Recommendation: Add support for .env files in docker-compose.yml and document how to use them securely.

---

Actionable Items

🔴 CRITICAL

• Restrict volume mounts in docker-compose.yml.
• Replace bash entrypoint with a more secure alternative.
• Verify integrity of the Node.js installation script.
• Add a non-root user to the Dockerfile.

🟡 WARNING

• Ensure backward compatibility for editable package installations.
• Provide flexibility for Python version selection.

💡 SUGGESTIONS

• Improve documentation with troubleshooting tips.
• Secure the Streamlit dashboard service.
• Enhance the testing script for better error reporting.
• Optimize multi-stage builds in the Dockerfile.
• Add .env file support for environment variable management.

---

Final Assessment

This PR introduces valuable functionality for local development but requires significant improvements to address security concerns and ensure compliance with best practices. Please prioritize addressing the critical issues before merging.

[github-actions]

🤖 AI Agent: security-scanner — **1. Prompt Injection Defense Bypass**

The provided pull request introduces a Docker-based local development workflow for the repository. While this is primarily a tooling and documentation update, it is critical to assess the changes for potential security risks, especially since this repository is a security-focused library. Below is the security analysis of the changes:

---

1. Prompt Injection Defense Bypass

No direct changes to the core code or prompt handling logic are present in this PR. The Docker setup does not directly interact with user input or prompt handling mechanisms.
Risk Level: 🔵 LOW
Recommendation: None required for this PR.

---

2. Policy Engine Circumvention

The Dockerfile and docker-compose.yml do not appear to modify or bypass any policy enforcement mechanisms in the toolkit. However, the introduction of a development environment could inadvertently lead to misconfigurations or assumptions about the security of the environment.
Risk Level: 🔵 LOW
Recommendation: Add a note in the documentation to clarify that the Docker-based environment is for local development only and should not be used in production.

---

3. Trust Chain Weaknesses

The Dockerfile and docker-compose.yml do not directly interact with SPIFFE/SVID validation or certificate pinning mechanisms. However, the Docker environment could introduce potential risks if the base images or dependencies are not verified.
Risk Level: 🟡 MEDIUM
Attack Vector: If the base images (python:3.11-slim and node:22) are compromised or replaced with malicious versions, it could lead to a supply chain attack.
Recommendation:

• Use a specific digest for the base images instead of relying on mutable tags like python:3.11-slim and node:22. For example:

  FROM python@sha256:<digest>
  FROM node@sha256:<digest>

• Regularly verify and update the base image digests to ensure they are secure.

---

4. Credential Exposure

The Dockerfile and docker-compose.yml do not appear to expose any sensitive credentials. However, the inclusion of docker-compose exec and docker-compose run commands in the documentation could lead to accidental exposure of environment variables or secrets if not properly managed.
Risk Level: 🔵 LOW
Recommendation:

• Ensure that sensitive environment variables (e.g., API keys, secrets) are not hardcoded in the docker-compose.yml file or passed via command-line arguments.
• Add a note in the documentation to use .env files for managing secrets securely.

---

5. Sandbox Escape

The Docker setup introduces a new runtime environment, which could potentially be exploited to escape the container sandbox. However, the provided docker-compose.yml does not include any privileged mode or unsafe configurations that would allow for container escape.
Risk Level: 🔵 LOW
Recommendation:

• Ensure that the containers run with the least privileges necessary. For example, explicitly set user: nonroot in the docker-compose.yml file to avoid running as the root user inside the container.

---

6. Deserialization Attacks

This PR does not introduce any new deserialization mechanisms or modify existing ones.
Risk Level: 🔵 LOW
Recommendation: None required for this PR.

---

7. Race Conditions

The Docker setup does not modify any concurrency or policy evaluation logic.
Risk Level: 🔵 LOW
Recommendation: None required for this PR.

---

8. Supply Chain

The Dockerfile and docker-compose.yml introduce dependencies on external base images (python:3.11-slim and node:22) and potentially other dependencies during the build process. This introduces a supply chain risk.
Risk Level: 🟠 HIGH
Attack Vector: A malicious actor could compromise the base images or dependencies, leading to the introduction of malicious code into the development environment.
Recommendation:

• Use specific image digests for the base images, as mentioned earlier.
• Implement a process to verify the integrity of dependencies installed during the Docker build process.
• Consider using tools like docker scan or trivy to scan the images for vulnerabilities as part of the CI/CD pipeline.

---

Summary of Findings

1. Trust Chain Weaknesses: 🟡 MEDIUM
   • Use specific image digests for base images.
2. Supply Chain Risks: 🟠 HIGH
   • Verify base images and dependencies, and scan for vulnerabilities.

---

Actionable Recommendations

1. Update the Dockerfile to use specific image digests for the base images (e.g., python@sha256:<digest>).
2. Add a step in the CI/CD pipeline to scan the Docker images for vulnerabilities using tools like trivy or docker scan.
3. Update the documentation to emphasize that the Docker-based environment is for local development only and should not be used in production.
4. Ensure that sensitive environment variables are managed securely using .env files and not hardcoded in the docker-compose.yml file.

By addressing these recommendations, the security posture of the repository can be maintained while enabling the new Docker-based development workflow.

[zeel2104]

@imran-siddique
Sorry for the delay on this one. I spent some extra time validating the Docker workflow end-to-end because the initial container setup and test run took a while to stabilize in this monorepo.

I’ve now added the root Dockerfile, docker-compose.yml, .dockerignore, helper scripts, and CONTRIBUTING.md Docker quickstart updates. I also verified the workflow with:

• docker compose up -d dev
• docker compose exec dev bash
• docker compose run --rm test

Thanks for the patience while I worked through the Docker setup and test behavior.

[github-actions]

🤖 AI Agent: code-reviewer

Review Summary

This pull request introduces a Docker-based local development workflow for the monorepo, which is a significant improvement for developer experience. The addition of a Dockerfile, docker-compose.yml, and helper scripts provides a standardized way to set up and run the development environment. The documentation updates in CONTRIBUTING.md are also a welcome addition.

However, there are several areas that require attention to ensure security, maintainability, and alignment with the project's goals. Below is a detailed review:

---

🔴 CRITICAL

1. Credential Handling in Docker Context

   • If the Docker setup involves any environment variables or secrets (e.g., API keys, private keys, or credentials), ensure that these are not hardcoded in the Dockerfile, docker-compose.yml, or helper scripts. They should be passed securely using environment variables or Docker secrets.
   • Verify that .dockerignore excludes sensitive files (e.g., .env, private keys, or configuration files containing secrets) to prevent them from being added to Docker images.

2. Sandbox Escape Vectors

   • Ensure that the docker-compose.yml and Dockerfile configurations do not inadvertently allow privileged access or host filesystem mounts that could lead to sandbox escapes. For example:
     • Avoid using privileged: true in docker-compose.yml.
     • Avoid mounting sensitive host directories (e.g., /, /etc, /var/run/docker.sock) unless absolutely necessary.

3. Node.js Version Security

   • Node.js 22 is not yet a stable LTS version as of the last known update. Using a non-LTS version could introduce security vulnerabilities. Consider using the latest LTS version of Node.js unless there is a specific requirement for Node.js 22.

---

🟡 WARNING

1. Backward Compatibility

   • While this PR does not introduce breaking changes to the public API, it modifies the development workflow. Ensure that the new Docker-based workflow does not disrupt existing workflows for developers who may not use Docker. Provide clear documentation on how to continue using the previous setup if needed.

2. Python Version

   • The Dockerfile uses Python 3.11. Ensure that all packages in the monorepo are fully compatible with Python 3.11. If any packages are pinned to older Python versions (e.g., 3.9 or 3.10), this could lead to runtime issues.

---

💡 SUGGESTIONS

1. Testing Coverage

   • While the PR mentions that tests pass for all packages, consider adding a CI pipeline step to validate the Docker-based workflow explicitly. For example:
     • Build the Docker image.
     • Run tests inside the container.
     • Verify that the results match the existing CI behavior.

2. Documentation Improvements

   • Expand the CONTRIBUTING.md section to include troubleshooting tips for common issues (e.g., Docker daemon not running, network issues, or permission errors).
   • Provide a clear explanation of the dashboard service in docker-compose.yml and its intended use case.

3. Helper Scripts

   • Review the helper scripts under scripts/docker/ to ensure they follow best practices for error handling and security. For example:
     • Use set -euo pipefail in shell scripts to catch errors early.
     • Avoid using eval or other potentially unsafe commands.

4. Multi-Stage Build Optimization

   • Review the multi-stage Dockerfile for opportunities to reduce image size. For example:
     • Use --no-cache-dir when installing Python packages with pip.
     • Remove unnecessary build dependencies in the final stage.

5. Service Isolation

   • Consider running the test service in an isolated network to prevent unintended interactions with the host or other services.

---

Action Items

1. Address the 🔴 CRITICAL issues related to credential handling, sandbox escape vectors, and Node.js version security.
2. Review the 🟡 WARNING items to ensure backward compatibility and Python version compatibility.
3. Implement the 💡 SUGGESTIONS to improve the overall quality and usability of the Docker-based workflow.

Once these issues are resolved, this PR will be a valuable addition to the repository, enhancing the developer experience while maintaining security and reliability.