Sécurité — MacLustr Command Center
État décrit : commit 45f0d03, déploiement du 2026-11-18. Chaque mesure cite le fichier qui l'implémente et, quand
il existe, le test qui la prouve. Les observations [prod] viennent du responsable du déploiement (2026-11-18) et
ne sont pas vérifiables depuis ce dépôt. Les lacunes sont listées en §14 ; aucun audit de
sécurité indépendant n'a été réalisé.
Documents liés : ARCHITECTURE.md · AGENT-PROTOCOL.md · OPERATIONS.md · API.md · ADR 0004, 0005, 0007, 0008, 0010.
1. Modèle de menace
1.1 Actifs
| Actif | Pourquoi il compte | Où il vit |
|---|---|---|
| Capacité d'agir sur les machines | une action malveillante arrête un service ou un nœud | clé command-signing.key (orchestrateur), politique locale de chaque agent |
| Comptes et passkeys | accès au pilotage | tables users, passkeys (clés publiques seulement) |
| Sessions et jetons | usurpation d'un utilisateur connecté | sessions, refresh_tokens (hachés SHA-256) |
| Journal d'audit | preuve de ce qui a été fait | audit_log (chaîne de hachage), clé audit-signing.key |
| AC des agents | permet d'émettre une identité d'agent | agent-ca.key |
| Données privées des nœuds | adresses IP/MAC, numéros de série, UUID matériel | nodes.inventory, node_state |
| Sorties de commandes et journaux | peuvent contenir des détails opérationnels | action_events (expurgées) |
| Sauvegardes | copie complète de la base | fichiers mcc-*.dump.enc, clé backup.key |
1.2 Acteurs
| Acteur | Capacité supposée |
|---|---|
| Anonyme sur Internet | atteint https://clustr.spboucher.ai (API, pages, /agent/v1/) |
| Utilisateur légitime de rôle faible (viewer, operator) | session valide, cherche à dépasser ses droits |
| Détenteur d'un lien d'invitation fuité | possède un jeton à usage unique valide quelques minutes |
| Voleur d'un appareil ou d'un jeton de session | rejoue un cookie, un jeton d'accès ou de rafraîchissement |
| Agent compromis (un nœud) | possède la clé et le certificat de cet agent, contrôle ce qu'il rapporte |
| Ingestion ou passerelle compromise | lit et modifie le trafic agent ↔ plan de contrôle |
| Site tiers dans le navigateur de la victime | déclenche des requêtes inter-origines (CSRF), tente d'encadrer l'interface |
| Attaquant sur l'hôte (compte du service) | hors périmètre des défenses logicielles : lit la base et les clés (voir §14) |
1.3 Points d'entrée
| Point d'entrée | Exposition | Authentification |
|---|---|---|
/api/v1/* |
Internet, via la passerelle | cookie de session ou jeton Bearer ; 7 opérations publiques, 3 liées à la transaction d'invitation |
/api/v1/events (SSE) |
Internet | session, revérifiée chaque minute |
/agent/v1/* |
Internet (relais de control-api) |
preuve de possession par requête ; /enroll : jeton à usage unique |
/.well-known/apple-app-site-association |
Internet | aucune (fichier public) |
Pages web (/, /signin, /setup, …) |
Internet | coquilles sans données ; les données passent par l'API |
| Écoute mTLS de l'ingestion (8801) | loopback en production [prod] | certificat client de l'AC privée |
mccctl |
SSH sur l'hôte | accès au compte du service ; audité actor_kind=cli |
| PostgreSQL | loopback | accès local |
1.4 Tableau STRIDE
| # | Menace | Catégorie | Mesure (source) | Preuve |
|---|---|---|---|---|
| S1 | Hameçonnage : faire signer une assertion pour une autre origine | Usurpation | WebAuthn lié à l'origine et au RP ID (identity/service.go : RPOrigins, RPID) |
TestChallengeAndAssertionAbuse — sous-tests « phishing origin », « wrong RP ID » (services/internal/identity/identity_test.go) |
| S2 | Rejeu d'un défi ou d'une assertion WebAuthn | Usurpation | défi à usage unique consommé avant vérification ; un échec le brûle (identity/webauthn.go : consumeChallenge) |
mêmes tests — « challenge replay », « a failed attempt burns the challenge », « expired challenge », « assertion for another challenge » |
| S3 | Authentificateur cloné | Usurpation | régression du compteur de signature → refus + audit (FinishAuthentication) |
TestClonedAuthenticatorDetected |
| S4 | Connexion sans vérification de l'utilisateur (UV) | Usurpation | userVerification=required, drapeau UV vérifié côté serveur |
sous-test « no user verification » ; options userVerification: required observées [prod] |
| S5 | Réutilisation d'une invitation | Usurpation | consommation atomique (UPDATE … WHERE consumed_at IS NULL) ; erreur unique pour tous les cas |
TestInvitationSingleUse (« reuse after exchange », « concurrent exchange has exactly one winner », « expired », « revoked ») ; TestHTTPInvitationAbuse ; Playwright « reusing the link in another browser is a dead end » |
| S6 | Invitation utilisée pour greffer une passkey sur un compte existant | Élévation | invitation link : session de ce compte + step-up + confirmation (LinkSetup) ; recovery seulement hors bande |
TestLinkInvitationRequiresTheRightAccountAndStepUp, TestRolesAndTakeoverProtection, TestRecoveryIsOutOfBandAndRevokesOldCredentials |
| S7 | Vol d'un jeton de rafraîchissement | Usurpation | rotation à chaque usage ; réutilisation d'un jeton déjà tourné → session révoquée + audit (identity/sessions.go : Refresh) |
TestRefreshRotationAndReuseDetection, TestHTTPNativeBearerRefreshAndDeviceRevocation |
| S8 | Usurpation d'un agent | Usurpation | certificat de l'AC privée (usage clientAuth), numéro de série non révoqué, signature par requête, fenêtre ±90 s, nonce (ingest/signed.go) |
TestSignedRequestRejections, TestSignedRequestCertificateProperties, TestRevocationAndForeignCA ; requête non signée refusée 401 [prod] |
| S9 | Usurpation du service d'ingestion par une clé d'agent volée | Usurpation | usages disjoints serverAuth / clientAuth (pki/pki.go) |
TestCAAndCertificates |
| T1 | Commande forgée ou modifiée en transit | Altération | signature Ed25519 de l'orchestrateur vérifiée par l'agent (protocol/envelope.go) |
TestVerifyRejections, TestTamperedCommandIsDetectedByTheAgent |
| T2 | Rejeu d'une commande signée | Altération | nonce persistant (agent/nonce), durée de vie ≤ 120 s |
TestVerifyAcceptsOnceThenRejectsReplay, TestRememberReplayRestart, TestConcurrentSingleWinner, TestSignRefusesLongLivedCommands |
| T3 | Commande dupliquée (double clic, reprise réseau, redémarrage) | Altération | Idempotency-Key + empreinte du corps ; une commande par action ; verrou par cible |
TestIdempotency, TestTargetLockAndRelease (api/ops_actions_test.go), TestCrashRestartNeverIssuesASecondCommand, TestTwoInstancesNoDuplicates ; tests/e2e/local-stack.sh |
| T4 | Modification du journal d'audit | Altération | déclencheurs refusant UPDATE/DELETE/TRUNCATE ; chaîne de hachage ; export signé |
TestChainAppendVerifyAndTamperDetection, TestAuditExportSignedAndVerifiableOffline, TestAuditVerifyExportCommand ; mccctl audit-verify OK [prod] |
| T5 | CSRF depuis un site tiers | Altération | cookie SameSite=Strict + en-tête X-MCC-CSRF (HMAC lié à la session) + vérification d'Origin (api/server.go : admit) |
TestHTTPSetupLoginCookiesAndCSRF, TestBootstrapRegisterLoginAndCSRF ; POST inter-origine refusé 403 [prod] |
| T6 | Injection de commande par les paramètres d'une action | Altération | schémas stricts côté serveur et agent ; argv fixes, jamais de shell ; valeurs commençant par - refusées (actions/schema.go, agent/policy, agent/executor) |
TestParamValidation, TestJobTemplates, TestPrepareRefusals, TestPurgeCacheNeverLeavesTheDirectory |
| T7 | Agent compromis envoyant des données fausses | Altération | validation stricte (métriques connues, cardinalité, horloge) ; effet limité à son propre nœud | TestReportValidation, TestCommandIsolationBetweenAgents ; non empêché : mentir sur ses propres mesures |
| R1 | Nier une action | Répudiation | toute création, refus, approbation, annulation est auditée avec acteur, session, appareil, IP, id de corrélation | TestAuditListingAndVerify, TestCreateActionRefusals (les refus sont audités) |
| R2 | Nier une opération hors bande | Répudiation | mccctl écrit actor_kind=cli (cmd/mccctl/main.go, identity/invitations.go) |
lecture du code ; pas de test dédié à l'entrée d'audit CLI |
| I1 | Fuite des données privées des nœuds à un rôle faible | Divulgation | permission nodes.private.read appliquée par nœud (api/cluster_nodes.go, cluster_network.go, cluster_storage.go) |
TestNodePrivateFieldsNeedPermission |
| I2 | Secrets dans les sorties de commandes | Divulgation | expurgation à l'agent puis au serveur (internal/redact) ; lignes de commande des processus jamais collectées |
TestString, TestValue, TestStreamPEM (redact), TestOutputCapAndRedaction |
| I3 | Oracle sur l'existence d'un compte ou d'une invitation | Divulgation | erreurs uniformes (ErrInvitation, ErrCredential, ErrUnauthenticated) |
« garbage and unknown tokens » (TestInvitationSingleUse), « unknown credential » |
| I4 | Jeton d'invitation dans les journaux ou le Referer |
Divulgation | jeton dans le fragment d'URL, retiré de l'historique ; Referrer-Policy: no-referrer ; les chaînes de requête ne sont pas journalisées (httpx.AccessLog) |
Playwright « invitation link: the fragment leaves the URL and the history at once » (01-identity.spec.ts) |
| I5 | Fuite par le flux d'événements | Divulgation | filtrage des sujets par permission (api/events_stream.go : topicPermission) |
TestHTTPEventStream |
| I6 | Fuite par la recherche ou le fil d'activité | Divulgation | la recherche respecte les permissions ; l'activité est une projection expurgée de l'audit | TestSearchRespectsPermissionsAndEscapesWildcards, TestActivityIsARedactedProjectionOfTheAuditLog |
| I7 | Détails internes dans les erreurs | Divulgation | erreurs inconnues → 500 internal opaque, détail journalisé avec l'id de corrélation (httpx.WriteError) |
lecture du code ; l'enveloppe d'erreur est testée pour 404 et 400 (TestHTTPEnvelopeFallbackAndRateLimit), pas le cas 500 |
| D1 | Force brute / saturation des cérémonies publiques | Déni de service | limite par IP sur les opérations publiques ; 5 échecs d'enregistrement révoquent l'invitation | TestLimiter, TestHTTPEnvelopeFallbackAndRateLimit, TestSetupAttemptLimit ; Playwright « rate limit on passkey ceremonies… » |
| D2 | Rafale d'actions par un compte | Déni de service | 30 actions/min par utilisateur (api/ops_actions.go) |
TestActionRateLimit |
| D3 | Rapports ou sorties démesurés | Déni de service | corps ≤ 1 Mio, cardinalités bornées, sortie ≤ 2 000 lignes / 512 Kio par commande | TestReportValidation, TestOutputCapAndRedaction |
| D4 | Verrouillage d'une cible par une action abandonnée | Déni de service | approbation expirée après 30 min, verrou libéré ; échéances sur toute commande | TestApprovalExpiresAndReleasesTheLock, TestDeliveredWithoutResultIsOutcomeUnknown |
| E1 | Rôle insuffisant | Élévation | permission par opération (table générée) + contrôle par ressource | TestAdministrationIsRefusedToViewersAndOperators, TestHTTPAuthorizationAndStepUp, TestRoleDefaults ; Playwright « the API itself refuses the viewer » |
| E2 | Élévation par octroi de politique | Élévation | un allow ne donne jamais actions.run.critical hors owner, ni les permissions d'administration sous admin ; deny l'emporte (authz.Decide) |
TestGrantsCannotEscalate, TestDenyWinsAndScopes, TestPolicyGrantsTakeEffectAndAreValidated, TestScopedDenyGrant |
| E3 | Un admin crée ou modifie un owner ; suppression du dernier owner | Élévation | authz.CanAssignRole ; verrou consultatif + ErrLastOwner |
TestCanAssignRole, TestUserAdministrationRules, TestLastOwnerProtected |
| E4 | Auto-approbation d'une action critique | Élévation | l'approbateur ≠ le demandeur, actions.approve + step-up (api/ops_actions.go : decide) |
TestApprovalFlow |
| E5 | Session volée utilisée pour une opération sensible | Élévation | step-up (cérémonie passkey < 5 min) exigé côté serveur | TestStepUp, TestHTTPAuthorizationAndStepUp ; Playwright « step-up: an aged session is asked for the passkey… » |
| E6 | Agent poussé à exécuter plus que ce que le propriétaire du nœud autorise | Élévation | politique locale policy.json ; fichier invalide ou inscriptible par d'autres → tout est refusé ; FREEZE |
TestDefaultAndFiles, TestServiceGlobs, TestCachePaths, TestAgentRefusesByPolicy |
| E7 | Appareil ou session révoqués encore utilisables | Élévation | révocation vérifiée à chaque requête (session, appareil, compte désactivé) ; flux SSE coupé dans la minute | TestSessionLifetimesAndRevocation, TestAdminRevokesSessionsDevicesAndPasskeys ; Playwright « revoking a device signs that device out on its next request » |
2. Principes
- Pas de secret partagé pour s'authentifier : passkeys seulement ; les jetons de session sont aléatoires
(256 bits,
services/internal/secret/secret.go) et stockés hachés. - Décision côté serveur : les trois clients ne décident de rien ; les drapeaux affichés par l'interface
(
requires_confirmation, permissions) sont revérifiés par le serveur. - Refus par défaut : une opération absente de la table générée est refusée (
admit) ; un type d'action absent du catalogue est refusé ; un agent sans fichier de politique n'accepte que quatre commandes de lecture. - Séparation des pouvoirs entre services : l'API n'a pas de clé d'agent, l'ingestion n'a pas de clé de commande, l'orchestrateur n'est pas exposé.
- Honnêteté : une valeur non mesurable est déclarée, une issue inconnue est dite inconnue.
3. Passkeys / WebAuthn
Bibliothèque github.com/go-webauthn/webauthn ; configuration dans services/internal/identity/service.go.
| Paramètre | Valeur | Source |
|---|---|---|
| RP ID / origine (production) | clustr.spboucher.ai / https://clustr.spboucher.ai |
MCC_RP_ID, MCC_PUBLIC_ORIGIN (manifeste mld) ; validés au démarrage (config.validate) |
| Vérification de l'utilisateur | required, revérifiée sur chaque assertion |
service.go, webauthn.go |
| Identifiants découvrables | residentKey=required (connexion sans nom d'utilisateur) |
service.go |
| Attestation | none : aucun filtrage de modèle d'authentificateur |
service.go, ADR 0005 |
| Défi | à usage unique, valide 5 min (challengeTTL), stocké côté serveur |
webauthn_challenges |
| Compteur de signature | une régression refuse la connexion et laisse le compteur stocké intact | FinishAuthentication |
| Dernière passkey | un utilisateur ne peut pas supprimer sa seule passkey (409 last_passkey) |
RevokePasskey — TestPasskeyManagement |
| Ajout d'une passkey | session + step-up | table des opérations (BeginRegistration, FinishRegistration) |
Les apps Apple utilisent les mêmes passkeys via Associated Domains : le fichier AASA est servi par control-api
(serveAASA, identifiants d'apps dans MCC_APPLE_APP_IDS) et répondait en production [prod]. L'usage réel de
passkeys dans les apps natives n'est pas vérifié ici : voir APPLE-APPS.md.
Non vérifié : authentificateurs de plateforme réels et navigateurs Safari / Firefox réels. Les tests utilisent un
authentificateur logiciel (services/internal/identity/vauth) et l'authentificateur virtuel de Playwright (Chromium).
4. Invitations, amorçage, récupération
Source : services/internal/identity/invitations.go.
- Jeton de 32 octets aléatoires (base64url), seul son SHA-256 est stocké. Durée par défaut 15 min, maximum 24 h.
- Lien
https://clustr.spboucher.ai/setup#<jeton>: le jeton est dans le fragment (jamais envoyé au serveur par la navigation) ; la page l'échange parPOST /invitations/exchangepuis l'efface de l'URL. - L'échange consomme le jeton atomiquement et ouvre une transaction de 10 min (
setupTxTTL) : cookie__Host-mcc_setuppour le web,transaction_token(en-têteX-MCC-Setup-Transaction) pour les apps natives. - 5 échecs de vérification (
maxSetupFailures) révoquent l'invitation. - Trois finalités :
new_account;link(changer le rôle d'un compte existant — exige d'être connecté à ce compte, un step-up et une confirmation explicite) ;recovery(nouvelle passkey sans connexion — créable uniquement hors bande, une seule ouverte par compte : indexinvitations_one_open_recovery). - Un admin ne peut inviter ni owner ni modifier un owner (
authz.CanAssignRole). - Une récupération aboutie révoque toutes les passkeys et sessions précédentes du compte.
- Premier owner :
mccctl bootstrap-owner, refusé dès qu'un owner capable de se connecter existe (BootstrapOwner).
État de production : aucun compte owner n'existe encore ; le propriétaire doit ouvrir lui-même le lien d'amorçage avec sa passkey. Aucun parcours authentifié n'a donc été exercé en production par une personne.
5. Sessions et jetons
Source : services/internal/identity/sessions.go, services/internal/api/server.go.
| Web | Apps natives | |
|---|---|---|
| Porteur | cookie __Host-mcc_session (Secure; HttpOnly; SameSite=Strict; Path=/, cookie de session) |
Authorization: Bearer <jeton d'accès> |
| Durée | inactivité 30 min glissante, absolue 12 h | accès 10 min ; rafraîchissement 30 jours, rotatif ; absolue 180 jours (bearerAbsolute) |
| Stockage serveur | SHA-256 du jeton (sessions.token_hash) |
idem + refresh_tokens |
| Rotation | — | chaque rafraîchissement remplace les deux jetons ; réutilisation d'un jeton tourné = révocation de la session |
| Appareil | cookie __Host-mcc_device (identifiant d'appareil, non secret) |
device_id renvoyé puis représenté par le client |
- En développement sur HTTP, le préfixe
__Host-et l'attributSecuresont absents (core.cookieName). - Un en-tête
Authorizationprésent désactive entièrement la lecture des cookies. - Chaque requête revérifie : session non révoquée, appareil non révoqué, compte non désactivé, expirations.
- Désactiver un compte, révoquer un appareil ou une passkey révoque les sessions liées dans la même transaction.
- Tout échec d'authentification renvoie le même
401 unauthenticated. - Le flux SSE est borné à 30 min et revérifie la session chaque minute.
6. CSRF
core.admit applique, pour toute méthode non sûre :
| Contexte | Exigence |
|---|---|
| Session par cookie | Origin égal à l'origine publique et X-MCC-CSRF valide |
| Transaction d'invitation par cookie | Origin égal à l'origine publique |
Jeton Bearer ou opération publique |
si un en-tête Origin est présent, il doit être l'origine publique |
Le jeton CSRF est HMAC-SHA256(csrf.key, "mcc-csrf-v1\0" || jeton de session) (identity.CSRFToken) : il est lié à
la session et n'est stocké nulle part ; le client l'obtient par GET /me ou dans le résultat de connexion.
Échec : 403 csrf_failed. Le relais /agent/v1/ refuse toute requête portant un en-tête Origin
(agent_proxy.go).
7. Autorisation : rôles, octrois, step-up
Source : services/internal/authz/authz.go.
| Rôle | Permissions par défaut |
|---|---|
| viewer | cluster.read, nodes.read, services.read, models.read, jobs.read, alerts.read, maintenance.read, actions.read |
| operator | viewer + nodes.private.read, logs.read, alerts.ack, maintenance.write, jobs.submit, actions.run.low, actions.run.medium |
| admin | operator + nodes.write, alerts.manage, actions.run.high, actions.approve, audit.read, audit.export, users.manage, invitations.manage, agents.manage, settings.manage |
| owner | les 26 permissions, dont actions.run.critical |
Octrois (policy_grants) : allow ou deny, pour un utilisateur ou un rôle, sur une permission, éventuellement
limité à une ressource (un nœud par son id, son site ou une étiquette ; un service par son id ou son nœud —
DecideFacets). Ordre de décision : un deny applicable l'emporte toujours ; sinon le défaut du rôle ; sinon un
allow applicable. Bornes codées (grantable) : actions.run.critical n'est accordable qu'à un owner ;
users.manage, invitations.manage, agents.manage, settings.manage, audit.export ne le sont qu'à partir
d'admin. Les octrois sont mis en cache 3 s par control-api et le cache est invalidé à chaque modification.
Step-up : la session doit porter une cérémonie passkey de moins de 5 minutes (MCC_STEPUP_WINDOW,
sessions.authenticated_at). 19 opérations l'exigent d'office (liste dans API.md §6) :
gestion des utilisateurs, passkeys, sessions et appareils d'autrui, invitations, agents et jetons d'enrôlement,
octrois, réglages, retrait d'un nœud, export d'audit, approbation d'action. S'y ajoutent les actions de criticité
high ou critical, vérifiées dans le handler. Échec : 403 step_up_required.
8. Sûreté des actions
Source : services/internal/actions/, services/internal/api/ops_actions.go, services/internal/orchestrator/.
Catalogue typé (18 types, catalog.go). Aucune commande libre, aucun shell (ADR 0008).
Les exigences découlent de la criticité seule :
| Criticité | Permission | Step-up | Justification | Confirmation saisie | Seconde approbation |
|---|---|---|---|---|---|
low |
actions.run.low |
— | — | — | — |
medium |
actions.run.medium |
— | — | — | — |
high |
actions.run.high |
oui | — | — | — |
critical |
actions.run.critical (owner) |
oui | oui | oui (alias de la cible, comparé par le serveur) | oui (autre personne, actions.approve, step-up) |
| Type | Criticité | Verrou | État en v1 |
|---|---|---|---|
inventory.refresh, diagnostic.run |
low | nœud | disponibles ; autorisés par défaut sur tous les agents |
service.health_check |
low | service | disponible ; autorisé par défaut |
service.logs.tail |
low | aucun | disponible ; exige aussi logs.read ; autorisé par défaut |
service.restart, service.start |
medium | service | disponibles ; exigent service managed + liste blanche locale |
service.stop |
high | service | idem |
agent.restart, cache.purge |
medium | nœud | disponibles ; exigent la politique locale |
node.maintenance.set |
medium | nœud | exécuté par le serveur (aucune commande agent) |
job.run |
medium | job | interne : créé seulement par POST /jobs |
job.cancel |
medium | aucun | exécuté par le serveur |
model.server.start, model.server.stop |
high | nœud | au catalogue (available=true) mais non implémentés par l'agent v1 : aucun agent ne déclare la capacité, donc la pré-vérification échoue (422 capability_missing quand l'agent est en ligne) |
deploy.release, system.update.schedule |
high | service / nœud | désactivés (available=false, 422 action_unavailable) |
system.reboot, system.shutdown |
critical | nœud | implémentés ; désactivés sur chaque agent par la politique locale (allow_reboot / allow_shutdown à faux) |
Chaîne de contrôles pour POST /actions (dans l'ordre du code) : limite 30/min par utilisateur →
Idempotency-Key (8 à 128 caractères) → type connu, non interne, disponible → schéma des paramètres →
permission(s) sur le nœud et la cible précis → step-up → rejeu idempotent éventuel → gel d'urgence →
confirmation → justification → pré-vérifications (actions.Precheck : cible présente, service managed, nœud hors
maintenance sauf dérogation override_maintenance, agent enrôlé, en ligne et déclarant la capacité, mémoire libre
pour model.server.start) → insertion + verrou + audit dans une transaction. Chaque refus est audité et ne laisse
aucune ligne d'action. Les pré-vérifications sont refaites par l'orchestrateur juste avant la signature
(TestPrechecksAreVerifiedAgainAtDispatch).
| Mécanisme | Détail |
|---|---|
| Idempotence | même clé + même corps → même action (200) ; même clé + corps différent → 409 idempotency_conflict ; unicité (requested_by, idempotency_key) en base |
| Verrou | un verrou par cible (action_locks) ; seconde action concurrente → 409 target_locked avec l'id du détenteur |
| Approbation | état pending_approval ; expire après 30 min (ApprovalTTL) ; le demandeur ne peut ni approuver ni rejeter |
| Signature | enveloppe Ed25519, validité 90 s (maximum 120 s accepté par l'agent), nonce, destinataire |
| Anti-rejeu | nonce journalisé sur disque par l'agent avant acceptation |
| Jamais de ré-émission | ADR 0010 |
| Bornes d'exécution | délai par type, 2 commandes simultanées au plus par agent et une par cible, sortie plafonnée et expurgée |
Arrêts d'urgence (trois niveaux indépendants) :
- Global : réglage
orchestrator.frozen=true(mccctl freezesur l'hôte, ouPUT /settings/orchestrator.frozenpar un owner avec step-up). Plus aucune commande n'est émise ;POST /actionset l'approbation répondent503 orchestrator_frozen. - Par nœud, côté propriétaire du nœud : fichier
<état>/FREEZE→ l'agent refuse toute commande (raisonfrozen). - Par nœud, côté serveur : révocation de l'agent (
POST /agents/{id}/revoke) →401 agent_revokeden quelques secondes.
9. Modèle de confiance des agents
Détail : AGENT-PROTOCOL.md. En résumé :
- L'agent n'écoute sur aucun port, ne tourne jamais en root (LaunchAgent, ou LaunchDaemon avec
UserName; sous Linux utilisateur dédiémcc-agentavecNoNewPrivileges,ProtectSystem=strict,ProtectHome=yes—agents/linux/mcc-agent.service). - Sa clé privée (ECDSA P-256) est générée sur le nœud et n'en sort pas ; certificat de 30 jours renouvelé automatiquement.
- Enrôlement : jeton à usage unique (15 min par défaut), empreinte de l'AC vérifiée par l'agent avant d'écrire
quoi que ce soit ; un alias appartenant à un autre matériel est refusé (
409 alias_in_use) —TestEnrollment. - Le serveur ne fait pas confiance à l'agent au-delà de son nœud : il ne voit que ses propres commandes, ses rapports sont validés, sa sortie est expurgée une seconde fois.
- L'agent ne fait pas confiance au transport : il vérifie la signature de l'orchestrateur puis applique sa politique locale, que le serveur ne peut pas modifier.
- Politique par défaut déployée partout [prod] : commandes de lecture seulement (
diagnostic.run,inventory.refresh,service.health_check,service.logs.tail).
10. Intégrité du journal d'audit
Source : services/internal/audit/.
- Table en ajout seul : déclencheurs
audit_no_update(UPDATE, DELETE) etaudit_no_truncate(0001_init.sql). - Chaîne :
hash = SHA-256(hash précédent || encodage canonique de l'entrée), écriture sérialisée par verrou consultatif. L'entrée d'audit et le changement d'état qu'elle décrit sont validés dans la même transaction quand l'appelant fournit la sienne. - Les paramètres dont le nom évoque un secret (
token,secret,password,cookie,challenge,signature…) sont masqués avant écriture (audit.Redact). - Vérification :
mccctl audit-verify(chaîne complète, sur l'hôte) ;GET /audit/verify(audit.read). - Export :
GET /audit/export(audit.export+ step-up) produit des lignes JSON suivies d'un manifeste signé Ed25519 (plage, nombre d'entrées, hachage précédent, hachage de tête, SHA-256 du corps).mccctl audit-verify-export [--pubkey <base64>] <fichier>vérifie le fichier hors ligne, sans base ni réseau ; la clé publique est publiée parGET /audit/verify(export_public_key).
Limite : la chaîne détecte une modification, elle ne l'empêche pas pour qui contrôle la base et réécrit toute la chaîne ; seule une tête de chaîne conservée ailleurs (un export signé, une sauvegarde hors hôte) permet de le prouver. Aucun ancrage externe automatique n'existe.
11. Inventaire des secrets
Tous dans MCC_SECRETS_DIR (~/.config/mcc sur l'hôte [prod]), créés au premier usage en mode 0600. Aucun
secret n'est dans le dépôt (.gitignore : *.key, *.pem, *.p8, .env*, secrets/) ni dans la table
settings. Le fichier ~/.config/mcc/env lu par scripts/mccctl ne contient que de la configuration.
| Fichier | Nature | Utilisé par | Rotation (déduite du code ; aucune n'a été exercée) |
|---|---|---|---|
agent-ca.key, agent-ca.crt |
AC privée ECDSA P-256, valide 10 ans | telemetry-ingest |
pas de procédure outillée : remplacer l'AC impose de ré-enrôler tous les agents (voir OPERATIONS.md §8) |
command-signing.key |
graine Ed25519 (hex) | action-orchestrator |
arrêter l'orchestrateur, écarter le fichier, redémarrer : une nouvelle clé est créée et sa partie publique inscrite dans command_keys ; les agents l'apprennent par un renouvellement déclenché à la première commande portant un identifiant de clé inconnu ; marquer l'ancienne retired_at en SQL (aucune commande mccctl pour cela) |
audit-signing.key |
graine Ed25519 | control-api (exports), mccctl audit-verify-export sans --pubkey |
écarter le fichier et redémarrer control-api ; conserver l'ancienne clé publique pour vérifier les exports antérieurs |
csrf.key |
32 octets | control-api |
écarter le fichier et redémarrer : les jetons CSRF changent, les sessions restent valides, les clients relisent le jeton par GET /me |
backup.key |
32 octets (AES-256-GCM) | mccctl backup, restore, restore-test |
une nouvelle clé ne déchiffre pas les sauvegardes antérieures : garder l'ancienne tant qu'elles existent. Une copie hors hôte est obligatoire (rappel affiché à la création) |
Clé APNs (MCC_APNS_KEY_FILE) |
.p8 |
action-orchestrator |
absente : le fournisseur est inactif |
Côté nœud (~/.mcc-agent, 0700) : agent.key (clé privée de l'agent), agent.crt, ca.crt,
command-keys.json. Côté second nœud de sauvegarde : une clé SSH dédiée, restreinte par commande forcée au dépôt
rsync dans un seul répertoire [prod].
Jetons affichés une seule fois, jamais stockés en clair : lien d'invitation, jeton d'enrôlement d'agent.
12. En-têtes, CSP, limites de débit
En-têtes posés par control-api sur toutes les réponses (httpx.SecurityHeaders) :
X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, X-Frame-Options: DENY,
Cross-Origin-Opener-Policy: same-origin, Cross-Origin-Resource-Policy: same-origin,
Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=(), et en HTTPS
Strict-Transport-Security: max-age=63072000; includeSubDomains. Les réponses d'API portent Cache-Control: no-store
et X-Correlation-Id (toujours généré par le serveur).
CSP des pages (apps/web/src/proxy.ts), avec un nonce par requête :
default-src 'self'; script-src 'self' 'nonce-…' 'strict-dynamic'; style-src 'self' 'nonce-…';
img-src 'self' data:; font-src 'self'; connect-src 'self'; object-src 'none'; frame-ancestors 'none';
base-uri 'none'; form-action 'self'; manifest-src 'self'; worker-src 'self''unsafe-eval' n'est ajouté qu'hors production. Aucun attribut style en ligne. Preuves : Playwright « sign-in
page: CSP header with a nonce, no referrer, no password field » et le test « no CSP violation and no console error »
de chaque fichier de spécification ; HSTS, en-têtes et CSP à nonce observés [prod].
Limites de débit telles qu'implémentées (en mémoire, par processus ; seau à jetons httpx.Limiter) :
| Portée | Limite | Clé | Source |
|---|---|---|---|
| Opérations publiques et de transaction d'invitation (toutes confondues) | 30/min, rafale 15 | IP cliente | api/server.go (authLimiter) |
| Requêtes authentifiées | 900/min, rafale 300 | session | api/server.go (userLimiter) |
| Création d'actions | 30/min, rafale 30 | utilisateur | api/ops_actions.go |
/agent/v1/enroll au relais |
20/min, rafale 10 | IP cliente | api/agent_proxy.go |
/agent/v1/enroll à l'ingestion |
6/min, rafale 6 | IP cliente | ingest/server.go |
| Échecs de signature d'agent | 30 par minute puis 429 |
IP + certificat présenté | ingest/signed.go |
Ces valeurs diffèrent de celles écrites dans le contrat (10/min par IP pour les cérémonies, 5/min pour l'échange
d'invitation, 10/min par session pour le step-up) : voir API.md §8.
L'adresse cliente n'est lue dans X-Forwarded-For que si le pair TCP est un proxy de confiance
(MCC_TRUSTED_PROXIES ; TestResolveIPTrustsOnlyConfiguredProxies).
13. Données privées des nœuds
- Adresses IP et MAC, numéro de série, UUID matériel, cibles NAS : visibles seulement avec
nodes.private.read, évaluée par nœud (undenylimité à un site ou une étiquette s'applique). Par défaut : operator et au-dessus. - Journaux et sorties de commandes :
logs.readsur le nœud, en plus deactions.read. - Jamais collecté par l'agent : lignes de commande des processus, blocs
envde PM2 (seulPORTest lu), arguments des serveurs d'inférence au-delà de--modelet--port, identifiants dans les URL de volumes. docs/REAL-INFRASTRUCTURE-INVENTORY.mdetdocs/recon/contiennent des adresses privées : le dépôt doit rester privé.
14. Lacunes connues
| Sujet | État |
|---|---|
| Audit de sécurité indépendant | non réalisé |
| Compte owner en production | inexistant : aucun parcours authentifié exercé en production par une personne |
| Navigateurs et authentificateurs réels | Safari, Firefox et authentificateurs de plateforme non exercés (tests : authentificateur virtuel, Chromium) |
| Compromission de l'hôte | la base et toutes les clés sont lisibles par le compte du service ; pas de HSM ni de séparation par utilisateur système entre les trois services |
| Protection anti-rejeu des requêtes d'agent | cache de nonces en mémoire : après un redémarrage de l'ingestion, réduite à la fenêtre ±90 s (appels idempotents) |
| Limites de débit | en mémoire, remises à zéro au redémarrage ; valeurs différentes du contrat ; les opérations d'enregistrement par transaction d'invitation n'ont pas de limite par IP (seulement les 5 échecs par invitation) |
go test -race |
non exécuté sur ingest et agent |
| Rotation des clés | procédures déduites du code, non outillées, jamais exercées ; aucune rotation de l'AC sans ré-enrôlement |
| Ancrage externe de l'audit | aucun automatique |
| Push APNs | inactif (pas de clé) : aucune notification hors de l'application |
| Température, puissance | non mesurées (agent sans root) — sans effet de sécurité, mais pas d'alerte thermique |
| Terminal d'administration | non livré (ADR 0008) |
| CI hébergée | aucune ; make ci local, crochet pre-push à installer par make hooks (absent du dépôt de travail consulté) |
| Suite de tests | au commit 45f0d03, go test ./... échoue sur 1 test (TestJobRunsToSuccess, assertion périmée) : voir ACCEPTANCE.md §1 |
| Réplication | aucune ; une seule base sur un seul hôte |
Mise à jour (même soir, commit suivant
45f0d03) :TestJobRunsToSuccessa été corrigé (assertion alignée sur le format réel des paramètres) etgo test -count=1 ./...est de nouveau vert sur les 26 paquets. L'événement SSEnode.stateémis par l'ingestion porte désormais les champs du contrat (alias,freshness,maintenance,observed_at) en plus devalues/availability,node.updatedportechange, et les trois binaires sont estampillés de la même version. Les autres écarts listés dans API.md §8 restent ouverts.
15. Réponse aux incidents
Les commandes mccctl s'exécutent sur l'hôte : ~/apps/maclustr-command-center/scripts/mccctl <commande>.
Les opérations d'API demandent une session ; tant qu'aucun owner n'existe en production, seules les voies
mccctl et SQL sont disponibles. Ces procédures sont déduites du code ; aucune n'a été répétée en conditions réelles.
15.1 Appareil perdu ou volé
- Depuis un autre appareil : Réglages → Sécurité → révoquer l'appareil (
DELETE /me/devices/{id}), ou par un adminDELETE /devices/{id}(step-up). Effet : sessions de l'appareil révoquées, jeton push effacé. - Si la passkey était liée à l'appareil (non synchronisée) : la révoquer (
DELETE /me/passkeys/{id}). - Si c'était la seule passkey :
mccctl recovery-invite --handle <h>sur l'hôte ; ouvrir le lien sur le nouvel appareil. Toutes les anciennes passkeys et sessions sont révoquées. - Vérifier l'audit (
auth.login,session.*) sur la période.
15.2 Agent compromis (un nœud)
- Révoquer l'agent :
POST /agents/{id}/revoke(step-up). Coupure en quelques secondes. - Sur le nœud, si accessible :
touch ~/.mcc-agent/FREEZE, puisagents/macos/uninstall.sh --purge. - Considérer comme non fiables les données rapportées par ce nœud depuis la compromission supposée.
- Examiner l'audit et
action_eventspour les commandes exécutées sur ce nœud. - Après remise en état : nouveau jeton d'enrôlement, nouvelle identité (l'ancienne ne revient pas).
Portée : la clé d'un agent ne permet ni de commander un autre nœud, ni de lire les commandes d'un autre agent, ni de se faire passer pour l'ingestion.
15.3 Ingestion compromise
mccctl freeze(arrêt de toute émission de commande).- Arrêter
mcc-telemetry-ingest(pm2 stop). Les agents tamponnent jusqu'à 6 h. - Portée : l'attaquant a pu lire la télémétrie, jeter ou retarder des commandes, écrire de fausses données en
base, et lire
agent-ca.key(émettre des identités d'agent). Il n'a pas pu forger de commande. - Remise en état : reconstruire le binaire depuis le dépôt ; si la clé d'AC est suspecte, remplacer l'AC et ré-enrôler tous les agents (OPERATIONS.md §8).
mccctl unfreezeune fois l'état vérifié.
15.4 Invitation fuitée
DELETE /invitations/{id}(step-up) si elle n'est pas consommée. Sans compte : attendre son expiration (15 min par défaut) ou, sur l'hôte,update invitations set revoked_at = now() where id = '<id>'.- Si elle a été consommée par un tiers : désactiver le compte créé (
PATCH /users/{id}disabled: true, ce qui révoque ses sessions), puis examiner l'audit (invitation.exchange,invitation.complete). - Une invitation ne peut jamais donner accès à un compte existant sans la session de ce compte.
15.5 Prise de contrôle de compte suspectée
mccctl freeze.- Désactiver le compte (admin ou owner, step-up) — ses sessions sont révoquées. S'il s'agit du seul owner :
mccctl recovery-invite --handle <h>(révoque passkeys et sessions) et ouvrir le lien soi-même. - Revoir : passkeys ajoutées (
passkey.add), octrois (policy_grants), invitations créées, actions demandées, agents enrôlés, réglages modifiés. Exporter l'audit et le vérifier hors ligne. mccctl unfreeze.
15.6 Gel d'urgence
ssh <hôte>
~/apps/maclustr-command-center/scripts/mccctl freeze # orchestrator.frozen = true, audité
~/apps/maclustr-command-center/scripts/mccctl status
# … investigation …
~/apps/maclustr-command-center/scripts/mccctl unfreezeLe gel n'interrompt pas une commande déjà en cours sur un nœud : pour cela, annuler l'action (POST /actions/{id}/cancel) ou poser FREEZE sur le nœud (qui ne bloque que les commandes suivantes). Arrêt complet du
produit : OPERATIONS.md §12.