Risk API

Endpoints d'evaluation de risque, de monitoring de securite et de gestion des evenements de securite. Le systeme implemente un moteur de detection de fraude base sur des regles.

Base URL : /api/v2/risk

Endpoints

Methode	Endpoint	Description	Auth
GET	/risk/score	Score de risque du compte	Oui
GET	/risk/events	Evenements de securite	Oui
GET	/risk/events/:id	Details d'un evenement	Oui
POST	/risk/events/:id/acknowledge	Acquitter un evenement	Oui
GET	/risk/overview	Vue d'ensemble securite	Oui

---

GET /risk/score

Obtenir le score de risque actuel du compte.

GET /api/v2/risk/score
Authorization: Bearer <access_token>

Reponse 200 OK

{
  "score": 25,
  "level": "LOW",
  "factors": [
    {
      "type": "NEW_DEVICE",
      "impact": 15,
      "description": "Login from new device",
      "occurredAt": "2025-01-15T08:00:00Z"
    },
    {
      "type": "LOCATION_CHANGE",
      "impact": 10,
      "description": "Login from new city",
      "occurredAt": "2025-01-15T08:00:00Z"
    }
  ],
  "recommendation": "ALLOW",
  "lastCalculatedAt": "2025-01-15T10:30:00Z"
}

---

GET /risk/events

Lister les evenements de securite du compte.

GET /api/v2/risk/events?severity=HIGH&acknowledged=false&page=1&limit=20
Authorization: Bearer <access_token>

Query Parameters

Parametre	Type	Defaut	Description
type	string	--	Filtrer par type d'evenement
severity	string	--	Filtrer par severite
acknowledged	boolean	--	Filtrer par acquittement
from	ISO date	30 jours	Date de debut
to	ISO date	maintenant	Date de fin
page	number	1	Numero de page
limit	number	20	Resultats par page

Reponse 200 OK

{
  "data": [
    {
      "id": "event-uuid-1",
      "type": "IMPOSSIBLE_TRAVEL",
      "severity": "HIGH",
      "description": "Login detected 500km away within 30 minutes",
      "metadata": {
        "previousLocation": {
          "city": "Paris",
          "country": "France"
        },
        "newLocation": {
          "city": "London",
          "country": "UK"
        },
        "distance": 344,
        "timeDelta": 1800
      },
      "action": "CHALLENGE",
      "acknowledged": false,
      "createdAt": "2025-01-15T09:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "unacknowledged": 1
  }
}

---

POST /risk/events/:id/acknowledge

Acquitter un evenement de risque (marquer comme examine).

POST /api/v2/risk/events/:id/acknowledge
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "note": "This was me traveling for work"
}

Reponse 200 OK

{
  "id": "event-uuid",
  "acknowledged": true,
  "acknowledgedAt": "2025-01-15T10:30:00Z",
  "note": "This was me traveling for work"
}

---

GET /risk/overview

Vue d'ensemble complete de la securite du compte.

GET /api/v2/risk/overview
Authorization: Bearer <access_token>

Reponse 200 OK

{
  "riskScore": {
    "current": 25,
    "level": "LOW",
    "trend": "STABLE"
  },
  "summary": {
    "totalEvents": 12,
    "unacknowledgedEvents": 1,
    "last30Days": {
      "criticalEvents": 0,
      "highEvents": 1,
      "mediumEvents": 3,
      "lowEvents": 8
    }
  },
  "devices": {
    "total": 3,
    "trusted": 2,
    "suspicious": 0,
    "new": 1
  },
  "sessions": {
    "active": 2,
    "maxAllowed": 4,
    "unusualLocations": 0
  },
  "recentActivity": {
    "lastLogin": "2025-01-15T08:00:00Z",
    "lastPasswordChange": "2024-12-01T00:00:00Z",
    "lastProfileChange": "2025-01-10T14:00:00Z"
  },
  "recommendations": [
    {
      "type": "REVIEW_DEVICES",
      "priority": "LOW",
      "message": "You have 1 new device. Review your device list.",
      "actionUrl": "/settings/devices"
    }
  ]
}

Types d'evenements de risque

Type	Description	Severite par defaut
NEW_DEVICE	Connexion depuis un appareil non reconnu	LOW
LOCATION_CHANGE	Connexion depuis un nouvel emplacement	LOW
IMPOSSIBLE_TRAVEL	Connexion geographiquement impossible	HIGH
FAILED_LOGINS	Multiples tentatives de connexion echouees	MEDIUM
BRUTE_FORCE	Attaque brute-force suspectee	CRITICAL
CONCURRENT_SESSIONS	Limite de sessions depassee	MEDIUM
VPN_PROXY	Connexion depuis un VPN/proxy connu	LOW
ACCOUNT_SHARING	Partage de compte suspecte	MEDIUM
PASSWORD_SPRAY	Meme mot de passe sur plusieurs comptes	HIGH
RATE_LIMIT_EXCEEDED	Violations repetees du rate limit	MEDIUM

Niveaux de severite

Severite	Impact score	Description
CRITICAL	+40 a +50	Action immediate requise
HIGH	+25 a +40	Investigation rapide
MEDIUM	+15 a +25	Surveiller la situation
LOW	+5 a +15	Informatif

Calcul du score de risque

Score	Niveau	Action recommandee
0-30	LOW	ALLOW (acces normal)
31-60	MEDIUM	STEP_UP (verification supplementaire)
61-85	HIGH	CHALLENGE (re-authentification)
86-100	CRITICAL	BLOCK (acces bloque)

Decroissance du score

• -5 points par jour sans incident
• Score minimum : 0
• Reinitialisation lors d'un changement de mot de passe

Regles du moteur de risque

Deplacement impossible

SI distance_connexion > 500km ET temps_depuis_derniere_connexion < 1 heure
ALORS score += 40, severite = HIGH, action = CHALLENGE

SI distance_connexion > 300km ET temps_depuis_derniere_connexion < 2 heures
ALORS score += 25, severite = MEDIUM, action = STEP_UP

Tentatives de connexion echouees

SI tentatives_echouees >= 3 en 10 minutes
ALORS score += 15, severite = MEDIUM, action = STEP_UP

SI tentatives_echouees >= 5 en 10 minutes
ALORS score += 25, severite = HIGH, action = ACCOUNT_LOCK

Confiance de l'appareil

SI device.trustScore < 20
ALORS score += 20, severite = MEDIUM, action = STEP_UP

SI device.status == SUSPICIOUS
ALORS score += 35, severite = HIGH, action = CHALLENGE

VPN/Proxy

SI ip DANS liste_vpn_connus OU ip DANS liste_proxy_connus
ALORS score += 20, severite = LOW, action = LOG

Actions

Action	Description
ALLOW	Acces normal
LOG	Autoriser mais enregistrer pour examen
STEP_UP	Verification supplementaire requise
CHALLENGE	Re-authentification requise
BLOCK	Acces refuse
ACCOUNT_LOCK	Verrouillage temporaire du compte

Codes d'erreur

Code	HTTP	Description
RISK_001	404	Evenement de risque introuvable
RISK_002	400	Evenement deja acquitte
RISK_003	403	Acces aux evenements d'un autre compte interdit