rivex-agent 0.19.3

Rivex security posture collection agent (cross-platform)

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 et changelog (obligatoire a chaque changement de code)

1. Choisir le prochain numéro (souvent +1 sur le patch : 0.7.x).
2. Mettre a jour : agent_launcher.py (APP_VERSION), pyproject.toml, config.json (défaut), core/config_manager.py si c’est la source du défaut de version, test/unit/test_protection.py (payload d’exemple) si la version y figure, src/server/frontend/public/agent/version.json (téléchargement dashboard), badge agent dans le README a la racine du depot.
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.

Apres --update, l'installation des paquets listes dans requirements-linux.txt / requirements-windows.txt utilise python3 (ou python) du PATH, car le binaire n'est pas un interpreteur Python. En cas d'echec ou d'absence sur le PATH, definir RIVEX_PIP_PYTHON=/usr/bin/python3 (ou equivalent).

D. Mode portable (developpement)

git clone https://gitlab.com/rivex/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

Commande	Description
rivex-agent --enroll --url https://rivex.example.com --enroll_key <CLE> --c "srv-prod"	Enregistre une machine (cle admin ou fiche machine)
rivex-agent --enroll --url https://rivex.example.com --enroll_key <CLE>	Raccourci : --enroll_key seul declenche l'enrôlement (URL/commentaire/tag demandes si absents)
rivex-agent --scan	Effectue un scan complet et envoie le payload
rivex-agent --sync	Synchronise l etat avec le serveur
rivex-agent --status	Affiche l etat local
rivex-agent --diagnostic	Rapport complet (config, log, deps systeme, etc.)
rivex-agent --install	Installe comme service systeme (root/admin)
rivex-agent --uninstall [--purge]	Retire l installation
rivex-agent --install_status	Etat de l installation (JSON)
rivex-agent --check_system_deps	Audit des outils OS requis
rivex-agent --install_system_deps	Installe les outils OS manquants
rivex-agent --check_protection	Verifie l integrite des fichiers critiques
rivex-agent --patch <source>	Applique un patch de remediation (file / URL)
rivex-agent --propose-update	Verifie une MAJ et notifie (sans appliquer) ; propose l'installation si lance en session root interactive. Le mode service execute cette sonde a chaque demarrage.
rivex-agent --help	Aide complete groupee par categorie
rivex-agent -v / --version	Affiche la version de l agent (build / APP_VERSION)

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 HMAC avec le agent_token (meme schema que les requetes HTTP signees, methode SOCKET / chemin /hello).
• 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 -E
• Windows : UAC prompt via ShellExecuteW runas

Si deja admin, aucune invite n apparait.

Chemins

Mode	Config	Runtime	Logs
Portable	.runtime/config.json	.runtime/	.runtime/logs/
Installe Linux	/etc/rivex-agent/config.json (seed) + /var/lib/rivex-agent/.runtime/config.json (live)	/var/lib/rivex-agent/.runtime/	/var/log/rivex-agent/
Installe Windows	%ProgramData%\Rivex\Agent\config.json (seed) + .runtime\config.json (live)	%ProgramData%\Rivex\Agent\.runtime\	%ProgramData%\Rivex\Agent\logs\

Compatibilite

• Python 3.9 - 3.12
• 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).

Support

Documentation complete : _agent_explication.md (FR). Changelog : CHANGELOG.md. Issues / support : https://gitlab.com/rivex/pa4a/-/issues