wiki/Catalogue-Self-Hosted/apps/app-docker-socket-proxy.md

---
title: Docker Socket Proxy
created: 2026-06-06
updated: 2026-06-06
type: app
tags: [catalogue, reverse-proxy, docker, security, hardening]
confidence: high
contested: false
sources: [https://selfh.st/apps/?tag=Reverse+Proxy, https://github.com/tecnativa/docker-socket-proxy]
---

# 🔌 Docker Socket Proxy

> **Proxy HTTP/HTTPS filtrant l'accès à l'API Docker Socket, écrit en Python**. Réputation : composant de sécurité quasi obligatoire pour toute stack self-hosted qui monte `/var/run/docker.sock` dans des conteneurs tiers.

## 📋 Informations Générales

| Champ | Valeur |
| :--- | :--- |
| **Site web** | [github.com/tecnativa/docker-socket-proxy](https://github.com/tecnativa/docker-socket-proxy) |
| **GitHub** | [tecnativa/docker-socket-proxy](https://github.com/tecnativa/docker-socket-proxy) |
| **License** | Apache-2.0 |
| **Langage** | Python 75.8%, Shell |
| **Étoiles GitHub** | 2.5k ⭐ |
| **Dernière MAJ** | 2026-04 |
| **Catégorie** | [[cat-reverse-proxy\|Sécurité]], Reverse Proxy, Docker |

## 📝 Description

**Docker Socket Proxy** est un **reverse proxy minimaliste** placé en amont du socket Docker Unix. Son rôle : **appliquer une liste blanche d'API endpoints** autorisés (ex : GET /containers/json) afin qu'un conteneur compromis ne puisse pas escalader ses privilèges et prendre le contrôle du daemon Docker.

Le problème qu'il résout est critique : monter `/var/run/docker.sock` dans un conteneur (ce que font **Watchtower**, **Traefik**, **Portainer**, **Dozzle**, etc.) lui donne par défaut **un accès root complet à l'hôte**. Un attaquant qui compromet l'un de ces conteneurs peut alors démarrer de nouveaux conteneurs privilégiés, lire le filesystem hôte, ou exfiltrer des secrets. Docker Socket Proxy **intercepte les requêtes** et **refuse tout endpoint non explicitement autorisé**.

L'outil est extrêmement léger (image basée sur Alpine + script Python de ~300 lignes), **zéro configuration** par défaut, et proposé en deux saveurs : l'originale (Tecnativa) et un fork **linuxserver** avec la même philosophie.

**Public cible** : **tous les utilisateurs self-hosted** qui montent le socket Docker dans des conteneurs. Devrait être systématique. C'est l'un des **quick wins sécurité** les plus rentables du domaine.

## 🚀 Installation

### Option 1 : Docker Compose (standard)

```yaml
# docker-compose.yml
services:
  docker-socket-proxy:
    image: tecnativa/docker-socket-proxy
    container_name: docker-socket-proxy
    restart: unless-stopped
    environment:
      - CONTAINERS=1     # autoriser GET /containers
      - IMAGES=1         # autoriser les opérations sur les images
      - NETWORKS=1
      - VOLUMES=1
      - POST=0           # bloquer toutes les méthodes POST (lecture seule)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - socket-proxy

networks:
  socket-proxy:
    internal: true
```

> ⚠️ **Réseau `internal: true`** crucial : empêche tout conteneur compromis d'exfiltrer via ce proxy.

### Utilisation depuis une app (exemple Traefik)

```yaml
services:
  traefik:
    image: traefik:v3
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro  # ❌ NON
      # ✅ Remplacer par :
      # On monte le proxy réseau au lieu du socket direct
    networks:
      - socket-proxy

# Portainer, Watchtower, etc. pointent vers http://docker-socket-proxy:2375
```

> ⚠️ **Note** : la plupart des apps qui consomment l'API Docker (Portainer, Traefik) **parlent au socket Unix** — il faut des proxys TCP spéciques ([tecnativa](https://github.com/tecnativa/docker-socket-proxy) ou [socat](https://linux.die.net/man/1/socat)) ou des forks qui supportent HTTP.

### Option 2 : Variante Traefik

Non applicable — ce n'est pas un reverse proxy HTTP public, c'est un **proxy interne** pour l'API Docker.

## ⚙️ Configuration Initiale

1. **Choisir les endpoints autorisés** via variables d'environnement (par convention `<ENDPOINT>=1`)
2. **Méthodes** : `GET`, `POST`, `PUT`, `DELETE`, `HEAD`, `PATCH` (0 = bloqué, 1 = autorisé)
3. **Endpoints courants** : `CONTAINERS`, `IMAGES`, `NETWORKS`, `VOLUMES`, `SERVICES`, `TASKS`, `NODES`, `SECRETS`, `INFO`, `VERSION`, `EVENTS`
4. **Posture stricte recommandée** : n'autoriser que ce qui est strictement nécessaire

```bash
# Exemple : lecture seule stricte (Watchtower)
WATCHTOWER_MONITOR_ONLY=true
WATCHTOWER_HTTP_API_METRICS=true
```

## 🔀 Alternatives

### Open Source
- **socat TCP→Unix** (sans filtrage, juste pour exposer en TCP)
- **docker-socket-proxy linuxserver** : fork avec la même philosophie
- **Tailscale + socket exposure** : exposition via réseau privé uniquement
- **Rootless Docker** : solution plus radicale (mais incompatible avec beaucoup d'images)

### Comparaison des approches

| Approche | Filtrage | Complexité | Compatibilité |
| :--- | :--- | :--- | :--- |
| **Docker Socket Proxy** | ✅ Granularité fine | Faible | ⚠️ Nécessite proxy HTTP |
| **Socket via réseau Tailnet** | ❌ Aucun | Moyenne | ✅ Universelle |
| **Rootless Docker** | ❌ (mais pas root) | Élevée | ⚠️ Limité |
| **Pas de socket monté** | ✅ Par construction | Variable | ❌ Apps qui en ont besoin KO |

### Propriétaires (ce que ça remplace)
- **Docker EE / Mirantis** : filtrage commercial
- **Sysdig Secure / Falco** : runtime security (complémentaire, pas remplaçant)

## 🔒 Sécurité

- ✅ **Liste blanche** par défaut : tout est bloqué sauf ce qui est activé
- ✅ **Méthodes HTTP** filtrables indépendamment
- ✅ **Image minimaliste** (Alpine + Python)
- ✅ **Pas de dépendances** réseau-sortant
- ✅ **Open source auditable** : ~300 lignes de Python, facile à relire
- ⚠️ **Ne protège pas contre** : un attaquant qui peut envoyer des requêtes *autorisées* malicieuses (ex : supprimer un conteneur via DELETE /containers/...)
- ⚠️ **À combiner avec** : [[app-fail2ban]], [[app-crowdsec]], monitoring d'API

## 📚 Ressources

- [README GitHub](https://github.com/tecnativa/docker-socket-proxy)
- [Discussion #45 sur la licence](https://github.com/Tecnativa/docker-socket-proxy/discussions/45)
- [Guide de hardening Docker](https://docs.docker.com/engine/security/)
- [Wiki selfh.st](https://selfh.st/apps/?tag=Reverse+Proxy)

## 🔗 Pages Liées

- [[cat-reverse-proxy]] — Catégorie Reverse Proxy
- [[securisation-home-lab]] — Sécurité
- [[docker-compose]] — Orchestration de conteneurs
- [[comparatif-reverse-proxy]] — Comparaison détaillée
- [[app-traefik]] — Consommateur typique de l'API Docker
- [[app-portainer]] — Consommateur typique de l'API Docker