Installare ed eseguire l'interfaccia della riga di comando di Defender (anteprima)

La CLI di Defender è uno strumento da riga di comando per MDASH e altri scanner di sicurezza in Microsoft Defender. Utilizza un sistema di IA multi-modello e agentico per aiutare i team di sicurezza e ingegneria a rilevare e correggere vulnerabilità del codice. Attraverso la CLI di Defender, puoi eseguire scansioni di codice agentico e applicare correzioni localmente o in pipeline CI/CD. La CLI di Defender è distribuita come eseguibile autonomo per Windows, macOS e Linux.

Prerequisiti

  • La CLI Defender supporta due metodi di autenticazione: utilizzare l'autenticazione basata su app per pipeline CI/CD e altre automazioni non interattive, e l'autenticazione interattiva per le scansioni dei terminali locali da parte degli utenti effettuati l'accesso. Le autorizzazioni necessarie dipendono dal metodo di autenticazione. Per ulteriori dettagli, vedi la configurazione di Defender CLI per la sicurezza del codice agentico.
  • Imposta la variabile di ambiente tenant, come DEFENDER_ASPM_TENANT_ID. Le variabili richieste dipendono dal metodo di autenticazione che si usa. Per ulteriori dettagli, vedi la configurazione di Defender CLI per la sicurezza del codice agentico.
  • Una copia locale del repository che vuoi analizzare.

Installare Defender CLI

Scarica il binario CLI per la tua piattaforma:

# Windows x64
Invoke-WebRequest ` 
    -Uri "https://cli.dfd.security.azure.com/public/v2/latest/Defender_win-x64.exe" ` 
    -OutFile "defender.exe"

Scansione

Di default, le scansioni vengono eseguite in modo asincrono. Questo significa che quando invii una scansione, lo scanner non aspetta che finisca. Esce immediatamente e ti restituisce un documento di lavoro. L'ID del lavoro funge da riferimento persistente che può essere successivamente utilizzato per scaricare artefatti del risultato della scansione, cancellare il lavoro, attendere il completamento del lavoro o interrogare il suo stato attuale.

Nei comandi seguenti, sostituisci il segnaposto <TARGET_SOURCE> con il percorso della directory del codice sorgente di destinazione, ad esempio my-code\project1. Se stai eseguendo la CLI di Defender dall'interno della directory del tuo codice, usa . per fare riferimento alla directory attuale.

# Step 1: Submit and get a job ID
./defender scan ai-scan submit <TARGET_SOURCE>
# Output: Job submitted: <JOB_ID>

# Step 2: Check job status
./defender status <JOB_ID>

# Step 3: (Optional) Wait for completion and download results
./defender status wait <JOB_ID> -o results.sarif

Eseguire la scansione con un profilo di scansione (Anteprima)

Un profilo di analisi seleziona i modelli di intelligenza artificiale che eseguono l'analisi. Sono disponibili due profili:

Profile Models Usa quando
gpt-general-profile GPT-5.4, GPT-5.3-Codex, GPT-5.4-Mini Analisi del codice agente per utilizzo generico (set di modelli di base).
mai-augmented-profile (anteprima) GPT-5.4, GPT-5.3-Codex, GPT-5.4-Mini + MAI-Cyber-1-Flash Vuoi che i modelli di base siano potenziati con il modello MAI-Cyber-1-Flash specializzato in cybersicurezza.

Vedere i profili disponibili e il valore predefinito corrente:

./defender scan profile model list
./defender scan profile model show-default

Eseguire un'analisi con un profilo specifico (sostituisce l'impostazione predefinita solo per questa analisi):

# Baseline profile:
./defender scan ai-scan submit <TARGET_SOURCE> --model-profile gpt-general-profile

# MAI-augmented profile:
./defender scan ai-scan submit <TARGET_SOURCE> --model-profile mai-augmented-profile

Filtrare in base alla gravità

Quando invii una scansione, puoi limitare i risultati restituiti solo a risultati di gravità alta e critica. Questo restringe l'output ai problemi che rappresentano il rischio maggiore, rendendo il triage più veloce e aiutando i team a dare priorità alla bonifica dove conta di più. Usa il --severity flag per impostare la soglia, con valori accettati di low (predefinito), medium, high, o critical.

./defender scan ai-scan submit <TARGET_SOURCE> --severity high

Gestire i lavori

Il comando Defender CLI status fornisce un accesso rapido ai lavori tracciati dal nome in codice MDASH. Ti permette di elencare tutti i lavori attualmente monitorati, visualizzare i dettagli di un lavoro specifico, bloccare e scaricare file SARIF, riscaricare il SARIF per una determinata esecuzione e altro ancora.

./defender status                         # List all tracked jobs
./defender status <JOB_ID>                # Show details of a job
./defender status result <JOB_ID>         # Download a finished report
./defender status log <JOB_ID>            # Print the path of the auto-saved debug log for a run

Scarica il risultato

Le scansioni vengono eseguite in modo asincrono di default e richiedono un po' di tempo per essere completate. Invece di controllare ripetutamente lo stato del lavoro, il wait comando attende che il lavoro si completi e scarica i risultati su un file SARIF. Per dettagli, vedi Revisionare i risultati della scansione del codice agentico dal terminale.

Il seguente comando attende la fine della scansione <JOB_ID> , poi salva i risultati su results.sarif:

./defender status wait <JOB_ID> -o results.sarif

Riscarica il risultato

Una volta che un lavoro ha raggiunto uno stato terminale (completato o fallito), scarica i risultati utilizzando il comando qui sotto. Questo comando è particolarmente utile se hai cancellato il file SARIF locale, se il comando originale wait è stato interrotto prima che terminasse, oppure se hai inviato il lavoro da una macchina ma vuoi recuperare i risultati da un'altra. Sostituisci <JOB_ID> con il tuo vero ID di lavoro.

./defender status result <JOB_ID>

Annulla processo

L'annullamento di una scansione non rimborsa i token già consumati. Durante un'analisi, MDASH effettua chiamate al modello LLM attive che utilizzano token durante l'elaborazione del lavoro. Se si annulla un'analisi già in esecuzione, MDASH interrompe la pianificazione di un nuovo lavoro, ma vengono comunque addebitati i token utilizzati prima che l'annullamento venga applicato. L'annullamento di una scansione può impedire l'ulteriore consumo di token da parte di operazioni future, ma non rimborsa i token già utilizzati.

./defender status cancel <JOB_ID>

Troubleshooting

Quando si risolvono problemi con la CLI di Defender, gli amministratori o i team di supporto possono chiederti di fornire il log salvato automaticamente per aiutare a diagnosticare il problema. Per trovare il percorso di log per una specifica esecuzione, si utilizza il seguente comando sulla stessa macchina in cui è avvenuta la scansione, sostituendolo <JOB_ID> con l'ID del lavoro della scansione.

./defender status log <JOB_ID>

Quando si risolve comportamenti inaspettati della CLI, un'opzione è rieseguire il comando con un livello di log più alto, come debug, che mostra output diagnostici più dettagliati rispetto al livello informativo predefinito. Questo può aiutarti a identificare la causa. Tuttavia, questo approccio funziona solo se riesci a riprodurre il problema rieseguendo il comando. Per adattare l'esempio qui sotto al tuo scenario:

  • Sostituire il segnaposto <failing-command> con il comando che non funziona. Ad esempio: scan ai-scan submit .
  • Impostate --log-level al livello appropriato. Valori attesi: trace, debug, info (predefinito), warn, error.
  • Facoltativamente, imposta --log-file su un percorso di file. Quando viene utilizzato questo flag, la CLI scrive l'output di debug nel file specificato invece di mostrarlo solo nella console.
./defender <failing-command> --log-level debug --log-file ./defender-debug.log

Ad esempio, se una scansione fallisce, rieseguire il comando e aggiungere il --log-level flag al comando come segue:

./defender scan ai-scan submit <TARGET_SOURCE> --log-level debug

Contenuti correlati

  • Last updated on