ethernmyth/mesh repository overview

⁠Mesh

A small, fast, secure-by-default developer security control plane over Docker.

Mesh is an authoritative, deterministic security control plane that sits between developer commands and the Docker execution layer.

Instead of requiring users to manually install toolchains, compilers, or build from source, Mesh is distributed as a lightweight, cross-platform Docker container image: ethernmyth/mesh:latest. Any developer or CI/CD pipeline with Docker installed can pull the image and immediately enforce preflight security policies, manage encrypted credentials, analyze stack topologies, run diagnostics, and automate container hardening without platform-specific dependencies.

⁠The Intention of Mesh

⁠Why Mesh Exists

Modern development teams rely heavily on Docker and Docker Compose to rapidly spin up local microservices, databases, caches, and web applications. However, local developer configurations frequently suffer from severe security misconfigurations:

1. Accidental Public Exposure: Database containers (PostgreSQL, MySQL, Redis, MongoDB) are often mapped to 0.0.0.0 or bound to public interfaces, exposing internal data stores to the host network, LAN, or public internet.
2. Credential Leakage: Plaintext passwords, tokens, and API keys are routinely committed to docker-compose.yml, embedded in .env files, logged to stdout/stderr, or pushed to Git repositories.
3. Excessive Privileges: Containers often run as root (UID 0), execute in privileged: true mode, or mount /var/run/docker.sock, giving compromised containers root escape capabilities on the host.
4. Reliability & Resource Starvation: Services lack CPU and memory constraints or healthcheck definitions, leading to memory exhaustion (OOM), silent hangs, and race conditions during stack boot.
5. Lack of Automated Hardening: Hardening configurations manually is tedious and error-prone, causing developers to skip security controls until production incidents occur.

Mesh solves this by providing a unified, deterministic preflight security control plane:

• Deterministic engine is authoritative: All security rules, scans, scores, and policy gates are 100% deterministic and fail closed on violations.
• Encrypted local vault: AES-256-GCM encryption with PBKDF2 derived keys. Plaintext secret values are never displayed on stdout/stderr, never logged, and never written to Git.
• Transient runtime injection: Secrets are injected only at launch into protected runtime files (0600 permissions) and are securely wiped upon mesh down.
• Automated lockdown: One command (mesh lockdown --apply) transforms insecure compose definitions into hardened, least-privilege configurations with automatic backups.
• Privacy-preserving advisory AI: When enabled, connects strictly to a user-configured local LLM (e.g. Ollama). All prompts pass through an automatic redaction pipeline first. The AI is advisory only and has zero execution authority.

⁠Architecture & Separation of Responsibility

mesh.yaml (User Config)
   │
   ▼
Config ──► Policy Engine ──► Deterministic Security Checks ──► Runtime (Docker Engine)
              │                     │
              │                     ├──► Graph / Doctor / Security Score / Lockdown
              │
              └──► Secrets Vault
                        │
                        ├──► Encrypted local vault (AES-256-GCM / PBKDF2)
                        │
                        └──► Transient runtime injection (Scrubbed on down)

Optional (User-configured local LLM):
Diagnostic context ──► Secret Redaction ──► Local Ollama ──► Advisory Notice (Human-in-the-loop)

⁠Separation of Responsibility

1. Docker executes: Docker and Docker Compose remain responsible for container lifecycle, networking, and process execution.
2. Mesh controls: Mesh governs preflight validation, security policy enforcement, secret lifecycles, environment diagnostics, and orchestration gates.
3. Deterministic engine is authoritative: Security rules and preflight gates cannot be bypassed by heuristic or probabilistic guesses.
4. AI is advisory only: The LLM cannot authorize changes, modify files, rotate secrets, or execute Docker commands. Human review and explicit approval are mandatory.

⁠100% User-Configured: No Hardcoded Ports, Containers, Images, or AI

⁠Installation & Usage via Docker (ethernmyth/mesh:latest)

Because Mesh runs as a Docker container, you do not need to install Go, compilers, or build tools on your machine. Simply pull the image from Docker Hub and start using Mesh immediately.

⁠1. Pull the Docker Image

docker pull ethernmyth/mesh:latest

⁠2. Running Mesh Commands

Run Mesh by mounting the Docker socket and your current working directory:

# General syntax
docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$PWD:/work" \
  -w /work \
  -e MESH_VAULT_PASSWORD \
  ethernmyth/mesh:latest <command>

⁠3. Create a CLI Alias (Recommended)

To run mesh seamlessly as a native command, add an alias or function to your shell profile:

⁠Linux / macOS / WSL (Bash or Zsh):

Add this line to ~/.bashrc or ~/.zshrc:

alias mesh='docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock -v "$PWD:/work" -w /work -e MESH_VAULT_PASSWORD ethernmyth/mesh:latest'

Then reload your shell:

source ~/.bashrc   # or source ~/.zshrc

⁠Windows (PowerShell):

Add this function to your PowerShell profile ($PROFILE):

function mesh {
    docker run --rm -it `
      -v /var/run/docker.sock:/var/run/docker.sock `
      -v "${PWD}:/work" `
      -w /work `
      -e MESH_VAULT_PASSWORD `
      ethernmyth/mesh:latest $args
}

Now you can simply type mesh init, mesh security scan, mesh up, etc., in any project directory!

⁠CLI Command Reference

All commands are available directly through the Docker image:

⁠Complete Step-by-Step Workflow

Follow these steps to run the complete Mesh workflow using the Docker image.

⁠Step 1: Initialize Stack Configuration

In your project directory, initialize a new mesh.yaml:

mesh init

This generates a starter mesh.yaml file in your workspace.

⁠Step 2: Configure Your Services & Ports

Edit mesh.yaml with your custom services, images, ports, and policy rules. Note how all ports and images are user-defined:

name: my-app-stack

services:
  # User-configured frontend / reverse proxy
  gateway:
    image: nginx:alpine
    user: "10001:10001"
    read_only: true
    ports:
      - "8080:80"                      # User-specified port mapping
    resources:
      limits:
        cpu: "0.5"
        memory: "256M"
    healthcheck:
      test: ["CMD-SHELL", "wget -q --spider http://localhost:80 || exit 1"]

  # User-configured backend API
  api:
    image: my-company/backend-api:v1.2.0
    user: "10001:10001"
    read_only: true
    ports:
      - "3000:3000"                    # User-specified port mapping
    secrets:
      - app_secret_key
      - db_password
    depends_on:
      - postgres
    resources:
      limits:
        cpu: "1.0"
        memory: "512M"
    healthcheck:
      test: ["CMD-SHELL", "wget -q --spider http://localhost:3000/health || exit 1"]

  # User-configured PostgreSQL database
  postgres:
    image: postgres:18-alpine           # User-specified database image
    user: "10001:10001"
    read_only: true
    ports:
      - "127.0.0.1:5433:5432"          # Custom user-defined host port (5433) safely bound to localhost
    secrets:
      - db_password
    resources:
      limits:
        cpu: "1.0"
        memory: "1G"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready || exit 1"]
    security:
      public_database: deny

security:
  privileged: deny
  host_network: deny
  docker_socket: deny
  root_user: warn
  public_database: deny
  writable_root_filesystem: warn
  missing_healthcheck: warn
  resource_limits: require
  excessive_capabilities: deny
  hardcoded_secrets: deny

# User-configured local AI (Disabled by default)
ai:
  enabled: false
  provider: ollama
  endpoint: http://host.docker.internal:11434  # User-defined local endpoint
  model: qwen3                                 # User-defined model

⁠Step 3: Run Preflight Security Scan & Scoring

Audit your stack configuration deterministically before running containers:

# Run deterministic policy scan
mesh security scan

# View quantitative security score and category deductions (A-F grade)
mesh security score

If any service violates a deny or require rule (such as public database port exposure, privileged mode, or missing resource limits), mesh security scan --fail-closed immediately halts execution with a non-zero exit code.

⁠Step 4: Manage Encrypted Secrets

Manage credentials without ever writing plaintext passwords into YAML files, Dockerfiles, or Git:

# Optional: supply vault master passphrase (or omit to use local protected vault.key)
export MESH_VAULT_PASSWORD="my-secure-master-passphrase"

# Generate cryptographically secure random secrets
mesh secret create db_password
mesh secret create app_secret_key

# List secrets in the vault (metadata only; values are NEVER displayed)
mesh secret list

# Verify secret hygiene and audit bindings
mesh security secrets

# Rotate a secret safely
mesh secret rotate db_password

⁠Step 5: Dependency Graph & Environment Diagnostics

Inspect service dependencies and verify environment health:

# Display dependency topology tree
mesh graph

# Run comprehensive environment diagnostics
mesh doctor

⁠Step 6: Automated Security Lockdown

Let Mesh automatically remediate configuration weaknesses (non-root enforcement, read-only rootfs, localhost port restrictions, resource limits, healthchecks):

# Preview proposed hardening changes without altering files
mesh lockdown --preview

# Apply hardening transformations to mesh.yaml (creates automatic .bak backup)
mesh lockdown --apply -y

# Re-run security scan and score to confirm compliance
mesh security scan
mesh security score

⁠Step 7: Launch and Inspect Containers

Start the stack with preflight validation and automated transient runtime secret injection:

# Launch containers in detached mode
mesh up -d

# Inspect live container states, health status, and port bindings
mesh status

# Stream service logs
mesh logs api

# Run doctor diagnostics against the live running stack
mesh doctor

⁠Step 8: Advisory AI Analysis (Optional & Local)

When you enable AI in mesh.yaml with your preferred local Ollama endpoint and model:

# Architectural explanation and boundary analysis
mesh ai explain

# Finding diagnostics and remediation guidance
mesh ai diagnose

# Quantitative hardening advice prioritized by security score
mesh ai security

⁠Step 9: Teardown & Secret Sanitization

When stopping your containers, Mesh automatically scrubs all transient secret files from disk:

mesh down

⁠Security Policy Model

Policies in mesh.yaml support four deterministic actions:

• deny: Blocks container launch (mesh up fails closed with a non-zero exit).
• require: Mandatory security parameter; blocks startup if omitted.
• warn: Emits an advisory finding in CLI output but permits execution.
• allow: Silently permits the configuration option.

You can set global policies under the top-level security: block, and override specific rules per service under services.<name>.security:.

⁠Security Invariants

The Mesh implementation strictly adheres to these non-negotiable security guarantees:

• Zero Plaintext Secret Display: Secrets are never printed to stdout/stderr, logged, or checked into Git.
• Encrypted Secret Storage: Secrets at rest are encrypted with AES-256-GCM and PBKDF2 derived keys via MESH_VAULT_PASSWORD.
• Preflight Fail-Closed: Configured deny or require policy violations immediately block container startup (mesh up).
• Secret Redaction Pipeline: Automatic masking of passwords, bearer tokens, AWS keys, JWTs, private keys, and known vault secrets before sending any prompt to AI.
• Safe AI Defaults: AI is disabled by default; when enabled, it connects strictly to a user-configured local Ollama endpoint. Never transmits data to external or remote cloud providers.
• Docker Socket Containment: Detects and flags /var/run/docker.sock mounts into containers as critical security risks.
• Dynamic Port & Database Scanning: Evaluates privileged mode, root users, host networking, public database exposure, writable root filesystems, excessive Linux capabilities, missing health checks, and missing resource limits dynamically across all user-configured ports and images.
• Ephemeral Runtime Secrets: Plaintext secret files provisioned for Docker Compose are scrubbed upon mesh down.

⁠Building the Docker Image from Source (Maintainers)

If you are developing or contributing to Mesh, you can build the Docker image locally:

# Run unit and integration tests
go test -v ./...
go vet ./...

# Build the official lightweight scratch container image
docker build -t ethernmyth/mesh:latest .

Container properties:

• Base: scratch (zero overhead, no shell, no package manager, no compiler)
• User: 65534:65534 (rootless nobody)
• Image Size: ~10.2 MB disk usage / ~3.09 MB content size
• Binary: Statically linked Go binary (CGO_ENABLED=0) with stripped symbols (-ldflags="-s -w")
• CA Certificates: Included for secure outbound TLS (Ollama endpoints, Docker API)

⁠Security Assumptions & Boundaries

1. Docker Daemon Access: The Docker socket or API is the most privileged boundary on a host. Mesh warns if docker.sock is mounted into application containers and interacts with Docker through least-privilege operations.
2. Local Encrypted Vault: The vault encrypts data using AES-256-GCM. When MESH_VAULT_PASSWORD is supplied, keys are derived via PBKDF2 (100,000 iterations). Plaintext secrets are decrypted in-memory only during runtime injection and written to transient files with 0600 permissions.
3. Execution Layer Scope: Mesh orchestrates local Docker stacks and Docker Compose projects. It is deliberately not a Kubernetes replacement or distributed cluster scheduler.
4. Advisory AI Boundary: LLMs cannot authorize configuration changes or execute commands. All AI suggestions must be reviewed and applied by humans using deterministic tools (such as mesh lockdown --apply).

⁠Author

Created and Maintained by: Ethern Myth⁠