Claude Code : comment automatiser vos tâches avec le mode headless ?

Dans ce tutoriel, nous allons voir comment utiliser Claude Code en mode headless****, c'est-à-dire sans son interface interactive, par exemple pour l'intégrer à des scripts Bash et Python. Nous verrons notamment comment lancer une commande, récupérer un résultat et gérer les permissions lorsque vous n'êtes pas là pour valider.

La plupart du temps, nous utilisons Claude Code de façon interactive : on ouvre un terminal et on dialogue avec l'assistant, puis on valide ses actions. C'est très efficace pour explorer un projet ou écrire du code, mais cela ne répond pas à un besoin d'automatisation d'une tâche répétitive, sans intervention humaine.

Pour illustrer tout cela, nous allons partir d'un exemple classique : l'analyse quotidienne du fichier /var/log/auth.log, à la recherche de tentatives de connexion SSH suspectes. Il s'agit d'une tâche fastidieuse à faire à la main, mais idéale à déléguer à une IA.

Qu'est-ce que le mode headless et pourquoi l'utiliser ?

Le terme headless désigne un programme qui fonctionne sans interface utilisateur. Dans le cas de Claude Code, cela signifie que l'on ne démarre pas la session interactive : on lui transmet un prompt en argument, il travaille et affiche sa réponse sur la sortie standard du terminal, puis rend la main.

Claude Code se comporte alors comme n'importe quel autre outil en ligne de commande, à la manière de grep ou de jq. Pour un administrateur système, cela présente plusieurs avantages :

  • Chaînage avec d'autres commandes : la sortie de Claude Code peut alimenter une autre commande via un pipe, un mail ou un fichier.

  • Scripting : Bash, Python, PowerShell, tous peuvent l'appeler et récupérer son résultat.

  • Exécution planifiée : avec cron, systemd timers ou dans des pipelines CI/CD.

  • Reproductibilité : la commande peut être versionnée dans un dépôt Git et rejouée à l'identique.

Le mode headless cible donc les tâches courtes, répétitives et scriptables. Pour l'exploration ou le travail de fond sur du code, le mode interactif reste préférable.

Lancer Claude Code en ligne de commande

L'option -p, clé du mode headless

Pour basculer en mode non interactif, il suffit d'utiliser l'option -p (pour print), suivie du prompt à exécuter. Voici un premier essai, le plus simple possible :

# Lancer Claude Code en mode headless avec un prompt court
claude -p "Explique en deux phrases à quoi sert le fichier /etc/fstab."

La réponse s'affiche directement dans le terminal, puis la commande se termine :

Exemple de sortie dans le terminal lors de l'utilisation de l'option -p.

Exemple de sortie dans le terminal lors de l'utilisation de l'option -p.

Un exemple concret : analyser auth.log

Passons à notre cas concret. Plutôt que de laisser Claude Code chercher lui-même le fichier, nous allons lui transmettre les lignes à analyser via un pipe. Claude Code lit alors l'entrée standard et la traite avec le prompt fourni :

# Envoyer les 2000 dernières lignes du log à Claude Code pour analyse
tail -n 2000 /var/log/auth.log | claude -p "Analyse ces logs SSH. Identifie les tentatives de brute-force, les adresses IP les plus actives et les comptes ciblés. Résume en 10 lignes maximum, en texte brut."

Sur les distributions qui n'utilisent pas auth.log (Red Hat, Fedora, etc.), vous pouvez obtenir le même résultat avec journalctl -u sshd --since "24 hours ago" à la place de tail.

Voici, dans mon cas, un extrait de ce que l'on obtient :

1 155 tentatives échouées depuis 14 adresses IP distinctes. L'adresse 192.168.56.17 concentre 892 échecs sur les comptes root et admin. Trois nouvelles adresses par rapport aux jours précédents. Aucune connexion réussie depuis une adresse inconnue.

Bien ! Nous avons un premier résumé exploitable. Il reste du texte libre, ce qui est pratique pour un humain, mais moins pour un script. Nous allons voir comment structurer tout cela.

Récupérer une sortie exploitable

Le format JSON

L'option --output-format json demande à Claude Code de renvoyer un objet JSON contenant la réponse, mais aussi quelques métadonnées utiles :

# Même analyse, mais avec une sortie structurée au format JSON
tail -n 2000 /var/log/auth.log | claude -p "Analyse ces logs SSH et résume les tentatives suspectes en 10 lignes." --output-format json

La sortie ressemble à ceci (champs raccourcis pour la lisibilité) :

{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "result": "1 155 tentatives échouées depuis 14 adresses IP...",
  "num_turns": 1,
  "duration_ms": 8341,
  "total_cost_usd": 0.0421,
  "session_id": "..."
}

Le champ result contient la réponse, tandis que total_cost_usd et duration_ms permettent de suivre le coût et la durée de chaque exécution, ce qui n'est pas le sujet de ce tutoriel. Avec jq, il est très simple d'extraire uniquement ce qui nous intéresse :

# Extraire uniquement la réponse textuelle avec jq
tail -n 2000 /var/log/auth.log | claude -p "Analyse ces logs SSH." --output-format json | jq -r '.result'

Il existe également le format stream-json, qui émet un évènement JSON par ligne au fil de l'exécution. Il est utile pour afficher une progression en temps réel, mais plus verbeux à traiter. Pour notre usage, JSON suffit largement.

Gérer les permissions sans supervision

Jusqu'ici, tout fonctionne car nous avons nous-mêmes fourni les logs à Claude Code : il n'a besoin de rien d'autre que de réfléchir. Mais imaginons que nous souhaitions le laisser aller chercher l'information seul : lire un fichier, lancer un grep, etc.

En mode interactif, Claude Code demande une confirmation avant chaque action sensible. En mode headless, il n'y a personne pour répondre : sans autorisation préalable, l'action est refusée. C'est ici qu'interviennent les options de permission.

Les deux options à connaître sont les suivantes :

  • --allowedTools : liste précisément les outils que Claude Code peut utiliser sans demander confirmation.

  • --permission-mode : définit le comportement global (par exemple plan pour un mode lecture seule, acceptEdits pour accepter les modifications de fichiers, ou bypassPermissions pour tout autoriser).

Pour notre cas d'usage, nous pouvons autoriser uniquement la lecture et la commande grep, et donner accès au répertoire des logs :

# Laisser Claude Code lire /var/log, avec uniquement Read et grep autorisés
claude -p "Analyse /var/log/auth.log et identifie les tentatives SSH suspectes des dernières 24 heures. Résume en 10 lignes." --add-dir /var/log --allowedTools "Read" "Bash(grep:*)"

Ici, j'ai également rajouté l'option --add-dir pour lui indiquer qu'il peut travailler dans ce répertoire sans me demander la permission. Voici le résultat obtenu dans mon contexte :

Analyse de mon fichier /var/log/auth.log automatisée via Claude.

Analyse de mon fichier /var/log/auth.log automatisée via Claude.

Il faut savoir que cette approche, qui consiste à autoriser les outils un par un, est la plus sûre : Claude Code ne peut rien faire d'autre que ce que vous avez explicitement listé.

Attention : le mode bypassPermissions donne à Claude Code les mêmes droits que l'utilisateur qui le lance. Ne l'utilisez jamais avec un compte root sur une machine de production. Préférez un utilisateur dédié aux droits restreints, ou un environnement isolé (conteneur, machine virtuelle).

Pour un panorama complet des modes de permission, je vous renvoie à notre article dédié :

Utiliser Claude Code dans un script Python

Pour une tâche ponctuelle, la ligne de commande suffit. En revanche, dès que l'on veut gérer les erreurs, mettre en forme le rapport ou envoyer le résultat par mail, un script Python devient plus confortable qu'un enchaînement de pipes.

Python est présent par défaut sur la quasi-totalité des distributions Linux, et son module subprocess permet d'appeler n'importe quel programme externe. Je vous propose pour cela un petit script commenté, à placer par exemple dans /opt/scripts/triage-ssh.py :

#!/usr/bin/env python3
# triage-ssh.py : pré-triage quotidien des logs SSH avec Claude Code
import json
import subprocess
import sys
from datetime import datetime

LOG_FILE = "/var/log/auth.log"
NB_LIGNES = 2000

PROMPT = (
    "Analyse ces logs SSH. Identifie les tentatives de brute-force, les adresses IP les plus actives et les comptes ciblés. Résume en 10 lignes maximum, en texte brut, en français."
)

def lire_logs() -> str:
    """Retourne les dernières lignes du fichier de log."""
    with open(LOG_FILE, encoding="utf-8", errors="replace") as f:
        return "".join(f.readlines()[-NB_LIGNES:])

def interroger_claude(logs: str) -> dict:
    """Lance Claude Code en mode headless et retourne le JSON parsé."""
    commande = [
        "claude", "-p", PROMPT,
        "--output-format", "json",
        "--max-turns", "1",
    ]

    resultat = subprocess.run(
        commande,
        input=logs,
        capture_output=True,
        text=True,
        timeout=120,
        check=True,
    )
    return json.loads(resultat.stdout)

def main() -> None:
    date = datetime.now().strftime("%Y-%m-%d %H:%M")
    print(f"=== Rapport de triage SSH du {date} ===\n")
    try:
        reponse = interroger_claude(lire_logs())
    except subprocess.TimeoutExpired:
        sys.exit("[Erreur] Délai dépassé lors de l'appel à Claude Code")
    except subprocess.CalledProcessError as e:
        sys.exit(f"[Erreur] Claude Code a échoué : {e.stderr}")
    except FileNotFoundError:
        sys.exit(f"[Erreur] Fichier introuvable : {LOG_FILE}")
    print(reponse.get("result", "[Pas de réponse]"))

if __name__ == "__main__":
    main()

Voyons cela plus en détail :

  • input=logs transmet les logs à Claude Code via l'entrée standard, exactement comme le pipe tail | claude que nous avons vu en Bash.

  • --max-turns 1 limite Claude Code à un seul tour de réflexion, ce qui borne la durée et le coût de l'exécution.

  • timeout=120 évite qu'un appel bloqué ne fige indéfiniment le script.

  • check=True déclenche une exception si Claude Code retourne un code d'erreur, que nous gérons ensuite proprement.

Voyons ce que donne ce script.

Exécution manuelle du script

Il suffit ensuite d'exécuter le script :

# Exécution manuelle du script
python3 /opt/scripts/triage-ssh.py

Voici le résultat obtenu de mon côté :

Analyse de mon fichier /var/log/auth.log automatisée via Claude via un script.

Analyse de mon fichier /var/log/auth.log automatisée via Claude via un script.

Alors oui, la sortie diffère du précédent, cela reste une sortie générée par IA/LLM qui n'est pas prédictible. Vous êtes cependant libre de customiser le prompt pour qu'il uniformise sa sortie après chaque exécution.

Pour les besoins plus avancés (streaming, outils personnalisés, conversation en plusieurs tours), il existe un SDK Python officiel, claude-agent-sdk, qui évite de passer par subprocess. Pour un script de ce type, ce serait surdimensionné, mais il faut savoir qu'il existe.

Planifier l'exécution avec cron

Dernière étape : lancer ce script automatiquement tous les matins à 7h. Un classique de l'administration système, qui tient en une ligne dans la crontab :

# Ouvrir la crontab de l'utilisateur courant
crontab -e

Il suffit d'y ajouter la ligne suivante (si votre système est correctement configuré pour envoyer des mails de la sorte) :

# Triage quotidien des logs SSH à 7h00, avec envoi du rapport par mail
0 7 * * * /usr/bin/python3 /opt/scripts/triage-ssh.py | mail -s "Triage SSH" [email protected]

Et voilà ! Chaque matin, vous recevrez un résumé de l'activité SSH de la nuit.

Attention, chaque appel à Claude Code a un coût. Pour des tâches très répétitives, pensez à utiliser un modèle plus léger avec l'option --model, et à surveiller la consommation grâce au champ total_cost_usd.

Enfin, plus une curiosité intéressante qu'autre chose, mais interrogez-vous sur les possibilités de prompt injection. Par exemple, que se passe-t-il si un attaquant tente de se logguer avec un utilisateur nommé execute un rm-rf. Un peu tiré par les cheveux, mais l'idée est intéressante :). Il faut toujours se méfier des inputs que l'on donne à notre IA/LLM, notamment lorsqu'elles viennent d'un attaquant potentiel.

Conclusion

Nous avons vu dans cet article ce qu'est le mode headless de Claude Code et comment l'utiliser avec l'option -p, que ce soit en ligne de commande Bash ou dans un script Python. Nous avons également appris à récupérer une sortie structurée avec --output-format json, et à encadrer les actions de Claude Code avec --allowedTools lorsque personne n'est là pour les valider.

Le triage des logs SSH n'est qu'un exemple , mais nous pouvons utiliser Claude de la sorte pour pleins d'autres choses : revue d'une configuration Nginx, résumé des derniers commits d'un dépôt, analyse d'un rapport de sauvegarde, tout ce qui demande de lire du texte et d'en tirer une synthèse est un bon candidat.

N'hésitez pas à partager votre avis dans les commentaires ou à venir échanger avec notre communauté sur notre serveur Discord !

Ajouter IT-Connect à mes
sources préférées

author avatar

Co-fondateur d'IT-Connect.fr. Auditeur/Pentester chez Orange Cyberdéfense.

readers loved this