Sécurité d'un agent durable

Expérimental. Le protocole réseau, le SDK et cette page peuvent changer, ou la fonctionnalité peut être retirée, dans une version mineure ultérieure. Agents durables indique ce qui détermine son maintien.

Un agent durable est du code que vous exécutez ou déployez, et Collie traite son texte comme non approuvé. Cette page décrit ce à quoi un agent durable peut accéder, ce qui en interdit l'accès aux tiers, ce que Collie fait de son texte et ce que conserve le journal d'audit. Sécurité couvre Collie dans son ensemble.

Ce qu'un agent durable peut faire et ne peut pas faire

Un agent durable pose une question, et un appareil associé décide. Un agent durable reçoit ce que vous répondez et lui envoyez, ainsi que les requêtes du réseau. Collie ne lui donne aucun accès à vos terminaux.

Seule l'action tactile d'une personne répond à une question. La route de réponse fonctionne pour un appareil associé derrière la porte d'écriture, et rien dans le pont ne l'appelle pour un agent durable, un hook ou une sortie de modèle. Sur le téléphone, Toujours autoriser nécessite un second appui. Un agent durable qui le propose détient l'autorisation qui requiert le plus d'attention, car une seule réponse provenant d'un outil hostile laisserait passer tous les appels ultérieurs sans poser de question.

L'agent durable, et non Collie, applique les effets d'une action approuvée. Un bouton de l'agent durable s'exécute avec les droits de l'agent durable, et Collie transmet uniquement l'appui.

Un agent durable ne peut pas saturer votre écran de verrouillage. Collie traite chaque question une seule fois, identifiée par l'agent durable et l'appel d'outil, et la transmet par notification push au maximum une fois. Il autorise 3 notifications push par conversation et par minute, 10 par hôte et par minute et 30 par hôte et par heure. La notification qui correspondrait à la 31e devient une notification récapitulative unique, et l'hôte n'en envoie plus aucune avant une heure. Une carte est toujours affichée.

Attention. Le même utilisateur peut répondre à une question sur un socket. Un socket bloque les autres utilisateurs, mais pas un processus de votre propre utilisateur, ce qui inclut un outil exécuté par votre agent. La vérification des descendants constitue la propre défense de l'agent durable, et Collie ne peut pas déterminer si un agent durable l'exécute.

Avec cette vérification, un agent durable refuse answer, send, abort, action, rename, close, reopen et starter venant de lui-même, de tout processus qu'il a lancé, et de tout appelant qu'il ne peut distinguer de ceux-ci. Le refus renvoie 403 caller-refused, et les lectures restent ouvertes. La vérification nécessite Bun sur Linux, où le SDK lit l'appelant d'un socket. Le tableau indique ce qu'elle applique selon l'environnement d'exécution de l'agent durable :

Isolez les outils de l'agent dans un bac à sable ne pouvant pas joindre le socket, traitez la carte comme une simple notification plutôt que comme un verrou, ou exécutez l'agent durable sur Bun. callerCheck: "off" correspond au choix propre de l'agent durable de s'exécuter sans cette vérification.

Le transport par socket

Un socket privé bloque tout autre utilisateur, et sa seule protection est son chemin d'accès.

ls -ld /run/user/1000 /run/user/1000/desk /run/user/1000/desk/app.sock

Le socket ne transmet aucun jeton ni en-tête Authorization. Collie ne se connecte que si le chemin complet est privé, et il exécute ce parcours avant chaque connexion, de / vers le bas, avec lstat, de façon à ne suivre aucun lien :

Un chemin qui échoue devient aussitôt inaccessible, sans délai de grâce. collie doctor nomme la même vérification dans sa ligne durable-socket et fournit le correctif. Un chemin où rien n'existe indique no socket at <path>, ce qui ne constitue pas un défaut de confidentialité.

Un agent durable conçu avec le SDK crée le dossier du socket avec le mode 0700 lorsqu'il est absent. Il refuse de démarrer dans un dossier existant doté d'un autre mode. Il configure le socket avec le mode 0600, et supprime tout fichier de socket inactif avant d'écouter.

Le transport par socket est destiné à Linux et macOS. Windows ne dispose d'aucun transport par socket, utilisez-y donc le transport par jeton.

Le transport par jeton

Une URL et un jeton permettent d'atteindre un agent durable sur un autre hôte, et le jeton sert d'unique contrôle d'accès.

openssl rand -hex 32

Toute personne qui détient le jeton agit comme votre téléphone. Elle peut lire chaque conversation, répondre à chaque question, envoyer du texte, arrêter un tour, renommer ou fermer, et exécuter un starter. Une connexion TLS provenant d'Internet ne possède aucun appelant à vérifier, la vérification des descendants n'existe donc pas ici. Un agent durable joint de cette manière ne devrait proposer qu'Allow et Deny, jamais une autorisation permanente.

L'hôte voit le texte. TLS prend fin au niveau de l'hôte, il voit donc chaque requête, y compris le jeton dans son en-tête, et les conversations résident dans son stockage.

Collie conserve le jeton en clair à deux endroits. sources.json le stocke pour une entrée, et une sauvegarde ou une synchronisation du dossier de configuration l'emporte. Collie maintient ce fichier au mode 0600, restreint un fichier trop permissif au démarrage avec une ligne dans son journal, et collie doctor affiche une ligne sources rouge pour un fichier lisible par le groupe ou les autres. Le format réservé aux agents durables le conserve dans .env ou config.toml, et un fichier qui le stocke doit être en mode 0600. Collie n'affiche jamais le jeton. collie durable list indique (token set), collie doctor indique set, <n> bytes, et aucune erreur ni ligne de journal ne contient la valeur. attach le lit à partir de la variable désignée par --token-env, de sorte qu'il ne figure dans aucune ligne de commande.

Le jeton n'expire pas. Pour le renouveler, transmettez le nouveau jeton à l'agent durable avant de redémarrer Collie, sinon le téléphone indique que l'agent durable l'a refusé. Un agent durable peut accepter un second jeton pendant l'exécution d'un renouvellement : l'exemple Cloudflare parqué accepte COLLIE_TOKEN et, tant qu'il est défini, COLLIE_TOKEN_NEXT (ADR 0103). Les étapes figurent dans Jetons.

Il s'agit d'un appel sortant que Collie effectue vers l'URL configurée, et il est rejeté en ne joignant rien. Chaque requête transmet Authorization: Bearer <token>, la version du protocole, l'ETag de la dernière lecture, et pour une action le corps de ce que vous avez répondu ou envoyé. Une lecture est un GET sans corps.

Chaque interrogation via https constitue une requête que votre hôte peut facturer, et une réponse "nothing changed" compte également. Sans aucun téléphone ouvert, l'interrogation au repos s'exécute toutes les 10 s, Collie effectue donc 8 640 requêtes par jour, et toutes les 2 s lorsqu'un téléphone observe. Un agent durable indisponible ou rejetant le jeton est sollicité au maximum une fois toutes les 10 s, et ces requêtes sont facturées aussi. Utilisez un forfait payant pour un agent durable interrogé toute la journée par Collie.

Ce que Collie fait au texte d'un agent durable

Collie nettoie chaque chaîne provenant d'un agent durable avant que quiconque ne la lise, et l'affiche sous forme de texte.

Un agent durable doit envoyer des chaînes respectant les limites. Collie ne part pas du principe que c'est le cas. Chaque chaîne passe par trois étapes :

1. 01
   Suppression des contrôles. Collie supprime les caractères de contrôle C0, DEL et les contrôles C1. Les champs multilignes conservent le saut de ligne et la tabulation : le texte d'un élément, la sortie et le résumé d'un appel d'outil, ainsi que la raison d'une question.
2. 02
   Suppression des caractères invisibles et de direction. Collie supprime les marques de direction U+200E, U+200F et U+061C, les remplacements et isolats U+202A à U+202E et U+2066 à U+2069, les caractères de largeur nulle U+200B à U+200D, le séparateur de mots U+2060, l'indicateur d'ordre des octets U+FEFF et les caractères d'étiquette U+E0000 à U+E007F, qui peuvent contenir une phrase invisible entière.
3. 03
   Tronquage de la chaîne. Collie tronque la chaîne à sa limite en octets sur un caractère entier et la termine par ….

Une question dont le titre ou la raison a changé lors du nettoyage porte la mention "Text shortened" sur sa carte. Une option ou un bouton de bandeau qui ne contient plus aucun mot est supprimé, afin qu'un bouton ne soit jamais vide. Un champ sans aucun mot est désigné par son identifiant.

Les identifiants ne sont jamais nettoyés ni tronqués. Un identifiant comporte de 1 à 128 octets sans aucun caractère de contrôle, sans espace et sans aucun de /, ? ou #, sinon l'objet qui le porte est supprimé.

Collie affiche le texte sous forme de texte. Un élément markdown présente des titres, des listes, des mises en valeur, des fragments de code et des liens, et le HTML brut n'est jamais rendu : une balise s'affiche sous forme de texte brut. Un lien dans un élément markdown ouvre uniquement une adresse web. Un élément link nécessite une adresse https:// avec un hôte, sans nom d'utilisateur ni mot de passe, sans espace, caractère de contrôle ou invisible, et comportant au maximum 2048 caractères. Sinon, Collie ignore l'élément et écrit une ligne dans son journal pour chaque conversation. Les images et les fichiers ne sont pas des éléments.

Ce qui est journalisé

Collie consigne chaque écriture effectuée par un téléphone vers un agent durable dans <state-dir>/audit.log, mode 0600.

Chaque ligne contient le nom de l'agent durable sous forme de session, l'appareil associé et l'événement :

La fermeture et le renommage d'une conversation ou d'un onglet utilisent les événements habituels, pane.close, pane.rename et tab.rename. COLLIE_AUDIT_CONTENT=none masque toutes les chaînes du détail sauf quelques champs précis comme l'identifiant de requête ; l'aperçu d'un send disparaît donc aussi. Le journal indique ce qui s'est produit après coup. Il ne bloque rien.

Collie conserve également un reçu pour chaque réponse, envoi, arrêt, appui sur un bouton et démarreur, sans aucun texte saisi. Emplacement où Collie conserve les données d'un agent durable précise la durée de conservation.