SPB Git

Repository Public

SECURITY.md 40.0 KB 459 lines markdown

1# Sécurité — MacLustr Command Center23État décrit : commit `45f0d03`, déploiement du 2026-11-18. Chaque mesure cite le fichier qui l'implémente et, quand4il existe, le test qui la prouve. Les observations **[prod]** viennent du responsable du déploiement (2026-11-18) et5ne sont pas vérifiables depuis ce dépôt. Les lacunes sont listées en [§14](#14-lacunes-connues) ; aucun audit de6sécurité indépendant n'a été réalisé.78Documents liés : [ARCHITECTURE.md](ARCHITECTURE.md) · [AGENT-PROTOCOL.md](AGENT-PROTOCOL.md) ·9[OPERATIONS.md](OPERATIONS.md) · [API.md](API.md) · ADR [0004](DECISIONS/0004-agent-transport-mtls-lan.md),10[0005](DECISIONS/0005-passkeys-only-identity.md), [0007](DECISIONS/0007-unprivileged-agent.md),11[0008](DECISIONS/0008-no-arbitrary-shell.md), [0010](DECISIONS/0010-at-most-once-commands.md).1213## 1. Modèle de menace1415### 1.1 Actifs1617| Actif | Pourquoi il compte | Où il vit |18|---|---|---|19| 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 |20| Comptes et passkeys | accès au pilotage | tables `users`, `passkeys` (clés publiques seulement) |21| Sessions et jetons | usurpation d'un utilisateur connecté | `sessions`, `refresh_tokens` (hachés SHA-256) |22| Journal d'audit | preuve de ce qui a été fait | `audit_log` (chaîne de hachage), clé `audit-signing.key` |23| AC des agents | permet d'émettre une identité d'agent | `agent-ca.key` |24| Données privées des nœuds | adresses IP/MAC, numéros de série, UUID matériel | `nodes.inventory`, `node_state` |25| Sorties de commandes et journaux | peuvent contenir des détails opérationnels | `action_events` (expurgées) |26| Sauvegardes | copie complète de la base | fichiers `mcc-*.dump.enc`, clé `backup.key` |2728### 1.2 Acteurs2930| Acteur | Capacité supposée |31|---|---|32| Anonyme sur Internet | atteint `https://clustr.spboucher.ai` (API, pages, `/agent/v1/`) |33| Utilisateur légitime de rôle faible (viewer, operator) | session valide, cherche à dépasser ses droits |34| Détenteur d'un lien d'invitation fuité | possède un jeton à usage unique valide quelques minutes |35| Voleur d'un appareil ou d'un jeton de session | rejoue un cookie, un jeton d'accès ou de rafraîchissement |36| Agent compromis (un nœud) | possède la clé et le certificat de cet agent, contrôle ce qu'il rapporte |37| Ingestion ou passerelle compromise | lit et modifie le trafic agent ↔ plan de contrôle |38| Site tiers dans le navigateur de la victime | déclenche des requêtes inter-origines (CSRF), tente d'encadrer l'interface |39| 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) |4041### 1.3 Points d'entrée4243| Point d'entrée | Exposition | Authentification |44|---|---|---|45| `/api/v1/*` | Internet, via la passerelle | cookie de session ou jeton `Bearer` ; 7 opérations publiques, 3 liées à la transaction d'invitation |46| `/api/v1/events` (SSE) | Internet | session, revérifiée chaque minute |47| `/agent/v1/*` | Internet (relais de `control-api`) | preuve de possession par requête ; `/enroll` : jeton à usage unique |48| `/.well-known/apple-app-site-association` | Internet | aucune (fichier public) |49| Pages web (`/`, `/signin`, `/setup`, …) | Internet | coquilles sans données ; les données passent par l'API |50| Écoute mTLS de l'ingestion (8801) | loopback en production **[prod]** | certificat client de l'AC privée |51| `mccctl` | SSH sur l'hôte | accès au compte du service ; audité `actor_kind=cli` |52| PostgreSQL | loopback | accès local |5354### 1.4 Tableau STRIDE5556| # | Menace | Catégorie | Mesure (source) | Preuve |57|---|---|---|---|---|58| 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`) |59| 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 » |60| S3 | Authentificateur cloné | Usurpation | régression du compteur de signature → refus + audit (`FinishAuthentication`) | `TestClonedAuthenticatorDetected` |61| 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]** |62| 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 » |63| 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` |64| 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` |65| 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]** |66| S9 | Usurpation du service d'ingestion par une clé d'agent volée | Usurpation | usages disjoints `serverAuth` / `clientAuth` (`pki/pki.go`) | `TestCAAndCertificates` |67| 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` |68| T2 | Rejeu d'une commande signée | Altération | nonce persistant (`agent/nonce`), durée de vie ≤ 120 s | `TestVerifyAcceptsOnceThenRejectsReplay`, `TestRememberReplayRestart`, `TestConcurrentSingleWinner`, `TestSignRefusesLongLivedCommands` |69| 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` |70| 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]** |71| 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]** |72| 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` |73| 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 |74| 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) |75| 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 |76| 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` |77| 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` |78| 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 » |79| 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`) |80| I5 | Fuite par le flux d'événements | Divulgation | filtrage des sujets par permission (`api/events_stream.go` : `topicPermission`) | `TestHTTPEventStream` |81| 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` |82| 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** |83| 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… » |84| D2 | Rafale d'actions par un compte | Déni de service | 30 actions/min par utilisateur (`api/ops_actions.go`) | `TestActionRateLimit` |85| 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` |86| 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` |87| 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 » |88| 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` |89| E3 | Un admin crée ou modifie un owner ; suppression du dernier owner | Élévation | `authz.CanAssignRole` ; verrou consultatif + `ErrLastOwner` | `TestCanAssignRole`, `TestUserAdministrationRules`, `TestLastOwnerProtected` |90| E4 | Auto-approbation d'une action critique | Élévation | l'approbateur ≠ le demandeur, `actions.approve` + step-up (`api/ops_actions.go` : `decide`) | `TestApprovalFlow` |91| 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… » |92| 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` |93| 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 » |9495## 2. Principes96971. **Pas de secret partagé pour s'authentifier** : passkeys seulement ; les jetons de session sont aléatoires98   (256 bits, `services/internal/secret/secret.go`) et stockés hachés.992. **Décision côté serveur** : les trois clients ne décident de rien ; les drapeaux affichés par l'interface100   (`requires_confirmation`, permissions) sont revérifiés par le serveur.1013. **Refus par défaut** : une opération absente de la table générée est refusée (`admit`) ; un type d'action absent102   du catalogue est refusé ; un agent sans fichier de politique n'accepte que quatre commandes de lecture.1034. **Séparation des pouvoirs entre services** : l'API n'a pas de clé d'agent, l'ingestion n'a pas de clé de104   commande, l'orchestrateur n'est pas exposé.1055. **Honnêteté** : une valeur non mesurable est déclarée, une issue inconnue est dite inconnue.106107## 3. Passkeys / WebAuthn108109Bibliothèque `github.com/go-webauthn/webauthn` ; configuration dans `services/internal/identity/service.go`.110111| Paramètre | Valeur | Source |112|---|---|---|113| 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`) |114| Vérification de l'utilisateur | `required`, revérifiée sur chaque assertion | `service.go`, `webauthn.go` |115| Identifiants découvrables | `residentKey=required` (connexion sans nom d'utilisateur) | `service.go` |116| Attestation | `none` : aucun filtrage de modèle d'authentificateur | `service.go`, ADR 0005 |117| Défi | à usage unique, valide 5 min (`challengeTTL`), stocké côté serveur | `webauthn_challenges` |118| Compteur de signature | une régression refuse la connexion et laisse le compteur stocké intact | `FinishAuthentication` |119| Dernière passkey | un utilisateur ne peut pas supprimer sa seule passkey (`409 last_passkey`) | `RevokePasskey` — `TestPasskeyManagement` |120| Ajout d'une passkey | session + step-up | table des opérations (`BeginRegistration`, `FinishRegistration`) |121122Les apps Apple utilisent les mêmes passkeys via Associated Domains : le fichier AASA est servi par `control-api`123(`serveAASA`, identifiants d'apps dans `MCC_APPLE_APP_IDS`) et répondait en production **[prod]**. L'usage réel de124passkeys dans les apps natives n'est pas vérifié ici : voir [APPLE-APPS.md](APPLE-APPS.md).125126Non vérifié : authentificateurs de plateforme réels et navigateurs Safari / Firefox réels. Les tests utilisent un127authentificateur logiciel (`services/internal/identity/vauth`) et l'authentificateur virtuel de Playwright (Chromium).128129## 4. Invitations, amorçage, récupération130131Source : `services/internal/identity/invitations.go`.132133- Jeton de 32 octets aléatoires (base64url), seul son SHA-256 est stocké. Durée par défaut 15 min, maximum 24 h.134- Lien `https://clustr.spboucher.ai/setup#<jeton>` : le jeton est dans le fragment (jamais envoyé au serveur par la135  navigation) ; la page l'échange par `POST /invitations/exchange` puis l'efface de l'URL.136- L'échange consomme le jeton **atomiquement** et ouvre une transaction de 10 min (`setupTxTTL`) : cookie137  `__Host-mcc_setup` pour le web, `transaction_token` (en-tête `X-MCC-Setup-Transaction`) pour les apps natives.138- 5 échecs de vérification (`maxSetupFailures`) révoquent l'invitation.139- Trois finalités : `new_account` ; `link` (changer le rôle d'un compte existant — exige d'être connecté **à ce140  compte**, un step-up et une confirmation explicite) ; `recovery` (nouvelle passkey sans connexion — **créable141  uniquement hors bande**, une seule ouverte par compte : index `invitations_one_open_recovery`).142- Un admin ne peut inviter ni owner ni modifier un owner (`authz.CanAssignRole`).143- Une récupération aboutie révoque toutes les passkeys et sessions précédentes du compte.144- Premier owner : `mccctl bootstrap-owner`, refusé dès qu'un owner capable de se connecter existe (`BootstrapOwner`).145146État de production : **aucun compte owner n'existe encore** ; le propriétaire doit ouvrir lui-même le lien147d'amorçage avec sa passkey. Aucun parcours authentifié n'a donc été exercé en production par une personne.148149## 5. Sessions et jetons150151Source : `services/internal/identity/sessions.go`, `services/internal/api/server.go`.152153| | Web | Apps natives |154|---|---|---|155| Porteur | cookie `__Host-mcc_session` (`Secure; HttpOnly; SameSite=Strict; Path=/`, cookie de session) | `Authorization: Bearer <jeton d'accès>` |156| Durée | inactivité 30 min glissante, absolue 12 h | accès 10 min ; rafraîchissement 30 jours, rotatif ; absolue 180 jours (`bearerAbsolute`) |157| Stockage serveur | SHA-256 du jeton (`sessions.token_hash`) | idem + `refresh_tokens` |158| Rotation | — | chaque rafraîchissement remplace les deux jetons ; réutilisation d'un jeton tourné = révocation de la session |159| Appareil | cookie `__Host-mcc_device` (identifiant d'appareil, non secret) | `device_id` renvoyé puis représenté par le client |160161- En développement sur HTTP, le préfixe `__Host-` et l'attribut `Secure` sont absents (`core.cookieName`).162- Un en-tête `Authorization` présent désactive entièrement la lecture des cookies.163- Chaque requête revérifie : session non révoquée, appareil non révoqué, compte non désactivé, expirations.164- Désactiver un compte, révoquer un appareil ou une passkey révoque les sessions liées dans la même transaction.165- Tout échec d'authentification renvoie le même `401 unauthenticated`.166- Le flux SSE est borné à 30 min et revérifie la session chaque minute.167168## 6. CSRF169170`core.admit` applique, pour toute méthode non sûre :171172| Contexte | Exigence |173|---|---|174| Session par cookie | `Origin` égal à l'origine publique **et** `X-MCC-CSRF` valide |175| Transaction d'invitation par cookie | `Origin` égal à l'origine publique |176| Jeton `Bearer` ou opération publique | si un en-tête `Origin` est présent, il doit être l'origine publique |177178Le jeton CSRF est `HMAC-SHA256(csrf.key, "mcc-csrf-v1\0" || jeton de session)` (`identity.CSRFToken`) : il est lié à179la session et n'est stocké nulle part ; le client l'obtient par `GET /me` ou dans le résultat de connexion.180Échec : `403 csrf_failed`. Le relais `/agent/v1/` refuse toute requête portant un en-tête `Origin`181(`agent_proxy.go`).182183## 7. Autorisation : rôles, octrois, step-up184185Source : `services/internal/authz/authz.go`.186187| Rôle | Permissions par défaut |188|---|---|189| viewer | `cluster.read`, `nodes.read`, `services.read`, `models.read`, `jobs.read`, `alerts.read`, `maintenance.read`, `actions.read` |190| operator | viewer + `nodes.private.read`, `logs.read`, `alerts.ack`, `maintenance.write`, `jobs.submit`, `actions.run.low`, `actions.run.medium` |191| admin | operator + `nodes.write`, `alerts.manage`, `actions.run.high`, `actions.approve`, `audit.read`, `audit.export`, `users.manage`, `invitations.manage`, `agents.manage`, `settings.manage` |192| owner | les 26 permissions, dont `actions.run.critical` |193194**Octrois (`policy_grants`)** : `allow` ou `deny`, pour un utilisateur ou un rôle, sur une permission, éventuellement195limité à une ressource (un nœud par son id, son site ou une étiquette ; un service par son id ou son nœud —196`DecideFacets`). Ordre de décision : un `deny` applicable l'emporte toujours ; sinon le défaut du rôle ; sinon un197`allow` applicable. Bornes codées (`grantable`) : `actions.run.critical` n'est accordable qu'à un owner ;198`users.manage`, `invitations.manage`, `agents.manage`, `settings.manage`, `audit.export` ne le sont qu'à partir199d'admin. Les octrois sont mis en cache 3 s par `control-api` et le cache est invalidé à chaque modification.200201**Step-up** : la session doit porter une cérémonie passkey de moins de 5 minutes (`MCC_STEPUP_WINDOW`,202`sessions.authenticated_at`). 19 opérations l'exigent d'office (liste dans [API.md §6](API.md#6-table-des-permissions)) :203gestion des utilisateurs, passkeys, sessions et appareils d'autrui, invitations, agents et jetons d'enrôlement,204octrois, réglages, retrait d'un nœud, export d'audit, approbation d'action. S'y ajoutent les actions de criticité205`high` ou `critical`, vérifiées dans le handler. Échec : `403 step_up_required`.206207## 8. Sûreté des actions208209Source : `services/internal/actions/`, `services/internal/api/ops_actions.go`, `services/internal/orchestrator/`.210211**Catalogue typé** (18 types, `catalog.go`). Aucune commande libre, aucun shell ([ADR 0008](DECISIONS/0008-no-arbitrary-shell.md)).212Les exigences découlent **de la criticité seule** :213214| Criticité | Permission | Step-up | Justification | Confirmation saisie | Seconde approbation |215|---|---|---|---|---|---|216| `low` | `actions.run.low` | — | — | — | — |217| `medium` | `actions.run.medium` | — | — | — | — |218| `high` | `actions.run.high` | oui | — | — | — |219| `critical` | `actions.run.critical` (owner) | oui | oui | oui (alias de la cible, comparé par le serveur) | oui (autre personne, `actions.approve`, step-up) |220221| Type | Criticité | Verrou | État en v1 |222|---|---|---|---|223| `inventory.refresh`, `diagnostic.run` | low | nœud | disponibles ; autorisés par défaut sur tous les agents |224| `service.health_check` | low | service | disponible ; autorisé par défaut |225| `service.logs.tail` | low | aucun | disponible ; exige aussi `logs.read` ; autorisé par défaut |226| `service.restart`, `service.start` | medium | service | disponibles ; exigent service `managed` + liste blanche locale |227| `service.stop` | high | service | idem |228| `agent.restart`, `cache.purge` | medium | nœud | disponibles ; exigent la politique locale |229| `node.maintenance.set` | medium | nœud | exécuté par le serveur (aucune commande agent) |230| `job.run` | medium | job | interne : créé seulement par `POST /jobs` |231| `job.cancel` | medium | aucun | exécuté par le serveur |232| `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) |233| `deploy.release`, `system.update.schedule` | high | service / nœud | **désactivés** (`available=false`, `422 action_unavailable`) |234| `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) |235236**Chaîne de contrôles** pour `POST /actions` (dans l'ordre du code) : limite 30/min par utilisateur →237`Idempotency-Key` (8 à 128 caractères) → type connu, non interne, disponible → schéma des paramètres →238permission(s) sur le nœud et la cible précis → step-up → rejeu idempotent éventuel → gel d'urgence →239confirmation → justification → pré-vérifications (`actions.Precheck` : cible présente, service `managed`, nœud hors240maintenance sauf dérogation `override_maintenance`, agent enrôlé, en ligne et déclarant la capacité, mémoire libre241pour `model.server.start`) → insertion + verrou + audit dans une transaction. Chaque refus est audité et ne laisse242aucune ligne d'action. Les pré-vérifications sont **refaites par l'orchestrateur** juste avant la signature243(`TestPrechecksAreVerifiedAgainAtDispatch`).244245| Mécanisme | Détail |246|---|---|247| 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 |248| Verrou | un verrou par cible (`action_locks`) ; seconde action concurrente → `409 target_locked` avec l'id du détenteur |249| Approbation | état `pending_approval` ; expire après 30 min (`ApprovalTTL`) ; le demandeur ne peut ni approuver ni rejeter |250| Signature | enveloppe Ed25519, validité 90 s (maximum 120 s accepté par l'agent), nonce, destinataire |251| Anti-rejeu | nonce journalisé sur disque par l'agent avant acceptation |252| Jamais de ré-émission | [ADR 0010](DECISIONS/0010-at-most-once-commands.md) |253| 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 |254255**Arrêts d'urgence** (trois niveaux indépendants) :2562571. Global : réglage `orchestrator.frozen=true` (`mccctl freeze` sur l'hôte, ou `PUT /settings/orchestrator.frozen`258   par un owner avec step-up). Plus aucune commande n'est émise ; `POST /actions` et l'approbation répondent259   `503 orchestrator_frozen`.2602. Par nœud, côté propriétaire du nœud : fichier `<état>/FREEZE` → l'agent refuse toute commande (raison `frozen`).2613. Par nœud, côté serveur : révocation de l'agent (`POST /agents/{id}/revoke`) → `401 agent_revoked` en quelques262   secondes.263264## 9. Modèle de confiance des agents265266Détail : [AGENT-PROTOCOL.md](AGENT-PROTOCOL.md). En résumé :267268- L'agent n'écoute sur aucun port, ne tourne jamais en root (LaunchAgent, ou LaunchDaemon avec `UserName` ; sous269  Linux utilisateur dédié `mcc-agent` avec `NoNewPrivileges`, `ProtectSystem=strict`, `ProtectHome=yes` —270  `agents/linux/mcc-agent.service`).271- 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é272  automatiquement.273- Enrôlement : jeton à usage unique (15 min par défaut), empreinte de l'AC vérifiée par l'agent avant d'écrire274  quoi que ce soit ; un alias appartenant à un autre matériel est refusé (`409 alias_in_use`) — `TestEnrollment`.275- Le serveur **ne fait pas confiance à l'agent au-delà de son nœud** : il ne voit que ses propres commandes, ses276  rapports sont validés, sa sortie est expurgée une seconde fois.277- L'agent **ne fait pas confiance au transport** : il vérifie la signature de l'orchestrateur puis applique sa278  politique locale, que le serveur ne peut pas modifier.279- Politique par défaut déployée partout **[prod]** : commandes de lecture seulement (`diagnostic.run`,280  `inventory.refresh`, `service.health_check`, `service.logs.tail`).281282## 10. Intégrité du journal d'audit283284Source : `services/internal/audit/`.285286- Table en ajout seul : déclencheurs `audit_no_update` (UPDATE, DELETE) et `audit_no_truncate` (`0001_init.sql`).287- Chaîne : `hash = SHA-256(hash précédent || encodage canonique de l'entrée)`, écriture sérialisée par verrou288  consultatif. L'entrée d'audit et le changement d'état qu'elle décrit sont validés dans la même transaction quand289  l'appelant fournit la sienne.290- Les paramètres dont le nom évoque un secret (`token`, `secret`, `password`, `cookie`, `challenge`, `signature`…)291  sont masqués avant écriture (`audit.Redact`).292- Vérification : `mccctl audit-verify` (chaîne complète, sur l'hôte) ; `GET /audit/verify` (`audit.read`).293- Export : `GET /audit/export` (`audit.export` + step-up) produit des lignes JSON suivies d'un manifeste signé294  Ed25519 (plage, nombre d'entrées, hachage précédent, hachage de tête, SHA-256 du corps).295  `mccctl audit-verify-export [--pubkey <base64>] <fichier>` vérifie le fichier **hors ligne**, sans base ni réseau ;296  la clé publique est publiée par `GET /audit/verify` (`export_public_key`).297298Limite : la chaîne détecte une modification, elle ne l'empêche pas pour qui contrôle la base **et** réécrit toute299la chaîne ; seule une tête de chaîne conservée ailleurs (un export signé, une sauvegarde hors hôte) permet de le300prouver. Aucun ancrage externe automatique n'existe.301302## 11. Inventaire des secrets303304Tous dans `MCC_SECRETS_DIR` (`~/.config/mcc` sur l'hôte **[prod]**), créés au premier usage en mode 0600. Aucun305secret n'est dans le dépôt (`.gitignore` : `*.key`, `*.pem`, `*.p8`, `.env*`, `secrets/`) ni dans la table306`settings`. Le fichier `~/.config/mcc/env` lu par `scripts/mccctl` ne contient que de la configuration.307308| Fichier | Nature | Utilisé par | Rotation (déduite du code ; **aucune n'a été exercée**) |309|---|---|---|---|310| `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](OPERATIONS.md#8-rotation-des-clés)) |311| `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) |312| `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 |313| `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` |314| `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) |315| Clé APNs (`MCC_APNS_KEY_FILE`) | `.p8` | `action-orchestrator` | **absente** : le fournisseur est inactif |316317Côté nœud (`~/.mcc-agent`, 0700) : `agent.key` (clé privée de l'agent), `agent.crt`, `ca.crt`,318`command-keys.json`. Côté second nœud de sauvegarde : une clé SSH dédiée, restreinte par commande forcée au dépôt319rsync dans un seul répertoire **[prod]**.320321Jetons affichés une seule fois, jamais stockés en clair : lien d'invitation, jeton d'enrôlement d'agent.322323## 12. En-têtes, CSP, limites de débit324325**En-têtes posés par `control-api` sur toutes les réponses** (`httpx.SecurityHeaders`) :326`X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`, `X-Frame-Options: DENY`,327`Cross-Origin-Opener-Policy: same-origin`, `Cross-Origin-Resource-Policy: same-origin`,328`Permissions-Policy: camera=(), microphone=(), geolocation=(), payment=()`, et en HTTPS329`Strict-Transport-Security: max-age=63072000; includeSubDomains`. Les réponses d'API portent `Cache-Control: no-store`330et `X-Correlation-Id` (toujours généré par le serveur).331332**CSP des pages** (`apps/web/src/proxy.ts`), avec un nonce par requête :333334```335default-src 'self'; script-src 'self' 'nonce-…' 'strict-dynamic'; style-src 'self' 'nonce-…';336img-src 'self' data:; font-src 'self'; connect-src 'self'; object-src 'none'; frame-ancestors 'none';337base-uri 'none'; form-action 'self'; manifest-src 'self'; worker-src 'self'338```339340`'unsafe-eval'` n'est ajouté qu'hors production. Aucun attribut `style` en ligne. Preuves : Playwright « sign-in341page: CSP header with a nonce, no referrer, no password field » et le test « no CSP violation and no console error »342de chaque fichier de spécification ; HSTS, en-têtes et CSP à nonce observés **[prod]**.343344**Limites de débit telles qu'implémentées** (en mémoire, par processus ; seau à jetons `httpx.Limiter`) :345346| Portée | Limite | Clé | Source |347|---|---|---|---|348| Opérations publiques et de transaction d'invitation (toutes confondues) | 30/min, rafale 15 | IP cliente | `api/server.go` (`authLimiter`) |349| Requêtes authentifiées | 900/min, rafale 300 | session | `api/server.go` (`userLimiter`) |350| Création d'actions | 30/min, rafale 30 | utilisateur | `api/ops_actions.go` |351| `/agent/v1/enroll` au relais | 20/min, rafale 10 | IP cliente | `api/agent_proxy.go` |352| `/agent/v1/enroll` à l'ingestion | 6/min, rafale 6 | IP cliente | `ingest/server.go` |353| Échecs de signature d'agent | 30 par minute puis `429` | IP + certificat présenté | `ingest/signed.go` |354355Ces valeurs **diffèrent** de celles écrites dans le contrat (10/min par IP pour les cérémonies, 5/min pour l'échange356d'invitation, 10/min par session pour le step-up) : voir [API.md §8](API.md#8-écarts-connus-entre-contrat-et-implémentation).357L'adresse cliente n'est lue dans `X-Forwarded-For` que si le pair TCP est un proxy de confiance358(`MCC_TRUSTED_PROXIES` ; `TestResolveIPTrustsOnlyConfiguredProxies`).359360## 13. Données privées des nœuds361362- Adresses IP et MAC, numéro de série, UUID matériel, cibles NAS : visibles seulement avec `nodes.private.read`,363  évaluée **par nœud** (un `deny` limité à un site ou une étiquette s'applique). Par défaut : operator et au-dessus.364- Journaux et sorties de commandes : `logs.read` sur le nœud, en plus de `actions.read`.365- Jamais collecté par l'agent : lignes de commande des processus, blocs `env` de PM2 (seul `PORT` est lu),366  arguments des serveurs d'inférence au-delà de `--model` et `--port`, identifiants dans les URL de volumes.367- `docs/REAL-INFRASTRUCTURE-INVENTORY.md` et `docs/recon/` contiennent des adresses privées : le dépôt doit rester368  privé.369370## 14. Lacunes connues371372| Sujet | État |373|---|---|374| Audit de sécurité indépendant | non réalisé |375| Compte owner en production | **inexistant** : aucun parcours authentifié exercé en production par une personne |376| Navigateurs et authentificateurs réels | Safari, Firefox et authentificateurs de plateforme non exercés (tests : authentificateur virtuel, Chromium) |377| 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 |378| 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) |379| 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) |380| `go test -race` | non exécuté sur `ingest` et `agent` |381| 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 |382| Ancrage externe de l'audit | aucun automatique |383| Push APNs | inactif (pas de clé) : aucune notification hors de l'application |384| Température, puissance | non mesurées (agent sans root) — sans effet de sécurité, mais pas d'alerte thermique |385| Terminal d'administration | non livré (ADR 0008) |386| CI hébergée | aucune ; `make ci` local, crochet `pre-push` à installer par `make hooks` (absent du dépôt de travail consulté) |387| Suite de tests | au commit `45f0d03`, `go test ./...` échoue sur 1 test (`TestJobRunsToSuccess`, assertion périmée) : voir [ACCEPTANCE.md §1](ACCEPTANCE.md#1-état-des-suites-de-tests) |388| Réplication | aucune ; une seule base sur un seul hôte |389390> **Mise à jour (même soir, commit suivant `45f0d03`)** : `TestJobRunsToSuccess` a été corrigé (assertion alignée sur le format réel des paramètres) et `go test -count=1 ./...` est de nouveau vert sur les 26 paquets. L'événement SSE `node.state` émis par l'ingestion porte désormais les champs du contrat (`alias`, `freshness`, `maintenance`, `observed_at`) en plus de `values`/`availability`, `node.updated` porte `change`, et les trois binaires sont estampillés de la même version. Les autres écarts listés dans API.md §8 restent ouverts.391392393## 15. Réponse aux incidents394395Les commandes `mccctl` s'exécutent sur l'hôte : `~/apps/maclustr-command-center/scripts/mccctl <commande>`.396Les opérations d'API demandent une session ; **tant qu'aucun owner n'existe en production, seules les voies397`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.398399### 15.1 Appareil perdu ou volé4004011. Depuis un autre appareil : Réglages → Sécurité → révoquer l'appareil (`DELETE /me/devices/{id}`), ou par un402   admin `DELETE /devices/{id}` (step-up). Effet : sessions de l'appareil révoquées, jeton push effacé.4032. Si la passkey était **liée à l'appareil** (non synchronisée) : la révoquer (`DELETE /me/passkeys/{id}`).4043. Si c'était la seule passkey : `mccctl recovery-invite --handle <h>` sur l'hôte ; ouvrir le lien sur le nouvel405   appareil. Toutes les anciennes passkeys et sessions sont révoquées.4064. Vérifier l'audit (`auth.login`, `session.*`) sur la période.407408### 15.2 Agent compromis (un nœud)4094101. Révoquer l'agent : `POST /agents/{id}/revoke` (step-up). Coupure en quelques secondes.4112. Sur le nœud, si accessible : `touch ~/.mcc-agent/FREEZE`, puis `agents/macos/uninstall.sh --purge`.4123. Considérer comme non fiables les données rapportées par ce nœud depuis la compromission supposée.4134. Examiner l'audit et `action_events` pour les commandes exécutées sur ce nœud.4145. Après remise en état : nouveau jeton d'enrôlement, nouvelle identité (l'ancienne ne revient pas).415416Portée : la clé d'un agent ne permet ni de commander un autre nœud, ni de lire les commandes d'un autre agent, ni417de se faire passer pour l'ingestion.418419### 15.3 Ingestion compromise4204211. `mccctl freeze` (arrêt de toute émission de commande).4222. Arrêter `mcc-telemetry-ingest` (`pm2 stop`). Les agents tamponnent jusqu'à 6 h.4233. Portée : l'attaquant a pu lire la télémétrie, jeter ou retarder des commandes, écrire de fausses données en424   base, **et lire `agent-ca.key`** (émettre des identités d'agent). Il n'a pas pu forger de commande.4254. Remise en état : reconstruire le binaire depuis le dépôt ; si la clé d'AC est suspecte, remplacer l'AC et426   ré-enrôler tous les agents ([OPERATIONS.md §8](OPERATIONS.md#8-rotation-des-clés)).4275. `mccctl unfreeze` une fois l'état vérifié.428429### 15.4 Invitation fuitée4304311. `DELETE /invitations/{id}` (step-up) si elle n'est pas consommée. Sans compte : attendre son expiration432   (15 min par défaut) ou, sur l'hôte, `update invitations set revoked_at = now() where id = '<id>'`.4332. Si elle a été consommée par un tiers : désactiver le compte créé (`PATCH /users/{id}` `disabled: true`, ce qui434   révoque ses sessions), puis examiner l'audit (`invitation.exchange`, `invitation.complete`).4353. Une invitation ne peut jamais donner accès à un compte existant sans la session de ce compte.436437### 15.5 Prise de contrôle de compte suspectée4384391. `mccctl freeze`.4402. Désactiver le compte (admin ou owner, step-up) — ses sessions sont révoquées. S'il s'agit du seul owner :441   `mccctl recovery-invite --handle <h>` (révoque passkeys et sessions) et ouvrir le lien soi-même.4423. Revoir : passkeys ajoutées (`passkey.add`), octrois (`policy_grants`), invitations créées, actions demandées,443   agents enrôlés, réglages modifiés. Exporter l'audit et le vérifier hors ligne.4444. `mccctl unfreeze`.445446### 15.6 Gel d'urgence447448```sh449ssh <hôte>450~/apps/maclustr-command-center/scripts/mccctl freeze     # orchestrator.frozen = true, audité451~/apps/maclustr-command-center/scripts/mccctl status452# … investigation …453~/apps/maclustr-command-center/scripts/mccctl unfreeze454```455456Le gel n'interrompt pas une commande déjà en cours sur un nœud : pour cela, annuler l'action (`POST457/actions/{id}/cancel`) ou poser `FREEZE` sur le nœud (qui ne bloque que les commandes suivantes). Arrêt complet du458produit : [OPERATIONS.md §12](OPERATIONS.md#12-arrêt-durgence).459
Files main
Menu

Theme