Référence du SDK backend des plugins

Le code backend des plugins s'exécute dans le bac à sable JavaScript d'Ogma et reçoit un objet sdk de l'application hôte.

Pour connaître le format complet des paquets de plugins, les champs du manifeste, les permissions et les exemples, commencez par le guide du système de plugins.

Point d'entrée

Les plugins backend exposent une fonction init :

async function init(sdk) {
  sdk.console.log("plugin started");
}

Ogma appelle init(sdk) lorsque le plugin est activé.

Espaces de noms principaux

Espace de noms	Fonction
sdk.console	Écrire des messages dans le tampon des journaux du plugin.
sdk.meta	Lire les métadonnées du plugin et les chemins de ses données.
sdk.events	Enregistrer des fonctions de rappel pour les événements Ogma.
sdk.requests	Interroger l'historique HTTP et les données des requêtes.
sdk.findings	Consulter ou créer des constats de sécurité lorsque les permissions le permettent.
sdk.scope	Lire les informations sur le périmètre actif.
sdk.storage	Conserver l'état du plugin sous forme de paires clé/valeur.
sdk.fs	Effectuer des opérations sur les fichiers dans le répertoire de données privé du plugin.
sdk.path	Utiliser des fonctions utilitaires pour construire des chemins dans le répertoire de données du plugin.
sdk.api	Exposer des gestionnaires backend au frontend du plugin.

Journalisation

sdk.console.log("message")
sdk.console.warn("warning")
sdk.console.error("error")

Les messages sont visibles dans l'interface des journaux du plugin. Gardez les journaux concis et évitez d'y écrire des secrets.

Métadonnées

sdk.meta.id()
sdk.meta.packageId()
sdk.meta.version()
sdk.meta.path()

Utilisez sdk.meta.path() pour les données propres au plugin. Ne présumez pas que le code du plugin exécuté en bac à sable peut accéder à des chemins arbitraires du système de fichiers.

sdk.storage.set("key", "value")
sdk.storage.get("key")
sdk.storage.keys()
sdk.storage.delete("key")
sdk.storage.clear()

sdk.fs.readFile("relative/file.txt")
sdk.fs.writeFile("relative/file.txt", "text")
sdk.fs.appendFile("relative/file.txt", "more")
sdk.fs.exists("relative/file.txt")
sdk.fs.existsSync("relative/file.txt")
sdk.fs.mkdir("relative/dir")
sdk.path.join("a", "b", "c")

Événements

sdk.events.onInterceptRequest(function(req) {
  return req
})

sdk.events.onInterceptResponse(function(req, res) {
  sdk.console.log(res.getCode())
})

sdk.events.onProjectChange(function() {
  sdk.console.log("project changed")
})

Les fonctions de rappel doivent être rapides. Les traitements longs doivent être déclenchés par des actions explicites de l'utilisateur ou par des gestionnaires de l'API backend.

Gestionnaires de la passerelle frontend

Les plugins backend peuvent exposer des gestionnaires destinés aux panneaux frontend des plugins :

sdk.api.register("ping", async function(input) {
  return { ok: true, input: input };
});

Le frontend appelle le gestionnaire via le SDK frontend d'Ogma. Voir la référence du SDK frontend.

Exigences de sécurité

• Considérez le trafic HTTP, les constats, les journaux et les exports comme des données sensibles.
• Ne demandez que les permissions nécessaires à votre plugin.
• Ne journalisez jamais par défaut les identifiants d'authentification, les cookies, les jetons porteurs ou le trafic privé.
• Veillez à ce que le comportement du plugin soit explicite et compréhensible pour l'utilisateur.