Démarrage rapide des plugins

Ce guide vous permet de passer rapidement d'un dossier vide à un plugin opérationnel.

1) Créer un plugin minimal avec un backend uniquement

Créez un dossier contenant les fichiers suivants :

my-plugin/
  manifest.json
  backend/
    script.js

manifest.json :

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "0.1.0",
  "plugins": [
    {
      "kind": "backend",
      "id": "my-plugin-backend",
      "entrypoint": "backend/script.js"
    }
  ]
}

backend/script.js :

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

  sdk.events.onInterceptResponse(function(req, res) {
    if (!res) return;
    if (res.getCode() === 403) {
      sdk.console.warn("403 on " + req.getUrl());
    }
  });
}

Installez le plugin depuis Plugins > Installer, sélectionnez le dossier, activez le plugin et vérifiez que le message Plugin started apparaît dans les journaux.

2) Si vous utilisez TypeScript

Utilisez cette structure :

my-plugin/
  manifest.json
  backend/
    src/index.ts

Regroupez le code avec la commande suivante :

pnpm add -D @ogmabox/ogma-sdk esbuild typescript
pnpm exec esbuild backend/src/index.ts \
  --bundle \
  --platform=neutral \
  --format=iife \
  --external:@ogma/sdk --external:@ogmabox/ogma-sdk \
  --outfile=backend/script.js

Installez ensuite le dossier comme indiqué ci-dessus.

3) Ajouter un frontend ultérieurement

N'ajoutez une entrée frontend et des fichiers d'interface que si vous avez besoin d'un panneau :

my-plugin/
  frontend/
    script.js
    style.css   # optional

Complétez ensuite manifest.json avec :

{
  "kind": "frontend",
  "id": "my-plugin-frontend",
  "entrypoint": "frontend/script.js",
  "backend": { "id": "my-plugin-backend" }
}

Pour la communication du frontend, utilisez window.ogmaSDK.ready(...) et placez les appels au backend dans les gestionnaires sdk.api.

4) Permissions généralement nécessaires

Pour l'exemple backend ci-dessus :

• aucune (les permissions par défaut, sans risque particulier, sont accordées automatiquement)

Si votre plugin envoie des requêtes sortantes, ajoutez :

"permissions": ["send_requests"]

Si votre plugin écrit des constats de sécurité, ajoutez :

"permissions": ["write_findings"]

Ne demandez que les permissions que vous utilisez réellement.

Dépannage du premier plugin

• Plugin failed to initialize : ouvrez Journaux et vérifiez que init(sdk) est défini.
• Invalid manifest : vérifiez les virgules et les guillemets du JSON.
• Aucun rappel n'est déclenché : vérifiez que le plugin est activé et que l'événement correspondant (onInterceptResponse) est enregistré.

Pour consulter les références complètes des API :

• Système de plugins
• SDK backend
• SDK frontend