Dans cette note, je souhaite décrire et expliquer comment j'intègre des sessions de terminal dans des documentations.

Convention mainstream que j'ai adoptée

Je suis la convention mainstream suivante pour représenter des sessions terminal (de type bash, zsh…) :

Première partie :

$ echo "Hello, world!"
Hello, world!

$ ls -l
total 0
-rw-r--r-- 1 user user 0 Feb 25 10:00 file.txt

Seconde partie :

$ sudo su
# systemctl restart nginx 
$ exit

$ uptime # Affiche l'uptime
uptime 10:00:00 up 1 day, 2:45, 1 user, load average: 0.15, 0.10, 0.05

Les lignes commençant par $ ou # indiquent les commandes saisies par l'utilisateur, tandis que les autres correspondent aux sorties du terminal.
Il m'arrive également d'ajouter des commentaires en fin de ligne à l'aide de # ….

Origine de cette convention ?

J'ai cherché à retracer l'origine de cette pratique et elle semble très ancienne, probablement adoptée dès les débuts d'Unix en 1971.
On retrouve cette syntaxe notamment dans le livre The Unix Programming Environment (pdf), publié en 1984.

---

Ne pas inclure de $ si un bloc ne contient aucune sortie de commande

La règle MD014 de Markdownlint aborde ce sujet :

MD014 - Dollar signs used before commands without showing output

Tags: code

Aliases: commands-show-output

This rule is triggered when there are code blocks showing shell commands to be typed, and the shell commands are preceded by dollar signs ($):

$ ls
$ cat foo
$ less bar

The dollar signs are unnecessary in the above situation, and should not be included:

ls
cat foo
less bar

However, an exception is made when there is a need to distinguish between typed commands and command output, as in the following example:

$ ls
foo bar
$ cat foo
Hello world
$ cat bar
baz

Rationale: it is easier to copy and paste and less noisy if the dollar signs are omitted when they are not needed. See https://cirosantilli.com/markdown-style-guide#dollar-signs-in-shell-code for more information.

source

Pendant un certain temps, j’ai suivi la recommandation de ne pas inclure de $ dans un bloc de commande lorsqu’il n’affiche aucune sortie.

Après quelques années, j’ai décidé de ne plus appliquer cette règle pour la raison suivante :

• Lorsque la documentation mélange des fichiers de configuration et des commandes sans $, j’ai du mal à distinguer ce qui doit être exécuté dans un terminal et ce qui relève de la configuration.

Pour éviter toute ambiguïté, j’ai adopté une approche radicale : toujours utiliser $ pour indiquer une commande à exécuter, même si le bloc ne contient pas de sortie.

Je n'aime pas les $ dans les blocs de commande, car que je ne peux pas copier / coller facilement !

Je comprends tout à fait cette remarque. Cependant, ces "screenshots" de session de terminal n'ont pas vocation à être copiées / collées en masse.
Ils ont avant tout une fonction explicative.
Ce sont des sortes de "screenshot".

Si j'éprouve le besoin de faire souvent des "copier / coller" d'exemples de session terminal, alors je considère que c'est le signe qu'un script "helper" serait plus approprié pour exécuter ce groupe de commandes d’un seul coup.

Par exemple, je peux remplacer ce contenu :

Ensure that the following prerequisites have been installed: mise and direnv, see instruction in ../README.md.

$ mise trust
$ mise install
$ scw version
Version    2.34.0

Par celui-ci (qui indique l'existence du script ./scripts/mise-install.sh) :

Ensure that the following prerequisites have been installed: mise and direnv, see instruction in ../README.md (or execute ./scripts/mise-install.sh).

$ mise trust
$ mise install
$ scw version
Version    2.34.0

Cela évite les copier-coller répétitifs tout en conservant la clarté de l’explication.

Cette note est aussi disponible au format vidéo : https://www.youtube.com/watch?v=J9jsd4m9YkQ.

De 2018 à 2023, j'utilisais l'outil "pass" (https://www.passwordstore.org/) couplé avec GNU Privacy Guard pour chiffrer et déchiffrer les secrets dans mes projets professionnels.

Bien que cette méthode fonctionnait, elle s'avérait laborieuse.
La procédure documentant l'installation, la création des clés et la configuration de gnupg était l'étape posant le plus de difficultés d'onboarding des développeurs sur ces projets.
Au feeling, je dirais que trois développeurs sur quatre bloquaient à cette étape.

En parallèle à cette méthode, j'ai essayé d'utiliser la cli de Bitwarden, mais l'expérience n'a pas été très concluante, principalement à cause de problèmes de latence lors de son exécution.

Aujourd'hui, j'ai exploré une nouvelle méthode basée sur age et son support natif des clés ssh.

Voici le repository Git du résultat de cette exploration : age-secret-skeleton.

Le résultat est très positif et je pense avoir trouvé ma nouvelle méthode de chiffrement des secrets dans mes projets 🙂.

Pour en savoir plus, vous pouvez à la fois suivre le README.md du repository et continuer la lecture de cette note.

Détail des fichiers du repository

.
├── .envrc
├── .gitignore
├── .mise.toml
├── README.md
├── scripts
│   ├── decrypt_secrets.sh
│   └── encrypt_secrets.sh
├── .secret
├── .secret.age
├── .secret.skel
└── ssh-keys
    ├── john-doe.pub
    └── stephane-klein.pub

• /.secret : fichier qui contient les secrets en clair. Ce fichier est ignoré par .gitignore afin qu'il ne soit pas présent dans le repository git
• /.secret.age : fichier qui contient le contenu du fichier .secret chiffré avec age. Ce fichier est ajouté au repository git.
• /ssh-keys/ : ce dossier contient les clés publiques ssh des personnes qui ont accès au contenu de .secret.age
• /scripts/decrypt_secrets.sh : permet de déchiffrer avec age le contenu de .secret.age et écrit le résultat en clair dans .secret
• /scripts/encrypt_secrets.sh : permet de chiffrer avec age le contenu de .secret vers .secret.age. Ce script doit être exécuté quand le contenu de .secret est modifié ou quand une nouvelle clé est ajoutée dans /ssh-keys/
• /.envrc : Dans ce skeleton, ce fichier charge uniquement les variables d'environnement présentes dans .secret mais dans un vrai projet, il permet de charger automatiquement des variables d'environnement qui ne sont pas des secrets.
• /.secret.skel : ce fichier contient l'exemple de contenu du fichier .secret, sans les secrets. Par exemple :

# You can either request these secrets from Stéphane Klein (contact@stephane-klein.info)
# or, if your public ssh key is present in `./ssh-keys/` use the ./scripts/decrypt_secrets.sh command
# which will automatically decrypt the .secret.age file to .secret

export POSTGRES_PASSWORD="..."
export SCW_SECRET_KEY="..."

Ce fichier n'est pas nécessaire au bon fonctionnement du workflow mais je le trouve utile pour :

• documenter le contenu de .secret aux personnes qui ont juste accès au dépôt Git
• permettre de review les modifications de .secret.skel dans des Merge Request.

Utilisation des clés ssh

L'un des avantages majeurs de age par rapport à pass + gnupg est son support natif des clés SSH pour chiffrer et déchiffrer les secrets.

Ainsi, je n'ai plus besoin de demander aux développeurs deux types de clés (SSH et gnupg) : une seule clé SSH suffit.

De plus, il me semble qu'un grand nombre de développeurs possèdent déjà une clé SSH, alors que je pense que gnupg reste une technologie bien moins répandue.

Détail d'implémentation des scripts

Vvoici le contenu de /scripts/encrypt_secrets.sh :

#!/usr/bin/env bash
set -e

cd "$(dirname "$0")/../"

# Prepare recipient arguments for age
recipient_args=()
for pubkey in ./ssh-keys/*.pub; do
    if [ -f "$pubkey" ]; then
        recipient_args+=("-R" "$pubkey")
    fi
done

# Execute age with all public keys
age "${recipient_args[@]}" -o .secret.age .secret

La boucle permet de passer toutes les clés ssh du dossier /ssh-keys/* en paramètre d' age.

Voici le contenu de /scripts/decrypt_secrets.sh :

#!/usr/bin/env bash
set -e

cd "$(dirname "$0")/../"

# Prepare identity arguments for age
identity_args=()
for key in ~/.ssh/id_*; do
    if [ -f "$key" ] && ! [[ "$key" == *.pub ]]; then
        identity_args+=("-i" "$key")
    fi
done

# Execute age with all identity files
age -d "${identity_args[@]}" -o .secret .secret.age

cat << EOF
Secret decrypted in .secret
Don't forget to run the command:

$ source .envrc
EOF

La boucle permet de passer en paramètre toutes les clés privées ssh du dossier ~/.ssh/ en espérant en trouver une qui correspond à une clé publique du dossier /ssh-keys/.

Plusieurs niveaux de sécurisation

Si je veux cloisonner les secrets en limitant leur accès à des groupes d'utilisateurs distincts, je peux utiliser des secrets différents selon l'environnement.

Par exemple :

.
├── production
│   ├── .secret.age
│   └── ssh-keys
└── sandbox
    ├── .secret.age
    └── ssh-keys

Cette structure me permet de donner à certains utilisateurs accès aux secrets de l'environnement sandbox, sans leur donner accès à ceux de production.

Aller plus loin avec par exemple Vault ?

Je pense qu'il est possible d'aller plus loin en matière de sécurité avec des solutions comme Vault, mais trouve que la méthode basée sur age reste plus simple à déployer dans une petite équipe.