Importazione tramite API

L’API di DefectDojo consente soluzioni di pipeline robuste, che acquisiscono automaticamente nuove scansioni nella tua istanza. Un’automazione di questo tipo può assumere diverse forme:

• Un’importazione giornaliera che scansiona il tuo ambiente su base quotidiana e poi importa i risultati della scansione in DefectDojo (simile alla nostra funzionalità Connectors)
• Una pipeline CI/CD che scansiona il nuovo codice man mano che viene distribuito, e importa i risultati in DefectDojo come azione attivata

Queste pipeline possono essere create chiamando direttamente il nostro endpoint API /reimport con un file di scansione allegato, in un modo che ricorda molto da vicino il nostro Import Scan Form.

Nei workflow di GitHub Actions, l’azione DefectDojo ufficiale chiama questo endpoint al posto vostro. Consultare Importazione da GitHub Actions.

L’API di DefectDojo#

L’API di DefectDojo è documentata direttamente nell’app utilizzando il framework OpenAPI. Puoi accedere a questa documentazione dal Menu Utente nell’angolo in alto a destra, sotto ‘API v2 OpenAPI3’.

- La documentazione può essere usata per testare le chiamate API con vari parametri, e lo fa utilizzando il Token API del tuo utente.

Se hai bisogno di accedere a un token API per uno script o un’altra integrazione, puoi trovare questa informazione sotto l’opzione API v2 Token dello stesso menu.

Considerazioni generali sull’API#

• Sebbene la nostra documentazione OpenAPI sia dettagliata per quanto riguarda i parametri utilizzabili con ciascun endpoint, essa presuppone che il lettore abbia una solida comprensione dei concetti chiave di DefectDojo (gerarchia dei Prodotti, Riscontri, deduplicazione, ecc.).
• Gli utenti che desiderano un’integrazione di importazione funzionante ma hanno meno familiarità con DefectDojo nel suo complesso dovrebbero considerare il nostro Universal Importer.
• L’API di DefectDojo può a volte creare oggetti dati non intenzionali, in particolare se su l’endpoint /import o /reimport viene utilizzato ‘Auto-Create Context’.
• Fortunatamente, è molto difficile eliminare accidentalmente dati tramite l’API. La maggior parte degli oggetti può essere rimossa solo tramite una chiamata DELETE dedicata all’endpoint pertinente.

Note specifiche sugli endpoint /import e /reimport#

L’endpoint /reimport può essere usato sia per un’importazione iniziale, sia per un “Reimport” che estende un Test con Riscontri aggiuntivi. Non è necessario creare prima un Test con /import prima di poter usare l’endpoint /reimport. Finché ‘Auto Create Context’ è abilitato, l’endpoint /reimport può creare un nuovo Test, Engagement, Prodotto o Tipo di Prodotto. In quasi tutti i casi, puoi usare esclusivamente l’endpoint /reimport quando aggiungi dati tramite API.

Tuttavia, l’endpoint /import può essere usato invece per una pipeline in cui vuoi sempre archiviare ogni risultato di scansione in un oggetto Test distinto, anziché usare /reimport per gestire il diff all’interno di un singolo oggetto Test. Entrambe le opzioni sono accettabili, e l’endpoint che scegli dipende dalla tua struttura di reporting, o dal fatto che tu debba ispezionare un’esecuzione isolata di una Pipeline.

Utilizzo del campo Data di completamento della scansione (API: scan_date)#

DefectDojo offre un’ampia gamma di report di scanner supportati, ma non tutti i report contengono le informazioni più importanti per un utente. Il campo scan_date è una funzionalità intelligente e flessibile che permette agli utenti di impostare la data di completamento di un determinato report di scansione, e di propagarla a tutti i riscontri importati.

Questo campo non è obbligatorio, ma il valore predefinito per questo campo è la data di importazione (nel momento in cui la richiesta viene elaborata e viene restituita una risposta di successo).

Ecco i seguenti casi d’uso per questo campo, e i risultati applicati al Test:

1. Se il report non imposta la data, e scan_date non è impostato all’importazione
   • La data del Riscontro sarà il valore predefinito di scan_date
2. Se il report imposta la data, e scan_date non è impostato all’importazione
   • La data del Riscontro sarà quella impostata dal report
3. Se il report non imposta la data, e scan_date è impostato all’importazione
   • La data del Riscontro sarà quella impostata dall’utente per scan_date
4. Se il report imposta la data, e scan_date è impostato all’importazione
   • La data del Riscontro sarà quella impostata dall’utente per scan_date