Guide de développement de l'API Clue¶

Ce guide explique comment configurer un environnement de développement pour l'API Clue.

Prérequis¶

Avant de commencer, assurez-vous d'avoir les éléments suivants installés sur votre système :

Python 3.10, 3.11 ou 3.12 (3.12 recommandé)
Poetry pour la gestion des dépendances
Docker et Docker Compose pour les dépendances de test
Git

Configuration de l'environnement de développement¶

1. Cloner le dépôt¶

git clone https://github.com/CybercentreCanada/clue.git
cd clue/api

2. Installer Poetry¶

Si vous n'avez pas Poetry installé, suivez le guide d'installation officiel.

Vérifier l'installation de Poetry :

poetry --version

3. Configurer l'environnement Python¶

Configurer Poetry pour utiliser Python 3.12 (ou votre version préférée) :

poetry env use 3.12

Vérifier l'environnement :

poetry env info

4. Installer les dépendances¶

Installer toutes les dépendances, y compris les dépendances de développement et de test :

poetry install --all-extras --with test,dev,types

Cela installera :

Les dépendances principales
Les extras du serveur (Werkzeug, bcrypt, PyYAML, etc.)
Les dépendances de test (pytest, mypy, coverage, etc.)
Les dépendances de développement (pre-commit, ruff, etc.)
Les dépendances de vérification de type

5. Créer les répertoires et la configuration requis¶

Créer les répertoires nécessaires pour la configuration et les journaux de Clue :

sudo mkdir -p /etc/clue/conf/
sudo mkdir -p /etc/clue/lookups/
sudo mkdir -p /var/log/clue
sudo chmod a+rw /etc/clue/conf/
sudo chmod a+rw /etc/clue/lookups/
sudo chmod a+rw /var/log/clue

Copier les fichiers de configuration :

cp build_scripts/classification.yml /etc/clue/conf/classification.yml
cp test/unit/config.yml /etc/clue/conf/config.yml

6. Démarrer les dépendances de test¶

Démarrer les services requis (Redis et Keycloak) en utilisant Docker Compose :

cd dev
docker-compose up --build -d
cd ..

Attendre que les services soient en bonne santé :

poetry run python build_scripts/keycloak_health.py

Flux de travail de développement¶

Qualité du code et formatage¶

Le projet utilise plusieurs outils pour maintenir la qualité du code :

# Vérifier le formatage
poetry run ruff format clue --diff

# Appliquer le formatage
poetry run ruff format clue

# Exécuter les vérifications du linter
poetry run ruff check clue

# Corriger les problèmes auto-corrigeables
poetry run ruff check clue --fix

# Exécuter la vérification de type
poetry run type_check

# Exécuter tous les tests
poetry run test

Tester des fichiers ou des fonctions spécifiques¶

# Exécuter des fichiers de test spécifiques
poetry run pytest test/unit/test_specific_module.py

# Exécuter des fonctions de test spécifiques
poetry run pytest test/unit/test_specific_module.py::test_function_name

Démarrer le serveur de développement¶

Démarrer le serveur API Clue :

poetry run server

Le serveur démarrera et sera disponible sur le port configuré, généralement 5000 (vérifiez votre fichier config.yml et vos variables d'environnement pour les détails).

Tester les services d'enrichissement¶

Pour tester les connexions aux plugins depuis l'API centrale, vous devrez peut-être démarrer des serveurs de test supplémentaires :

# Terminal 1
poetry run flask --app test.utils.test_server run --no-reload --port 5008

# Terminal 2
poetry run flask --app test.utils.bad_server run --no-reload --port 5009

# Terminal 3
poetry run flask --app test.utils.slow_server run --no-reload --port 5010

# Terminal 4
poetry run flask --app test.utils.telemetry_server run --no-reload --port 5011

Structure du projet¶

api/
├── clue/              # Code principal de l'application
│   ├── api/           # Points de terminaison API
│   ├── cache/         # Utilitaires de mise en cache
│   ├── common/        # Utilitaires et aides communs
│   ├── constants/     # Constantes de l'application
│   ├── cronjobs/      # Tâches planifiées
│   ├── extensions/    # Extensions Flask
│   ├── helper/        # Modules d'aide
│   ├── models/        # Modèles de données
│   ├── plugin/        # Système de plugins
│   ├── remote/        # Intégrations de services distants
│   ├── security/      # Modules de sécurité
│   └── services/      # Logique métier des services
├── build_scripts/     # Scripts de construction et utilitaires
├── dev/               # Fichiers d'environnement de développement
├── docs/              # Documentation
├── scripts/           # Scripts utilitaires
└── test/              # Fichiers de test
    ├── integration/   # Tests d'intégration
    ├── unit/          # Tests unitaires
    └── utils/         # Utilitaires de test

Scripts Poetry disponibles¶

Le projet définit plusieurs scripts pratiques dans pyproject.toml :

poetry run server - Démarrer le serveur API Clue
poetry run test - Exécuter la suite de tests
poetry run type_check - Exécuter la vérification de type
poetry run coverage_report - Générer des rapports de couverture (doit être exécuté après test)
poetry run plugin - Gestion interactive des plugins

Configuration¶

Variables d'environnement¶

Les variables d'environnement suivantes peuvent remplacer les paramètres de configuration :

CLUE_CONFIG_PATH - Chemin vers le fichier de configuration principal (par défaut : /etc/clue/conf/config.yml)
CLUE_CLASSIFICATION_PATH - Chemin vers le fichier de classification (par défaut : /etc/clue/conf/classification.yml)
CLUE_PLUGIN_DIRECTORY - Chemin vers l'emplacement de stockage des extensions Clue vers l'API centrale (par défaut

/etc/clue/plugins)
CLUE_SESSION_COOKIE_SAMESITE - Définir l'attribut SameSite pour les cookies de session. Doit être Strict, Lax ou None pour la sécurité
CLUE_HSTS_MAX_AGE - Valeur max-age HTTP Strict Transport Security en secondes pour une sécurité HTTPS renforcée
FLASK_ENV - Environnement Flask (development/production)
FLASK_DEBUG - Activer le mode débogage Flask
REDIS_HOST - Remplacer le nom d'hôte Redis
REDIS_PORT - Remplacer le port Redis

Fichiers de configuration¶

Clue utilise deux fichiers de configuration principaux :

/etc/clue/conf/config.yml - Configuration principale de l'application
/etc/clue/conf/classification.yml - Configuration de la classification

Configuration principale (`config.yml`)¶

Le fichier de configuration principal définit tous les aspects du serveur API Clue. Voici les sections clés :

Configuration de l'API¶

api:
  # Paramètres de sécurité
  secret_key: "your-secret-key-here" # Clé secrète Flask pour les sessions
  session_duration: 3600 # Durée de la session en secondes (1 heure)
  validate_session_ip: true # Valider que l'IP de session correspond
  validate_session_useragent: true # Valider que l'agent utilisateur de session correspond
  validate_session_xsrf_token: true # Activer la validation du jeton XSRF

  # Débogage et audit
  debug: false # Activer le mode débogage Flask
  audit: true # Enregistrer les appels API pour l'audit

  # Découverte de service
  discover_url: null # URL de découverte de service optionnelle

  # Sources d'enrichissement externes
  external_sources: [] # Liste des services d'enrichissement externes

  # Cibles OAuth on Behalf (OBO)
  obo_targets: {} # Services vers lesquels Clue peut faire du OBO

Configuration de l'authentification¶

auth:
  # Authentification par clé API
  allow_apikeys: false # Activer l'authentification par clé API
  apikeys: # Carte des clés API aux identifiants d'utilisateur
    "api-key-1": "user1"
    "api-key-2": "user2"

  # Paramètres OAuth
  oauth:
    enabled: false # Activer l'authentification OAuth
    gravatar_enabled: false # Activer Gravatar pour les avatars d'utilisateur
    other_audiences: [] # Audiences JWT supplémentaires à accepter
    providers: {} # Configurations des fournisseurs OAuth

  # Authentification de compte de service
  service_account:
    enabled: false # Activer l'authentification de compte de service
    accounts: [] # Liste des informations d'identification de compte de service

  # Propagation de jeton
  propagate_clue_key: true # Inclure le jeton Clue dans les requêtes OBO

Configuration des services principaux¶

core:
  # Configuration Redis
  redis:
    host: "127.0.0.1" # Nom d'hôte du serveur Redis
    port: 6379 # Port du serveur Redis

  # Extensions à charger
  extensions: [] # Liste des extensions Clue à charger

  # Collecte de métriques
  metrics:
    export_interval: 5 # Intervalle d'exportation des métriques en secondes
    redis: # Instance Redis pour les métriques
      host: "127.0.0.1"
      port: 6379
    apm_server: # Surveillance des performances des applications
      server_url: null # URL du serveur APM
      token: null # Jeton d'authentification APM

Configuration de la journalisation¶

logging:
  # Niveaux de journalisation : DEBUG, INFO, WARNING, ERROR, CRITICAL, DISABLED
  log_level: "DEBUG" # Niveau de journalisation actuel

  # Destinations de sortie
  log_to_console: true # Enregistrer dans la console/stdout
  log_to_file: false # Enregistrer dans des fichiers
  log_to_syslog: false # Enregistrer sur le serveur syslog

  # Paramètres de journalisation de fichier
  log_directory: "/var/log/clue/" # Répertoire des fichiers journaux
  log_as_json: false # Utiliser le format JSON pour les journaux

  # Paramètres syslog
  syslog_host: "localhost" # Nom d'hôte du serveur syslog
  syslog_port: 514 # Port du serveur syslog

  # Surveillance de la santé
  heartbeat_file: null # Fichier à toucher pour les vérifications de santé
  export_interval: 5 # Intervalle de journalisation du compteur

Configuration de l'interface utilisateur¶

ui:
  cors_origins: [] # Origines CORS autorisées pour l'interface Web

Configuration de source externe¶

Lors de la configuration de sources d'enrichissement externes, chaque source prend en charge ces options :

api:
  external_sources:
    - name: "example-source" # Nom de source unique
      url: "https://api.example.com" # URL de l'API source
      classification: "TLP:CLEAR" # Niveau de classification minimum
      max_classification: "TLP:RED" # Niveau de classification maximum
      include_default: true # Inclure dans les requêtes par défaut
      production: false # Indicateur prêt pour la production
      default_timeout: 30 # Délai d'attente de requête en secondes
      built_in: true # Indicateur de source intégrée
      maintainer: "Admin <admin@example.com>" # Contact RFC-5322
      documentation_link: "https://docs.example.com" # URL de documentation
      datahub_link: "https://datahub.example.com" # Entrée DataHub
      obo_target: null # Nom de cible OBO

Configuration du fournisseur OAuth¶

Pour l'authentification OAuth, configurez les fournisseurs comme ceci :

auth:
  oauth:
    enabled: true
    providers:
      keycloak:
        client_id: "clue-api" # ID client OAuth
        client_secret: "your-client-secret" # Secret client OAuth
        audience: "clue-api" # Audience JWT
        scope: "openid profile email groups" # Portées OAuth
        jwks_uri: "https://auth.example.com/realms/clue/protocol/openid-connect/certs"
        access_token_url: "https://auth.example.com/realms/clue/protocol/openid-connect/token"
        authorize_url: "https://auth.example.com/realms/clue/protocol/openid-connect/auth"
        api_base_url: "https://auth.example.com/realms/clue/protocol/openid-connect"

        # Gestion des utilisateurs
        auto_create: true # Créer automatiquement les utilisateurs
        auto_sync: false # Synchroniser automatiquement les données utilisateur
        required_groups: ["clue-users"] # Groupes OAuth requis

        # Mappage de rôle et de classification
        role_map: # Mapper les groupes OAuth aux rôles Clue
          "clue-admins": "admin"
          "clue-analysts": "analyst"
        classification_map: # Mapper les groupes OAuth aux niveaux d'habilitation
          "clue-admins": "TLP:RED"
          "clue-analysts": "TLP:AMBER"

        # Configuration de l'ID utilisateur
        uid_randomize: false # Générer des noms d'utilisateur aléatoires
        uid_regex: "^(.+)@example\\.com$" # Extraire le nom d'utilisateur de l'email
        uid_format: "{0}" # Chaîne de format du nom d'utilisateur

Configuration de la classification (`classification.yml`)¶

Le fichier de configuration de la classification définit le système de classification des données utilisé par Clue. Ce fichier suit le format du moteur de classification Assemblyline.

Pour des informations détaillées sur la configuration du moteur de classification, consultez la documentation du moteur de classification Assemblyline.

Aspects clés de la configuration de la classification :

Niveaux de classification : Définir les niveaux de classification hiérarchiques (par exemple, TLP:CLEAR, TLP:GREEN, TLP:AMBER, TLP:RED)
Classifications requises : Spécifier les niveaux de classification minimums pour différents types de données
Règles d'application : Configurer comment les classifications sont appliquées et propagées
Schémas de marquage : Définir les marquages visuels et textuels pour les données classifiées

Exemple de configuration de classification de base :

classification:
  enforce: true
  dynamic_groups: false
  levels:
    - TLP:CLEAR
    - TLP:GREEN
    - TLP:AMBER
    - TLP:RED
  required:
    - TLP:CLEAR
  groups:
    - name: "TLP"
      short_name: "TLP"
      description: "Traffic Light Protocol"
      auto_select: true

Validation de la configuration¶

Clue valide la configuration par rapport à un schéma JSON au démarrage. Si la configuration est invalide, le serveur ne démarrera pas avec des messages d'erreur descriptifs indiquant quels paramètres doivent être corrigés.

Développement Docker¶

Construction de l'image Docker¶

Construire l'image Docker de développement :

poetry build
docker build -t clue-api:dev .

Docker Compose pour la pile complète¶

L'environnement de développement utilise Docker Compose pour fournir les services essentiels pour les tests et le développement. Le fichier api/dev/docker-compose.yml définit les services suivants :

Service Redis¶

redis:
  image: redis
  ports:
    - "6379:6379"
  healthcheck:
    test: ["CMD", "redis-cli", "ping"]
    interval: 30s
    timeout: 10s
    retries: 3

Objectif : Redis sert de couche de mise en cache et de stockage de session pour Clue. Il est utilisé pour :

Gestion des sessions et état d'authentification des utilisateurs
Mise en cache des résultats d'enrichissement pour améliorer les performances
Limitation de débit et gestion des quotas
Agrégation de métriques et stockage de données temporaires

Notes de développement :

Exposé sur le port standard 6379
Inclut des vérifications de santé pour s'assurer que le service est prêt avant l'exécution des tests
Aucune persistance configurée - les données sont perdues lorsque le conteneur s'arrête (adapté au développement)

Service Keycloak (construction personnalisée)¶

keycloak:
  build:
    context: ./keycloak
    dockerfile: Dockerfile
    no_cache: true
  environment:
    KC_HEALTH_ENABLED: true
  ports:
    - "9100:8080"
  expose:
    - "9100"
  healthcheck:
    test: ["CMD-SHELL", "curl -f http://localhost:8080/health/ready"]
    interval: 5s
    timeout: 5s
    retries: 15

Objectif : Keycloak fournit des services d'authentification OAuth/OpenID Connect pour tester les flux d'authentification dans Clue.

Fonctionnalités du Dockerfile personnalisé : L'image Keycloak personnalisée (api/dev/keycloak/Dockerfile) étend l'image officielle Keycloak 18.0.2 avec :

Compte administrateur préconfiguré :
Nom d'utilisateur : admin
Mot de passe : admin
Permet un accès immédiat à la console d'administration Keycloak
Mode développement : S'exécute en mode développement avec le débogage activé pour un dépannage plus facile
Royaume pré-importé : Importe automatiquement la configuration de royaume incluse depuis keycloak-realm.json
Fonctionnalités améliorées : Active l'échange de jetons et les fonctionnalités d'autorisation fine qui peuvent être utilisées par Clue

Utilisateurs de test préconfigurés : Le royaume importé inclut plusieurs utilisateurs de test pour le développement et les tests :

admin - Utilisateur administratif
dewey, donald, goose - Utilisateurs de test standard
guest - Utilisateur invité avec des autorisations limitées
huey, louie - Utilisateurs de test supplémentaires

Points forts de la configuration du royaume : Le fichier keycloak-realm.json configure un royaume intégré avec :

Applications clientes : Clients OAuth préconfigurés pour l'intégration de l'API Clue
Groupes d'utilisateurs : Différents groupes d'utilisateurs avec des niveaux de permissions variables
Flux d'authentification : Flux OAuth standard pour l'authentification Web et API
Paramètres de sécurité : En-têtes de sécurité et gestion de session appropriés
Internationalisation : Support pour les locales anglaise et française
Durées de vie des jetons : Configuré pour le développement (durées de vie plus courtes pour les tests)

Démarrer la pile de développement¶

Pour démarrer tous les services de développement :

cd api/dev
docker-compose up --build -d

Pour vérifier que les services sont en bonne santé :

# Vérifier l'état du service
docker-compose ps

# Vérifier les journaux si nécessaire
docker-compose logs redis
docker-compose logs keycloak

# Ou utiliser la vérification de santé intégrée
poetry run python build_scripts/keycloak_health.py

Accès aux services¶

Redis : Disponible sur localhost:6379 (aucune authentification requise)
Console d'administration Keycloak : http://localhost:9100/admin
Nom d'utilisateur : admin
Mot de passe : admin
Royaume Keycloak : http://localhost:9100/realms/HogwartsMini

Arrêter et nettoyer¶

# Arrêter les services
docker-compose down

# Arrêter et supprimer les volumes (repartir de zéro)
docker-compose down -v

# Reconstruire à partir de zéro
docker-compose down -v && docker-compose up --build

Intégration avec l'API Clue¶

Lorsque l'API Clue est configurée pour l'authentification OAuth, elle peut se connecter à l'instance Keycloak locale en utilisant :

auth:
  oauth:
    enabled: true
    providers:
      keycloak:
        client_id: "clue-api"
        jwks_uri: "http://localhost:9100/realms/HogwartsMini/protocol/openid-connect/certs"
        access_token_url: "http://localhost:9100/realms/HogwartsMini/protocol/openid-connect/token"
        authorize_url: "http://localhost:9100/realms/HogwartsMini/protocol/openid-connect/auth"
        api_base_url: "http://localhost:9100/realms/HogwartsMini/protocol/openid-connect"
        # ... autre configuration

Cette configuration fournit un environnement de développement complet pour tester l'authentification, l'autorisation, la mise en cache et toutes les fonctionnalités de l'API Clue sans nécessiter de services externes.

Dépannage¶

Problèmes d'environnement¶

Si vous rencontrez des problèmes avec l'environnement Python :

Supprimer l'environnement existant : poetry env remove python
Le recréer : poetry env use 3.12
Réinstaller les dépendances : poetry install --all-extras --with test,dev,types

Dépendances de service¶

Si les services Docker ne démarrent pas correctement :

Arrêter tous les conteneurs : docker-compose down
Supprimer les volumes : docker-compose down -v
Reconstruire : docker-compose up --build

Ressources supplémentaires¶

Contribuer¶

Voir Contribution pour des informations générales sur la façon de contribuer.

En plus des pratiques de contribution standard, voici quelques directives supplémentaires spécifiques au projet API Clue :

Hooks pre-commit¶

Installer les hooks pre-commit pour exécuter automatiquement des vérifications avant les commits :

poetry run pre-commit install

Vérifications avant soumission¶

Avant d'ouvrir une PR, assurez-vous que :¶

Tous les tests passent : poetry run test
Le code est correctement formaté : poetry run ruff format clue
Le linting passe : poetry run ruff check clue
La vérification de type passe : poetry run type_check

Notez que l'installation de hooks pre-commit aidera également à gérer ces cas.

Obtenir de l'aide¶

Vous pouvez contacter l'équipe de développement Clue sur le discord aurora CCCS : https://discord.gg/GUAy9wErNu