Canarytokens dockerisés

par Thinkst Applied Research

Aperçu

Les Canarytokens aident à suivre l'activité et les actions sur votre réseau.

Si vous rencontrez des problèmes, consultez notre FAQ ici, ou créez une issue et nous essaierons de vous répondre dès que possible.

Table des matières

Code de conduite
Prérequis
Migration vers v3
Installation (sous Ubuntu)
Persistance des données
Comment activer HTTPS
Activer l'authentification de base sur votre site Canarytokens
Quoi de neuf ?
FAQ
Contribuer

Code de conduite

Ce projet et toutes les personnes qui y participent sont régis par le Code de conduite. En participant, vous vous engagez à respecter ce code. Veuillez signaler tout comportement inacceptable à [email protected].

Prérequis

Au moins un nom de domaine. Si vous souhaitez activer le suivi d'ouverture des PDF, au moins deux domaines.
Un hôte Docker accessible depuis Internet. Vous pouvez installer Docker sur un hôte Linux rapidement.

Migration vers v3

Selon que vous utilisez letsencrypt ou non : docker compose -f docker-compose.yml down ou docker compose -f docker-compose-letsencrypt.yml down
Si vous utilisez une version plus ancienne de Docker, vous devrez mettre à niveau.
docker-compose ne fonctionne plus, et vous devrez exécuter docker network prune avant de démarrer votre instance Canarytokens avec docker compose. Canarytokens v2 fonctionnera toujours.
Récupérez la dernière version du dépôt canarytokens-docker.
Et en conséquence : docker compose -f docker-compose.yml up -d ou docker compose -f docker-compose-letsencrypt.yml up -d

NB : Le dépôt canarytokens-docker mis à jour ne contient plus le Dockerfile pour Canarytokens v2, son exécution nécessite donc d'utiliser l'image taguée thinkst/canarytokens:v2_latest. Nous recommandons vivement de passer à v3. Veuillez nous contacter si vous rencontrez des difficultés avec la migration.

Installation (sous Ubuntu)

Démarrez votre hôte Docker et notez l'IP publique.
Configurez vos domaines pour que leurs serveurs de noms pointent vers l'IP publique de l'hôte Docker. Cela nécessite une modification chez votre bureau d'enregistrement. Le simple changement des enregistrements NS dans le fichier de zone ne suffit pas. Vous aurez besoin d'un enregistrement A de votre domaine pointant vers votre IP publique.
Clonez la configuration Docker :

$ git clone https://github.com/thinkst/canarytokens-docker
$ cd canarytokens-docker

Installez Docker compose (s'il n'est pas déjà présent) :

$ sudo apt-get install python3-pip python3-dev
$ sudo pip install -U docker-compose
#if this breaks with PyYAML errors, install the libyaml development package
# sudo apt-get install libyaml-dev

Nous distribuons deux fichiers .env qui seront utilisés pour la configuration, à savoir switchboard.env.dist et frontend.env.dist. Vous devrez les copier/renommer en switchboard.env et frontend.env respectivement (cela garantit que votre configuration ne soit pas écrasée si vous récupérez des changements). Une fois cela fait, vous pouvez les modifier :

Veuillez parcourir vos deux fichiers de configuration nouvellement créés, switchboard.env et frontend.env, et remplir la section Required Settings. Les Optional Settings ne sont pas nécessaires au fonctionnement et ont des valeurs par défaut sensées, alors ne les modifiez pas si vous n'en avez pas besoin.
Ensuite, décidez du fournisseur de messagerie que vous souhaitez utiliser pour envoyer les alertes. Vous devrez choisir entre mailgun, SMTP et sendgrid. Les détails requis correspondants se trouvent dans le fichier .env pertinent.
Générez une seule graine de clé WireGuard unique à définir comme CANARY_WG_PRIVATE_KEY_SEED dans switchboard.env et frontend.env avec la commande :

dd bs=32 count=1 if=/dev/urandom 2>/dev/null | base64

Voici des exemples de fichiers pour une configuration qui utilise :
- les domaines example1.com, example2.com et example3.com (PDF) pour les déclencheurs de canarytoken via switchboard
- l'IP publique 1.1.1.1 pour les déclencheurs switchboard
- le domaine 'my.domain' pour servir le frontend
- le nom de domaine Mailgun 'x.y' et la clé API 'zzzzzzzzzz'
- la graine de clé WireGuard vk/GD+frlhve/hDTTSUvqpQ/WsQtioKAri0Rt5mg7dw=
- frontend.env

#These domains are used for general purpose tokens
CANARY_PUBLIC_IP=1.1.1.1
CANARY_DOMAINS=example1.com,example2.com

#These domains are only used for PDF tokens
CANARY_NXDOMAINS=example3.com

#Requires a Google Cloud API key to generate an incident map on the history page with the Maps JavaScript API
CANARY_GOOGLE_API_KEY=<grab google maps api key>
LOG_FILE=frontend.log

switchboard.env (Exemple utilisant Mailgun pour l'e-mail)

CANARY_PUBLIC_DOMAIN=mydomain.com
LOG_FILE=switchboard.log
CANARY_MAILGUN_DOMAIN_NAME=x.y
CANARY_MAILGUN_API_KEY=zzzzzzzzzz
[email protected]
CANARY_ALERT_EMAIL_FROM_DISPLAY="Example Canarytokens"
CANARY_ALERT_EMAIL_SUBJECT="Canarytoken"
CANARY_WG_PRIVATE_KEY_SEED=vk/GD+frlhve/hDTTSUvqpQ/WsQtioKAri0Rt5mg7dw=

Enfin, téléchargez et lancez les images :

$ docker compose up

Le front end et le switchboard fonctionneront alors au premier plan. Le front end est accessible à l'adresse http://example1.com/generate. Si vous souhaitez exécuter cela en arrière-plan, vous pouvez utiliser

$ docker compose up -d

NOTE : Si vous ne possédez qu'un seul domaine et souhaitez utiliser des jetons PDF, vous pouvez utiliser des sous-domaines pour CANARY_NXDOMAINS. En utilisant example.com comme domaine, vous pouvez définir CANARY_NXDOMAINS sur nx.example.com. Connectez-vous ensuite à la console de gestion de votre DNS (où vous pouvez modifier les enregistrements DNS de votre domaine) et ajoutez un enregistrement NS de nx.example.com pointant vers example.com.

Persistance des données

Les jetons sont enregistrés dans un fichier de base de données Redis situé en dehors des conteneurs Docker. Recherchez dump.rdb dans le répertoire canarytokens-docker/data.

Si vous souhaitez effacer tous vos jetons, supprimez dump.rdb.

Comment activer HTTPS

Nous avons un fichier docker-compose séparé qui automatisera (en grande partie) la mise en place et l'exécution d'un serveur Canarytokens avec HTTPS. Vous devrez faire ce qui suit :

Modifiez le fichier certbot.env. Vous devrez fournir votre domaine et votre adresse e-mail (ils sont nécessaires au processus d'enregistrement de certbot). Par ex.

# Specify a single domain name
MY_DOMAIN_NAME=example.com

# or multiple domains names with this different key (comment out MY_DOMAIN_NAME above if you do):
# MY_DOMAIN_NAMES=example.com anotherexample.net thirdexample.org

[email protected]

Désormais, lorsque vous voulez démarrer votre serveur, vous utiliserez docker compose -f docker-compose-letsencrypt.yml up, ce qui exécutera le serveur au premier plan afin que vous puissiez vous assurer que tout démarre correctement.
Si tout fonctionne, vous pouvez appuyer sur CTRL+C, exécuter docker compose -f docker-compose-letsencrypt.yml down pour repartir d'une page blanche, puis relancer docker compose -f docker-compose-letsencrypt.yml up -d avec l'option -d pour exécuter le serveur en arrière-plan (en mode démon)
Veuillez garder à l'esprit que l'utilisation de la méthode HTTPS utilisera l'e-mail que vous avez spécifié et le nom de domaine pour enregistrer le certificat. Vous pouvez en savoir plus sur le processus let's encrypt (en utilisant cerbot) ici. Le processus consiste à vérifier que vous êtes bien le propriétaire du domaine que vous avez spécifié et à vous enregistrer auprès de let's encrypt.
IL Y A UNE LIMITE DE DÉBIT. Ne montez et ne descendez donc pas ce serveur en continu, sinon vous atteindrez rapidement la limite de génération de certificats let's encrypt. Pour éviter cela, à des fins de test, vous pouvez ajouter --staging à la commande ./certbot-auto dans cerbot-nginx/start.sh, ce qui testera si let's encrypt vous délivre le certificat.

Activer l'authentification de base sur votre site Canarytokens

Vous pouvez suivre ces étapes si vous souhaitez disposer d'un site canarytokens public mais souhaitez une authentification de base pour y accéder.

git clone https://github.com/thinkst/canarytokens-docker.git
Accédez au dossier nginx :
- pour HTTP :
```
cd canarytokens-docker/nginx
```
- pour HTTPS :
```
cd canarytokens-docker/certbot-nginx
```
sudo htpasswd -c .htpasswd user où user peut être le nom d'utilisateur que vous souhaitez utiliser.
sudo chown <user>:<user> .htpasswd où user est l'utilisateur Linux local
modifiez le fichier nginx.conf approprié et

server {
    ...
    location ~* (/generate|/manage|/download|/history|/settings|/resources|/legal).* {
        auth_basic           "Basic Auth Restricted Canrytokens"; <---- ADD
        auth_basic_user_file /etc/nginx/.htpasswd;                 <---- ADD

modifiez le Dockerfile approprié et ajoutez sous COPY nginx.conf ...

COPY .htpasswd /etc/nginx/.htpasswd

reconstruisez les images en utilisant :
- pour HTTP :
```
docker compose build
```
- pour HTTPS :
```
docker compose -f docker-compose-letsencrypt.yml build
```

redémarrez vos conteneurs Docker, et profitez-en !

Merci, @mamisano d'avoir repéré un problème stupide en utilisant ce qui précède 🙏

Quoi de neuf ?

Nous allons suivre ici quelques nouvelles fonctionnalités/ajouts afin qu'il soit rapide et facile de voir ce qui a été récemment ajouté.

nous avons déplacé la section « What's new? » vers GitHub Discussions. Consultez-la ici.
nous avons désormais la possibilité d'envoyer les journaux d'erreurs vers un webhook de votre choix, vous alertant ainsi, vous ou votre équipe, des échecs, au lieu que ces erreurs ne vivent uniquement dans un fichier journal. Fournissez simplement l'URI du webhook correspondant dans la valeur ERROR_LOG_WEBHOOK de votre fichier switchboard.env. (2021-04-09)
nous avons renommé les fichiers .env distribués en switchboard.env.dist et frontend.env.dist. Cela garantit que votre configuration locale ne soit pas écrasée lorsque vous récupérez des changements depuis le dépôt. (Nous utilisons toujours switchboard.env et frontend.env pour la configuration, cela signifie simplement que les nouveaux clones du dépôt nécessitent que les utilisateurs copient/renomment les fichiers dist)
nous avons ajouté une variable switchboard.env supplémentaire appelée CANARY_IPINFO_API_KEY. Cela vous permet d'utiliser votre clé API ipinfo.io si vous le souhaitez (gardez à l'esprit que ipinfo.io offre un niveau gratuit allant jusqu'à 1000 requêtes par jour).
nous avons désormais le support de Slack. Lorsque vous fournissez un webhook, vous fournissez simplement l'URL de votre webhook Slack. (Merci à @shortstack).
nous avons ajouté une nouvelle variable d'environnement au fichier frontend.env appelée CANARY_AWSID_URL, qui vous permet de spécifier une URL privée ou différente pour le jeton AWS ID. Cela signifie que vous pouvez facilement changer de compte. (2018-10-17)
si vous avez l'intention de construire l'image pour l'exécuter sur un autre système avec une architecture différente, vous pouvez construire les images avec docker compose build --build-arg ARCH=<target arch>/, en notant la barre oblique à la fin de l'argument. L'image ne se construira pas correctement si cela n'est pas inclus.

FAQ

Nous avons une FAQ ici

Contribuer

Veuillez consulter nos documents Code de conduite et Contributing avant de soumettre une pull request.

Nous attendons avec impatience vos précieuses contributions.