Vue d'ensemble

Ukweli est une plateforme complète d'analyse de sécurité conçue pour l'Afrique, permettant d'analyser des URLs, fichiers, domaines, IPs et autres indicateurs de menace à travers une interface unifiée et des APIs de threat intelligence de classe mondiale.

Note : Ukweli signifie "Vérité" en swahili, reflétant notre engagement à fournir des analyses précises et fiables.

Architecture

Ukweli est construit avec une architecture moderne et scalable :

Backend : FastAPI (Python) pour des performances élevées et une API REST complète
Frontend : HTML/CSS/JavaScript vanilla pour une expérience utilisateur fluide
Base de données : Supabase (PostgreSQL) pour le stockage persistant
APIs externes : Intégration avec VirusTotal, URLScan, Shodan, OTX, Hybrid Analysis

Fonctionnalités

Analyse d'URL

Analyse complète des URLs avec vérification lexicale, TLS, DNS, WHOIS, GeoIP, HTML statique et dynamique.

Analyse de fichiers

Détection de malware dans les fichiers avec analyse statique et intégration VirusTotal.

Recherche avancée

Recherche unifiée dans toutes les bases de données de threat intelligence pour domaines, IPs, hashes, ASNs.

Threat Intelligence

Intégration avec VirusTotal, URLScan, Shodan, AlienVault OTX, Hybrid Analysis.

Tableau de bord

Visualisation des rapports d'analyse avec statistiques et historique complet.

Sécurité renforcée

Protection XSS, CSRF, CORS, rate limiting, HSTS, Content Security Policy.

Démarrage rapide

1. Analyse d'une URL

Pour analyser une URL suspecte :

Accédez à la page principale
Entrez l'URL dans le champ de saisie (ex: https://example.com)
Cliquez sur "Scanner"
Attendez que l'analyse se termine (généralement 30-60 secondes)
Consultez le rapport détaillé

Exemple d'URL à analyser :
https://example.com
example.com (le https:// sera ajouté automatiquement)

2. Analyse d'un fichier

Pour analyser un fichier suspect :

Cliquez sur l'onglet "Fichier"
Sélectionnez le fichier à analyser (max 100MB)
Cliquez sur "Analyser le fichier"
Consultez le rapport combiné (VirusTotal + Scanner malware)

Attention : Les fichiers sont analysés avec VirusTotal et un scanner malware statique. Ne téléchargez jamais de fichiers depuis des sources non fiables.

3. Recherche avancée

Pour rechercher un indicateur dans toutes les bases de données :

Cliquez sur "Recherche" dans la barre de navigation
Entrez votre requête (domaine, IP, hash, ASN, URL)
Cliquez sur "Rechercher"
Consultez les résultats de toutes les APIs

Analyse d'URL

L'analyse d'URL d'Ukweli effectue une analyse multi-dimensionnelle complète pour détecter les menaces potentielles et les comportements suspects.

Composants de l'analyse

1. Analyse lexicale

Examine la structure de l'URL pour détecter :

Entropie : Mesure du caractère aléatoire (URLs générées automatiquement)
Typosquatting : Détection de domaines similaires (ex: faceb00k.com)
Caractères suspects : Caractères spéciaux, sous-domaines multiples
Longueur : URLs anormalement longues

2. Analyse TLS/Certificat

Vérifie la sécurité de la connexion :

Validité du certificat SSL/TLS
Émetteur du certificat
Date d'expiration
Noms alternatifs (SAN)

3. Analyse DNS

Résout et analyse les enregistrements DNS :

Résolution A/AAAA (adresses IP)
Enregistrements MX (email)
Enregistrements TXT (SPF, DKIM, etc.)
Détection d'IPs privées

4. GeoIP

Localise géographiquement les serveurs :

Pays, région, ville
Coordonnées géographiques
Fournisseur d'accès (ISP)
Numéro ASN

5. WHOIS

Récupère les informations d'enregistrement du domaine :

Date de création
Date d'expiration
Registrar
Informations de contact

6. Analyse HTML statique

Examine le contenu HTML de la page :

Détection de formulaires
Liens externes
Scripts intégrés
Métadonnées

7. Analyse dynamique (Playwright)

Exécute la page dans un navigateur pour capturer :

Comportement JavaScript
Requêtes réseau
Redirections
Captures d'écran
Permissions demandées

8. APIs de Threat Intelligence

Interroge les bases de données de réputation :

VirusTotal : Réputation multi-moteur (70+ antivirus)
URLScan : Scan complet avec verdicts
Shodan : Informations sur l'hôte et vulnérabilités
AlienVault OTX : Threat intelligence communautaire
Hybrid Analysis : Analyse sandbox

Interprétation des résultats

Score de risque

Le score de risque est calculé sur 100 points :

70-100 : SAFE - Probablement sûr
40-69 : SUSPICIOUS - Suspect, nécessite attention
0-39 : MALICIOUS - Probablement malveillant

Étiquettes

Les étiquettes fournissent une classification rapide :

SAFE : Aucun indicateur de menace détecté
SUSPICIOUS : Certains indicateurs suspects présents
MALICIOUS : Plusieurs indicateurs de menace détectés
UNKNOWN : Données insuffisantes pour déterminer

Analyse de fichiers

L'analyse de fichiers combine deux approches complémentaires pour une détection maximale des menaces : l'analyse par VirusTotal et un scanner malware statique.

Types de fichiers supportés

Exécutables Windows : .exe, .dll, .sys
Documents Office : .doc, .docx, .xls, .xlsx, .ppt, .pptx
PDF : .pdf
Archives : .zip, .rar, .7z
Scripts : .js, .vbs, .bat, .ps1

Processus d'analyse

1. VirusTotal

VirusTotal analyse le fichier avec 70+ moteurs antivirus et fournit :

Statistiques de détection (malicieux, suspicieux, inoffensif)
Résultats détaillés par moteur
Informations sur le fichier (type, taille, hashes)
Historique des analyses

2. Scanner malware statique

Analyse locale du fichier pour détecter :

Signatures de malware connus
Comportements suspects dans le code
Chaînes de caractères suspectes
Encodage/obfuscation

Astuce : Pour une analyse plus approfondie, utilisez également l'analyse dynamique avec Hybrid Analysis via la recherche avancée.

Recherche avancée

La fonctionnalité de recherche avancée permet de rechercher un indicateur dans toutes les bases de données de threat intelligence disponibles simultanément.

Types de recherche supportés

Type	Format	APIs utilisées
Domaine	`example.com`	Shodan, VirusTotal, OTX
IP	`192.168.1.1`	Shodan, VirusTotal, OTX
ASN	`AS12345` ou `12345`	Shodan
Hash MD5	`5d41402abc4b2a76b9719d911017c592`	VirusTotal, OTX, Hybrid Analysis
Hash SHA1	`aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d`	VirusTotal, OTX, Hybrid Analysis
Hash SHA256	`e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`	VirusTotal, OTX, Hybrid Analysis
URL	`https://example.com`	VirusTotal, OTX, URLScan

Résultats de recherche

Chaque API retourne des informations spécifiques :

Shodan

Informations sur l'hôte (OS, ports, services)
Vulnérabilités connues
Organisation et localisation
Résultats de recherche pour domaines/ASNs

VirusTotal

Statistiques de réputation
Détections par moteurs antivirus
Informations sur les fichiers (pour hashes)
Historique des analyses

OTX (AlienVault)

Score de réputation
Pulses de threat intelligence
Compteur de malware
Passive DNS

Tableau de bord

Le tableau de bord administrateur permet de consulter tous les rapports d'analyse générés sur la plateforme.

Fonctionnalités

Liste des rapports : Tous les rapports avec filtres et recherche
Statistiques : Vue d'ensemble des analyses (total, par type, par statut)
Détails : Consultation complète de chaque rapport
Export : Téléchargement des rapports en JSON

Accès restreint : Le tableau de bord est accessible uniquement aux administrateurs authentifiés.

Vue d'ensemble de l'API

Ukweli expose une API REST complète pour intégrer les fonctionnalités d'analyse dans vos applications.

Base URL

https://votre-domaine.com/api

Authentification

La plupart des endpoints sont publics. Certains endpoints administrateur nécessitent une authentification via session cookie ou Bearer token.

Format des réponses

Toutes les réponses sont au format JSON avec la structure suivante :

{
  "status": "success|error",
  "data": { ... },
  "error": "message d'erreur si applicable"
}

Endpoints API

Analyse

POST /api/scan

Lance une analyse d'URL ou de domaine.

Request:
{
  "url": "https://example.com"
}

Response:
{
  "job_id": "abc123...",
  "status_url": "/api/status/abc123...",
  "report_url": "/api/report/abc123..."
}

GET /api/status/{job_id}

Récupère le statut d'une analyse en cours.

Response:
{
  "job_id": "abc123...",
  "status": "pending|running|done|error",
  "url": "https://example.com",
  "created_ts": 1234567890,
  "finished_ts": 1234567900,
  "duration": 10.5
}

GET /api/report/{job_id}

Récupère le rapport complet d'une analyse terminée.

POST /api/search

Recherche un indicateur dans toutes les bases de données.

Request:
{
  "query": "example.com"
}

Response:
{
  "query": "example.com",
  "query_type": "domain",
  "shodan": { ... },
  "virustotal": { ... },
  "otx": { ... },
  "summary": {
    "total_apis_used": 3,
    "successful_apis": 3,
    "successful_api_names": ["shodan", "virustotal", "otx"]
  }
}

Fichiers

POST /api/scan/file

Analyse un fichier uploadé.

Request: multipart/form-data
  file: [fichier]

Response:
{
  "virustotal": { ... },
  "malware_scanner": { ... },
  "combined_verdict": "safe|suspicious|malicious"
}

Exemples d'utilisation de l'API

JavaScript (Fetch)

// Lancer une analyse
const response = await fetch('/api/scan', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ url: 'https://example.com' })
});

const data = await response.json();
const jobId = data.job_id;

// Poller le statut
const pollStatus = async () => {
  const statusRes = await fetch(`/api/status/${jobId}`);
  const status = await statusRes.json();
  
  if (status.status === 'done') {
    // Récupérer le rapport
    const reportRes = await fetch(`/api/report/${jobId}`);
    const report = await reportRes.json();
    console.log(report);
  } else if (status.status === 'error') {
    console.error('Erreur:', status.error);
  } else {
    // Réessayer après 2 secondes
    setTimeout(pollStatus, 2000);
  }
};

pollStatus();

Python (requests)

import requests
import time

# Lancer une analyse
response = requests.post('https://votre-domaine.com/api/scan', 
    json={'url': 'https://example.com'})
data = response.json()
job_id = data['job_id']

# Poller le statut
while True:
    status_res = requests.get(f'https://votre-domaine.com/api/status/{job_id}')
    status = status_res.json()
    
    if status['status'] == 'done':
        # Récupérer le rapport
        report_res = requests.get(f'https://votre-domaine.com/api/report/{job_id}')
        report = report_res.json()
        print(report)
        break
    elif status['status'] == 'error':
        print(f"Erreur: {status.get('error')}")
        break
    else:
        time.sleep(2)

cURL

# Lancer une analyse
curl -X POST https://votre-domaine.com/api/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# Récupérer le statut
curl https://votre-domaine.com/api/status/{job_id}

# Récupérer le rapport
curl https://votre-domaine.com/api/report/{job_id}

Guide API pour développeurs

L'API Ukweli permet aux développeurs et ingénieurs en cybersécurité d'intégrer les fonctionnalités d'analyse d'Ukweli dans leurs projets externes (SOC, SIEM, outils de sécurité, etc.).

Base URL : https://votre-domaine.com/api/v1

Logique de fonctionnement de l'API

Comprendre comment fonctionne l'API Ukweli est essentiel pour l'intégrer efficacement dans vos projets. Voici une explication claire et détaillée du processus complet.

Vue d'ensemble du flux

L'API Ukweli fonctionne selon un modèle asynchrone en 4 étapes principales :

Création du job : Vous soumettez une URL à analyser
Analyse asynchrone : L'analyse s'exécute en arrière-plan
Suivi du statut : Vous vérifiez régulièrement l'avancement
Récupération du rapport : Vous obtenez les résultats complets

Étape 1 : Création du job (POST /api/v1/analyze)

Lorsque vous envoyez une requête d'analyse :

POST /api/v1/analyze
{
  "url": "https://example.com"
}

Ce qui se passe côté serveur :

Validation et normalisation : L'URL est validée et normalisée (ajout de https:// si nécessaire)
Vérification des limites : Le serveur vérifie qu'il n'y a pas trop de jobs en attente ou en cours
Génération d'un job_id unique : Un identifiant unique (32 caractères hexadécimaux) est créé
Création du job : Un job est créé avec le statut "pending" (en attente)
Soumission asynchrone : L'analyse est soumise à un pool de threads pour exécution en arrière-plan
Réponse immédiate : Vous recevez immédiatement le job_id et les URLs pour suivre le statut

Important : La réponse est immédiate. L'analyse n'est pas encore terminée, elle vient juste d'être lancée. Vous devez utiliser le job_id pour suivre l'avancement.

Étape 2 : Analyse asynchrone (en arrière-plan)

Une fois le job créé, l'analyse s'exécute en parallèle avec plusieurs modules :

Modules d'analyse exécutés :

Analyses rapides (séquentielles)

Analyse lexicale URL : Détection de patterns suspects dans l'URL
Résolution DNS : Récupération des adresses IP
Récupération HTML : Téléchargement du contenu de la page
Analyse HTML statique : Détection de formulaires, scripts, liens

Analyses parallèles (simultanées)

TLS/Certificat : Validation du certificat SSL
WHOIS : Informations d'enregistrement du domaine
GeoIP : Localisation géographique des IPs

APIs Threat Intelligence (parallèles)

VirusTotal : Réputation multi-moteur (70+ antivirus)
URLScan : Scan complet avec verdicts
Shodan : Informations sur l'hôte
AlienVault OTX : Threat intelligence
Hybrid Analysis : Analyse sandbox

Analyse dynamique

Playwright : Exécution dans un navigateur réel
Capture d'écran : Image de la page rendue
Requêtes réseau : Analyse du trafic généré
Comportement JavaScript : Détection d'activités suspectes

Optimisations de performance :

Parallélisation : Les analyses indépendantes s'exécutent en parallèle pour gagner du temps
Timeouts intelligents : Chaque module a un timeout adapté (4-30 secondes selon la complexité)
Résilience : Si une analyse échoue, les autres continuent
Timeout global : L'analyse complète a un timeout de 60 secondes maximum

Évolution du statut du job :

pending → running → done (ou error)

pending : Le job est créé et attend d'être traité
running : L'analyse est en cours d'exécution
done : L'analyse est terminée, le rapport est disponible
error : Une erreur s'est produite pendant l'analyse

Étape 3 : Suivi du statut (GET /api/v1/jobs/{job_id})

Pour savoir si votre analyse est terminée, vous devez interroger régulièrement l'endpoint de statut :

GET /api/v1/jobs/{job_id}
Authorization: Bearer ukw_votre_cle_api

Réponse pendant l'analyse (status: "running") :

{
  "job_id": "abc123def456",
  "url": "https://example.com",
  "status": "running",
  "created_at": 1234567890.0,
  "started_at": 1234567891.0,
  "finished_at": null,
  "duration": null
}

Réponse une fois terminée (status: "done") :

{
  "job_id": "abc123def456",
  "url": "https://example.com",
  "status": "done",
  "created_at": 1234567890.0,
  "started_at": 1234567891.0,
  "finished_at": 1234567895.0,
  "duration": 4.5,
  "report_available": true,
  "result_summary": {
    "score": 75,
    "verdict": "safe",
    "threats_detected": []
  }
}

Stratégie de polling recommandée :

Intervalle initial : Attendre 2-3 secondes après la création du job
Polling actif : Vérifier toutes les 2-3 secondes pendant l'analyse
Arrêt : Arrêter le polling quand status == "done" ou status == "error"
Timeout client : Arrêter après 90 secondes maximum (l'analyse serveur timeout à 60s)

Étape 4 : Récupération du rapport (GET /api/v1/reports/{job_id})

Une fois le statut "done", vous pouvez récupérer le rapport complet :

GET /api/v1/reports/{job_id}
Authorization: Bearer ukw_votre_cle_api

Le rapport contient :

Métadonnées : Timestamp, URL analysée, durée
Résultats par module : Tous les détails de chaque analyse
Score de risque : Score sur 100 (0-39: malveillant, 40-69: suspect, 70-100: sûr)
Verdict : SAFE, SUSPICIOUS, MALICIOUS, ou UNKNOWN
Explication : Raison du verdict avec détails
Données brutes : Toutes les données collectées pour analyse approfondie

Schéma complet du flux

1. Client → Serveur
POST /api/v1/analyze
{"url": "https://example.com"}
2. Serveur (immédiat)
→ Création job_id
→ Statut: "pending"
→ Lancement analyse asynchrone
→ Retour job_id au client
3. Serveur (en arrière-plan, ~5-60 secondes)
→ Statut: "running"
├─ Analyse lexicale URL
├─ Résolution DNS
├─ TLS + WHOIS (parallèle)
├─ GeoIP
├─ Récupération HTML
├─ Analyse HTML
├─ APIs Threat Intel (parallèle)
│  ├─ VirusTotal
│  ├─ URLScan
│  ├─ Shodan
│  ├─ OTX
│  └─ Hybrid Analysis
└─ Analyse dynamique (Playwright)
→ Calcul du score de risque
→ Statut: "done"
4. Client → Serveur (polling)
GET /api/v1/jobs/{job_id}
→ Répéter toutes les 2-3 secondes
→ Jusqu'à status == "done"
5. Client → Serveur (récupération)
GET /api/v1/reports/{job_id}
→ Rapport complet JSON

Durées typiques

Type d'analyse	Durée typique	Détails
Analyse rapide	3-10 secondes	Analyses locales uniquement (DNS, TLS, HTML)
Analyse standard	10-30 secondes	Avec quelques APIs Threat Intelligence
Analyse complète	30-60 secondes	Toutes les analyses + toutes les APIs + Playwright
Timeout maximum	60 secondes	L'analyse s'arrête automatiquement après ce délai

Gestion des erreurs et timeouts

Erreurs possibles :

400 Bad Request : URL invalide ou mal formatée
429 Too Many Requests : Quota API dépassé
503 Service Unavailable : Trop de jobs en cours, réessayez plus tard
404 Not Found : Job_id introuvable (expiré ou invalide)

Gestion des timeouts :

Timeout global : 60 secondes maximum par analyse
Timeout par module : Chaque module a son propre timeout (4-30s)
Résilience : Si un module timeout, les autres continuent
Résultat partiel : Vous recevez toujours un rapport, même si certaines analyses ont échoué

Important : Les jobs expirent après un certain temps. Si vous attendez trop longtemps avant de récupérer le rapport, il peut ne plus être disponible. Récupérez le rapport dès que le statut est "done".

Stockage et cache

Stockage en mémoire : Les jobs actifs sont stockés en mémoire pour accès rapide
Persistance Supabase : Les rapports complets sont sauvegardés dans Supabase
Cache des résultats : Les URLs déjà analysées peuvent être mises en cache
Rétention : Les rapports sont conservés selon la configuration du serveur

Authentification et quotas

Sans clé API : Quotas par défaut (60 req/min, 200 req/heure, 5000 req/jour)
Avec clé API : Quotas personnalisés définis par l'administrateur
Suivi d'utilisation : Chaque requête est enregistrée pour statistiques
Limites de jobs : Maximum 5 jobs en attente, 10 jobs actifs simultanément

Astuce : Pour des intégrations en production, utilisez toujours une clé API pour bénéficier de quotas plus élevés et d'un suivi détaillé de votre utilisation.

Comment demander une clé API

1. Via le formulaire sur la page d'accueil

La méthode la plus simple pour demander une clé API :

Accédez à la page d'accueil d'Ukweli
Cliquez sur le bouton "Demander une clé API" en bas à gauche
Remplissez le formulaire avec :
- Nom de la clé : Un nom descriptif pour votre projet (ex: "Mon SOC", "Intégration SIEM")
- Description : Décrivez brièvement l'utilisation prévue
- Email du propriétaire : Votre adresse email professionnelle
Soumettez la demande

2. Traitement de la demande

Une fois votre demande soumise, un administrateur Ukweli examinera votre demande et :

Définira les limites de taux appropriées (requêtes par minute, heure, jour)
Approuvera ou rejettera la demande
Vous enverra la clé API par email une fois approuvée

Important : La clé API n'est affichée qu'une seule fois lors de la génération. Assurez-vous de la sauvegarder immédiatement dans un gestionnaire de mots de passe sécurisé.

3. Après réception de votre clé API

Une fois votre clé API reçue, voici comment l'utiliser :

Configuration

Vous pouvez configurer votre clé API de plusieurs façons :

Option 1 : Variables d'environnement (recommandé)

# Linux/Mac
export UKWELI_API_KEY="ukw_votre_cle_api_ici"
export UKWELI_API_URL="https://ukweli.ngitcorp.com"

# Windows (PowerShell)
$env:UKWELI_API_KEY="ukw_votre_cle_api_ici"
$env:UKWELI_API_URL="https://ukweli.ngitcorp.com"

Option 2 : Fichier de configuration (config.json)

{
  "api": {
    "base_url": "https://ukweli.ngitcorp.com",
    "api_key": "ukw_votre_cle_api_ici",
    "api_prefix": "/api/v1"
  }
}

Workflow d'utilisation typique

Création du job : Envoyez une requête POST à /api/v1/analyze avec l'URL à analyser
Réception du job_id : L'API retourne immédiatement un job_id unique
Suivi du statut : Vérifiez régulièrement le statut via GET /api/v1/jobs/{job_id}
Récupération du rapport : Une fois le statut "done", récupérez le rapport via GET /api/v1/reports/{job_id}

Gestion des erreurs courantes

Erreur	Solution
`401 Unauthorized`	Vérifiez que votre clé API est correctement configurée dans les headers
`429 Too Many Requests`	Vous avez dépassé votre quota. Attendez ou contactez l'administrateur pour augmenter les limites
`404 Not Found`	Vérifiez que l'URL de base et le préfixe API sont corrects
`Timeout`	Les analyses peuvent prendre 30 secondes à 5 minutes. Augmentez le timeout de votre client si nécessaire

Bonnes pratiques

Sécurité : Ne commitez jamais votre clé API dans votre code source. Utilisez des variables d'environnement ou des fichiers de configuration non versionnés
Quotas : Respectez les limites de taux configurées par l'administrateur. En cas de dépassement, implémentez un backoff exponentiel
Gestion des jobs : Conservez les job_id pour pouvoir récupérer les rapports plus tard
Polling : Utilisez un intervalle de 2-5 secondes pour vérifier le statut des jobs
Timeouts : Configurez un timeout approprié (300-600 secondes) selon le type d'analyse

Documentation interactive

Pour tester et explorer l'API de manière interactive, utilisez la documentation Swagger :

Swagger UI : /api/docs - Interface interactive complète
ReDoc : /api/redoc - Documentation alternative
OpenAPI JSON : /api/openapi.json - Schéma OpenAPI complet

Astuce : Utilisez Swagger UI pour tester les endpoints directement depuis votre navigateur et voir les schémas de requête/réponse en temps réel.

Utiliser votre clé API

Méthodes d'authentification

Vous pouvez fournir votre clé API de deux façons :

1. Bearer Token (recommandé)

Authorization: Bearer ukw_votre_cle_api_ici

2. Header X-API-Key

X-API-Key: ukw_votre_cle_api_ici

Authentification optionnelle

L'authentification est optionnelle mais fortement recommandée :

Sans clé API : Quotas par défaut limités (60 req/min, 200 req/heure, 5000 req/jour)
Avec clé API : Quotas personnalisés selon vos besoins, suivi d'utilisation, priorité

Endpoints disponibles

1. Analyser une URL

Endpoint : POST /api/v1/analyze

Lance une analyse complète d'une URL ou d'un domaine.

curl -X POST https://votre-domaine.com/api/v1/analyze \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ukw_votre_cle_api" \
  -d '{
    "url": "https://example.com"
  }'

Réponse :

{
  "job_id": "abc123def456",
  "status": "pending",
  "status_url": "/api/v1/jobs/abc123def456",
  "report_url": "/api/v1/reports/abc123def456",
  "url": "https://example.com"
}

Note : L'analyse est asynchrone. Utilisez le job_id pour suivre le statut.

2. Statut d'un job

Endpoint : GET /api/v1/jobs/{job_id}

Récupère le statut d'une analyse en cours.

curl https://votre-domaine.com/api/v1/jobs/abc123def456 \
  -H "Authorization: Bearer ukw_votre_cle_api"

Statuts possibles :

pending : En attente
running : En cours d'analyse
done : Terminé
error : Erreur

3. Récupérer un rapport

Endpoint : GET /api/v1/reports/{job_id}

Récupère le rapport complet d'analyse une fois terminé.

curl https://votre-domaine.com/api/v1/reports/abc123def456 \
  -H "Authorization: Bearer ukw_votre_cle_api"

Le rapport contient toutes les informations d'analyse : score de risque, verdict, détails par module, etc.

4. Analyser un fichier

Endpoint : POST /api/v1/files/analyze

Analyse un fichier suspect (malware, document, etc.).

curl -X POST https://votre-domaine.com/api/v1/files/analyze \
  -H "Authorization: Bearer ukw_votre_cle_api" \
  -F "file=@/chemin/vers/fichier.exe"

5. Recherche avancée

Endpoint : GET /api/v1/search?query={indicateur}

Recherche un indicateur (domaine, IP, hash) dans toutes les bases de threat intelligence.

curl "https://votre-domaine.com/api/v1/search?query=example.com" \
  -H "Authorization: Bearer ukw_votre_cle_api"

6. Santé de l'API

Endpoint : GET /api/v1/health

Vérifie que l'API est opérationnelle (authentification non requise).

curl https://votre-domaine.com/api/v1/health

Exemples d'intégration

Python

import requests
import time

API_KEY = "ukw_votre_cle_api"
BASE_URL = "https://votre-domaine.com/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Analyser une URL
response = requests.post(
    f"{BASE_URL}/analyze",
    headers=headers,
    json={"url": "https://example.com"}
)
job = response.json()
job_id = job["job_id"]

# Poller le statut jusqu'à ce que l'analyse soit terminée
while True:
    status = requests.get(
        f"{BASE_URL}/jobs/{job_id}",
        headers=headers
    ).json()
    
    if status["status"] == "done":
        break
    elif status["status"] == "error":
        raise Exception("Erreur d'analyse")
    
    time.sleep(2)

# Récupérer le rapport
report = requests.get(
    f"{BASE_URL}/reports/{job_id}",
    headers=headers
).json()

print(f"Score: {report['score']}, Verdict: {report['verdict']}")

JavaScript/Node.js

const API_KEY = 'ukw_votre_cle_api';
const BASE_URL = 'https://votre-domaine.com/api/v1';

const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json'
};

// Analyser une URL
const analyzeResponse = await fetch(`${BASE_URL}/analyze`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ url: 'https://example.com' })
});

const job = await analyzeResponse.json();
const jobId = job.job_id;

// Poller le statut
const pollStatus = async () => {
  while (true) {
    const statusResponse = await fetch(`${BASE_URL}/jobs/${jobId}`, { headers });
    const status = await statusResponse.json();
    
    if (status.status === 'done') {
      break;
    } else if (status.status === 'error') {
      throw new Error('Erreur d\'analyse');
    }
    
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
  
  // Récupérer le rapport
  const reportResponse = await fetch(`${BASE_URL}/reports/${jobId}`, { headers });
  const report = await reportResponse.json();
  
  console.log(`Score: ${report.score}, Verdict: ${report.verdict}`);
};

await pollStatus();

Bash/cURL

#!/bin/bash

API_KEY="ukw_votre_cle_api"
BASE_URL="https://votre-domaine.com/api/v1"

# Analyser une URL
JOB_RESPONSE=$(curl -s -X POST "$BASE_URL/analyze" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}')

JOB_ID=$(echo $JOB_RESPONSE | jq -r '.job_id')

# Poller le statut
while true; do
  STATUS=$(curl -s "$BASE_URL/jobs/$JOB_ID" \
    -H "Authorization: Bearer $API_KEY" | jq -r '.status')
  
  if [ "$STATUS" = "done" ]; then
    break
  elif [ "$STATUS" = "error" ]; then
    echo "Erreur d'analyse"
    exit 1
  fi
  
  sleep 2
done

# Récupérer le rapport
REPORT=$(curl -s "$BASE_URL/reports/$JOB_ID" \
  -H "Authorization: Bearer $API_KEY")

SCORE=$(echo $REPORT | jq -r '.score')
VERDICT=$(echo $REPORT | jq -r '.verdict')

echo "Score: $SCORE, Verdict: $VERDICT"

Gestion des quotas et limites

Limites de taux

Chaque clé API a des limites personnalisées définies par l'administrateur :

Par minute : Nombre maximum de requêtes par minute
Par heure : Nombre maximum de requêtes par heure
Par jour : Nombre maximum de requêtes par jour

Gestion des erreurs de quota

Si vous dépassez vos limites, vous recevrez une erreur 429 Too Many Requests :

{
  "detail": "Quota quotidien dépassé. Limite: 20000, Utilisé: 20001"
}

L'en-tête Retry-After indique le nombre de secondes à attendre avant de réessayer.

Sécurité et bonnes pratiques

Protection de votre clé API

Ne commitez jamais vos clés API dans votre code source
Utilisez des variables d'environnement pour stocker vos clés
Régénérez vos clés immédiatement si elles sont compromises
Utilisez HTTPS pour toutes les requêtes
Limitez les permissions de vos clés API au strict nécessaire

Exemple : Variables d'environnement

# .env
UKWELI_API_KEY=ukw_votre_cle_api
UKWELI_BASE_URL=https://votre-domaine.com/api/v1

# Python
import os
from dotenv import load_dotenv

load_dotenv()
API_KEY = os.getenv("UKWELI_API_KEY")
BASE_URL = os.getenv("UKWELI_BASE_URL")

Documentation interactive

Pour explorer l'API de manière interactive :

Swagger UI : /api/docs - Interface interactive complète
ReDoc : /api/redoc - Documentation alternative
OpenAPI JSON : /api/openapi.json - Schéma OpenAPI complet

Astuce : Utilisez Swagger UI pour tester les endpoints directement depuis votre navigateur et voir les schémas de requête/réponse en temps réel.

Configuration des clés API

Pour utiliser toutes les fonctionnalités d'Ukweli, vous devez configurer les clés API des services externes. Ces clés peuvent être configurées via l'interface web ou les variables d'environnement.

Clés API requises

Service	Obligatoire	Où l'obtenir
VirusTotal	Recommandé	virustotal.com
URLScan	Recommandé	urlscan.io
Shodan	Optionnel	shodan.io
AlienVault OTX	Optionnel	otx.alienvault.com
Hybrid Analysis	Optionnel	hybrid-analysis.com

Configuration via l'interface

Cliquez sur "Paramètres" dans la barre de navigation
Entrez vos clés API dans les champs correspondants
Cliquez sur "Sauvegarder"

Sécurité : Ne partagez jamais vos clés API. Elles sont stockées localement et ne sont jamais transmises à des tiers.

Variables d'environnement

Les clés API et autres paramètres peuvent également être configurés via des variables d'environnement, ce qui est recommandé pour les déploiements en production.

Variables principales

Variable	Description	Exemple
`VIRUSTOTAL_API_KEY`	Clé API VirusTotal	`abc123...`
`URLSCAN_API_KEY`	Clé API URLScan	`uuid-format`
`SHODAN_API_KEY`	Clé API Shodan	`32-char-key`
`OTX_API_KEY`	Clé API AlienVault OTX	`64-char-hex`
`HYBRID_ANALYSIS_API_KEY`	Clé API Hybrid Analysis	`64-char-key`
`SUPABASE_URL`	URL de votre projet Supabase	`https://xxx.supabase.co`
`SUPABASE_KEY`	Clé API Supabase (service role)	`eyJhbGc...`
`MAX_PENDING_JOBS`	Nombre max de jobs en attente (défaut: 5)	`10`
`API_TIMEOUT`	Timeout global pour les APIs (défaut: 50s)	`60`

Configuration Supabase

Supabase est utilisé pour le stockage persistant des jobs, du cache et des quotas API. La configuration est optionnelle mais recommandée pour les déploiements en production.

Étapes de configuration

Créez un projet sur supabase.com
Récupérez l'URL du projet et la clé API (service role)
Configurez les variables d'environnement SUPABASE_URL et SUPABASE_KEY

Note : La configuration Supabase est optionnelle et réservée aux administrateurs. Pour plus d'informations, contactez le support à support.ukweli@ngitcorp.com.

Fonctionnalités de sécurité

Ukweli implémente plusieurs couches de sécurité pour protéger la plateforme et ses utilisateurs.

Protections implémentées

1. Protection XSS (Cross-Site Scripting)

Échappement automatique des données utilisateur et validation stricte des entrées.

2. Protection CSRF (Cross-Site Request Forgery)

Tokens CSRF pour toutes les requêtes modifiant l'état.

3. CORS (Cross-Origin Resource Sharing)

Configuration stricte des en-têtes CORS pour limiter les origines autorisées.

4. Rate Limiting

Limitation du nombre de requêtes par IP pour prévenir les abus.

5. HSTS (HTTP Strict Transport Security)

Forçage de HTTPS pour toutes les connexions.

6. Content Security Policy (CSP)

Politique de sécurité du contenu pour prévenir les injections.

7. Validation des entrées

Validation stricte de tous les paramètres d'entrée (URLs, fichiers, etc.).

8. Protection SSRF

Validation des URLs pour prévenir les attaques Server-Side Request Forgery.

Authentification

La plateforme utilise une authentification sécurisée avec validation serveur des sessions et protection CSRF pour toutes les actions sensibles.

Bonnes Pratiques - Protection contre le Phishing et les URLs Malveillantes

Ce guide vous aidera à identifier et éviter les pièges de phishing et autres menaces liées aux URLs malveillantes.

Reconnaître les URLs suspectes

Caractéristiques d'une URL légitime

Domaine clair et reconnaissable : https://www.banque-exemple.com
HTTPS avec certificat valide : cadenas vert dans la barre d'adresse
Nom de domaine cohérent : correspond au service attendu
Pas de caractères suspects : pas de caractères spéciaux étranges
URL courte et simple : pas d'empilement de sous-domaines

Signaux d'alerte dans une URL

1. Typosquatting (domaines similaires)

Mauvais : www.faceb00k.com (0 au lieu de o)
Mauvais : www.g00gle.com (0 au lieu de o)
Mauvais : www.micr0soft.com (0 au lieu de o)
Bon : www.facebook.com
Bon : www.google.com
Bon : www.microsoft.com

2. Sous-domaines suspects

Mauvais : facebook.com.security-verify.com
Mauvais : paypal.com.secure-login.net
Bon : security.facebook.com
Bon : secure.paypal.com

3. Caractères spéciaux et obfuscation

Mauvais : www.bank.com@malicious-site.com
Mauvais : www.bank.com%2F@malicious-site.com
Mauvais : www.bank.com/login?redirect=evil.com
Bon : www.bank.com/login

4. IP au lieu de nom de domaine

Mauvais : http://192.168.1.100/login
Mauvais : http://45.67.89.123/secure
Bon : https://www.votresite.com/login

5. URLs très longues avec paramètres suspects

Mauvais : www.site.com/login?token=abc123&redirect=http://evil.com
Mauvais : www.site.com/verify?email=user@mail.com&key=xyz789&return=malicious.com

6. Extensions de domaine suspectes

Mauvais : www.paypal.tk
Mauvais : www.bank.ml
Mauvais : www.amazon.cf
Bon : www.paypal.com
Bon : www.bank.fr
Bon : www.amazon.com

7. URLs avec beaucoup de tirets ou caractères aléatoires

Mauvais : www.secure-bank-verify-login-now.com
Mauvais : www.a1b2c3d4e5f6g7h8.com

Vérifier avant de cliquer

Méthode 1 : Survoler le lien (Desktop)

Passez la souris sur le lien sans cliquer
Regardez l'URL qui apparaît en bas à gauche du navigateur
Vérifiez que l'URL correspond bien au service attendu

Attention : Les attaquants peuvent utiliser des techniques avancées pour masquer la vraie URL. Toujours vérifier après le clic !

Méthode 2 : Utiliser un outil d'analyse

Copiez l'URL suspecte
Utilisez Ukweli ou un autre outil d'analyse
Vérifiez le rapport avant de visiter le site

Méthode 3 : Vérifier le certificat SSL

Cliquez sur le cadenas dans la barre d'adresse
Vérifiez :
- Le certificat est valide (pas expiré)
- Le nom du domaine correspond
- L'émetteur est reconnu (Let's Encrypt, DigiCert, etc.)

Méthode 4 : Vérifier le domaine sur des bases de données

VirusTotal : https://www.virustotal.com
URLScan : https://urlscan.io
Google Safe Browsing : Vérification automatique dans Chrome/Firefox

Protection des informations personnelles

Ne JAMAIS partager

Mots de passe (même par email "officiel")
Codes PIN ou codes de sécurité
Numéros de carte bancaire complets
CVV (code à 3 chiffres au dos de la carte)
Codes d'authentification à deux facteurs (2FA)
Informations d'identité (passeport, CNI, etc.)

Bonnes pratiques

Vérifiez toujours l'URL avant de saisir des informations
Utilisez des mots de passe uniques pour chaque site
Activez l'authentification à deux facteurs (2FA) partout où c'est possible
Ne réutilisez jamais un mot de passe
Utilisez un gestionnaire de mots de passe (Bitwarden, 1Password, etc.)

Questions à se poser

Pourquoi ce site me demande-t-il ces informations ?
Est-ce que j'ai initié cette demande ?
Le site est-il légitime ?
Y a-t-il une urgence réelle ?

Sécurité des emails

Signaux d'alerte dans un email

1. Expéditeur suspect

Mauvais : noreply@paypal-security.com (au lieu de paypal.com)
Mauvais : support@amazon-verify.net (au lieu de amazon.com)
Mauvais : security@bank-urgent.tk

2. Urgence artificielle

Mauvais : "Votre compte sera suspendu dans 24h"
Mauvais : "Action immédiate requise"
Mauvais : "Dernière chance avant fermeture"
Mauvais : "Votre compte a été compromis - cliquez maintenant"

3. Erreurs de grammaire et d'orthographe

Fautes d'orthographe nombreuses
Grammaire incorrecte
Formulations étranges
Traduction automatique visible

4. Liens suspects

Liens raccourcis (bit.ly, tinyurl.com) sans contexte
Liens qui ne correspondent pas au texte
Boutons "Cliquez ici" sans URL visible

5. Pièces jointes inattendues

Fichiers .exe, .scr, .bat
Documents Office avec macros (.docm, .xlsm)
Archives compressées (.zip, .rar) non sollicitées

Bonnes pratiques pour les emails

Vérifiez l'adresse de l'expéditeur complète (pas juste le nom)
Ne cliquez jamais sur les liens dans les emails suspects
Tapez l'URL manuellement dans le navigateur
Contactez l'organisation par un canal officiel si vous avez un doute
Ne téléchargez jamais de pièces jointes suspectes
Activez le filtre anti-spam de votre boîte mail

Vérification d'un email suspect

Regardez l'en-tête complet de l'email
Vérifiez le domaine de l'expéditeur
Recherchez l'URL dans un moteur de recherche
Utilisez Ukweli pour analyser les liens

Sécurité des réseaux sociaux

Pièges courants

1. Messages directs suspects

Messages de "personnes que vous connaissez" avec des liens
Offres trop belles pour être vraies
Demandes d'aide urgentes avec liens

2. Publications avec liens raccourcis

Liens bit.ly, tinyurl.com sans contexte
"Regardez cette vidéo de vous !"
"Vous avez gagné un prix !"

3. Applications tierces

Applications qui demandent trop de permissions
Applications non officielles
Connexions via des sites tiers

Bonnes pratiques

Vérifiez toujours l'identité de l'expéditeur
Ne cliquez pas sur les liens dans les messages privés suspects
Utilisez uniquement les applications officielles
Activez l'authentification à deux facteurs
Vérifiez les paramètres de confidentialité régulièrement

Sécurité bancaire et financière

Règles d'or

Votre banque ne vous demandera JAMAIS :
- Votre mot de passe complet
- Votre code PIN
- Votre numéro de carte complet
- De confirmer vos identifiants par email
Toujours vérifier :
- L'URL du site bancaire (tapez-la manuellement)
- Le certificat SSL (cadenas vert)
- Que vous êtes sur le site officiel
En cas de doute :
- Fermez immédiatement la page
- Contactez votre banque par téléphone
- Ne répondez jamais à l'email suspect

Sites bancaires légitimes

URL directe : Tapez l'URL vous-même
HTTPS obligatoire : Toujours un cadenas vert
Certificat valide : Vérifiez le certificat SSL
Pas de redirections : Le site ne vous redirige pas ailleurs

Signaux d'alarme bancaires

Email vous demandant de "vérifier votre compte"
SMS avec lien de "confirmation"
Appel téléphonique vous demandant vos identifiants
Site qui ressemble à votre banque mais avec une URL différente

Protection des appareils

Antivirus et sécurité

Installez un antivirus à jour
Activez le pare-feu de votre système
Mettez à jour régulièrement votre système d'exploitation
Mettez à jour vos navigateurs et applications

Navigateurs sécurisés

Utilisez les dernières versions de Chrome, Firefox, Edge
Activez la navigation sécurisée (Safe Browsing)
Installez des extensions de sécurité (uBlock Origin, Privacy Badger)
Désactivez JavaScript pour les sites non fiables (optionnel)

Extensions recommandées

uBlock Origin : Bloque les publicités et trackers
Privacy Badger : Protège la vie privée
HTTPS Everywhere : Force HTTPS quand possible
Web of Trust (WOT) : Avertit sur les sites malveillants

Que faire en cas de doute

Checklist de sécurité

Arrêtez : Ne cliquez pas, ne téléchargez pas
Vérifiez : Utilisez Ukweli ou un autre outil
Analysez : Regardez l'URL, l'expéditeur, le contenu
Contactez : Appelez l'organisation par un canal officiel
Signalez : Signalez le phishing aux autorités

Si vous avez cliqué sur un lien suspect

Fermez immédiatement le navigateur
Ne saisissez AUCUNE information
Changez vos mots de passe si vous avez saisi des identifiants
Contactez votre banque si informations bancaires exposées
Scannez votre appareil avec un antivirus
Surveillez vos comptes pour toute activité suspecte

Si vous avez saisi des informations

Changez immédiatement tous les mots de passe concernés
Contactez votre banque si informations bancaires
Activez l'authentification à deux facteurs partout
Surveillez vos comptes pendant plusieurs semaines
Signalez l'incident aux autorités compétentes

Signaux d'alarme - Résumé rapide

Alerte maximale

URL avec IP au lieu de nom de domaine
Site demandant votre mot de passe complet
Email urgent demandant une action immédiate
Site bancaire avec URL différente de l'officielle
Certificat SSL invalide ou expiré

Alerte modérée

URL avec beaucoup de tirets ou caractères aléatoires
Sous-domaine suspect (ex: paypal.com.secure-login.net)
Email avec fautes d'orthographe nombreuses
Lien raccourci sans contexte
Site demandant trop d'informations personnelles

Probablement sûr

URL claire et reconnaissable
Certificat SSL valide
Site officiel connu
Pas de demande d'informations sensibles
Communication cohérente et professionnelle

Ressources utiles

Outils d'analyse

Ukweli : Votre outil d'analyse actuel
VirusTotal : https://www.virustotal.com
URLScan : https://urlscan.io
Google Safe Browsing : Intégré dans Chrome/Firefox

Bases de données de phishing

PhishTank : https://www.phishtank.com
OpenPhish : https://openphish.com
Anti-Phishing Working Group : https://apwg.org

Organismes de signalement

France

Signal Spam : https://www.signal-spam.fr
Phishing Initiative : https://www.phishing-initiative.fr
ANSSI : https://www.ssi.gouv.fr

International

FBI Internet Crime Complaint Center (IC3)
Europol (pour l'Europe)

Formations et guides

ANSSI - Guide d'hygiène informatique : https://www.ssi.gouv.fr/guide/guide-dhygiene-informatique/
Cybermalveillance.gouv.fr : https://www.cybermalveillance.gouv.fr
CERT-FR : https://www.cert.ssi.gouv.fr

Conseils supplémentaires

Pour les entreprises

Formez vos employés régulièrement
Mettez en place des politiques de sécurité claires
Utilisez des outils de filtrage d'emails
Testez régulièrement avec des simulations de phishing
Ayez un plan de réponse en cas d'incident

Pour les particuliers

Restez informé des nouvelles techniques de phishing
Partagez ces bonnes pratiques avec votre entourage
Utilisez des mots de passe forts et uniques
Activez l'authentification à deux facteurs partout
Faites confiance à votre instinct : si c'est suspect, c'est probablement suspect

Pour les développeurs

Validez toujours les URLs côté serveur
Utilisez HTTPS partout
Implémentez la protection CSRF
Validez les entrées utilisateur
Utilisez des bibliothèques de sécurité éprouvées

En cas d'urgence

Si vous pensez être victime d'une attaque de phishing :

Ne paniquez pas
Isolez l'appareil du réseau si possible
Changez immédiatement tous les mots de passe
Contactez votre banque si informations bancaires
Signalez l'incident aux autorités
Consultez un expert en cybersécurité si nécessaire

Checklist quotidienne

Avant de cliquer sur un lien ou de saisir des informations :

☐ L'URL est-elle claire et reconnaissable ?
☐ Le certificat SSL est-il valide ?
☐ Ai-je initié cette demande ?
☐ Le site demande-t-il des informations sensibles ?
☐ Y a-t-il un sentiment d'urgence artificiel ?
☐ L'expéditeur est-il légitime ?
☐ Ai-je vérifié avec un outil d'analyse ?

En cas de doute, ne cliquez pas !

Dernière mise à jour : 2024
Ce guide est fourni à titre informatif. En cas de doute, consultez toujours un expert en cybersécurité.

FAQ (Foire aux questions)

Questions générales

Combien de temps prend une analyse ?

Une analyse complète prend généralement entre 30 et 60 secondes, selon la disponibilité des APIs externes et la complexité de l'URL analysée.

Les analyses sont-elles mises en cache ?

Par défaut, les analyses ne sont pas mises en cache pour garantir des résultats toujours à jour. Chaque analyse est exécutée complètement.

Quelle est la limite de taille pour les fichiers ?

La limite actuelle est de 100MB par fichier. Cette limite peut être ajustée dans la configuration.

Puis-je utiliser l'API sans interface web ?

Oui, l'API REST est complètement indépendante de l'interface web et peut être utilisée directement depuis n'importe quelle application.

Questions techniques

Quels langages de programmation sont supportés ?

L'API REST peut être utilisée depuis n'importe quel langage supportant HTTP/JSON (Python, JavaScript, Go, Java, etc.).

Comment gérer les timeouts ?

Les timeouts sont configurés automatiquement. Si une API ne répond pas dans les délais, l'analyse continue avec les autres APIs disponibles.

Les clés API sont-elles stockées de manière sécurisée ?

Oui, les clés API sont stockées de manière sécurisée et ne sont jamais transmises à des tiers.

Dépannage

Problèmes courants

L'analyse ne démarre pas

Vérifiez que les clés API sont correctement configurées
Vérifiez les logs du serveur pour les erreurs
Assurez-vous que le serveur est accessible

Erreur "API key not set"

Configurez les clés API manquantes via l'interface de paramètres ou les variables d'environnement.

Timeout lors de l'analyse

Les timeouts peuvent survenir si les APIs externes sont lentes. Augmentez la valeur de API_TIMEOUT si nécessaire.

Erreur de connexion à Supabase

Les problèmes de connexion à Supabase doivent être résolus par l'administrateur. Contactez le support à support.ukweli@ngitcorp.com si vous rencontrez ce problème.

Support

Pour obtenir de l'aide ou signaler un problème :

Consultez cette documentation complète
Vérifiez les logs du serveur pour les erreurs détaillées
Consultez la section FAQ ci-dessus
Contactez l'équipe de support par email

Support : support.ukweli@ngitcorp.com • Développé par NGIT Corp