Condividi tramite

Individuare le API shadow utilizzando Dev Proxy

Usando il Centro API di Azure si catalogano le API usate nell'organizzazione. In questo modo è possibile indicare quali API si usano, dove si trova l'API nel ciclo di vita e chi contattare in caso di problemi. In breve, avere un catalogo aggiornato di API consente di migliorare la postura di sicurezza, di governance e di conformità.

Quando si compila un’app, soprattutto se si integrano nuovi scenari, è possibile usare API non registrate nel Centro API di Azure. Queste API sono chiamate API shadow. Le API shadow sono API non registrate nell’organizzazione. Potrebbero essere API che non sono ancora state registrate o che non devono essere usate nell’organizzazione.

Un modo per verificare la presenza di API shadow consiste nell'usare Dev Proxy. Dev Proxy è un simulatore di API che intercetta e analizza le richieste API dalle applicazioni. Una funzionalità di Dev Proxy controlla se le richieste API intercettate appartengono alle API registrate nel Centro API.

Screenshot di un prompt dei comandi in cui Dev Proxy controlla se le richieste API registrate sono effettivamente registrate nel Centro API di Azure.

Prima di iniziare

Per rilevare le API shadow, è necessario avere un'istanza del Centro API di Azure con informazioni sulle API usate nell'organizzazione. Se non ne è già stato creato uno, vedere Avvio rapido: Creare il centro API. È anche necessario installare Dev Proxy.

Copiare le informazioni del Centro API

Dalla pagina Panoramica dell'istanza del Centro API di Azure copiare il nome dell'istanza del Centro API, il nome del gruppo di risorse e l' ID sottoscrizione. Queste informazioni sono necessarie per configurare il proxy ApiCenterOnboardingPlugin di sviluppo in modo che possa connettersi all'istanza di Centro API di Azure.

Ritaglio di schermata della pagina Panoramica del Centro API di Azure con diverse proprietà evidenziate.

Configurare il proxy di sviluppo

Per verificare se un’app usa API shadow, è necessario abilitare ApiCenterOnboardingPlugin nel file di configurazione di Dev Proxy. Per creare un report delle API usate dall’app, aggiungere un reporter.

Abilitare ApiCenterOnboardingPlugin

Nel file devproxyrc.json aggiungere la configurazione seguente:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": false
  }
}

Nelle proprietà subscriptionId, resourceGroupName e serviceName specificare le informazioni sull'istanza del Centro API di Azure.

Nella proprietà urlsToWatch specificare gli URL usati dall'app.

Suggerimento

Usare l’estensione Dev Proxy Toolkit di Visual Studio Code per gestire facilmente la configurazione del Dev Proxy.

Aggiungere un reporter

ApiCenterOnboardingPlugin genera un report delle API usate dall'app. Per visualizzare questo report, aggiungere un reporter al file di configurazione del proxy di sviluppo. Dev Proxy offre diversi generatori di rapporti. In questo esempio viene usato il reporter di testo normale.

Aggiornare il file devproxyrc.json con un riferimento al reporter di testo normale:

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    },
    {
      "name": "PlainTextReporter",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": false
  }
}

Controllare se l’app usa le API shadow

Per verificare se l'app usa API shadow, connettersi alla sottoscrizione di Azure, eseguire Dev Proxy e consentire l’intercettazione delle richieste API dall’app. Dev Proxy confronta quindi le informazioni sulle richieste API con le informazioni del Centro API di Azure e segnala le API non registrate nel Centro API.

Connettersi alla sottoscrizione di Azure

Dev Proxy usa le informazioni del Centro API di Azure per determinare se l’app usa le API shadow. Per ottenere queste informazioni è necessaria una connessione alla sottoscrizione di Azure. È possibile connettersi alla sottoscrizione di Azure in diversi modi.

Eseguire il Dev Proxy

Dopo esserti connesso alla tua sottoscrizione di Azure, avvia Dev Proxy. Se si avvia il proxy di sviluppo dalla stessa cartella in cui si trova il file devproxyrc.json, viene automaticamente caricata la configurazione. In alternativa, specificare il percorso del file di configurazione usando l'opzione --config-file.

All'avvio, Dev Proxy verifica che possa connettersi alla tua sottoscrizione di Azure. Quando la connessione ha esito positivo, viene visualizzato un messaggio simile al seguente:

 info    Plugin ApiCenterOnboardingPlugin connecting to Azure...
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

Premere r per avviare la registrazione delle richieste API dall'app.

Usare l'app

Usare l’app normalmente. Il proxy di sviluppo intercetta le richieste API e archivia in memoria le relative informazioni. Nella riga di comando in cui viene eseguito Dev Proxy, dovrebbero essere visualizzate informazioni sulle richieste API eseguite dall’app.

 info    Plugin ApiCenterOnboardingPlugin connecting to Azure...
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

◉ Recording... 

 req   ╭ GET https://jsonplaceholder.typicode.com/posts
 api   ╰ Passed through

 req   ╭ DELETE https://jsonplaceholder.typicode.com/posts/1
 api   ╰ Passed through

Controllare le API nascoste

Arrestare la registrazione premendo s. Il proxy di sviluppo si connette all'istanza del Centro API e confronta le informazioni relative alle richieste con le informazioni del Centro API.

 info    Plugin ApiCenterOnboardingPlugin connecting to Azure...
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

◉ Recording... 

 req   ╭ GET https://jsonplaceholder.typicode.com/posts
 api   ╰ Passed through

 req   ╭ DELETE https://jsonplaceholder.typicode.com/posts/1
 api   ╰ Passed through
○ Stopped recording
 info    Checking if recorded API requests belong to APIs in API Center...
 info    Loading APIs from API Center...
 info    Loading API definitions from API Center...

Al termine dell’analisi, Dev Proxy crea un report in un file chiamato ApiCenterOnboardingPlugin_PlainTextReporter.txt con il contenuto seguente:

New APIs that aren't registered in Azure API Center:

https://jsonplaceholder.typicode.com:
  DELETE https://jsonplaceholder.typicode.com/posts/1

APIs that are already registered in Azure API Center:

GET https://jsonplaceholder.typicode.com/posts

Eseguire automaticamente l'integrazione delle API nascoste

ApiCenterOnboardingPlugin non solo può rilevare le API shadow, ma anche eseguirne automaticamente l’onboarding nel Centro API. Per eseguire automaticamente l’onboarding delle API shadow, nel file di configurazione di Dev Proxy, aggiornare createApicEntryForNewApis a true.

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    },
    {
      "name": "PlainTextReporter",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": true
  }
}

Quando si esegue Dev Proxy con createApicEntryForNewApis impostato su true, questo crea automaticamente nuove voci API nel Centro API di Azure per le API shadow rilevate.

Screenshot del Centro API che mostra una nuova API di cui è stato eseguito l’onboarding.

Eseguire automaticamente l’onboarding delle API shadow con specifiche OpenAPI

Quando si sceglie di eseguire automaticamente l’onboarding delle API shadow nel Centro API, è possibile impostare Dev Proxy per generare le specifiche OpenAPI per l’API. L’onboarding delle API con specifiche OpenAPI accelera il processo di integrazione degli endpoint mancanti e fornisce le informazioni necessarie sull'API. Quando ApiCenterOnboardingPlugin rileva che Dev Proxy ha creato una nuova specifica OpenAPI, la associa all’API di cui è stato eseguito l’onboarding corrispondente nel Centro API.

Per generare automaticamente le specifiche OpenAPI per le API di cui è stato eseguito l’onboarding, aggiornare la configurazione di Dev Proxy per includere OpenApiSpecGeneratorPlugin.

{
  "$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
  "plugins": [
    {
      "name": "OpenApiSpecGeneratorPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    },
    {
      "name": "ApiCenterOnboardingPlugin",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
      "configSection": "apiCenterOnboardingPlugin"
    },
    {
      "name": "PlainTextReporter",
      "enabled": true,
      "pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
    }
  ],
  "urlsToWatch": [
    "https://jsonplaceholder.typicode.com/*"
  ],
  "apiCenterOnboardingPlugin": {
    "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
    "resourceGroupName": "demo",
    "serviceName": "contoso-api-center",
    "workspaceName": "default",
    "createApicEntryForNewApis": true
  }
}

Importante

Dev Proxy esegue i plug-in nell’ordine in cui sono registrati nella configurazione. È necessario registrare prima OpenApiSpecGeneratorPlugin, in modo che possa creare specifiche OpenAPI prima che ApiCenterOnboardingPlugin esegua l’onboarding di nuove API.

Quando si esegue Dev Proxy con questa configurazione, vengono create automaticamente nuove voci API nel Centro API di Azure per le API shadow rilevate. Per ogni nuova API, Dev Proxy genera una specifica OpenAPI e la associa all’API di cui è stato eseguito l’onboarding corrispondente nel Centro API.

 info    Plugin ApiCenterOnboardingPlugin connecting to Azure...
 info    Listening on 127.0.0.1:8000...

Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
Press CTRL+C to stop Dev Proxy

◉ Recording... 

 req   ╭ GET https://jsonplaceholder.typicode.com/posts
 api   ╰ Passed through

 req   ╭ DELETE https://jsonplaceholder.typicode.com/posts/1
 api   ╰ Passed through
○ Stopped recording
 info    Creating OpenAPI spec from recorded requests...
 info    Created OpenAPI spec file jsonplaceholder.typicode.com-20240614104931.json
 info    Checking if recorded API requests belong to APIs in API Center...
 info    Loading APIs from API Center...
 info    Loading API definitions from API Center...
 info    New APIs that aren't registered in Azure API Center:

https://jsonplaceholder.typicode.com:
  DELETE https://jsonplaceholder.typicode.com/posts/1
 info    Creating new API entries in API Center...
 info      Creating API new-jsonplaceholder-typicode-com-1718354977 for https://jsonplaceholder.typicode.com...
 info    DONE

Screenshot del Centro API di Azure che mostra una nuova API di cui è stato eseguito l’onboarding con una specifica OpenAPI.

Riassunto

Usando Dev Proxy e il relativo ApiCenterOnboardingPlugin, è possibile verificare se l'app usa le API shadow. Il plug-in analizza le richieste API dall’app e segnala le richieste API non registrate nel Centro API di Azure. Il plug-in consente di eseguire facilmente l’onboarding delle API mancanti nel Centro API. Combinando il plug-in ApiCenterOnboardingPlugin con OpenApiSpecGeneratorPlugin, è possibile generare automaticamente specifiche OpenAPI per le API di cui è appena stato eseguito l’onboarding. È possibile eseguire questo controllo manualmente o eseguire un’integrazione con la pipeline CI/CD per assicurarsi che l’app usi le API registrate prima di rilasciarla nell’ambiente di produzione.

Maggiori informazioni

  • Last updated on