rivex-agent

Agent collecteur multi-plateforme pour la plateforme de surveillance de posture de securite Rivex. Collecte logs systeme, version OS, niveaux de patchs, ports ouverts, permissions de fichiers sensibles et remonte le tout vers le serveur central chiffre.

Version courante : 0.41.0 (cli/constants.py, contrôlée en CI par scripts/check_agent_version.py).

Documentation détaillée : documentation/agent/ (architecture, collecte, installation, état côté serveur). Index global : documentation/README.md.

Version et changelog (obligatoire a chaque changement de code)

1. Choisir le prochain numéro (souvent +1 sur le patch : x.y.z).
2. Ne jamais éditer les versions à la main : depuis src/agent, python agent_launcher.py --bump_version {major|minor|patch} (ou --set_version x.y.z) met à jour les six déclarations — cli/constants.py (APP_VERSION), pyproject.toml, core/config_manager.py, config.json, src/server/frontend/public/agent/version.json et src/server/frontend/agent-version.json.template (URLs comprises). Puis python scripts/check_agent_version.py (aussi bloquant en CI), et le badge agent du README à la racine + documentation/README.md. Voir aussi cli/README.md pour la carte du package CLI et documentation/release-versioning.md.
3. Rédiger une section dans CHANGELOG.md (ce repertoire) : date, intitulé des correctifs / fonctionnalités , ligne pip install rivex-agent==... en bas de section si publie sur PyPI.

Composant PMEs : s installe sur chaque machine (serveur Linux ou poste Windows) pour alimenter le score de securite en temps reel du dashboard.

Installation

A. Via PyPI (recommande pour developpeurs / tests)

pip install rivex-agent
rivex-agent --version

B. Installation systeme (service au demarrage)

Linux (root requis) :

pip install rivex-agent
sudo rivex-agent --install
# => /opt/rivex-agent/ + systemd unit + symlink /usr/local/bin/rivex-agent
sudo systemctl status rivex-agent

Windows (admin requis) :

pip install rivex-agent
rivex-agent --install            # UAC prompt automatique
Get-Service RivexAgent

C. Binaire autonome (sans Python)

Telecharger depuis le dashboard Rivex ou la page releases :

• Linux : rivex-agent-linux-x86_64
• Windows : rivex-agent-windows-x86_64.exe

Binaires PyInstaller sans dependance externe. Fonctionnement identique a la version pip.

Les dependances (psutil, cryptography) sont embarquees : un binaire ne lance jamais pip, ni au demarrage ni apres --update (aucun lock requirements-*.lock a cote de l'executable, et sans lock l'agent n'installe aucune dependance).

D. Mode portable (developpement)

git clone https://gitlab.securechat.fr/esgi/4a/pa4a/pa4a
cd pa4a/src/agent
python agent_launcher.py --version

Tous les modes partagent la meme CLI. Seuls les chemins de config / logs different (voir "Chemins" ci-dessous).

Commandes principales

Sur Linux, la page de manuel installée est disponible via man rivex-agent (alias man agent_launcher.py).

Statuts sur le serveur (admin)

Si l administrateur suspend l agent, la sync echoue en 403 tant que l agent n est pas reactive ; le token local reste valide. En cas de revocation, le serveur regenere le token : rivex-agent --enroll --enroll_key avec la cle de la fiche machine (saisie explicite en CLI si l agent est en statut local revoked). Voir documentation/agent/etat-cote-serveur.md (depot) et la doc serveur.

Enrôlement depuis le dashboard (admin)

Admin → Téléchargements : bouton « Générer une clé et préparer les commandes » produit des one-liners (PyPI, binaire Linux, PowerShell Windows) qui enchaînent l'installation et --enroll --url <serveur> --enroll_key <clé>. Seuls le commentaire (--c) et les tags (--tag) restent à saisir interactivement.

Si l'admin active Lynis + installation à l'enrôlement (Admin → Réglages), le serveur renvoie platform_policy au register et l'agent installe Lynis sur Unix (best-effort, root requis).

Canal socket temps reel (v0.9.0+)

Depuis la v0.9.0, l agent maintient un canal TCP+TLS persistant vers le socket-server du backend. Les commandes (scan, sync, patch, reboot...) arrivent en push instantane (latence < 50 ms) au lieu d attendre le pull HTTP.

• Configuration : section socket de config.json ; host vide => derive automatiquement de server_url (meme hote que l API HTTP, port socket dedie, valeur par defaut possible depuis agent/version.json).
• Authentification : trame HELLO signee avec la cle d'appareil Ed25519 (device.key, generee a l'enrolement) et repli HMAC avec le agent_token (meme schema que les requetes HTTP signees, methode SOCKET / chemin /hello, horodatage + nonce anti-rejeu). Detail : documentation/serveur/socket-protocole.md.
• TLS : le certificat serveur du listener est signe par une sous-CA socket (pas la racine PKI). Le PEM d ancrage (socket-ca.pem) est servi en HTTPS sous /agent/ ; l agent le telecharge et installe automatiquement apres install (si server_url est deja dans le template), apres enrôlement, lors des --update et au demarrage du service si l empreinte SHA256 annoncee dans agent/version.json change. config.socket.ca_path pointe vers une copie locale (ex. /etc/rivex-agent/socket-ca.pem en installation Linux). Si vide et sans fichier installe : truststore OS (souvent insuffisant pour un cert interne).
• Reconnexion : automatique, backoff exponentiel borne + jitter (plafond config.socket.max_backoff_seconds, defaut 60 s).
• Fallback HTTP : si la socket est indisponible, le pull HTTP /api/agent/commands/pull reste actif. Aucune intervention requise.
• Pare-feu sortant (Linux / UFW) : le port utilisé pour la règle ufw allow out <port>/tcp est d’abord celui annoncé dans agent/version.json (socket_port), puis config.socket.port (resolve_effective_socket_port). Après --install, post-enrôlement et --update (agent enrôlé), l’agent tente d’activer UFW si besoin (règle SSH entrant requise avant ufw --force enable), puis d’appliquer la règle et ufw reload. Idem après close_port / ufw deny en remédiation. Avec --install_system_deps, si le paquet ufw est installé, tentative d’activation renvoyée dans le JSON (ufw_enable).
• Apres --update (Linux, installation systemd officielle) : tentative de systemctl restart rivex-agent.service pour recharger le processus.

{
  "socket": {
    "enabled": true,
    "host": "",
    "port": 8443,
    "ca_path": "/etc/rivex-agent/socket-ca.pem",
    "insecure": false,
    "use_tls": true,
    "max_backoff_seconds": 60
  }
}

Elevation automatique

Les actions --install, --uninstall, --service-run, --patch, --install_system_deps, --update, --set_scan_interval, --enable_auto_scan, --disable_auto_scan declenchent une elevation automatique :

• Linux : re-exec via sudo env RIVEX_AGENT_ELEVATED_REEXEC=1 … (volontairement sans -E : environnement contrôlé)
• Windows : UAC prompt via ShellExecuteW runas

Si deja admin, aucune invite n apparait. Avec RIVEX_AGENT_INSTALL_ROOT / RIVEX_AGENT_DATA_ROOT definies, pas de relance (stage: elevation) : ni sudo ni l UAC ne transmettent ces variables, lancer la commande directement en root ou depuis une console administrateur.

Chemins

Compatibilite

• Python 3.9.2 - 3.13 (plancher des dependances verrouillees ; binaires sans Python)
• Linux : Debian / Ubuntu / RHEL / Fedora / Arch (detection auto du gestionnaire de paquets avec priorite apt-get > yum > pacman > dnf)
• Windows : 10 / 11 / Server 2016+

Mise a jour automatique (--update)

--update telecharge et applique la derniere version selon le mode d installation (pip / binaire PyInstaller / portable). Prerequis :

• Version plancher : la MAJ auto fonctionne depuis 0.9.6 (installations pip) et 0.10.1 (binaires ; 0.11.2 minimum sous Windows a cause du verrou de service). Un binaire installe avant 0.10.1 embarque l ancien updater et doit etre remplace une fois manuellement. Les versions 0.12.0+ sont a jour cote code.
• Cote serveur : les artefacts (tarball, binaires) et leurs empreintes .sha256 doivent etre publies dans agent/ (servis par le dashboard). Un binaire sans SHA-256 verifiable est refuse (securite). Utiliser le script de release : python src/agent/scripts/build_release.py [--binaries-dir dist/] (les binaires PyInstaller se generent sur une machine dediee Windows/Linux ; un binaire absent de --binaries-dir n'a ni URL ni empreinte dans le manifeste, et un binaire gele n'accepte que l'empreinte du manifeste signe).
• Signature du manifeste : update.require_signature vaut true par defaut. Depuis 0.40.0 l'agent embarque la cle publique de release (core/release_trust.EMBEDDED_RELEASE_PUBLIC_KEYS) et la CI signe version.json et manifests/<version>.json (variable RIVEX_RELEASE_KEY_B64) ; un manifeste non signe ou signe par une autre cle est refuse (manifest_signature_no_signature, manifest_signature_invalid_signature). Un agent 0.39 n'embarque aucune cle et ne passe pas seul en 0.40 : voir documentation/agent/mise-a-jour.md §6. Cle de release (mise en place, rotation, release manuelle) : documentation/securite-agent-serveur.md §4.

Support

Documentation : documentation/agent/ (installation, collecte, commandes distantes, mise a jour, integrite) — _agent_explication.md est le manuel historique « Stage 1 », conserve pour reference mais plus a jour. Changelog : CHANGELOG.md. Issues / support : https://gitlab.securechat.fr/esgi/4a/pa4a/pa4a/-/issues