Guida per l'utente dell'app CISCO ASA REST API

Contenuto nascondere

1 App API REST CISCO ASA

2 Istruzioni per l'uso del prodotto

3 Sopraview

4 Richieste e risposte API ASA REST

5 Installa e configura l'agente e il client API ASA REST

6 La console della documentazione e l'esportazione degli script API

7 Abilitazione del debug dell'API REST sull'ASA

8 Messaggi syslog relativi all'API ASA REST

9 Documentazione correlata

10 Documenti / Risorse

10.1 Riferimenti

App API REST CISCO ASA

Istruzioni per l'uso del prodotto

Sopraview

Con il rilascio dell'API ASA REST di Cisco, ora disponi di un'altra opzione leggera e facile da usare per la configurazione e la gestione dei singoli Cisco ASA. L'ASA REST API è un'interfaccia di programmazione dell'applicazione (API) basata sui principi RESTful. Può essere rapidamente scaricato e abilitato su qualsiasi ASA su cui è in esecuzione l'API. Cisco Systems, Inc.

www.cisco.com

Richieste e risposte API ASA REST

Dopo aver installato un client REST nel browser, è possibile contattare l'agente REST dell'ASA specifico e utilizzare metodi HTTP standard per accedere alle informazioni di configurazione correnti ed emettere parametri di configurazione aggiuntivi.

Attenzione: Quando l'API REST è abilitata su un ASA, le connessioni tramite altri protocolli di gestione della sicurezza non vengono bloccate. Ciò significa che altri utenti che utilizzano CLI, ASDM o Security Manager potrebbero alterare la configurazione ASA mentre tu stai facendo lo stesso.

Richiedi struttura

L'API ASA REST fornisce accesso programmatico alla gestione di singoli ASA tramite un'API Representational State Transfer (REST). L'API consente ai client esterni di eseguire operazioni CRUD (Crea, Leggi, Aggiorna, Elimina) su risorse ASA. Tutte le richieste API vengono inviate tramite HTTPS all'ASA e viene restituita una risposta.

dove le proprietà dell'oggetto sono:

Proprietà	Tipo	Descrizione
messaggi	Elenco dei dizionari	Elenco dei messaggi di errore o di avviso
codice	Corda	Messaggio dettagliato corrispondente a Errore/Avviso/Informazioni
dettagli	Corda	Messaggio dettagliato corrispondente a Errore/Avviso/Informazioni

Nota: Le modifiche apportate dalle chiamate API REST non vengono mantenute nella configurazione di avvio ma vengono assegnate solo alla configurazione in esecuzione. Per salvare le modifiche alla configurazione di avvio, è possibile utilizzare la richiesta API POST a write mem. Per ulteriori informazioni, fare riferimento alla voce API Write Memory nel sommario Informazioni sull'API REST ASA.

Installa e configura l'agente e il client API ASA REST

Nota: L'agente API REST è un'applicazione basata su Java. Java Runtime Environment (JRE) è incluso nel pacchetto dell'agente API REST.

Sopraview

Sono disponibili diverse opzioni per la configurazione e la gestione dei singoli Cisco ASA:

Command Line Interface (CLI): invii comandi di controllo direttamente all'ASA tramite una console connessa.

Adaptive Security Device Manager (ASDM): un'applicazione di gestione “on-box” con un'interfaccia utente grafica che è possibile utilizzare per configurare, gestire e monitorare un ASA.
Cisco Security Manager: sebbene destinata a reti medio-grandi con molti dispositivi di sicurezza, questa applicazione grafica può essere utilizzata per configurare, gestire e monitorare i singoli ASA.

Con il rilascio dell'API ASA REST di Cisco, ora disponi di un'altra opzione leggera e facile da usare. Si tratta di un'interfaccia di programmazione dell'applicazione (API), basata sui principi "RESTful", che puoi scaricare e abilitare rapidamente su qualsiasi ASA su cui è in esecuzione l'API.

Richieste e risposte API ASA REST

L'API ASA REST offre accesso programmatico alla gestione di singoli ASA tramite un'API REST (Representational State Transfer). L'API consente ai client esterni di eseguire operazioni CRUD (Crea, Leggi, Aggiorna, Elimina) su risorse ASA; si basa sul protocollo HTTPS e sulla metodologia REST. Tutte le richieste API vengono inviate tramite HTTPS all'ASA e viene restituita una risposta. Questa sezione fornisce una panoramicaview di come sono strutturate le richieste e delle risposte attese,

Richiedi struttura

Le modalità di richiesta disponibili sono:

GET: recupera i dati dall'oggetto specificato.
PUT – Aggiunge le informazioni fornite all'oggetto specificato; restituisce un errore 404 Risorsa non trovata se l'oggetto non esiste.

POST – Crea l'oggetto con le informazioni fornite.
DELETE – Elimina l'oggetto specificato.

PATCH – Applica modifiche parziali all'oggetto specificato.

Struttura della risposta

Ogni richiesta produce una risposta HTTPS dall'ASA con intestazioni standard, contenuto della risposta e codice di stato.

La struttura della risposta può essere:

POSIZIONE: ID risorsa appena creata; solo per POST: contiene il nuovo ID risorsa (come rappresentazione URI).
CONTENT-TYPE: tipo di supporto che descrive il corpo del messaggio di risposta; descrive la rappresentazione e la sintassi del corpo del messaggio di risposta.

Ogni risposta include uno stato HTTP o un codice di errore. I codici disponibili rientrano in queste categorie:

20x – Un codice di duecento serie indica un'operazione riuscita, tra cui:
- 200 OK – Risposta standard per richieste riuscite.
- 201 Creato – Richiesta completata; nuova risorsa creata.
- 202 Accettato: richiesta accettata, ma elaborazione non completata.
- 204 No Content – Richiesta elaborata con successo dal server; nessun contenuto viene restituito.
4xx – Un codice della serie quattrocento indica un errore lato client, tra cui:
- 400 Richiesta errata: parametri di query non validi, inclusi parametri non riconosciuti, parametri mancanti o valori non validi.
- 404 Non trovato – Il file fornito URL non corrisponde a una risorsa esistente. Per esample, un HTTP DELETE potrebbe non riuscire perché la risorsa non è disponibile.
- 405 Metodo non consentito: è stata presentata una richiesta HTTP non consentita sulla risorsa; per esample, un POST su una risorsa di sola lettura.
5xx: un codice della serie cinquecento indica un errore lato server.

In caso di errore, oltre al codice errore, la risposta restituita può includere un oggetto errore contenente maggiori dettagli sull'errore. Lo schema di risposta all'errore/avviso JSON è il seguente:

dove le proprietà dell'oggetto sono:

Proprietà	Tipo	Descrizione
messaggi	Elenco dei dizionari	Elenco dei messaggi di errore o di avviso
codice	Corda	Codice errore/avviso/informazione
dettagli	Corda	Messaggio dettagliato corrispondente a Errore/Avviso/Informazioni

Nota: Le modifiche alla configurazione ASA apportate dalle chiamate API REST non vengono mantenute nella configurazione di avvio; ovvero le modifiche vengono assegnate solo alla configurazione in esecuzione. Per salvare le modifiche alla configurazione di avvio, puoi POSTARE una richiesta API writemem; per ulteriori informazioni, seguire la voce "Write Memory API" nel sommario Informazioni sull'API REST ASA.

Installa e configura l'agente e il client API ASA REST

L'agente API REST viene pubblicato individualmente con altre immagini ASA attive cisco.com. Per gli ASA fisici, il pacchetto API REST deve essere scaricato sulla flash del dispositivo e installato utilizzando il comando "rest-api image". L'agente API REST viene quindi abilitato utilizzando il comando "rest-api agent".
Con un ASA virtuale (ASAv), l'immagine API REST deve essere scaricata nella partizione "boot:". È quindi necessario eseguire il comando "rest-api image", seguito dal comando "rest-api agent", per accedere e abilitare l'agente API REST.
Per informazioni sui requisiti software e hardware dell'API REST e sulla compatibilità, vedere la matrice di compatibilità Cisco ASA.

Puoi scaricare il pacchetto API REST appropriato per il tuo ASA o ASAv da software.cisco.com/download/home. Individuare il modello Adaptive Security Appliances (ASA) specifico e quindi scegliere Plugin API REST Adaptive Security Appliance.

Nota: L'agente API REST è un'applicazione basata su Java. Java Runtime Environment (JRE) è incluso nel pacchetto dell'agente API REST.

Linee guida per l'utilizzo

Importante È necessario includere l'intestazione User-Agent: REST API Agent in tutte le chiamate API e gli script esistenti. Utilizzare -H 'User-Agent: REST API Agent' per CURL comando. In modalità multi-contesto, i comandi dell'agente API REST sono disponibili solo nel contesto Sistema.

Dimensione massima della configurazione supportata

L'ASA Rest API è un'applicazione “onboard” in esecuzione all'interno dell'ASA fisico e come tale presenta una limitazione sulla memoria ad essa allocata. La dimensione massima della configurazione di esecuzione supportata è aumentata durante il ciclo di rilascio a circa 2 MB sulle piattaforme recenti come 5555 e 5585. L'API ASA Rest presenta inoltre vincoli di memoria sulle piattaforme ASA virtuali. La memoria totale sull'ASAv5 può essere di 1.5 GB, mentre sull'ASAv10 è di 2 GB. I limiti dell'API Rest sono 450 KB e 500 KB rispettivamente per ASAv5 e ASAv10.

Pertanto, tenere presente che configurazioni in esecuzione di grandi dimensioni possono produrre eccezioni in varie situazioni ad uso intensivo di memoria, ad esempio un numero elevato di richieste simultanee o volumi di richieste di grandi dimensioni. In queste situazioni, le chiamate GET/PUT/POST dell'API Rest potrebbero iniziare a fallire con i messaggi 500 – Internal Server Error e l'agente API Rest si riavvierà automaticamente ogni volta. Le soluzioni alternative a questa situazione consistono nello spostamento su piattaforme ASA/FPR o ASAV con memoria più elevata oppure nella riduzione delle dimensioni della configurazione in esecuzione.

Scarica e installa l'agente API REST

Utilizzando la CLI, attenersi alla seguente procedura per scaricare e installare l'agente API REST ASA su un ASA specifico:

Fase 1: Sull'ASA desiderato, emettere la copia disk0: comando da cui scaricare il pacchetto API REST ASA corrente cisco.com nella memoria flash dell'ASA.
- Per esempioampon: copia tftp://10.7.0.80/asa-restapi-111-lfbff-k8.SPA disco0:
Fase 2: Emetti l'immagine rest-api disk0:/ comando per verificare e installare il pacchetto.
- Per esempioampon: immagine rest-api disk0:/asa-restapi-111-lfbff-k8.SPA

Il programma di installazione eseguirà controlli di compatibilità e convalida, quindi installerà il pacchetto. L'ASA non si riavvierà.

Abilita l'agente API REST

Seguire questi passaggi per abilitare l'agente API REST ASA su un ASA specifico:

Fase 1: Assicurarsi che sull'ASA sia installata l'immagine software corretta.
- Consultare la sezione API REST della matrice di compatibilità ASA (https://www.cisco.com/c/en/us/td/docs/security/asa/compatibility/asamatrx.html#pgfId-131643) per determinare quale immagine ASA è richiesta.

Fase 2: Utilizzando la CLI, assicurati che il server HTTP sia abilitato sull'ASA e che i client API possano connettersi all'interfaccia di gestione.
- Per esempioampon: Abilitazione del server http
- http0.0.0.0

Fase 3: Utilizzando la CLI, definire l'autenticazione HTTP per le connessioni API. Per esample: aaa autenticazione http console LOCALE
Fase 4: Utilizzando la CLI, crea una route statica sull'ASA per il traffico API. Per esample: percorso 0.0.0.0 0.0.0.0 1
Fase 5: Utilizzando la CLI, abilitare l'agente API REST ASA sull'ASA. Per esample: agente rest-api

Autenticazione API REST

Esistono due modi per eseguire l'autenticazione: autenticazione HTTP di base, che trasmette un nome utente e una password in ogni richiesta, oppure autenticazione basata su token con trasporto HTTPS sicuro, che trasmette un token creato in precedenza con ogni richiesta. In ogni caso, l'autenticazione verrà eseguita per ogni richiesta. Consulta la sezione "Token_Authentication_API" nella guida Informazioni sulla ASA REST API v7.14(x) per ulteriori informazioni sull'autenticazione basata su token.

Nota: Su ASA si consiglia l'uso di certificati emessi da un'autorità di certificazione (CA), in modo che i client API REST possano convalidare i certificati del server ASA quando stabiliscono connessioni SSL.

Autorizzazione al comando

Se l'autorizzazione al comando è configurata per utilizzare un server AAA esterno (ad esample, aaa comando di autorizzazione ), allora sul server deve esistere un utente denominato abilita_1 con privilegi di comando completi. Se l'autorizzazione del comando è configurata per utilizzare il database LOCALE dell'ASA (comando di autorizzazione aaa LOCAL), tutti gli utenti dell'API REST devono essere registrati nel database LOCALE con livelli di privilegio appropriati per i loro ruoli:

Per richiamare le richieste di monitoraggio è necessario un livello di privilegio pari o superiore a 3.

Per richiamare le richieste GET è richiesto il livello di privilegio 5 o superiore.
Il livello di privilegio 15 è necessario per richiamare le operazioni PUT/POST/DELETE.

Configura il tuo client API REST

Segui questi passaggi per installare e configurare un client API REST sul tuo browser host locale:

Fase 1: Acquista e installa un client API REST per il tuo browser.
- Per Chrome, installa il client REST di Google. Per Firefox, installa il componente aggiuntivo RESTClient. Internet Explorer non è supportato.

Fase 2: Avvia la seguente richiesta utilizzando il tuo browser: https: /api/oggetti/oggettidirete
- Se ricevi una risposta non di errore, hai raggiunto l'agente API REST funzionante sull'ASA.
- Se riscontri problemi con la richiesta dell'agente, puoi abilitare la visualizzazione delle informazioni di debug sulla console CLI, come descritto in Abilitazione del debug dell'API REST sull'ASA.

Fase 3: Facoltativamente, è possibile testare la connessione all'ASA eseguendo un'operazione POST.

Per esempioampon: Fornire le credenziali di autorizzazione di base ( ) o un token di autenticazione (vedi Autenticazione token per ulteriori informazioni).

Indirizzo della richiesta di destinazione: https://<asa management ipaddress>/api/objects/networkobjects

Tipo di contenuto del corpo: application / json

Corpo grezzo dell'operazione:

Ora puoi utilizzare l'API REST ASA per configurare e monitorare l'ASA. Fare riferimento alla documentazione API per le descrizioni delle chiamate ed esampmeno.

Informazioni sul ripristino completo di una configurazione di backup

Il ripristino di una configurazione di backup completa sull'ASA utilizzando l'API REST ricaricherà l'ASA. Per evitare ciò, utilizzare il comando seguente per ripristinare una configurazione di backup:

{
- “comandi”:[“copia /noconfirm disco0:/filenome> configurazione-esecuzione”]
}
- Dovefilename> è backup.cfg o qualunque nome tu abbia usato durante il backup della configurazione.

La console della documentazione e l'esportazione degli script API

È inoltre possibile utilizzare la console di documentazione in linea dell'API REST (denominata "UI Doc"), disponibile su host:port/doc/ come "sandbox" per conoscere e provare le chiamate API direttamente sull'ASA. Inoltre, è possibile utilizzare il pulsante Operazione di esportazione nell'interfaccia utente del documento per salvare il metodo visualizzato, ad esample come script JavaScript, Python o Perl file al tuo host locale. Puoi quindi applicare questo script al tuo ASA e modificarlo per l'applicazione su altri ASA e altri dispositivi di rete. Ciò è stato inteso principalmente come strumento educativo e di bootstrap.

Javascript

Utilizzando un JavaScript file richiede l'installazione di node.js, che può essere trovato su http://nodejs.org/.
Usando node.js, puoi eseguire un JavaScript file, tipicamente scritto per un browser, come uno script da riga di comando. Segui semplicemente le istruzioni di installazione, quindi esegui lo script con node script.js.

Pitone

Gli script Python richiedono l'installazione di Python, disponibile da https://www.python.org/.
Una volta installato Python, puoi eseguire il tuo script con python script.py nome utente e password.

Perla

L'utilizzo degli script Perl richiede alcune impostazioni aggiuntive: sono necessari cinque componenti: Perl stesso e quattro librerie Perl:

Pacchetto Perl, disponibile su http://www.perl.org/
Fascio::CPAN, reperibile su http://search.cpan.org/~andk/Bundle-CPAN-1.861/CPAN.pm

RIPOSO::Cliente, trovato a http://search.cpan.org/~mcrawfor/REST-Client-88/lib/REST/Client.pm
MIMO::Base64, trovato in http://perldoc.perl.org/MIME/Base64.html
JSON, trovato in http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm

Ecco un example di bootstrap di Perl su un Macintosh:

$ sudo perl -MCPAN e shell
cpan> installa pacchetto::CPAN

cpan> installa REST:: Cliente
cpan> installa MIME::Base64
cpan> installa JSON

Dopo aver installato le dipendenze, puoi eseguire il tuo script utilizzando perl script.pl nome utente e password.

Abilitazione del debug dell'API REST sull'ASA

Se riscontri problemi di configurazione o connessione all'API REST sull'ASA, puoi utilizzare il seguente comando CLI per abilitare la visualizzazione dei messaggi di debug sulla tua console. Utilizzare la forma no del comando per disabilitare i messaggi di debug.
debug rest-api [agente | cli | cliente | demone | processo | token-auth] [errore | evento] nessun debug rest-api

Sintassi Descrizione

agente: (Facoltativo) Abilita le informazioni di debug dell'agente API REST.
cli: (Facoltativo) Abilita i messaggi di debug per le comunicazioni da daemon a agente della CLI dell'API REST.
cliente: (Facoltativo) Abilita le informazioni di debug per l'instradamento dei messaggi tra il client API REST e l'agente API REST.

demone: (Facoltativo) Abilita i messaggi di debug per le comunicazioni daemon-agente dell'API REST.
processo: (Facoltativo) Abilita le informazioni di debug di avvio/arresto del processo dell'agente API REST.
autenticazione token: (Facoltativo) Informazioni sul debug dell'autenticazione del token API REST.

errore: (Facoltativo) Utilizza questa parola chiave per limitare i messaggi di debug solo agli errori registrati dall'API.
evento: (Facoltativo) Utilizza questa parola chiave per limitare i messaggi di debug solo agli eventi registrati dall'API.

Linee guida per l'utilizzo

Se non fornisci una parola chiave specifica per il componente (ovvero, se esegui semplicemente il comando debug rest-api), i messaggi di debug vengono visualizzati per tutti i tipi di componenti. Se non si fornisce la parola chiave evento o errore, verranno visualizzati sia i messaggi di evento che quelli di errore per il componente specificato. Per esample, l'evento debug rest-api daemon mostrerà solo i messaggi di debug degli eventi per le comunicazioni da daemon API ad agente.

Comandi correlati

Comando/Descrizione

eseguire il debug dell'HTTP; Usa questo comando per view informazioni dettagliate sul traffico HTTP.

Messaggi syslog relativi all'API ASA REST

I messaggi di registro di sistema relativi all'API ASA REST sono descritti in questa sezione.

342001

Messaggio di errore: %ASA-7-342001: l'agente API REST è stato avviato correttamente.
- Spiegazione: L'agente API REST deve essere avviato correttamente prima che un client API REST possa configurare l'ASA.
- Azione raccomandata: Nessuno.

342002

Messaggio di errore: %ASA-3-342002: Agente API REST non riuscito, motivo: motivo
- Spiegazione: L'agente API REST potrebbe non avviarsi o bloccarsi per vari motivi e il motivo è specificato.
- motivo: la causa dell'errore dell'API REST

Azione raccomandata: Le azioni intraprese per risolvere il problema variano a seconda del motivo registrato. Per esample, l'agente API REST si arresta in modo anomalo quando il processo Java esaurisce la memoria. In tal caso, è necessario riavviare l'agente API REST. Se il riavvio non riesce, contattare il TAC Cisco per identificare la correzione della causa principale.

342003

Messaggio di errore: %ASA-3-342003: ricevuta notifica di errore dell'agente API REST. L'agente verrà riavviato automaticamente.
- Spiegazione: È stata ricevuta una notifica di errore dall'agente API REST e si sta tentando di riavviare l'agente.
- Azione raccomandata: Nessuno.

342004

Messaggio di errore: %ASA-3-342004: Impossibile riavviare automaticamente l'agente API REST dopo 5 tentativi non riusciti. Utilizza i comandi "no rest-api agent" e "rest-api agent" per riavviare manualmente l'agente.
- Spiegazione: L'agente API REST non è riuscito ad avviarsi dopo molti tentativi.
- Azione raccomandata: Vedere syslog %ASA-3-342002 (se registrato) per comprendere meglio il motivo dell'errore. Prova a disabilitare l'agente API REST immettendo il comando no rest-api agent e riabilita l'agente API REST utilizzando il comando rest-api agent.

Documentazione correlata

Utilizzare il seguente collegamento per trovare ulteriori informazioni sull'ASA e sulla sua configurazione e gestione:

Navigazione nella documentazione della serie Cisco ASA: http://www.cisco.com/go/asadocs
Utilizzare il seguente collegamento a view un elenco delle funzionalità ASA non supportate su ASAv: http://www.cisco.com/c/en/us/td/docs/security/asa/asa92/configuration/general/asa-general-cli/introasav.html#pgfId-1156883

Questo documento deve essere utilizzato insieme ai documenti disponibili nella sezione "Documentazione correlata".
Cisco e il logo Cisco sono marchi o marchi registrati di Cisco e/o delle sue affiliate negli Stati Uniti e in altri paesi. Per view un elenco dei marchi Cisco, vai a questo URL: www.cisco.com/go/trademarks. I marchi di terze parti menzionati sono di proprietà dei rispettivi titolari. L'uso della parola partner non implica un rapporto di partnership tra Cisco e qualsiasi altra azienda. (1721R)
Gli indirizzi IP (Internet Protocol) e i numeri di telefono utilizzati in questo documento non sono da intendersi come indirizzi e numeri di telefono effettivi. Qualsiasi esampi, l'output della visualizzazione dei comandi, i diagrammi della topologia di rete e altre figure incluse nel documento vengono mostrati solo a scopo illustrativo.
Qualsiasi utilizzo di indirizzi IP o numeri di telefono reali in contenuti illustrativi è involontario e casuale.

Cisco Systems, Inc.

www.cisco.com

Documenti / Risorse

App API REST CISCO ASA [pdf] Guida utente
App API REST ASA, ASA, App API REST, App API, App

Riferimenti

Manuale d'uso