Steampunk Spotter (5.12+) : analyse Ansible cloud, lint étendu, recommandations

Steampunk Spotter est un analyseur statique Ansible cloud développé par XLAB Steampunk (Slovénie) qui complète ansible-lint avec des règles que ce dernier n'a pas : compatibilité multi-versions Ansible, détection de modules dépréciés/renommés/déplacés entre collections, scoring de qualité, et récriture automatique d'anti-patterns courants. Le service est freemium (compte gratuit pour usage individuel, plans payants pour équipes/CI). Cette page documente la version 5.12.0 d'avril 2026, testée sur AlmaLinux 10.

Pressé ? Setup Spotter en 4 commandes

# 1. Installation via pipx (recommandé)
pipx install steampunk-spotter

# 2. Vérifier
spotter --version    # 5.12.0+

# 3. Créer un compte gratuit + récupérer le token
# https://app.spotter.steampunk.si/

# 4. Login + scan
export SPOTTER_TOKEN="<votre-token>"
spotter scan playbook.yml

Sécurité non négociable :

• Token API via variable d'environnement (SPOTTER_TOKEN) ou stocké dans un secret manager, JAMAIS en clair dans un script ou commit Git.
• pipx plutôt que pip --user, isolation Python, pas de pollution globale, mises à jour atomiques.
• Conscience du modèle cloud : Spotter envoie le contenu de vos playbooks à api.spotter.steampunk.si pour analyse. Sur du code propriétaire/classifié, vérifier la politique data de XLAB ou utiliser le mode --export-payload pour scan offline.
• Complément, pas remplaçant d'ansible-lint : la règle d'or est ansible-lint --profile production en CI bloquante + Spotter en analyse approfondie pré-merge.

Ce que vous allez apprendre

• Installer Spotter via pipx et l'authentifier (token vs user/password).
• Scanner un playbook, un rôle ou une collection, interpréter les résultats (HINT / WARNING / ERROR).
• Choisir le bon --display-level et --profile selon le contexte (dev / pre-merge / CI bloquante).
• Réécrire automatiquement certains anti-patterns avec --rewrite.
• Intégrer Spotter dans une CI GitHub Actions ou GitLab CI.
• Comparer Spotter à ansible-lint, quand préférer lequel.

Prérequis

Élément	Vérification
Python 3.10+	python3 --version
pipx installé	pipx --version
Compte Spotter (gratuit)	app.spotter.steampunk.si
Connectivité Internet sortante vers api.spotter.steampunk.si	curl -I https://api.spotter.steampunk.si/

Glissez pour voir

Installation et authentification

Installation via pipx

pipx install steampunk-spotter
spotter --version
# 5.12.0

L'install crée un binaire ~/.local/bin/spotter qui pointe vers le venv pipx isolé. Pas de pollution Python globale, mises à jour atomiques avec pipx upgrade steampunk-spotter.

Création du compte

Rendez-vous sur app.spotter.steampunk.si/register, créez un compte gratuit (validation email obligatoire). Le plan Community suffit pour un usage individuel : 100 scans/mois, 1 organisation, accès à la majorité des règles.

Authentification, 3 méthodes

# Méthode 1 : login interactif (génère un token côté serveur, le stocke localement)
spotter login
# → Username/Password ou Token

# Méthode 2 : variable d'environnement (recommandée pour CI/CD)
export SPOTTER_TOKEN="eyJhbGc..."
spotter scan playbook.yml

# Méthode 3 : flag CLI (debug ponctuel uniquement, jamais en production)
spotter scan -t "eyJhbGc..." playbook.yml

Récupérer un token : interface web → My Settings → API Tokens → New Token. Donnez un nom explicite (ci-github, laptop-bob) pour pouvoir révoquer ciblé plus tard.

Token Spotter = clé d'accès aux scans + résultats stockés

Un token Spotter compromis permet à l'attaquant de :

• Scanner du code arbitraire et le stocker dans votre historique
• Lire les résultats de tous vos scans précédents (potentiellement sensibles)
• Consommer votre quota mensuel

Stocker dans un secret manager (HashiCorp Vault, GitHub Secrets, GitLab CI variables masquées). Rotation périodique recommandée. Révocation immédiate si fuite.

Scanner un playbook

Scan basique

spotter scan playbook.yml

Sortie typique (texte coloré, niveaux HINT / WARNING / ERROR avec liens vers la doc) :

Check results:
playbook.yml:5:7: WARNING: [W1100] Use of with_items is discouraged. Consider using loop instead.
playbook.yml:5:7: HINT: [H1900] (rewritable) Required collection community.general is missing from requirements.yml.

Scan summary:
Spotter took 1.888 s to scan your input.
It resulted in 0 error(s), 1 warning(s) and 1 hint(s).
Can rewrite 1 file(s) with 1 change(s).
Overall status: WARNING

Chaque ligne suit le format <fichier>:<ligne>:<col>: <niveau>: [<id>] <message>. Les ID (W1100, H1900, E1300) sont stables et permettent de skip/enforce ciblé.

Scanner plusieurs cibles

# Plusieurs rôles ou collections d'un coup
spotter scan path/to/role1 path/to/role2 path/to/collection/

# Un répertoire entier (tous les .yml détectés)
spotter scan ansible-project/

Filtrer par niveau

# N'afficher que les ERROR (mode strict pour CI bloquante)
spotter scan --display-level error playbook.yml

# Afficher WARNING + ERROR (skip les hints en pre-merge)
spotter scan --display-level warning playbook.yml

Les 3 niveaux :

• HINT, suggestion (ex: pinning manquant, optimisation possible).
• WARNING, pratique discutable (ex: with_items legacy, state: latest).
• ERROR, bug ou faille (ex: module inexistant, paramètre obsolète, secret en clair).

Profils de scan

# Profil par défaut (équilibré)
spotter scan playbook.yml

# Profil sécurité (focus secrets, sudoers, no_log, supply chain)
spotter scan --profile security playbook.yml

# Profil complet (tous les checks, peut être verbeux)
spotter scan --profile full playbook.yml

Cibler une version Ansible précise

# Scanner contre Ansible 2.18 (pour valider compatibilité descendante)
spotter scan -a 2.18 playbook.yml

# Désactiver la détection auto (utile en CI sur runner sans Ansible)
spotter scan --no-ansible-version playbook.yml

L'option -a [2.0, 2.19] est puissante : Spotter détecte alors les modules/options qui n'existent pas encore dans cette version mineure. Idéal pour des collections publiées qui doivent supporter requires_ansible: ">=2.18".

Skip et enforce ciblés

# Désactiver des checks par ID (à justifier en commentaire YAML !)
spotter scan --skip-checks E1300,H1900 playbook.yml

# Forcer des checks même si désactivés par défaut
spotter scan --enforce-checks E001,W400 playbook.yml

Anti-pattern : skip systématique sans documenter le pourquoi. Préférer un commentaire # noqa: E1300 — légitime parce que ... à côté de la ligne fautive.

Réécriture automatique

spotter scan --rewrite playbook.yml

Spotter applique les fixes pour les checks marqués (rewritable) dans la sortie. Exemples typiques :

• with_items → loop:
• Modules legacy renommés (yum: → ansible.builtin.dnf:)
• FQCN incomplets (copy: → ansible.builtin.copy:)
• Ajout de community.general dans requirements.yml quand un module y appartient

Toujours git diff après --rewrite pour valider, l'auto-correction n'est jamais 100 % infaillible.

Configuration projet

Pour un projet partagé, créer un fichier de config réutilisable :

spotter config set ./spotter.yml
spotter config get          # affiche la config active
spotter config clear        # remet à zéro

Format spotter.yml (équivalent JSON disponible) :

ansible_version: "2.18"
display_level: warning
profile: security
skip_checks:
  - event: W003
    fqcn: ansible.builtin.uri
enforce_checks:
  - event: E005
    fqcn: community.crypto.x509_certificate

Avec ce fichier versionné dans le repo, toute l'équipe scanne avec les mêmes règles sans devoir mémoriser les flags CLI.

Intégration CI/CD

GitHub Actions (durci 2026)

# .github/workflows/ci.yml — extrait Spotter
name: CI

on: [push, pull_request]

permissions: {}

jobs:
  spotter-scan:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
        with:
          persist-credentials: false

      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5.6.0
        with:
          python-version: '3.12'

      - name: Install Spotter
        run: pipx install steampunk-spotter

      - name: Scan
        env:
          SPOTTER_TOKEN: ${{ secrets.SPOTTER_TOKEN }}
        run: |
          spotter scan \
            --origin ci \
            --display-level warning \
            --profile security \
            --sarif spotter.sarif \
            playbook.yml

      - uses: github/codeql-action/upload-sarif@<SHA40>
        if: always()
        with:
          sarif_file: spotter.sarif

Bonnes pratiques CI :

• --origin ci, Spotter taggue le scan comme provenant de CI (utile pour le filtrage côté UI).
• --sarif, export au format SARIF que GitHub Code Scanning consomme nativement (alertes inline sur la PR).
• Token via GitHub Secrets, jamais en clair dans le workflow.
• Pinning par SHA des actions (zizmor compliant).

GitLab CI

# .gitlab-ci.yml — extrait
spotter-scan:
  stage: lint
  image: python:3.12-slim
  variables:
    SPOTTER_TOKEN: $SPOTTER_TOKEN_MASKED  # variable masquée GitLab
  script:
    - pip install steampunk-spotter
    - spotter scan --origin ci --display-level warning playbook.yml
  only:
    - merge_requests

Spotter vs ansible-lint, comment choisir

Critère	ansible-lint	Spotter
Modèle	CLI local pure	Cloud (token requis)
Coût	Gratuit, open-source	Freemium
Règles	~100 règles (profile production)	~300+ règles
Multi-version Ansible	Pas natif	Natif (-a 2.18)
Modules renommés/déplacés	Limité	Excellent (BD à jour côté serveur)
Scoring qualité	Non	Oui (note globale par scan)
Auto-fix	--fix (basique)	--rewrite (étendu)
Historique scans	Non (chaque run isolé)	Oui (UI web)
Intégration GitHub Code Scanning	Via plugins	Natif (SARIF)
Confidentialité	Local 100 %	Code envoyé au cloud

Glissez pour voir

Stratégie recommandée 2026 :

1. ansible-lint --profile production dans la CI bloquante, base mandatory, gratuit, local.
2. Spotter en scan pre-merge sur des PR significatives, détecte ce qu'ansible-lint laisse passer.
3. Spotter --rewrite ponctuellement pour migration de masse (ex: collection renommée upstream).

Pièges fréquents

Symptôme	Cause	Fix
Error: you are not logged in!	Pas de token configuré	spotter login ou export SPOTTER_TOKEN=...
Scan lent (>10 s) sur petit playbook	Latence cloud	Préférer ansible-lint en dev, Spotter en CI/pre-merge
Quota mensuel atteint	Plan Community = 100 scans/mois	Upgrade ou réserver Spotter aux scans CI
Faux positifs H1900 collection missing	requirements.yml pas dans le path scanné	Scanner le dossier projet plutôt qu'un fichier isolé
ansible_version non détecté	Pas de ansible-core sur le runner CI	Forcer avec -a 2.18

Glissez pour voir

À retenir

• Spotter v5.12+ : analyseur Ansible cloud freemium, complète ansible-lint (multi-version, modules renommés, scoring).
• Installation pipx non négociable, pas de pollution Python globale.
• Token via env var/secret manager uniquement, jamais en clair.
• --profile security pour focus sécurité, --rewrite pour migration assistée.
• Stratégie 2026 : ansible-lint en CI bloquante (gratuit, local) + Spotter en pre-merge (détection avancée).
• Conscience cloud : Spotter envoie votre code à un service tiers, peser sur du code propriétaire.

Pour aller plus loin

Extension VS Code Ansible L'extension officielle Red Hat, autocomplétion FQCN, lint inline, snippets, Lightspeed AI

ansible-lint production profile Le linter de référence local, base mandatory en CI, gratuit, open-source

Pipeline CI Collections Pipeline GitHub Actions / GitLab CI durci 2026, intégrer ansible-lint + ansible-test sanity

Auditer un rôle Galaxy Avant d'installer un rôle tiers, l'auditer en 7 axes, sécurité supply chain

×

📖 Voir la documentation →