This document outlines security best practices and the shared responsibility model for running WineBot.

WineBot provides a Windows compatibility layer inside a Linux container. Because Wine runs Windows binaries with the same privileges as the winebot user, a compromised Windows application can theoretically access any data within the container or attempt to pivot to your local network.

If your automation does not require internet access, run the container with network isolation:

docker run --network none ...

In docker-compose.yml, use an internal network:

networks:
  winebot-net:
    internal: true

VNC traffic is not encrypted by default. To secure the remote desktop:

1. Bind VNC to localhost only: VNC_BIND=127.0.0.1.
2. Use an SSH Tunnel to access the desktop:

   ssh -L 5900:localhost:5900 user@remote-host

3. Always set a strong VNC_PASSWORD.

Always set an API_TOKEN in production environments. The dashboard and CLI will require this token to perform any actions.

Mount your apps/ and automation/ directories as Read-Only (:ro) to prevent malicious scripts from modifying your local source files or installers. (Enabled by default in compose/docker-compose.yml).

If you discover a security vulnerability in WineBot, please open a GitHub Issue or contact the maintainers directly. Do not disclose sensitive bugs in public comments until a patch is available.

All secrets use the INFRA_<SERVICE>_<CREDENTIAL> pattern:

• Local dev: Copy .env.example → .env and fill in values. .env is gitignored.
• Linux server: Copy deploy/winebot-credentials.template to /etc/winebot-credentials with chmod 600 and chown root:root.

• ❌ No hardcoded passwords, API keys, or tokens in source files
• ❌ No internal IPs, hostnames, or infrastructure topology in committed docs
• ✅ All secrets read from environment variables
• ✅ Fallback values documented as placeholders only
• ✅ .env files, /etc/winebot-credentials in .gitignore
• ✅ Use scripts/ci/check-credentials.sh as a pre-commit hook or CI gate to detect accidental credential leakage. Run --history to scan all commits.

All operational scripts log in structured JSON format to stderr:

{"ts":"2026-06-28T12:34:56Z","level":"info","logger":"script-name","message":"Processing complete","elapsed_s":123.4}

from logging_utils import get_logger
logger = get_logger("my-script")
logger.start("Processing")
logger.complete("Done")
logger.error("Failed", exc_info=True)

source "$(dirname "$0")/logging_utils.sh"
log_start "Processing"
log_complete "Done"