Module complémentaire de FreeScout qui ajoute une couche de mise à jour sécurisée pour les modules communautaires : vérification SHA-256, staging, sauvegarde, contrôles de santé, détection de crash, retour arrière automatique, restaurations, journal et rapports.
UpdateGuard n'est pas « un autre updater » : son rôle est intégrité + sauvegarde + validation + contrôle de santé + détection de crash + retour arrière + restauration + journal. Objectif : qu'une mauvaise mise à jour ait le moins de chances possible de rendre FreeScout inutilisable, et que l'administrateur comprenne et restaure rapidement la situation.
- Ne modifie ni le cœur de FreeScout ni les autres modules (ni Refresh) : il utilise les mécanismes existants
(
module.json,latestVersionUrl,latestVersionZipUrl,freescout:module-install, hooks Eventy). - Refresh est facultatif : sans lui, interface FreeScout standard ; avec lui, entrée dans sa barre latérale et
feuille de style d'adaptation (
updateguard-refresh.css) qui retombe sur le style standard s'il disparaît. - Interface responsive (ordinateur, tablette, téléphone) : sur téléphone, les tableaux deviennent des cartes et les
actions secondaires passent dans le menu
⋮. - 7 langues : français, anglais, allemand, espagnol, italien, néerlandais, portugais (Brésil). La langue suit le
profil FreeScout de l'utilisateur ; une langue absente utilise l'anglais.
install.shparle français ou anglais. - Réservé aux administrateurs (routes
auth+roles:admin, vérification répétée dans chaque contrôleur, CSRF). - Les mises à jour ne s'exécutent jamais dans une requête web : l'interface crée une tâche, le planificateur de
FreeScout l'exécute dans la minute (
updateguard:run), la page affiche la progression.
Prérequis : FreeScout ≥ 1.8, PHP ≥ 7.1 avec l'extension zip, la tâche cron de FreeScout
(* * * * * php artisan schedule:run).
curl -fsSLO https://github.com/00MY00/UpdateGuard/releases/latest/download/install.sh
sudo bash install.sh # --path /var/www/html, --dry-run, --uninstall, --lang fr|enLe script vérifie le SHA-256 de l'archive publiée, sauvegarde l'éventuelle version précédente (remise en place en cas
d'erreur), active le module, lance les migrations puis php artisan updateguard:health.
Installation manuelle : décompresser UpdateGuard.zip dans Modules/, puis Gérer › Modules › UpdateGuard ›
Activer.
UpdateGuard ne se met pas à jour lui-même (« UpdateGuard updates are handled by FreeScout ») : son module.json
déclare latestVersionUrl / latestVersionZipUrl, c'est le bouton natif de FreeScout (ou install.sh) qui le met à
jour. Quand une nouvelle version existe, le tableau de bord et la page Modules affichent « Mettre à jour dans
FreeScout », qui ouvre la page Modules de FreeScout.
UpdateGuard se vérifie lui-même sans se mettre à jour (à chaque vérification des versions, « Vérifier maintenant » sur sa fiche, ou « Analyser tous les modules ») :
- Intégrité : chaque fichier installé est comparé à
FILES.sha256, publié avec la release de la version installée (releases/download/v<version>/, tags jamais déplacés). Un fichier modifié, manquant ou ajouté sur le serveur est signalé (« Fichiers modifiés », avec la liste). - VirusTotal (s'il est activé) : l'empreinte de l'
UpdateGuard.zipofficiel de cette release (sonSHA256SUMS) est recherchée, une seule requête par version grâce au cache. Si VirusTotal ne la connaît pas, l'archive officielle peut lui être envoyée (code public ; elle est d'abord comparée àSHA256SUMS).
| Badge | Signification |
|---|---|
| ✓ Vérifié | fichiers identiques à la release et 0 détection VirusTotal |
| ✓ Intègre | fichiers identiques à la release (VirusTotal désactivé ou archive pas encore connue) |
| × Fichiers modifiés | le code installé n'est pas celui publié : alerte sur le tableau de bord |
| × Signalé par VirusTotal | l'archive officielle est signalée : alerte sur le tableau de bord |
| ? Non vérifiable | FILES.sha256 introuvable (version de développement, réseau) |
UpdateGuard ne s'analyse pas avec ses propres règles : son code contient les motifs de détection et se signalerait lui-même. Le contrôle d'intégrité le remplace : il prouve que le code installé est exactement le code publié. Limite : il protège contre une modification sur le serveur, pas contre un dépôt GitHub compromis (VirusTotal apporte alors un avis extérieur).
Menu Gérer › UpdateGuard. Sur téléphone avec Refresh : panneau Profil (menu ☰) › UpdateGuard ; sans Refresh : menu ☰ de FreeScout › Gérer › UpdateGuard.
| Page | Contenu |
|---|---|
| Tableau de bord | modules surveillés, mises à jour disponibles, modules sains, avertissements, échecs, dernière mise à jour, dernier retour arrière, opérations en cours, bouton « Tout vérifier » |
| Modules | version installée / dernière, niveau de sécurité, santé, dernière sauvegarde ; actions Mettre à jour, Vérifier, Contrôle de santé, Sauvegardes, Journal ; fiche détaillée avec rapport de compatibilité, retour à la dernière version saine, mises à jour automatiques autorisées ou non |
| Restaurations | toutes les sauvegardes (module, version, date, taille, santé, raison, version saine) ; Restaurer (page de confirmation « Actuelle / Restaurer »), Télécharger, Voir le rapport, Supprimer |
| Journaux et rapports | filtres module, date, gravité, état, ID de mise à jour, automatique/manuelle ; rapports TXT, JSON, HTML |
| Rapports de sécurité | un rapport par paquet analysé : date, module, version, intégrité, analyse locale, analyse externe, risque, décision, résultat ; rapport complet (constats, JSON) et décisions sur une mise à jour en attente |
| Réglages | Mises à jour, Sécurité (Security Gate), VirusTotal, Retour arrière, Rétention, Notifications, Avancé |
| Niveau | Condition | Automatique |
|---|---|---|
| ✓ Full Safe Update | version distante + ZIP + SHA-256 + contrôle de santé natif | oui (si activé) |
| ! Protected Update | version distante + ZIP + SHA-256 ou contrôle natif | seulement si le réglage l'autorise |
| ! Generic Validation | version distante + ZIP, ni SHA-256 ni contrôle natif : tests génériques | jamais |
| × Unsupported Automatic Update | pas de latestVersionUrl / latestVersionZipUrl, module officiel sous licence |
jamais |
| ↻ Mis à jour par FreeScout | UpdateGuard lui-même (voir plus haut : il se vérifie, FreeScout le met à jour) | jamais |
La sauvegarde et le retour arrière des fichiers sont faits à tous les niveaux.
Mise à jour détectée → préflight → téléchargement (HTTPS) → SHA-256 → staging → compatibilité des projets
→ tests génériques → Security Gate (analyse locale, scanners externes, score, politique) → sauvegarde
→ installation → vidage du cache → contrôle de santé → observation → SUCCÈS → version marquée stable
Contrôle de santé en ÉCHEC → retour arrière automatique → version précédente remise → cache reconstruit
→ contrôle de santé → version saine confirmée → version cible bloquée → rapport pour l'administrateur
- Préflight : espace disque, droits d'écriture (
Modules/,public/modules,bootstrap/cache, stockage), extension zip, stockage des sauvegardes. Toute erreur critique : ABORT avant toute modification. - SHA-256 :
SHA256SUMSpublié à côté du ZIP (ousha256sumsUrl). Empreinte différente : ABORT. Fichier annoncé mais illisible : ABORT. Pas de fichier : la mise à jour manuelle reste possible avec un avertissement, l'automatique est refusée. - Staging dans
storage/updateguard/staging/: jamais d'extraction directe dansModules/. Refus des../, chemins absolus, liens symboliques, fichiers hors du dossier du module, dossiers de premier niveau inattendus, archives corrompues,module.jsond'un autre module (nom ou alias différent). - Compatibilité des projets : FreeScout, PHP et modules liés déclarés par la nouvelle version (voir « Compatibilité des projets » plus bas). Elle est vérifiée avant l'installation ; le contrôle de santé vient après.
- Migrations : si la nouvelle version apporte des migrations, l'état de la base après un retour arrière est
inconnu : le retour arrière automatique est désactivé pour cette mise à jour et elle n'est jamais
automatique (sauf déclaration
"updateGuard": {"migrations": "backward-compatible"}du module). En version 1, les migrations ne sont jamais annulées automatiquement. - Observation (0, 5, 10, 30 ou 60 min) : la version reste « en attente de validation » ; les erreurs HTTP 500 et erreurs PHP fatales du module dans le journal Laravel déclenchent le retour arrière ; à la fin, un dernier contrôle de santé marque la version stable.
- Protection contre les boucles : une version en échec est bloquée (« Status: Blocked, Reason…, Last known good… ») et n'est plus retentée automatiquement ; une version plus récente est réévaluée. Une tentative automatique par version et par jour au maximum. L'administrateur peut réautoriser une version bloquée (action journalisée).
- Verrou global (
storage/updateguard/locks/) : une seule mise à jour / restauration à la fois ; un verrou abandonné (processus tué) est nettoyé et l'opération interrompue est signalée, jamais reprise à l'aveugle.
Un numéro de version doit toujours désigner le même contenu. UpdateGuard retient le SHA-256 de chaque version vue
dans SHA256SUMS. Si la même version revient avec un autre SHA-256 (release modifiée après publication, ou source
compromise), rien n'est installé automatiquement : bande d'alerte, mises à jour automatiques du module suspendues, et
bouton « Mettre à jour vers cette version » pour l'administrateur qui fait confiance à la nouvelle publication.
Toujours : verrou → sauvegarde de la version actuelle → vérification de l'empreinte de la sauvegarde → restauration
→ freescout:module-install → vidage du cache → contrôle de santé → rapport. Si elle échoue : état CRITICAL,
aucune seconde restauration automatique.
storage/updateguard/backups/<Module>/<version>-<date>/ : files/ (copie du module) et metadata.json (module,
version, date, empreinte, source, état de santé, ID de mise à jour, raison). Rétention : « garder les N dernières
versions » ET « supprimer les sauvegardes de plus de X jours » ; la dernière version saine n'est jamais
supprimée automatiquement. Rétention séparée du journal et des rapports.
| Commande | Rôle |
|---|---|
updateguard:run |
(planificateur, chaque minute) tâches en file, observations, mises à jour automatiques, verrous abandonnés |
updateguard:check [Module] |
versions distantes, SHA256SUMS, commandes de santé (planifié : chaque heure ou chaque jour) |
updateguard:update Module [--force] [--queue] [--zip=paquet.zip --sums=SHA256SUMS] [--yes] [--upload|--skip-upload] [--override] |
mise à jour sécurisée ; --zip : paquet local (mise à jour hors ligne) ; décisions de la porte de sécurité données d'avance (sinon question dans un terminal) |
updateguard:scan Module [--zip=…] [--sums=…] [--installed] [--upload] [--json] |
porte de sécurité sans rien installer : dernier paquet publié, paquet local, ou fichiers installés ; code de sortie 0 vérification réussie, 1 bloqué / problème critique, 2 erreur de scanner ou de configuration |
updateguard:health [Module] [--all] [--json] |
contrôle de santé d'un module, de tous, ou d'UpdateGuard lui-même |
updateguard:restore Module [backup] [--list] |
restaurer une sauvegarde (par défaut la dernière version saine) |
updateguard:cleanup |
appliquer la rétention (planifié chaque jour) |
Chaque opération reçoit un ID (UG-20261013-00042) et un rapport (TXT, JSON facile à joindre à une issue GitHub,
HTML). Le rapport sépare clairement « Native health check » et « Generic validation ». Journal : horodatage,
gravité (DEBUG, INFO, WARNING, ERROR, CRITICAL), module, versions source et cible, étape, message.
FreeScout continue de fonctionner normalement et son bouton « Mettre à jour » n'est pas masqué (le cœur n'est pas modifié). Sur la page Gérer › Modules, une note conseille de faire les mises à jour des modules communautaires avec UpdateGuard (désactivable : Réglages › Notifications). Les modules gérés sont signalés « Managed by UpdateGuard » : ne les mettez pas à jour en même temps par un autre mécanisme automatique.
Un module peut déclarer ses relations avec d'autres modules FreeScout (projets), par exemple : RefreshGlobal fonctionne sans Refresh, mais si Refresh est installé, sa version doit être prise en charge. Ce n'est jamais une dépendance imposée : UpdateGuard vérifie seulement ce que le module déclare, avant d'installer sa nouvelle version.
| Relation | Projet absent | Projet installé |
|---|---|---|
required_dependency |
MISSING_REQUIRED (bloque) | version vérifiée ; hors plage : INCOMPATIBLE |
optional_integration |
OPTIONAL / NOT INSTALLED (ne bloque pas) | version vérifiée ; hors plage : UNKNOWN |
recommended_companion |
OPTIONAL / NOT INSTALLED (signalé) | comme une intégration facultative |
conflict |
rien | INCOMPATIBLE (toutes versions, ou les plages données) |
compatibility_tested |
rien | version comparée aux versions testées |
États : COMPATIBLE (combinaison prise en charge), DEGRADED (fonctionne, intégration en mode ancien : plage
legacy), UNKNOWN (aucune information, ou version hors de la plage d'un projet facultatif), INCOMPATIBLE
(conflit déclaré, protocole d'interopérabilité refusé, dépendance obligatoire hors plage), MISSING_REQUIRED
(dépendance obligatoire absente ou désactivée). Le pire état donne le résultat global.
- Avant la mise à jour, le bouton « Mettre à jour » ouvre une page de confirmation : FreeScout, PHP, chaque projet
lié, protocole d'interopérabilité, puis « Mise à jour sûre », « Bloquée »… avec Annuler la mise à jour et, si
c'est permis, Installer quand même (case à cocher, enregistré en CRITICAL dans les journaux ;
updateguard:update --override-compatibilityen ligne de commande). - Pendant la mise à jour, après le téléchargement et le SHA-256, le paquet est vérifié à nouveau. Sources, par
priorité :
interop.jsondu paquet →interop.jsonpublié à côté du ZIP de la release →module.jsondu paquet (compatibility, et les anciensrequiredAppVersion,requiredPhpVersion,requires) → métadonnées de la version installée → inconnu. - Règles (Réglages › Règles de blocage) : un projet incompatible ou une dépendance obligatoire absente bloque (interrupteur) ; « Installer quand même » permis (interrupteur, jamais pour une mise à jour automatique) ; compatibilité inconnue : mise à jour automatique refusée (interrupteur, désactivé par défaut). DEGRADED ne bloque pas. FreeScout ou PHP trop ancien bloque toujours.
- Règles d'urgence d'UpdateGuard (
Config/compatibility_rules.php) : une combinaison découverte incompatible après la publication d'un module (sa release ne peut plus changer) peut être ajoutée par une version d'UpdateGuard ; elle s'ajoute aux métadonnées du module comme conflit connu, sans les remplacer. - La fiche de chaque module affiche une section Compatibilité des projets (version installée, dernière version, modules qui le déclarent) avec les liens vers les dépôts déclarés. Le résultat est enregistré dans le rapport de chaque mise à jour.
Chaque paquet de module est analysé avant d'être installé, dans le dossier de staging, après la vérification SHA-256 et la validation de l'archive. Les contrôles de santé restent après l'installation : ce sont deux responsabilités séparées. Tout est réglable dans Réglages › Sécurité ; chaque contrôle peut être désactivé, et avec l'interrupteur général « Activer la porte de sécurité » coupé, UpdateGuard fonctionne comme avant, sans analyse.
À lire. L'analyse locale ne garantit pas qu'un logiciel est sans malware. Les résultats de VirusTotal peuvent contenir des faux positifs. Envoyer un paquet à un service externe peut avoir des conséquences pour la confidentialité. Une empreinte SHA-256 prouve l'intégrité (c'est bien le fichier publié), pas la fiabilité de son auteur. L'administrateur reste responsable de la décision d'installer du code tiers.
⚠ Modules qui utilisent ou intègrent de l'IA (assistant, résumé ou réponse automatique aux tickets, appel à un modèle de langage comme OpenAI, Claude, Mistral, un modèle local…) : soyez particulièrement prudent. UpdateGuard ne peut pas encore vérifier ces modules contre l'injection de prompt (prompt injection). Un e-mail, un ticket ou une pièce jointe peut contenir des instructions cachées qui détournent l'IA : divulguer des données de clients ou de la configuration, modifier ou supprimer des tickets, envoyer des réponses ou des e-mails à la place d'un agent. Ce risque ne vient pas du code du paquet mais des données traitées pendant l'utilisation : ni l'analyse locale, ni le score, ni VirusTotal ne le détectent, et un paquet « sain » pour UpdateGuard peut quand même être exposé. Avant d'installer ou de mettre à jour un tel module : vérifiez ce que l'IA peut lire et faire (accès en lecture seule si possible, aucune action automatique sans validation humaine), quelles données partent vers un service externe, et testez-le d'abord sur une instance de test.
| Contrôle | Ce qui est recherché |
|---|---|
| Empreintes SHA256 | paquet comparé à SHA256SUMS : VERIFIED, MISMATCH, NOT AVAILABLE, DISABLED |
| Structure du paquet | Zip Slip (../, chemins absolus), liens symboliques, chemins en double ou en conflit (même nom à la casse près), taux de compression anormal (bombe ZIP), archive corrompue ; jamais d'extraction directe dans le module en service |
| Motifs PHP suspects | eval, assert avec du code, exec, system, shell_exec, passthru, proc_open, popen, pcntl_exec, backticks, create_function, preg_replace /e, base64_decode, gzinflate, gzuncompress, str_rot13… et surtout les combinaisons : eval(base64_decode(…)), nom de fonction construit ('sys'.'tem'), appel dynamique dans un fichier qui décode des données |
| Obfuscation | longues chaînes encodées, plusieurs couches de décodage, code en hexadécimal / octal, chaînes à entropie élevée, PHP caché dans une image ou après des données binaires, données après __halt_compiler() |
| Fichiers exécutables | binaires ELF, PE (Windows), Mach-O, .exe, .so, .dll, .phar… (reconnus par leur contenu, pas seulement par leur extension) |
| Écritures hors du module | écriture vers /etc, /usr, cron, .env, configuration du serveur web / PHP, fichiers du cœur de FreeScout (app/, config/, routes/…), un autre module, chemins qui remontent avec ../../ ; les écritures normales (storage_path(), le propre dossier du module) ne sont pas signalées |
| Réseau | curl_exec, fsockopen, stream_socket_client, file_get_contents('http…'), Guzzle : une requête seule n'est pas suspecte ; elle le devient si du code téléchargé est exécuté, si le fichier lit des secrets (.env, APP_KEY, mot de passe de la base) ou pour un domaine inhabituel |
| Scripts d'installation | curl … | sh, crontab, /etc/…, chmod 777, authorized_keys, rm -rf /… dans les scripts shell ; commandes ou requêtes réseau dans les migrations et les fichiers install*.php / update*.php ; scripts de composer.json |
L'analyse PHP lit les jetons du code (token_get_all) sans jamais l'exécuter : un nom de fonction dans un
commentaire, un docblock ou une traduction n'est pas un appel, et $this->exec() n'est pas exec().
Chaque constat a une gravité (LOW, MEDIUM, HIGH, CRITICAL) et un poids. Une règle compte une seule fois quel que
soit le nombre d'occurrences, et chaque famille de contrôles a un plafond : un gros module avec beaucoup de
base64_decode() ordinaires n'atteint pas un score élevé. Seules les combinaisons dangereuses montent haut.
| Exemple | Poids |
|---|---|
| SHA-256 différent, traversée de chemin dans l'archive | +100 |
| Code distant téléchargé puis exécuté | +80 |
| Écriture dans un dossier système | +70 |
| Écriture dans le cœur de FreeScout | +60 |
eval() de contenu décodé |
+60 |
| Code obfusqué (plafond de la famille) | +30 à +50 |
shell_exec() |
+20 |
base64_decode(), requête HTTP externe |
+5 |
Score de 0 à 100 : 0–20 LOW, 21–49 MEDIUM, 50–79 HIGH, 80–100 CRITICAL (seuils réglables).
Une règle activée arrête la mise à jour avant toute modification : la version installée continue de tourner. Chaque règle est un interrupteur, avec une explication sous chacune ; une règle grisée dépend d'un interrupteur désactivé (porte de sécurité, VirusTotal, mises à jour automatiques). Les règles sont rangées par situation :
| Situation | Règle (par défaut) |
|---|---|
| Toujours (manuelle et automatique) | SHA256SUMS annoncé mais illisible ✓ · empreinte différente ✓ · archive dangereuse ✓ · résultat critique de l'analyse locale ✓ · score ≥ seuil (80) ✓ · VirusTotal : résultat bloquant ✓ · VirusTotal ne répond pas (panne, clé, quota) ☐ |
| Mises à jour manuelles | résumé avant installation (jamais / seulement en cas d'avertissement / toujours) · passer outre un blocage ✓ · paquet inconnu de VirusTotal : demander avant d'envoyer ✓ · envoyer automatiquement ☐ |
| Mises à jour automatiques | niveau de sécurité minimum (Full Safe) · aucun SHA256SUMS publié ✓ · paquet inconnu de VirusTotal ✓ · nouvelles migrations de base de données ✓ · version republiée avec un autre SHA-256 ✓ |
La logique : une mise à jour manuelle a quelqu'un pour décider. Elle peut se mettre en pause (résumé, accord d'envoi) et, si c'est permis, être installée quand même après un blocage. Une mise à jour automatique n'a personne : dans le doute elle n'est pas faite, le tableau de bord indique pourquoi, et elle peut être lancée à la main. Un paquet inconnu de VirusTotal est retenté chaque heure (sans requête, grâce au cache) et passe dès qu'il a été envoyé et analysé.
- Résumé avant installation : la mise à jour se met en pause sans rien modifier et la page « Rapports de sécurité » affiche le résumé avec Continuer la mise à jour / Annuler.
- Passer outre un blocage : case « J'ai lu les constats et j'accepte le risque » + confirmation, « Installer quand même ». L'action est enregistrée en CRITICAL dans le journal et dans le rapport de sécurité, et ne vaut que pour le paquet analysé (même SHA-256). Jamais possible pour une empreinte différente (ce n'est pas le fichier publié) ni pour une archive dangereuse (elle ne peut pas être extraite sans risque) : ces deux règles ne peuvent qu'être désactivées.
Un module peut avoir besoin d'un comportement que l'analyse signale (lancer git, appeler l'API de son auteur…).
Depuis le rapport de sécurité, après vérification, « Faire confiance à ces constats » les accepte pour ce module :
motif obligatoire, case de confirmation, entrée dans le journal. Les constats acceptés restent affichés, marqués
« confiance accordée », mais ne comptent plus dans le score ni dans le blocage.
- La confiance porte sur chaque constat précis (règle + fichier + détail), pas sur le module : une nouvelle fonction, un nouveau domaine ou un nouveau fichier dans une version suivante est signalé de nouveau.
- Jamais pour une empreinte différente, une archive dangereuse ou un résultat d'un scanner externe.
- Le formulaire indique si VirusTotal confirme « rien détecté » ou s'il n'y a aucune confirmation externe.
- La fiche du module affiche l'état de chaque test de la dernière analyse et ce qui a été signalé, sans relancer d'analyse, ainsi que la liste des constats acceptés avec « Retirer ».
- Désactivable : Réglages › Règles de blocage › « Permettre aux administrateurs de faire confiance… ».
- Tableau de bord › « Analyser tous les modules » et fiche d'un module › « Analyse de sécurité » : le paquet publié du module (dernière version, comme pour une mise à jour) est analysé sans rien installer, ou les fichiers installés si le module ne publie pas de paquet. L'analyse tourne en tâche de fond (planificateur) ; à la fin la page ouvre le rapport, et la fiche du module affiche la dernière analyse.
- Si VirusTotal ne connaît pas encore un paquet, le tableau de bord et la fiche du module proposent « Envoyer et analyser » (ou « Tout envoyer et analyser »), toujours après l'avertissement de confidentialité.
- Les fichiers installés ne sont analysés que localement : il n'y a pas de paquet à chercher ni à envoyer.
- Commande équivalente :
php artisan updateguard:scan Module [--installed] [--json].
Réglages › VirusTotal : clé API (enregistrée chiffrée avec la clé de l'application FreeScout, jamais réaffichée en entier), « Tester la connexion », chercher d'abord l'empreinte, envoi automatique des fichiers inconnus (désactivé), seuils de détection, délai, compte gratuit / premium. Les règles qui concernent VirusTotal (résultat bloquant, service indisponible, demander avant d'envoyer, envoi automatique, paquet inconnu en mise à jour automatique) sont dans Règles de blocage.
Confidentialité : par défaut seul le SHA-256 du paquet est envoyé. Si VirusTotal ne connaît pas le fichier, UpdateGuard demande avant de l'envoyer : « Ce fichier n'est pas encore connu… Envoyer le module peut partager le paquet avec VirusTotal et ses partenaires de sécurité » — Annuler, Continuer sans envoyer, Envoyer et analyser. Rien n'est envoyé silencieusement ; l'envoi automatique n'a lieu que si vous l'activez. Ne l'activez pas pour des modules privés ou sous licence.
Limites de l'API gratuite (VirusTotal : 4 recherches par minute, 500 par jour, 15,5 K par mois ; modifiables dans les réglages, ou « Premium » pour aucune limite locale) : UpdateGuard tient un compteur partagé par toutes les tâches, attend un créneau libre pour les tâches de fond, n'attend jamais dans une page web et affiche l'utilisation du jour et du mois. Pour économiser : résultat gardé en cache par empreinte, réponse « inconnu » gardée 1 jour, aucune recherche pour un paquet déjà bloqué par l'analyse locale, moins d'interrogations après un envoi.
La clé API est testée dès sa saisie : refusée par VirusTotal, elle n'est pas enregistrée. Les réglages sont enregistrés automatiquement à chaque changement.
Résultat normalisé (malveillant, suspect, inoffensif, non détecté). Par défaut : 0 détection PASS, 1–2 WARNING,
3–5 HIGH, 6 et plus CRITICAL ; blocage à partir de 3 détections malveillantes (une seule détection ne bloque pas).
Les résultats sont mis en cache par SHA-256 + fournisseur (7 jours par défaut) : un paquet identique n'est pas
réanalysé. Une panne du scanner (délai, quota, clé invalide) ne fait jamais planter UpdateGuard : statut ERROR, et
la politique décide.
Les scanners implémentent Modules\UpdateGuard\Services\Security\SecurityScannerProviderInterface
(getName, isConfigured, lookupHash, scanFile, supportsUpload, testConnection) et renvoient un
ScanResult standard : PASS, WARNING, BLOCKED, ERROR, DISABLED, NOT_AVAILABLE. Fournisseurs inclus :
LocalStaticScanner et VirusTotalScanner. Un autre module peut en ajouter (MetaDefender, ClamAV, scanner REST
maison…) sans toucher à UpdateGuard :
\Eventy::addFilter('updateguard.security_providers', function ($providers, $settings) {
$providers[] = new \Modules\MyModule\Security\ClamAvScanner();
return $providers;
}, 20, 2);Un rapport par paquet analysé (mise à jour ou commande updateguard:scan) : module, versions actuelle et cible,
source, SHA-256 du paquet, scanners activés, constats (fichier et ligne), score, décision, passage outre éventuel,
puis résultat de la mise à jour, du contrôle de santé et du retour arrière. Rétention : 90 jours et 500 rapports par
défaut, bouton « Appliquer la rétention maintenant » et nettoyage quotidien (updateguard:cleanup).
UpdateGuard works with any community module that follows FreeScout's own update convention. To reach the Full Safe Update level, publish four things:
-
module.jsonwith the standard FreeScout keys:{ "name": "MyModule", "alias": "mymodule", "version": "1.2.0", "latestVersionUrl": "https://github.com/me/MyModule/releases/latest/download/version.txt", "latestVersionZipUrl": "https://github.com/me/MyModule/releases/latest/download/MyModule.zip", "healthCommand": "mymodule:health" }latestVersionUrlanswers the latest version as plain text (1.2.0, the convention offreescout:module-update) or as amodule.jsonwith a"version"(e.g.releases/latest/download/module.json), the two answers FreeScout's Modules page accepts.latestVersionZipUrl: a ZIP containingMyModule/module.jsonat its root (GitHub branch archivesMyModule-main/are accepted too). HTTPS only.- Optional:
sha256sumsUrl(default:SHA256SUMSnext to the ZIP),requiredAppVersion,requiredPhpVersion,requires(aliases of required modules),"updateGuard": {"migrations": "backward-compatible"}when the previous version keeps working with your new tables/columns.
-
SHA256SUMSnext to the ZIP (output ofsha256sum):3f5a…e1 MyModule.zip 9b0c…77 module.json -
A health command registered by your ServiceProvider,
<alias>:healthby convention (orhealthCommand, which must stay in your own<alias>:namespace — any other command is ignored):php artisan mymodule:health --json
- exit code
0= healthy, anything else = failure; - with
--json(optional, detected automatically), print one JSON object, kept in the report:
{ "status": "ok", "module": "MyModule", "version": "1.2.0", "checks": { "files": "ok", "classes": "ok", "views": "ok", "routes": "ok", "assets": "ok", "database": "ok" } }Keep it fast, read-only and free of network calls. It is run in a new process right after the install, after a restore, and at the end of the observation period. UpdateGuard only runs a command already registered by the installed code: nothing downloaded is ever executed to find it.
- exit code
-
Nothing else. Without a health command, UpdateGuard still runs its generic validation: structure (
module.json, ServiceProvider files, namespace, files listed inmodule.json),php -lon every PHP file, Laravel bootstrap with the new code, core FreeScout routes, your routes resolved to existing controllers and methods, Blade templates compiled and linted.
Declare how your module relates to other FreeScout modules. Never a hard dependency: UpdateGuard only checks what you
declare, before installing your new version. Put interop.json at the root of your module (it is in your ZIP), and
optionally next to the release ZIP (releases/latest/download/interop.json, or "interopUrl" in module.json) so
that administrators see the result before downloading; list it in SHA256SUMS. The same keys in module.json work
too.
{
"project": {
"id": "refresh-global",
"name": "RefreshGlobal",
"repository": "https://github.com/00MY00/RefreshGlobal",
"interop_protocol": "1.2.0"
},
"compatibility": {
"freescout": ">=1.8.0",
"php": ">=7.1",
"projects": {
"refresh": {
"relationship": "optional_integration",
"required": false,
"name": "Refresh",
"repository": "https://github.com/altmenorg/freescout-refresh",
"supported_versions": ">=1.7.0 <2.0.0",
"interop_protocol": ">=1.0.0 <2.0.0",
"legacy": {"supported_versions": ">=1.5.0 <1.7.0", "mode": "degraded"},
"conflicts": [">=1.9.0 <=1.9.2"]
}
}
}
}project: who your module is.idis stable (default: the module name in kebab-case,RefreshGlobal→refresh-global);interop_protocolis the version of the API you offer to other modules.- Projects are found by their declared
id, then by module alias, folder name or kebab-case name (refresh,workflow-packs,update-guard);"module": "Refresh"names the folder explicitly. relationship:required_dependency,optional_integration,recommended_companion,conflict,compatibility_tested.- Ranges:
>=1.7.0 <2.0.0,1.9.0 - 1.9.2,^1.2,~1.2.3,1.9.x,*, alternatives with||. interop_protocolis compared when both sides declare it;legacy.interop_protocolgives DEGRADED instead of INCOMPATIBLE.
// extra checks run by the generic validation (new process, after install)
\Eventy::addFilter('updateguard.health_check', function ($checks, $moduleName, $alias) {
if ($moduleName === 'MyModule') {
$checks['mymodule cache'] = ['result' => is_writable(storage_path('mymodule')) ? 'PASS' : 'FAIL', 'detail' => ''];
}
return $checks;
}, 20, 3);Actions: updateguard.before_update, updateguard.after_update, updateguard.update_failed,
updateguard.before_rollback, updateguard.after_rollback (job, report), updateguard.backup_created (backup),
updateguard.health_check (module name, result). Filter updateguard.health_status (status, module, native, generic).
php tests/unit/run.php # tests unitaires purs PHP (archives malveillantes, SHA-256, verrou, porte de sécurité, VirusTotal simulé, 7 langues…)
php tests/blade/compile.php <autoload.php> # compilation des vues Blade (illuminate/view)
bash tests/integration/run.sh # FreeScout réel dans Docker : porte de sécurité, retour arrière après
# un contrôle de santé raté, paquet bloqué, Zip Slip, JSON, pages
bash tools/build-release.sh # dist/UpdateGuard.zip, version.txt, module.json, install.sh, SHA256SUMSArchitecture, modèle de données, machine d'état et stratégies : docs/architecture.md.
Licence : AGPL-3.0, comme FreeScout.