Individuare API shadow usando Dev Proxy

Articolo
11/25/2024

Usando il Centro API di Azure si catalogano le API usate nell’organizzazione. In questo modo è possibile indicare quali API si usano, a che punto si trovano nel loro 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.

Prima di iniziare

Per rilevare le API shadow, è necessario disporre di 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. Inoltre, è necessario installare Dev Proxy.

Copiare le informazioni del Centro API

Nella pagina di 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 ApiCenterOnboardingPlugin del Dev Proxy in modo che possa connettersi all’istanza del Centro API di Azure.

Configurare Dev Proxy

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 Toolkit del Proxy di sviluppo di Visual Studio Code per gestire facilmente la configurazione del proxy di sviluppo.

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. Il proxy di sviluppo offre diversi reporter. 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 proxy di sviluppo

Dopo la connessione alla sottoscrizione di Azure, avviare il proxy di sviluppo. 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 del proxy di sviluppo verificare che si connetta alla 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 shadow

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’onboarding delle API shadow

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.

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. Eseguire l’onboarding di API con specifiche OpenAPI accelera l’onboarding di 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

Riepilogo

Usando Dev Proxy e ApiCenterOnboardingPlugin, è possibile verificare se l’app usa 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.

Condividi tramite

Individuare API shadow usando Dev Proxy

Prima di iniziare

Copiare le informazioni del Centro API

Configurare Dev Proxy

Abilitare `ApiCenterOnboardingPlugin`

Aggiungere un reporter

Controllare se l’app usa le API shadow

Connettersi alla sottoscrizione di Azure

Eseguire il proxy di sviluppo

Usare l'app

Controllare le API shadow

Eseguire automaticamente l’onboarding delle API shadow

Eseguire automaticamente l’onboarding delle API shadow con specifiche OpenAPI

Riepilogo

Ulteriori informazioni

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Individuare API shadow usando Dev Proxy

Prima di iniziare

Copiare le informazioni del Centro API

Configurare Dev Proxy

Abilitare ApiCenterOnboardingPlugin

Aggiungere un reporter

Controllare se l’app usa le API shadow

Connettersi alla sottoscrizione di Azure

Eseguire il proxy di sviluppo

Usare l'app

Controllare le API shadow

Eseguire automaticamente l’onboarding delle API shadow

Eseguire automaticamente l’onboarding delle API shadow con specifiche OpenAPI

Riepilogo

Ulteriori informazioni

Commenti e suggerimenti

Risorse aggiuntive

Abilitare `ApiCenterOnboardingPlugin`