CipiAgent

Installation de l'agent Cipi

CipiAgent (cipi/agent sur Packagist) est le compagnon officiel Laravel de Cipi. Il relie votre application et le panneau de contrôle du serveur avec :

• Déploiements déclenchés par Webhook à partir de GitHub et GitLab
• Surveillance de l'état (application, base de données, cache, file d'attente, validation de déploiement)
• Une application intégrée Serveur MCP pour les assistants IA (Curseur, VS Code, Claude Desktop)
• Une solution orientée RGPD anonymiseur de base de données

Sur un serveur géré par Cipi, cipi app create injecte le nécessaire .env automatiquement les variables. Le bilan de santé et MCP peuvent fonctionner sur n'importe quel hôte Laravel ; déploiement complet et journalisation l'accès s'attend à un environnement géré par Cipi.

Exigences

$ composer require cipi/agent

Le fournisseur de services découvre automatiquement – non config/app.php un changement est nécessaire. Après l'installation, s'engager et pousser ; Cipi déploie la mise à jour sur la prochaine version.

Facultatif : publiez le fichier de configuration (non-Cipi ou valeurs par défaut personnalisées) :

$ php artisan vendor:publish --tag=cipi-config
$ php artisan cipi:status   # verify config and DB connectivity

Commandes Artisan

Webhook — Déploiements automatiques

L'agent expose un point de terminaison POST à /cipi/webhook. Lorsque votre fournisseur Git envoie un push événement, l'agent vérifie la signature et rédige un .deploy-trigger fichier de drapeau. Un cron tâche exécutée toutes les minutes lorsque l'utilisateur de l'application détecte ce fichier, le supprime et exécute Deployer dans le arrière-plan.

Cette conception signifie que la réponse webhook est instantanée (pas de délai d'attente HTTP en attente de déploiement sur terminé) et Deployer s'exécute avec les autorisations utilisateur appropriées - non sudo requis.

Configurez votre fournisseur Git

Le jeton à utiliser est stocké dans .env comme CIPI_WEBHOOK_TOKEN. Vous pouvez également récupérez-le à tout moment avec :

$ cipi deploy myapp --webhook

Filtrage des branches

Par défaut, chaque poussée déclenche un déploiement. Pour restreindre les déploiements à une branche spécifique, ajoutez ceci à votre .env:

CIPI_DEPLOY_BRANCH=main

Les push vers n'importe quelle autre succursale recevront un skipped réponse et aucun déploiement ne sera déclenché.

Bilan de santé

L'agent expose également un point de terminaison GET à /cipi/health qui renvoie une charge utile JSON avec l'état de l'application, de la base de données, du cache, de la file d'attente et du hachage de validation Git actuellement déployé. Utile pour les services de surveillance externes tels que UptimeRobot. Protégé par le CIPI_HEALTH_TOKEN Jeton du porteur : générez-en un avec php artisan cipi:generate-token health.

$ curl -H "Authorization: Bearer YOUR_CIPI_HEALTH_TOKEN" \
    https://yourdomain.com/cipi/health

{
  "statut": "en bonne santé",
  "utilisateur_app": "monapplication",
  "MCP": "8.5",
  "php": "12.0.0",
  "environnement": "production",
  "chèques": {
    "application":      { "d'accord": vrai, "version": "2.1.0", "déboguer": faux },
    "base de données": { "d'accord": vrai, "base de données": "monapp_prod" },
    "cache":    { "d'accord": vrai },
    "file d'attente":    { "d'accord": vrai, "jobs_en attente": 0 },
    "déployer":   { "d'accord": vrai, "s'engager": "a1b2c3d4…", "short_commit": "a1b2c3d" }
  },
  "horodatage": "2026-06-10T14:22:01.000000Z"
}

Le commit de déploiement est résolu à partir de la première source disponible :

1. /home/{app_user}/.cipi/deploy.json (Cipi déployer des métadonnées)
2. /home/{app_user}/.cipi/last_commit
3. /home/{app_user}/logs/deploy.log
4. .git/HEAD ou git rev-parse HEAD

Authentification

Le jeton Porteur est résolu dans l’ordre : CIPI_HEALTH_TOKEN (dédié), alors CIPI_WEBHOOK_TOKEN (retomber). Désactivez entièrement le point de terminaison avec php artisan cipi:service health --disable ou CIPI_HEALTH_CHECK=false.

Surveillance des intégrations

Le point de terminaison de santé fonctionne avec n'importe quel vérificateur HTTP qui prend en charge les jetons Bearer, par exemple. Temps de disponibilitéRobot, Meilleure pile, Grafana, ou personnalisé MCP + curl. Sondage checks.queue.pending_jobs pour les alertes de retard de file d’attente.

MCP Serveur

cipi-agent comprend un intégré Serveur MCP (Protocole de contexte modèle) qui expose votre application à des assistants IA tels que Curseur, Code VS (avec GitHub copilote), et Bureau Claude. Le point final implémente MCP 2024-11-05 sur HTTP en utilisant JSON-RPC 2.0 et est protégé par le CIPI_MCP_TOKEN Jeton du porteur.

Le point de terminaison MCP est disponible sur POST /cipi/mcp et est désactivé par défaut. Pour activer ça :

$ php artisan cipi:service mcp --enable
$ php artisan cipi:generate-token mcp

Outils disponibles

Le serveur MCP expose six outils qu'un assistant IA peut appeler par son nom :

logs paramètres de l'outil

Opérations bloquées (sécurité MCP)

• Artisan : serve, tinker, queue:work, queue:listen, schedule:work, horizon, octane:start, reverb:start
• SQL : DROP, TRUNCATE, GRANT, REVOKE, E/S de fichier — lecture/écriture limitée à 100 lignes

Instructions de configuration

Exécutez le cipi:mcp Commande Artisan pour obtenir l'URL du point de terminaison et prête à être collée extraits de configuration pour votre client AI :

$ php artisan cipi:mcp

La commande imprime les outils disponibles et la configuration JSON pour Cursor, VS Code et Claude Bureau.

Curseur

Ajoutez ce qui suit à ~/.cursor/mcp.json (ou allez dans Curseur → Paramètres → MCP) :

{
  "mcpServeurs": {
    "cipi-monapplication": {
      "type": "http",
      "url": "https://votredomaine.com/cipi/mcp",
      "en-têtes": {
        "Autorisation": "Porteur YOUR_CIPI_MCP_TOKEN"
      }
    }
  }
}

Remplacer cipi-myapp avec le nom d'utilisateur de votre application, yourdomain.com avec votre domaine réel, et YOUR_CIPI_MCP_TOKEN avec le jeton de votre .env. Le curseur se connecte nativement via HTTP — aucun pont n'est nécessaire.

Code VS

VS Code (avec GitHub Copilot) prend en charge MCP nativement depuis la version 1.102. Ajoutez ce qui suit à .vscode/mcp.json dans votre projet (ou exécutez MCP : ouvrir la configuration utilisateur pour une configuration globale) :

{
  "serveurs": {
    "cipi-monapplication": {
      "type": "http",
      "url": "https://votredomaine.com/cipi/mcp",
      "en-têtes": {
        "Autorisation": "Porteur YOUR_CIPI_MCP_TOKEN"
      }
    }
  }
}

Remplacer cipi-myapp, yourdomain.com, et YOUR_CIPI_MCP_TOKEN comme ci-dessus. Utiliser MCP : Ajouter un serveur à partir de la palette de commandes pour une configuration guidée. Code VS se connecte via HTTP - aucun pont n'est nécessaire.

Bureau Claude

Claude Desktop nécessite le mcp-à distance pont pour convertir stdio en HTTP. Ajoutez le suite à ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServeurs": {
    "cipi-monapplication": {
      "commande": "npx",
      "arguments": [
        "-y",
        "mcp-télécommande",
        "https://votredomaine.com/cipi/mcp",
        "--en-tête",
        "Autorisation : Porteur YOUR_CIPI_MCP_TOKEN"
      ]
    }
  }
}

Installer mcp-remote globalement une fois avec :

$ npm install -g mcp-remote

Ce que vous pouvez faire avec

Une fois connecté, votre assistant IA peut interagir avec l'application gérée par Cipi de manière naturelle. langue. Par exemple :

Utilisateur :  Is the app healthy? Any pending jobs in the queue?

Claude : Calling health tool...
         Status: healthy — database, cache, and queue all OK.
         Queue: 0 pending jobs.

Utilisateur :  Show me the last errors from the log.

Claude : Calling logs tool (lines: 100)...
         Found 2 errors in the last 100 lines:
         [2026-03-04 14:22:01] production.ERROR: Connection refused [...]
         [2026-03-04 14:23:15] production.ERROR: Redis timeout [...]

Utilisateur :  Clear the cache and deploy the latest version.

Claude : Calling artisan tool (cache:clear)...
         Cache cleared successfully.
         Calling deploy tool...
         Deploy queued — Deployer will run within 1 minute.

Utilisateur :  What's the current migration status?

Claude : Calling artisan tool (migrate:status)...
         All 47 migrations have been run.

Utilisateur :  How many users signed up in the last 7 days?

Claude : Calling db_query tool (SELECT COUNT(*) FROM users WHERE created_at >= ...)...
         | count |
         |-------|
         | 23    |

Anonymiseur de base de données

cipi-agentcomprend un anonymiseur de base de données intégré qui crée des copies nettoyées de votre base de données de production - idéale pour le partage avec les développeurs, les équipes d'assurance qualité ou les environnements de test sans exposer les données réelles des utilisateurs. Il prend en charge les deux MCP et MySQL, utilise Plus faux-transformations basées sur configurées via un fichier JSON et s'exécute en tant que travail en arrière-plan afin que les bases de données volumineuses ne bloquent pas les requêtes HTTP.

Cette fonctionnalité réside à l'intérieur de votre Laravel demande (le cipi/agent emballer). Elle est distincte de la sauvegarde de base de données au niveau du serveur API exposée par cipi api — voir Agent contre Cipi API ci-dessous.

Cas d'utilisation

• Développement local — donnez à chaque développeur un ensemble de données réaliste sans copie e-mails, adresses ou notes de paiement de production
• Environnements de préparation/prévisualisation — actualiser une base de données hors production à partir de structure et volume de production, avec remplacement des informations personnelles
• Assurance qualité et démos — reproduire des bugs qui dépendent des données relationnelles sans risque RGPD
• Accès fournisseur ou entrepreneur — partager un dump SQL lors d'un VPN + production complet l'accès n'est pas acceptable
• Pipelines CI — courir cipi:anonymize sur le serveur ou le déclencheur POST /cipi/db à partir d’une étape d’automatisation sécurisée

Conditions préalables

Agent contre Cipi API

Les deux composants Cipi touchent aux bases de données, mais ils résolvent des problèmes différents :

Comment ça marche

1. Un authentifié POST /cipi/db demande (avec un destinataire email) files d'attente AnonymizeDatabaseJob
2. Le travail s'exécute php artisan cipi:anonymize, qui :
   • vide la base de données avec mysqldump ou pg_dump
   • coule à travers INSERT instructions et réécrit uniquement les colonnes répertoriées dans anonymization.json
   • écrit le résultat dans storage/cipi/anonymized_{jobId}.sql
3. En cas de succès, Laravel envoie un e-mail avec un URL de téléchargement limitée dans le temps (15 minutes)
4. GET /cipi/db/{token} sert le fichier – pas de jeton Bearer ; l'URL elle-même est le informations d'identification
5. En cas d'échec, un e-mail d'erreur en texte brut est envoyé à la même adresse

Notifications par courrier électronique

Le HTTP API ne renvoie pas l'URL de téléchargement dans la réponse JSON - l'e-mail est le seul canal de livraison pour POST /cipi/db. Comprendre qui le reçoit et ce qui doit être configuré évite les pannes silencieuses.

Qui reçoit l'e-mail ?

Exactement l'adresse que vous transmettez dans le corps JSON - rien d'autre :

{ "e-mail": "développeur@exemple.com" }

• Succès → HTML email avec le lien de téléchargement signé (15 minutes)
• Échec → e-mail en texte brut avec l'erreur et l'ID de la tâche
• Pas de CC, BCC ou secours à l'administrateur Cipi, CIPI_APP_USER, ou une adresse fixe à .env
• Celui qui détient CIPI_ANONYMIZER_TOKEN choisit le destinataire à chaque demande

Le courrier Laravel doit fonctionner

Les notifications utilisent les Laravel Mail façade et celle de votre application MAIL_* paramètres - la même configuration que les réinitialisations de mot de passe ou les formulaires de contact. C'est indépendant du serveur SMTP Cipi (cipi smtp configure pour la sauvegarde/le déploiement alertes sur l'hôte).

Production typique .env entrées :

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=...
MAIL_PASSWORD=...
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@myapp.example.com
MAIL_FROM_NAME="${APP_NAME}"

Test rapide du courrier (en tant qu'utilisateur de l'application, avant votre premier export) :

$ php artisan tinker --execute="Mail::raw('Cipi test de courrier anonymiseur', fn (\$m) => \$m->to('you@example.com')->subject('Mail test'));"

Si ce message n'arrive pas, corrigez d'abord le courrier Laravel - ou utilisez le chemin CLI (php artisan cipi:anonymize) qui écrit le fichier directement et ignore les e-mails.

Configuration – étape par étape

Exécutez ces commandes sur le serveur en tant qu'utilisateur de l'application (SSH : ssh myapp@your-server ou sudo su - myapp en tant que root - voir SSH en tant qu'utilisateur de l'application):

1. Installez l'agent (si ce n'est pas déjà fait composer.json):

$ composer require cipi/agent
# commit, push, deploy — or run on the current release

2. Activez le service et créez un jeton :

$ php artisan cipi:service anonymize --enable
$ php artisan cipi:generate-token anonymize

3. Échafaudez le fichier de configuration :

$ php artisan cipi:init-anonymize

Cela crée /home/{app_user}/.db/anonymization.json (autorisations 0640) à partir du modèle intégré. Le fichier vit en dehors du dépôt Git — ce n'est jamais le cas déployé avec votre code. Utiliser --force pour écraser un fichier existant.

4. Modifiez la configuration pour correspondre à vos vraies tables et colonnes sensibles (voir Configuration).

5. Vérifiez la file d'attente et le courrier : confirmez que le travailleur exécute les tâches et que Laravel peut les envoyer au adresse que vous transmettrez POST /cipi/db (voir Notifications par courrier électronique).

$ php artisan cipi:status          # DB connectivity
$ php artisan queue:work --once   # optional: confirm worker can run jobs
# send a test email — must arrive before using POST /cipi/db
$ php artisan tinker --execute="Mail::raw('Mail test', fn (\$m) => \$m->to('you@example.com')->subject('Mail test'));"

6. Déclenchez votre premier export anonymisé via HTTP ou CLI (voir exemples ci-dessous).

Configuration

Chemins valides (le premier match gagne) :

• /home/{app_user}/.db/anonymization.json — recommandé
• /home/{app_user}/.cipi/anonymization.json — alternative

Le fichier JSON possède deux clés de niveau supérieur : transformations (obligatoire) et options (facultatif).

{
  "transformations": {
    "utilisateurs": {
      "nom": "fauxNom",
      "e-mail": "fauxEmail",
      "mot de passe": "mot de passe",
      "téléphone": "faux numéro de téléphone",
      "adresse": "fausse adresse"
    },
    "commandes": {
      "notes_clients": "fauxParagraphe",
      "adresse_d'expédition": "fausse adresse"
    },
    "support_tickets": {
      "message_utilisateur": "fauxParagraphe",
      "agent_response": "fauxParagraphe"
    }
  },
  "options": {
    "algorithme_de hachage": "auto",
    "preserve_ids": vrai,
    "faux_locale": "fr_US"
  }
}

Sous transformations, chaque clé est un nom du tableau. Les clés imbriquées sont noms de colonnes; les valeurs sont des types de transformation (et non des noms de méthodes Faker bruts — voir tableau ci-dessous). Colonnes pas répertoriés conservent leurs valeurs d'origine, afin que vous puissiez anonymiser les informations personnelles tout en en préservant les clés étrangères, les énumérations et les champs de logique métier.

Transformations prises en charge

Possibilités

HTTP API — points de terminaison

Lorsque l'anonymiseur est désactivé (CIPI_ANONYMIZER=false), les itinéraires reviennent 404 — les points de terminaison sont entièrement masqués.

Exemples pratiques (curl)

Définissez les variables une fois (remplacez-les par le domaine de votre application et le jeton de .env):

exporter APP_URL="https://myapp.example.com"
exporter CIPI_ANONYMIZER_TOKEN="votre-jeton-de-l'environnement"

1. Mettre en file d'attente une tâche d'anonymisation

curl -sS -X POST "${APP_URL}/cipi/db" \
  -H "Autorisation : Porteur ${CIPI_ANONYMIZER_TOKEN}" \
  -H "Type de contenu : application/json" \
  -H "Accepter : application/json" \
  -d '{"email": "developer@example.com"}'

Réponse réussie (200):

{
  "statut": "en file d'attente",
  "message": "Le travail d'anonymisation de la base de données a été mis en file d'attente. Vous recevrez un e-mail avec les instructions de téléchargement une fois terminé.",
  "e-mail": "développeur@exemple.com"
}

L'appel HTTP revient immédiatement avec status: queued — ça fait pas garantir que l'e-mail de notification a été envoyé. Le traitement peut prendre quelques minutes sur des bases de données volumineuses (travail délai d'attente : 1 heure). Le message d'achèvement est envoyé uniquement au email dans votre corps JSON ; si rien n'arrive, vérifie storage/logs/laravel.log pour les erreurs de transport du courrier, php artisan queue:failed pour un travail raté, et que MAIL_* est configuré (voir Notifications par courrier électronique).

2. Téléchargez le dump (à partir du lien e-mail)

L'e-mail de fin contient une URL telle que :

https://myapp.example.com/cipi/db/AbCdEf...?expires=1710000000&signature=...

Enregistrez-le avec curl (collez l'URL complète de l'e-mail - pas d'en-tête Bearer) :

curl -sS -L -o anonymized.sql "PASTE_FULL_SIGNED_URL_FROM_EMAIL"

# Import locally (MySQL example)
mysql -u root -p myapp_local < anonymized.sql

Retour de liens expirés ou invalides 410 Gone ou 404. Demander un nouvel export avec POST /cipi/db si la fenêtre de 15 minutes est passée.

3. Recherchez un identifiant d'utilisateur par e-mail

Après l'anonymisation, les e-mails sont faux, mais les identifiants utilisateur restent les mêmes. Utilisez ceci avant anonymisation pour mapper un e-mail de production connu à un identifiant que vous pourrez trouver plus tard dans le déverser :

curl -sS -X POST "${APP_URL}/cipi/db/utilisateur" \
  -H "Autorisation : Porteur ${CIPI_ANONYMIZER_TOKEN}" \
  -H "Type de contenu : application/json" \
  -d '{"email": "client@production.com"}'

{
  "identifiant_utilisateur": 42,
  "e-mail": "client@production.com",
  "trouvé_à": "2026-06-10T14:22:01+00:00"
}

Cela interroge le live users table - s'exécute uniquement lorsque vous êtes autorisé à toucher à la production données. Cela ne modifie rien.

4. Réponses aux erreurs (dépannage)

CLI — exécuter sans HTTP

Pour les scripts, cron, ou les exports ponctuels sur le serveur :

$ php artisan cipi:anonymize \
    /home/myapp/.db/anonymization.json \
    /home/myapp/anonymized_export.sql

La commande imprime trois étapes (vidage → transformation → sauvegarde) et sort non nulle en cas d'échec. Ce n'est pas le cas envoyer un e-mail — copiez le fichier via SCP ou votre propre canal sécurisé.

Boucle de comparaison : Cipi API sauvegarde brute

Pour référence, un non anonymisé sauvegarde du serveur via Cipi API ressemble à ceci (hôte, jeton et sémantique différents) :

exporter CIPI_API_URL="https://api.myserver.com"
exporter CIPI_API_TOKEN="jeton-sanctum-avec-dbs-manage"

curl -sS -X POST "${CIPI_API_URL}/api/dbs/myapp_db/backup" \
  -H "Autorisation : Porteur ${CIPI_API_TOKEN}" \
  -H "Accepter : application/json"

Cela revient 202 avec un job_id — sondage GET /api/jobs/{id} pour le chemin de sauvegarde sur le serveur. Les archives contiennent données de production réelles; restreindre accéder en conséquence.

Conseils de sécurité et RGPD

• Magasin CIPI_ANONYMIZER_TOKEN dans la gestion des secrets – n'importe qui le possédant peut mettre les vidages en file d'attente et requête /cipi/db/user
• Faites pivoter le jeton après les changements d'équipe : php artisan cipi:generate-token anonymize
• Désactiver lorsque vous n'en avez pas besoin : php artisan cipi:service anonymize --disable (les points de terminaison renvoient 404)
• Les liens de téléchargement expirent dans 15 minutes — transférez soigneusement les e-mails
• Documentez quelles colonnes sont transformées pour votre DPA/politique de confidentialité
• Testez le dump : grep pour un e-mail de production connu – il ne devrait pas apparaître si fakeEmail a été défini sur cette colonne

Sécurité

Cipi L'agent utilise défense en profondeur: chaque fonctionnalité possède son propre jeton Bearer et peut être désactivé indépendamment. Lorsqu'ils sont désactivés, les itinéraires reviennent 404 (caché, pas 403).

Isolement des jetons

Vérification Webhook

• GitHub — X-Hub-Signature-256 HMAC-SHA256
• GitLab — X-Gitlab-Token comparaison d'en-tête

Code source et versions : github.com/cipi-sh/agent (MIT).

Variables ENV

Ces variables sont automatiquement injectées par Cipi dans le fichier de l'application..env pendant cipi app create. Basculez les fonctionnalités facultatives avec php artisan cipi:service {type} --enable|--disable ou définissez-les manuellement.