Documentation
API

Intégrez PAKKT dans vos outils et panels. Authentification par clé API, réponses JSON. Base URL : https://api.pakkt.io/api/v1

Sommaire

• Authentification
• Agents
• Règles XDP (PAKKT Engine)
• IP Whitelist / Blacklist
• Métriques
• Marketplace
• Firewall nftables
• Erreurs

Authentification

Toutes les requêtes doivent inclure votre clé API dans le header X-API-Key.

curl https://api.pakkt.io/api/v1/agents \
  -H "X-API-Key: pakkt_pub_VOTRE_CLE"

• Clés API générables depuis le panel (Clés API).
• Rate limit : 60 requêtes / minute par clé.
• La clé n'est affichée qu'une seule fois à la création, conservez-la en lieu sûr.

Agents

Listez et consultez les agents connectés à votre compte.

GET /agents

Liste tous vos agents.

Réponse

[
  {
    "id": "01J5...",
    "name": "VPS Paris",
    "hostname": "debian",
    "iface": "ens3",
    "version": "a1b2c3d",
    "status": "online",
    "last_seen_at": "2026-03-16T12:00:00Z",
    "created_at": "2026-03-01T10:00:00Z"
  }
]

GET /agents/:id

Détail d'un agent.

Réponse

{
  "id": "01J5...",
  "name": "VPS Paris",
  "hostname": "debian",
  "iface": "ens3",
  "version": "a1b2c3d",
  "status": "online",
  "last_seen_at": "2026-03-16T12:00:00Z",
  "created_at": "2026-03-01T10:00:00Z"
}

Règles XDP (PAKKT Engine)

Créez et gérez des règles de protection XDP via le PAKKT Engine. Chaque règle est un slot dans le moteur XDP (max 256 par interface), sans rechargement réseau nécessaire.

GET /agents/:id/programs

Liste toutes les règles XDP d'un agent.

Réponse

[
  {
    "id": "01J6...",
    "name": "Anti-Flood FiveM",
    "filename": "pakkt_engine.bpf.o",
    "iface": "ens3",
    "port_range_start": 30120,
    "port_range_end": 30120,
    "protocol": 17,
    "rule_type": 1,
    "max_pps": 5000,
    "status": "loaded",
    "loaded_at": "2026-03-15T08:00:00Z"
  }
]

POST /agents/:id/engine-rules

Créer une règle PAKKT Engine sur un agent.

Body

{
  "name": "Rate Limit SSH",
  "port_range_start": 22,
  "port_range_end": 22,
  "protocol": 6,
  "rule_type": 1,
  "max_pps": 500,
  "max_port_pps": 0,
  "min_pkt_size": 0,
  "max_pkt_size": 0
}

Réponse

{
  "id": "01J7...",
  "name": "Rate Limit SSH",
  "status": "pending_load",
  "created_at": "2026-03-16T12:30:00Z"
}

• protocol : 0 (any), 6 (TCP), 17 (UDP), 1 (ICMP)
• rule_type : 0 (block), 1 (rate_limit), 2 (allow_only)
• max_pps : paquets/seconde par IP source (0 = désactivé)
• max_port_pps : paquets/seconde globaux sur le port (0 = désactivé)
• L'interface est détectée automatiquement depuis l'agent, pas besoin de la spécifier
• Dedup : retourne 409 si une règle active existe déjà sur la même plage de ports

DELETE /agents/:id/programs/:prog_id

Décharger une règle XDP.

Réponse

204 No Content

IP Whitelist / Blacklist

Gérez les listes blanches et noires d'IPs par agent. Les entrées sont synchronisées via le heartbeat et appliquées au niveau XDP (kernel).

GET /agents/:id/ip-list

Liste les entrées IP d'un agent.

Paramètres query

Nom	Description	Exemple
type	blacklist ou whitelist (optionnel, retourne tout si omis)	blacklist

Réponse

[
  {
    "id": "01K2...",
    "list_type": "blacklist",
    "ip_address": "203.0.113.42",
    "reason": "Flood UDP détecté",
    "status": "active",
    "expires_at": "2026-03-17T12:00:00Z",
    "created_at": "2026-03-16T12:00:00Z"
  }
]

POST /agents/:id/ip-list

Ajouter une IP à la whitelist ou blacklist.

Body

{
  "list_type": "blacklist",
  "ip_address": "203.0.113.42",
  "reason": "Flood UDP détecté",
  "expires_at": "2026-03-17T12:00:00Z"
}

Réponse

{
  "id": "01K2...",
  "status": "pending_add",
  "created_at": "2026-03-16T12:00:00Z"
}

• list_type : blacklist ou whitelist
• expires_at : ISO 8601 (optionnel, blacklist uniquement, null = permanent)
• Statut initial : pending_add → active après confirmation agent

DELETE /agents/:id/ip-list/:entry_id

Retirer une entrée IP.

Réponse

204 No Content

• Passe en pending_remove puis est supprimée après confirmation agent

Métriques

Accédez aux métriques de trafic de vos agents : résumé temps réel ou historique.

GET /metrics/:agent_id/summary

Résumé des métriques sur une fenêtre temporelle.

Paramètres query

Nom	Description	Exemple
window	10m, 1h, ou 24h (défaut : 1h)	24h

Réponse

{
  "total_passed": "142857",
  "total_dropped": "4821",
  "total_bytes_passed": "89421300",
  "total_bytes_dropped": "2890400",
  "top_ports": [
    {
      "port": 30120,
      "packets_passed": "85420",
      "packets_dropped": "3200",
      "bytes_passed": "54128000",
      "bytes_dropped": "1920000"
    }
  ]
}

GET /metrics/:agent_id

Métriques historiques avec buckets temporels.

Paramètres query

Nom	Description	Exemple
from	Date ISO de début (défaut : 24h)	2026-03-15T00:00:00Z
to	Date ISO de fin (défaut : maintenant)	2026-03-16T00:00:00Z
interval	1m, 5m, ou 1h (défaut : 1m)	5m
port	Filtrer par port (optionnel)	30120

Réponse

[
  {
    "bucket": "2026-03-16T12:00:00Z",
    "port": 30120,
    "packets_passed": "8542",
    "packets_dropped": "124",
    "bytes_passed": "5412800",
    "bytes_dropped": "67200"
  }
]

Marketplace

Récupérez les templates de protection validés par PAKKT, filtrables par catégorie.

GET /marketplace/templates

Liste les templates marketplace.

Paramètres query

Nom	Description	Exemple
category	Filtrer par catégorie (optionnel)	Gaming

Réponse

[
  {
    "id": "tpl_fivem_shield",
    "title": "FiveM Shield",
    "description": "Protection anti-flood UDP pour FiveM",
    "type": "xdp",
    "category": "Gaming",
    "filename": "pakkt_engine.bpf.o",
    "protocol": 17,
    "rule_type": 1,
    "port_range_start": 30120,
    "port_range_end": 30130,
    "max_pps": 5000,
    "risk": "low"
  }
]

• Les templates nftables ont un champ nft avec chain, protocol, action, etc.
• Catégories : Gaming, Web, Infrastructure, Database

Firewall nftables

Gérez les règles nftables (firewall stateful) de vos agents.

GET /agents/:id/firewall

Liste les règles nftables d'un agent.

Réponse

[
  {
    "id": "01K8...",
    "name": "Anti brute-force SSH",
    "chain": "input",
    "protocol": "tcp",
    "port_start": 22,
    "port_end": 22,
    "action": "limit",
    "limit_rate": 5,
    "limit_unit": "minute",
    "conntrack": "new",
    "status": "active",
    "is_system": false,
    "packets_total": 4821,
    "bytes_total": 289260
  }
]

POST /agents/:id/firewall

Créer une règle nftables.

Body

{
  "name": "Block Redis",
  "chain": "input",
  "protocol": "tcp",
  "port_start": 6379,
  "port_end": 6379,
  "action": "drop"
}

Réponse

{
  "id": "01K9...",
  "name": "Block Redis",
  "status": "pending_add",
  "created_at": "2026-03-16T15:00:00Z"
}

• chain : input (défaut), forward, ou output
• action : drop, accept, reject, ou limit
• limit nécessite limit_rate et limit_unit (second ou minute)
• conntrack : new, established, related (ou combinaison CSV)
• Les règles système (is_system: true) ne peuvent pas être supprimées

DELETE /agents/:id/firewall/:rule_id

Supprimer une règle nftables.

Réponse

204 No Content

Erreurs

L'API retourne des codes HTTP standard avec un corps JSON.

Code	Description
400	Requête invalide (paramètres manquants ou incorrects)
401	Clé API manquante ou invalide
402	Compte suspendu (paiement en retard)
404	Ressource non trouvée
409	Conflit (ex: règle active existe déjà sur cette plage de ports)
422	Validation échouée (ex: agent pas encore connecté, ports invalides)
429	Rate limit atteint (60 req/min par clé)
500	Erreur interne