Swagger e OpenAPI pubblici: la documentazione delle API è un rischio?

Se sviluppi o gestisci un'API, probabilmente hai già incontrato Swagger o OpenAPI.

La documentazione può essere estremamente utile.

Permette di conoscere:

endpoint
metodi
parametri
request
response
autenticazione
versioni

In molti progetti è disponibile attraverso interfacce come:

/swagger
/swagger-ui
/api-docs
/openapi.json
/openapi.yaml

Ma una domanda è importante:

La documentazione delle API deve essere pubblica?

La risposta non è semplicemente sì o no.

Swagger e OpenAPI non sono la stessa cosa

Prima di tutto, una distinzione.

OpenAPI è una specifica utilizzata per descrivere API.

Swagger è un insieme di strumenti nato intorno a quella specifica.

Nella pratica, i due termini vengono spesso utilizzati insieme.

Un file OpenAPI potrebbe descrivere:

openapi: 3.0.0
info:
  title: Example API
  version: 1.0.0

paths:
  /users:
    get:
      responses:
        '200':
          description: OK

Da una specifica di questo tipo possono essere generate interfacce di documentazione interattive.

La documentazione è un problema di sicurezza?

Non necessariamente.

La documentazione di un'API può essere completamente pubblica e perfettamente legittima.

Per esempio, un servizio che offre una API pubblica agli sviluppatori potrebbe voler rendere disponibile:

https://api.example.com/docs

In questo caso la documentazione è parte del servizio.

Il problema cambia quando la documentazione pubblica descrive API che non dovrebbero essere pubbliche.

Cosa può rivelare una documentazione API?

Un documento OpenAPI può contenere moltissime informazioni:

/api/users
/api/orders
/api/admin/users
/api/internal/reports

oltre a:

• parametri;
• metodi HTTP;
• modelli dati;
• nomi dei campi;
• schemi di autenticazione;
• codici di errore;
• versioni;
• endpoint amministrativi.

In altre parole, può rendere molto più semplice comprendere la struttura dell'API.

Questo non significa che la documentazione sia una vulnerabilità.

Significa che dovrebbe essere pubblicata consapevolmente.

Il vero problema: documentazione di API interne

Immaginiamo che un'organizzazione abbia:

API pubblica
https://api.example.com/docs

API interna
https://internal-api.example.com/docs

La seconda documentazione potrebbe descrivere funzioni destinate esclusivamente a sistemi interni.

Se viene accidentalmente resa pubblica, può fornire informazioni che non era previsto esporre.

Questo è uno dei motivi per cui OWASP sottolinea l'importanza di mantenere un inventario aggiornato degli host e delle versioni delle API e di gestire correttamente la documentazione.

Endpoint "internal" non significa automaticamente sicuro

Un endpoint chiamato:

/internal/users

non è automaticamente interno.

Se è raggiungibile da Internet, dal punto di vista della rete è esposto.

Lo stesso vale per:

/admin
/debug
/test
/internal
/private

Il nome suggerisce l'intenzione dello sviluppatore.

Non costituisce un controllo di sicurezza.

La documentazione può rivelare vecchie versioni

Immaginiamo un progetto che abbia:

/v1/
/v2/

La documentazione potrebbe ancora contenere endpoint della versione precedente:

/v1/users
/v1/admin

anche se gli sviluppatori pensano di aver abbandonato la vecchia API.

Questo può essere un indizio importante.

Una delle problematiche specifiche individuate da OWASP riguarda proprio le API obsolete o dimenticate che rimangono esposte e non ricevono più lo stesso livello di protezione delle versioni attuali.

Swagger UI può eseguire richieste

Un'interfaccia Swagger UI non è necessariamente soltanto una pagina informativa.

Può permettere agli sviluppatori di provare direttamente gli endpoint documentati.

Per esempio:

GET /api/products
POST /api/orders

possono essere richiamati direttamente dall'interfaccia, a seconda della configurazione.

Questo rende ancora più importante assicurarsi che la documentazione punti agli endpoint corretti e che i meccanismi di autenticazione siano configurati in modo appropriato.

Un esempio di problema di configurazione

Immaginiamo che in sviluppo sia stato configurato:

Swagger UI
↓
API di test
↓
nessuna autenticazione

Quando il progetto viene portato in produzione, la documentazione potrebbe rimanere accidentalmente attiva.

A quel punto non è la presenza di Swagger a essere il problema.

È la configurazione dell'ambiente.

Documentazione pubblica vs documentazione privata

Una distinzione utile può essere:

API pubblica

/docs

può essere pubblicamente disponibile se è previsto dal servizio.

API privata

La documentazione può invece richiedere:

autenticazione
VPN
accesso aziendale
allowlist

oppure essere completamente esclusa dall'ambiente di produzione.

Non esiste una regola unica valida per tutte le architetture.

Cosa controllare?

Per una prima verifica:

• [ ] esistono endpoint Swagger/OpenAPI pubblici?
• [ ] sono previsti?
• [ ] descrivono API pubbliche o interne?
• [ ] esistono vecchie versioni documentate?
• [ ] sono presenti endpoint amministrativi?
• [ ] la documentazione espone informazioni sensibili?
• [ ] i dati di esempio contengono informazioni reali?
• [ ] Swagger UI può effettuare richieste verso ambienti sensibili?
• [ ] la documentazione viene aggiornata insieme all'API?

E i file OpenAPI?

Non bisogna controllare soltanto:

/swagger

Potrebbero essere esposti direttamente anche file come:

/openapi.json
/openapi.yaml
/swagger.json
/swagger.yaml

Un file JSON può essere molto meno appariscente di una pagina Swagger UI, ma contenere comunque la descrizione completa dell'API.

Documentazione e attack surface

Un endpoint di documentazione può essere interessante anche perché aiuta a comprendere la superficie applicativa.

Supponiamo di trovare:

/openapi.json

e al suo interno:

/users
/orders
/payments
/admin/reports
/internal/config

Questo non significa automaticamente che tutti questi endpoint siano vulnerabili o accessibili.

Ma fornisce informazioni utili per capire quali funzionalità esistono.

La soluzione non è sempre "nascondere Swagger"

Nascondere la documentazione può ridurre le informazioni disponibili pubblicamente, ma non sostituisce la sicurezza dell'API.

Se:

/admin/users

è accessibile senza autorizzazione, rimuovere:

/swagger

non risolve il problema.

L'endpoint deve essere protetto indipendentemente dalla presenza della documentazione.

Una buona gestione della documentazione

Una strategia pratica può essere:

Sviluppo
↓
Swagger completo

Staging
↓
Swagger protetto

Produzione
↓
Documentazione pubblica solo se realmente necessaria

e soprattutto:

Documentazione
        ↕
API reale

devono rimanere sincronizzate.

Una documentazione vecchia può essere quasi altrettanto problematica di una documentazione assente, perché rende difficile sapere quali API esistano realmente.

MiHakero e la discovery delle API

Swagger e OpenAPI sono un esempio perfetto di come la sicurezza esterna possa partire dalla discovery.

Trovare:

/openapi.json

non significa trovare una vulnerabilità.

Significa trovare una fonte di informazioni che può aiutare a comprendere l'API.

Da lì è possibile distinguere:

API pubbliche
API autenticate
API amministrative
API legacy
API di test

e capire quali superfici meritano un'analisi più approfondita.

Perché nella sicurezza API, conoscere quali endpoint esistono è spesso il primo passo per poterli proteggere correttamente.