SPB Git

Repository Public

SECURITY.md 7.4 KB

# Sécurité — MacLustr LLM API

# Surface exposée

Élément Exposition
https://llm.spboucher.ai publique, TLS terminé par Caddy sur la passerelle du cluster (Let's Encrypt), HSTS
Documentation, statut (/, /docs, /status, /api/status, /openapi.json) publics, sans donnée interne
API /v1/* clé API Bearer obligatoire (ou session admin + CSRF pour le Playground)
Dashboard /admin/api/* session Passkey obligatoire ; la coquille HTML /admin ne contient aucune donnée
Activation /setup/<jeton>, /api/setup/* jeton à usage unique généré localement
Passerelle :8810 LAN + interface WireGuard du tunnel ; toutes ses routes sont celles ci-dessus
Moteur MLX :8811 bouclage uniquement (127.0.0.1), refus de démarrer sur une autre adresse

# Clés API

  • Format mlx_sk_<8 hex>_<43 caractères> : 256 bits d'aléa (secrets.token_urlsafe(32)).
  • Seul un HMAC-SHA-256 à clé serveur est stocké (api_keys.key_hash) ; la clé serveur (secret.key, 32 octets, mode 600) est hors dépôt et hors base. Un KDF lent n'apporterait rien pour un secret de 256 bits.
  • Le secret n'est affiché qu'une fois, à la création ou à la rotation (réponse Cache-Control: no-store).
  • Par clé : modèles et endpoints autorisés, classe de priorité, requêtes/min, tokens/min, quotas quotidien et mensuel, concurrence maximale, date d'expiration, désactivation, révocation, rotation atomique.
  • Tentatives avec clés invalides : freinées par IP (30/min → 429 too_many_attempts).

# Administration par Passkey (WebAuthn / FIDO2)

  • Aucun mot de passe, aucun code PIN applicatif, aucun nom d'utilisateur : identifiants découvrables (residentKey: required), vérification utilisateur exigée (userVerification: required) → Touch ID, Face ID ou code de l'appareil, gérés par le système. Le serveur ne reçoit qu'une signature et ne stocke qu'une clé publique ; aucune donnée biométrique ne quitte l'appareil.
  • Vérifications serveur (bibliothèque webauthn) : défi, origine (https://llm.spboucher.ai), identifiant de partie de confiance, signature, drapeau de vérification utilisateur, compteur de signatures.
  • Défis : aléatoires, liés à leur usage (activation, connexion, ré-authentification), valables 5 minutes, consommés en transaction — une réponse rejouée est refusée.
  • Passkeys synchronisées (trousseau iCloud) acceptées et signalées comme telles ; plusieurs Passkeys possibles ; la dernière ne peut pas être supprimée.

# Lien d'activation à usage unique

maclustr-llm setup-link (à lancer sur le Mac mini) :

  • jeton de 256 bits, stocké sous forme de condensat, valable 15 minutes, usage unique ;
  • affiché dans le terminal seulement — jamais écrit dans un fichier, un journal ou Git ;
  • un nouveau lien invalide les précédents ; un lien d'activation est refusé si un administrateur existe déjà ;
  • l'enregistrement de la Passkey, la création de l'administrateur et l'invalidation du lien se font dans une seule transaction ; l'unicité de l'administrateur est en plus garantie par une contrainte de la base ;
  • le chemin /setup/… est masqué dans le journal de la passerelle et exclu du journal d'accès du proxy public ; la page est servie avec Cache-Control: no-store et Referrer-Policy: no-referrer.

# Récupération

maclustr-llm recover — même mécanisme, exige un accès réel au Mac mini (SSH ou clavier). Le lien permet d'ajouter une nouvelle Passkey au compte existant et révoque toutes les sessions. Il n'existe aucune route web de récupération.

# Sessions

Mesure Mise en œuvre
Cookie __Host-mllm_session : HttpOnly, Secure, SameSite=Strict, Path=/, sans domaine
Identifiant 256 bits aléatoires, stocké haché ; nouveau à chaque authentification
Durée 7 jours au plus, 12 h d'inactivité
CSRF jeton distinct (en-tête X-CSRF-Token) exigé sur toute requête non-GET, renouvelé à chaque lecture de session ; Origin étranger refusé
Authentification récente création / rotation / révocation de clé, ajout / suppression de Passkey, rechargement du moteur, révocation globale → Passkey datant de moins de 5 minutes, sinon 401 reauth_required
Révocation déconnexion, « révoquer les autres sessions », maclustr-llm revoke-sessions en local
Force brute routes d'authentification et d'activation freinées par IP (20 essais / 5 min)
Permissions vérifiées côté serveur sur chaque route ; une clé API ne donne jamais accès à l'administration

# En-têtes et navigateur

Content-Security-Policy stricte (script-src 'self', aucun script en ligne, aucune ressource externe), Strict-Transport-Security, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, Permissions-Policy. CORS ouvert sans credentials sur /v1 seulement (authentification par jeton, jamais par cookie cross-origin).

# Protection contre les abus et la surcharge

Taille du corps bornée (4 Mo), nombre de messages borné, fenêtre de contexte vérifiée avec le tokenizer du modèle avant d'atteindre le moteur, max_tokens plafonné, délais (file, premier token, génération), file bornée, budget de tokens en vol, garde sur la pression mémoire. Les messages d'erreur du moteur sont réduits à leur première ligne (pas de chemin ni de trace).

# Journalisation et conservation

Donnée Où Conservation
Prompts, réponses nulle part —
Journal d'accès de la passerelle (méthode, chemin sans jeton, statut, durée, identifiant) ~/maclustr-llm-data/logs/gateway.log rotation 5 × 20 Mo
Journal du moteur (progression, sans contenu) logs/engine.log rotation 5 × 20 Mo
Métadonnées par requête request_log 30 jours
Agrégats d'usage par minute usage_minute 400 jours
Échantillons système sys_samples 7 jours
Journal d'audit administratif audit_log conservé

Événements audités : activation, récupération, connexions réussies et échouées, ré-authentifications, déconnexions, ajout / suppression de Passkey, création / modification / rotation / révocation de clé, rechargement du moteur, révocation globale, création de liens.

# Tests de sécurité automatisés (tests/test_auth.py, tests/test_api.py)

Dashboard fermé sans session (toutes les routes) · une clé API n'ouvre pas l'administration · lien à usage unique, expirant, invalidé par le suivant · activation atomique · origine WebAuthn falsifiée refusée · signature falsifiée refusée · défi non rejouable · identifiant de session renouvelé et haché · CSRF et Origin · authentification récente · cycle de vie des clés · révocation globale · récupération qui révoque les sessions · freins anti-force-brute · aucun secret ni prompt au repos (base et journaux fouillés) · permissions des fichiers.

# Limites connues

  • Le pare-feu applicatif de macOS est désactivé sur le nœud (état trouvé à l'audit, commun au cluster) ; la protection repose sur l'écoute en bouclage du moteur, l'authentification de toutes les routes de la passerelle et le routeur du LAN.
  • Pas d'audit de sécurité indépendant ni de test d'intrusion externe.
  • Le terminal TLS est la passerelle du cluster (BHS64) : le trafic y est en clair avant de repartir chiffré dans WireGuard vers le Mac mini.
Files main
Menu

Theme