trailscraper : extraire des informations utiles d'AWS CloudTrail
Un outil de ligne de commande pour obtenir des informations précieuses sur AWS CloudTrail.
En bref
- De quoi s’agit-il ?
- Un outil en ligne de commande en Python pour filtrer les événements CloudTrail, télécharger des journaux et générer des politiques IAM à partir des enregistrements.
- À qui s’adresse-t-il ?
- trailscraper regroupe la sélection d'événements CloudTrail, le téléchargement de journaux et la génération de politiques IAM dans un seul outil en ligne de commande. Son README précise explicitement que les heuristiques derrière les actions IAM devinées ne couvrent pas nécessairement tous les cas particuliers d'AWS et invite les utilisateurs à ouvrir des issues ou des pull requests pour les cas manquants.
- Puis-je l’utiliser commercialement ?
- Oui. Apache-2.0 est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 1 jour.
- En quel langage est-il écrit ?
- Principalement Python, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 15 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
trailscraper est une boîte à outils pour CloudTrail et les politiques IAM
Le dépôt décrit trailscraper comme un outil en ligne de commande pour obtenir des informations précieuses d'AWS CloudTrail et comme une boîte à outils généraliste pour travailler avec les politiques IAM. Il est écrit en Python. Au moment des métadonnées du dépôt, il comptait 836 étoiles et 38 forks, 26 issues ouvertes et la branche par défaut master. Le README ne précise pas de date de publication pour la version actuelle ni de liste de mainteneurs au-delà du propriétaire du dépôt.
Installation via Homebrew, pip ou Docker
Le README documente trois méthodes d'installation. Sur macOS, `brew install trailscraper` installe l'outil. Avec pip, les prérequis sont Python 3.5 ou plus récent et pip lui-même, puis `pip install trailscraper`. Une commande Docker est également fournie : `docker run --rm --env-file <(env | grep AWS_) -v $HOME/.aws:/root/.aws ghcr.io/flosell/trailscraper:latest`. Selon le README, les versions à partir de 0.7.0 sont publiées sur le GitHub Container Registry, tandis que les versions plus anciennes restent sur DockerHub.
Sélectionner des événements depuis l'API CloudTrail ou des journaux locaux
La commande `select` filtre les événements CloudTrail et les affiche sous forme d'enregistrements JSON. Une forme documentée utilise `--use-cloudtrail-api` pour interroger directement l'API CloudTrail, avec des options comme `--filter-assumed-role-arn`, `--from` et `--to`. Une autre forme, sans `--use-cloudtrail-api`, recherche dans les journaux déjà téléchargés le même type de filtre. L'exemple de sortie du README montre des enregistrements contenant les champs `eventTime`, `eventSource` et `eventName`, mais il n'énumère pas toutes les options de filtre prises en charge.
Télécharger des journaux CloudTrail depuis S3
La commande `download` récupère les journaux CloudTrail depuis un bucket S3. Les options documentées incluent `--bucket`, `--account-id`, `--region`, `--from` et `--to`, avec la possibilité de passer plusieurs régions. Une note du README explique que les journaux des services globaux comme Route53, IAM, STS et CloudFront sont enregistrés dans `us-east-1`, donc les utilisateurs devraient inclure cette région lors du téléchargement s'ils veulent ces événements. Pour les trails organisationnels, le README montre une option `--org-id`.
Générer et étendre des politiques IAM
Deux commandes transforment les données CloudTrail en documents de politique IAM. `trailscraper generate` lit les enregistrements CloudTrail et produit une politique avec les champs `Statement`, `Action`, `Effect` et `Resource`, comme montré avec `gzcat some-records.json.gz | trailscraper generate`. `trailscraper guess` prend une politique existante et essaie d'ajouter des actions correspondantes potentiellement manquantes, car les journaux CloudTrail peuvent ne contenir qu'un sous-ensemble d'actions, comme des appels `Create` sans les actions `Delete` et `Update` correspondantes. La commande `guess` accepte aussi `--only Get` pour restreindre les actions devinées.
Limites connues et réponses de la FAQ
La FAQ traite de plusieurs cas particuliers. Si trailscraper manque des événements, le README suggère d'abord de vérifier que les journaux de `us-east-1` sont inclus, car certains services AWS globaux utilisent cette région. Il indique également que certaines actions générées peuvent ne pas être de véritables actions IAM, car il n'existe pas de bonne documentation lisible par machine pour mapper les événements CloudTrail aux actions IAM. trailscraper s'appuie donc sur des heuristiques qui ne couvrent probablement pas tous les cas spéciaux. Les utilisateurs sont invités à ouvrir une issue ou à soumettre une pull request pour les cas non couverts. Le README contient aussi une note sur Click et les erreurs d'environnement ASCII, recommandant des variables d'environnement de locale comme `LC_ALL=de_DE.utf-8` ou `LC_ALL=C.UTF-8`.
Lire les sorties avec le contexte IAM
TrailScraper ne se limite pas à afficher des événements CloudTrail : le README présente aussi des opérations pour explorer et réduire des politiques IAM. Cette association est utile pendant une revue d'accès, car l'événement observé et l'autorisation qui l'a rendu possible répondent à deux questions différentes. Une équipe peut commencer par l'installation documentée, fournir un profil AWS de lecture et conserver la sortie de la commande analysée. Le dépôt ne promet ni remédiation automatique ni décision de sécurité ; toute suppression ou modification de permission reste une action humaine à justifier.
Un outil à intégrer avec des garde-fous
La présence de variantes Homebrew, pip et d'une image ghcr.io/flosell/trailscraper:latest facilite l'essai, mais le tag latest n'offre pas le même contrôle qu'une version figée. Les credentials AWS montés depuis $HOME/.aws ou transmis par l'environnement doivent rester limités au compte et aux journaux nécessaires. Avant d'intégrer TrailScraper dans un job, comparez une même période CloudTrail, vérifiez les comptes et régions couverts, puis regardez si les politiques produites correspondent aux événements attendus. Ces contrôles portent sur trailscraper et ses entrées AWS, pas sur une garantie générale de conformité.
Conclusion éditoriale
trailscraper regroupe la sélection d'événements CloudTrail, le téléchargement de journaux et la génération de politiques IAM dans un seul outil en ligne de commande. Son README précise explicitement que les heuristiques derrière les actions IAM devinées ne couvrent pas nécessairement tous les cas particuliers d'AWS et invite les utilisateurs à ouvrir des issues ou des pull requests pour les cas manquants.
Notes de la communauté