Un connettore è un pacchetto Python che gira sul nodo FortiSOAR e pubblica nel Playbook Designer un elenco di azioni. Farlo funzionare vuol dire tre cose distinte, che l’esame tende a mescolare: installare il codice, salvare una o più configurazioni, e verificare che quella configurazione parli davvero col prodotto dall’altra parte del filo.
Installare: Content Hub, Connector Store e il pacchetto .tgz
Content Hub è il catalogo completo degli add-on: connettori, widget e solution pack. Il Connector Store, sotto Automation e poi Connectors, è la stessa pagina filtrata sui soli connettori. Entrambi hanno un prerequisito di rete che non produce un errore leggibile: se il repository Fortinet non è raggiungibile dall’istanza, la pagina si apre vuota.
repo.fortisoar.fortinet.comUn connettore che non arriva dal catalogo si carica dalla scheda Manage con Upload e poi Upload Connector, passando il file .tgz; la casella «Replace existing version» sostituisce la versione presente invece di affiancarla.
Le dipendenze Python si risolvono da pypi.org e dal repository Fortinet. Il caso intermedio è quello che frega: se il connettore si installa ma le dipendenze no, il connettore risulta installato lo stesso e compare «Connector Dependencies Failed To Install», con un link Install per riprovare. Dal 7.6.0 le integrazioni girano con l’utente fsr-integrations invece che con nginx, quindi gli snippet che scrivono fuori dalle due directory consentite possono rompersi dopo l’upgrade.
/opt/cyops-integrations
/tmpI permessi sono granulari per operazione: Create e Read su Connectors più Read su Playbooks per installare, Update e Read per configurare, Delete per disinstallare, Read su Security per installare dal Content Hub.
La configurazione: il flag che decide se il playbook parte
Un connettore accetta più configurazioni, una per ogni istanza del prodotto di destinazione, ciascuna con un Configuration Name univoco. Qui sta la trappola più costosa: almeno una configurazione deve essere marcata «Mark As Default Configuration», perché è quella che il connettore usa quando l’azione non ne specifica un’altra. Caso concreto che l’esame ama: sul connettore SMTP la configurazione usata per le notifiche di sistema deve essere proprio quella di default, altrimenti le notifiche non partono.
Sugli aggiornamenti di versione il comportamento non è uniforme. I campi esistenti conservano il valore. Se la nuova versione aggiunge un campo obbligatorio e info.json ne dichiara un default, il default viene proposto; se non lo dichiara e tu lasci il campo vuoto, la configurazione resta «Partially Configured» e l’errore compare nel Playbook Execution Log. Se invece cambia il tipo di un campo obbligatorio — da testo a elenco a discesa — il valore precedente non viene ereditato affatto.
Nel passo Connector del playbook scegli anche la versione. Se quella indicata non è installata il playbook non fallisce: ripiega in silenzio sulla più recente installata, confrontando major, minor e patch. Comodo in produzione, pericoloso in un quiz: «errore» è la risposta sbagliata.
Health check: Available o Disconnected, niente sfumature
L’icona Refresh nella barra Health Check invoca la funzione check_health del connettore, passandole il dizionario dei parametri di configurazione. Se parametri e connettività sono corretti la configurazione risulta Available; in ogni altro caso Disconnected. Non esistono stati intermedi, e per ingerire dati la configurazione deve essere Available.
Verify SSL è impostato su True per impostazione predefinita. Le chiamate passano dalla libreria requests, che legge un unico bundle di CA: con un certificato self-signed devi appendere a quel file il certificato, o l’intera catena in PEM, e l’indirizzo del server scritto in configurazione deve coincidere col CN del certificato.
/opt/cyops-integrations/.env/lib/python3.9/site-packages/certifi/cacert.pemSelf o Agent: dove gira davvero l’azione
Ogni configurazione ha un Target: Self, il nodo FortiSOAR corrente, oppure Agent. L’FSR Agent è il componente leggero da installare in un segmento di rete separato; riceve le azioni dal secure message exchange e gli basta connettività in uscita verso quella porta TCP, senza VPN e senza connessioni entranti. La scelta Self o Agent si ripete nel passo del playbook. Due dettagli che si dimenticano: la finestra di selezione elenca solo gli agent in stato «Remote Node Connected», e attivare o aggiornare un connettore su un agent riguarda quel solo agent, non gli altri e non il nodo base.
Chi vede, chi esegue, e dove guardare quando non funziona
Dal 7.0.0 esiste un RBAC sulle azioni: dalla scheda Actions & Playbooks si assegnano singole azioni a ruoli specifici. La sottigliezza che vale il punto intero è che il controllo scatta solo quando l’azione parte direttamente su un record. Il Playbook Designer mostra tutte le azioni a chiunque, e durante l’esecuzione di un playbook nessun controllo di ruolo viene fatto: per chiudere quella strada si marca il playbook come Private.
Anche la visibilità di una configurazione può passare da Public a Private e venire assegnata a dei team, con un effetto altrettanto parziale: chi non è nel team non vede la configurazione, ma può comunque eseguire i playbook di quel team che la usano.
Quando qualcosa non torna, i log dei connettori stanno in un file solo, e il livello predefinito è WARN: va alzato a INFO o DEBUG prima di sperare di trovarci qualcosa.
/var/log/cyops/cyops-integrations/connectors.logTutto questo è pilotabile via API dai playbook: ci sono rotte per elencare i connettori installati, creare una configurazione, leggere l’health check e invocare un’azione. L’health check richiesto con un config_id inesistente non dà errore: restituisce lo stato della configurazione di default.
GET /api/integration/connectors/
POST /api/integration/configuration/
GET /api/integration/connectors/healthcheck/imap/3.5.6/?config=a7c7df29
POST /api/integration/execute/