Aplicació CISCO ASA REST API

Instruccions d'ús del producte

Acabatview

Amb el llançament de l'API ASA REST de Cisco, ara teniu una altra opció lleugera i fàcil d'utilitzar per configurar i gestionar Cisco ASA individuals. L'API REST d'ASA és una interfície de programació d'aplicacions (API) basada en principis RESTful. Es pot descarregar i activar ràpidament a qualsevol ASA on s'executi l'API. Cisco Systems, Inc.

www.cisco.com

Sol·licituds i respostes de l'API ASA REST

Després d'instal·lar un client REST al vostre navegador, podeu contactar amb l'agent REST de l'ASA específic i utilitzar mètodes HTTP estàndard per accedir a la informació de configuració actual i emetre paràmetres de configuració addicionals.

Precaució: Quan l'API REST està habilitada en un ASA, les connexions per altres protocols de gestió de seguretat no es bloquegen. Això vol dir que altres persones que utilitzin CLI, ASDM o Security Manager podrien estar alterant la configuració ASA mentre feu el mateix.

Estructura de la sol·licitud

L'API REST ASA us ofereix accés programàtic per gestionar ASA individuals mitjançant una API REST (Representational State Transfer). L'API permet als clients externs realitzar operacions CRUD (Crear, Llegir, Actualitzar, Suprimir) en recursos ASA. Totes les sol·licituds d'API s'envien per HTTPS a l'ASA i es retorna una resposta.

on les propietats de l'objecte són:

Propietat	Tipus	Descripció
missatges	Llista de diccionaris	Llista de missatges d'error o advertència
codi	Corda	Missatge detallat corresponent a Error/Avís/Informació
detalls	Corda	Missatge detallat corresponent a Error/Avís/Informació

Nota: Els canvis fets per les trucades de l'API REST no es mantenen a la configuració d'inici, sinó que només s'assignen a la configuració en execució. Per desar els canvis a la configuració d'inici, podeu utilitzar la sol·licitud d'API POST a write mem. Per obtenir més informació, consulteu l'entrada Write Memory API a la taula de continguts de l'ASA REST API.

Instal·leu i configureu l'agent i el client de l'API REST ASA

Nota: L'Agent de l'API REST és una aplicació basada en Java. L'entorn d'execució de Java (JRE) s'inclou al paquet REST API Agent.

Acabatview

Hi ha diverses opcions disponibles per configurar i gestionar Cisco ASA individuals:

• Interfície de línia d'ordres (CLI): envieu ordres de control directament a l'ASA mitjançant una consola connectada.
• Adaptive Security Device Manager (ASDM): una aplicació de gestió "a la caixa" amb una interfície d'usuari gràfica que podeu utilitzar per configurar, gestionar i supervisar un ASA.
• Cisco Security Manager: tot i que està pensada per a xarxes mitjanes i grans de molts dispositius de seguretat, aquesta aplicació gràfica es pot utilitzar per configurar, gestionar i supervisar ASA individuals.

Amb el llançament de l'API ASA REST de Cisco, ara teniu una altra opció lleugera i fàcil d'utilitzar. Es tracta d'una interfície de programació d'aplicacions (API), basada en principis "RESTful", que podeu descarregar i activar ràpidament a qualsevol ASA en què s'executi l'API.

Després d'instal·lar un client REST al vostre navegador, podeu contactar amb l'agent REST de l'ASA específic i utilitzar mètodes HTTP estàndard per accedir a la informació de configuració actual i emetre paràmetres de configuració addicionals.

Precaució: Quan l'API REST està habilitada en un ASA, les connexions per altres protocols de gestió de seguretat no es bloquegen. Això vol dir que altres persones que utilitzin CLI, ASDM o Security Manager podrien estar alterant la configuració ASA mentre feu el mateix.

Sol·licituds i respostes de l'API ASA REST

L'API REST ASA us ofereix accés programàtic per gestionar ASA individuals mitjançant una API REST (Representational State Transfer). L'API permet als clients externs realitzar operacions CRUD (Crea, Read, Update, Delete) en recursos ASA; es basa en el protocol HTTPS i la metodologia REST. Totes les sol·licituds d'API s'envien per HTTPS a l'ASA i es retorna una resposta. Aquesta secció ofereix un finalview de com s'estructuren les sol·licituds i les respostes esperades,

Estructura de la sol·licitud

Els mètodes de sol·licitud disponibles són:

• GET: recupera dades de l'objecte especificat.
• PUT – Afegeix la informació subministrada a l'objecte especificat; retorna un error 404 Resource Not Found si l'objecte no existeix.
• POST: crea l'objecte amb la informació subministrada.
• ELIMINAR: elimina l'objecte especificat.
• PATCH: aplica modificacions parcials a l'objecte especificat.

Estructura de resposta

• Cada sol·licitud produeix una resposta HTTPS de l'ASA amb les capçaleres estàndard, el contingut de la resposta i el codi d'estat.

L'estructura de resposta pot ser:

• LOCALITZACIÓ: identificador de recurs recent creat; només per a POST: conté el nou ID de recurs (com a representació d'URI).
• CONTENT-TIP: tipus de suport que descriu el cos del missatge de resposta; descriu la representació i la sintaxi del cos del missatge de resposta.

Cada resposta inclou un codi d'error o estat HTTP. Els codis disponibles entren en aquestes categories:

• 20x: un codi de dues-centes sèries indica un funcionament correcte, que inclou:
  • 200 OK: resposta estàndard per a sol·licituds reeixides.
  • 201 Creat: sol·licitud completada; nou recurs creat.
  • 202 Acceptat: s'ha acceptat la sol·licitud, però el processament no s'ha completat.
  • 204 Sense contingut: el servidor ha processat la sol·licitud correctament; no es retorna cap contingut.
• 4xx: un codi de quatre-centes sèries indica un error del costat del client, que inclou:
  • 400 Sol·licitud incorrecta: paràmetres de consulta no vàlids, inclosos paràmetres no reconeguts, paràmetres que falten o valors no vàlids.
  • 404 No trobat: el proporcionat URL no coincideix amb un recurs existent. Per exampli, un HTTP DELETE pot fallar perquè el recurs no està disponible.
  • 405 Mètode no permès: es va presentar una sol·licitud HTTP que no està permesa al recurs; per example, un POST en un recurs de només lectura.
• 5xx: un codi de cinc-centes sèries indica un error del servidor.

En el cas d'un error, a més del codi d'error, la resposta de retorn pot incloure un objecte d'error que contingui més detalls sobre l'error. L'esquema de resposta d'error/advertència JSON és el següent:

on les propietats de l'objecte són:

Propietat	Tipus	Descripció
missatges	Llista de diccionaris	Llista de missatges d'error o advertència
codi	Corda	Codi d'error/avís/informació
detalls	Corda	Missatge detallat corresponent a Error/Avís/Informació

Nota: Els canvis a la configuració ASA fets per les trucades de l'API REST no es mantenen a la configuració d'inici; és a dir, els canvis s'assignen només a la configuració en execució. Per desar els canvis a la configuració d'inici, podeu POST una sol·licitud d'API writemem; per obtenir més informació, seguiu l'entrada "Escriptura de l'API de memòria" a la taula de continguts de l'API REST d'ASA.

Instal·leu i configureu l'agent i el client de l'API REST ASA

• L'agent de l'API REST es publica individualment amb altres imatges ASA activades cisco.com. Per als ASA físics, el paquet de l'API REST s'ha de baixar al flaix del dispositiu i instal·lar-lo mitjançant l'ordre "rest-api image". Aleshores, l'agent de l'API REST s'habilita mitjançant l'ordre "agent rest-api".
• Amb un ASA virtual (ASAv), la imatge de l'API REST s'ha de descarregar a la partició "boot:". A continuació, heu d'emetre l'ordre "rest-api image", seguida de l'ordre "rest-api agent", per accedir i habilitar l'agent de l'API REST.
• Per obtenir informació sobre els requisits i la compatibilitat de maquinari i programari de l'API REST, consulteu la matriu de compatibilitat de Cisco ASA.
• Podeu descarregar el paquet d'API REST adequat per al vostre ASA o ASAv des de software.cisco.com/download/home. Localitzeu el model específic d'Adaptive Security Appliances (ASA) i, a continuació, trieu el connector de l'API REST de l'Adaptive Security Appliance.

Nota: L'Agent de l'API REST és una aplicació basada en Java. L'entorn d'execució de Java (JRE) s'inclou al paquet REST API Agent.

Pautes d'ús

Important Heu d'incloure la capçalera User-Agent: REST API Agent a totes les trucades d'API i scripts existents. Utilitzeu -H 'User-Agent: REST API Agent' per a CURL comandament. En el mode multicontext, les ordres de l'Agent de l'API REST només estan disponibles al context del sistema.

Mida màxima de configuració admesa

L'API ASA Rest és una aplicació "integrada" que s'executa dins de l'ASA físic i, com a tal, té una limitació a la memòria assignada. La mida màxima de configuració en execució admesa ha augmentat durant el cicle de llançament fins a aproximadament 2 MB en plataformes recents, com ara la 5555 i la 5585. L'API ASA Rest també té restriccions de memòria a les plataformes ASA virtuals. La memòria total de l'ASAv5 pot ser d'1.5 GB, mentre que a l'ASAv10 és de 2 GB. Els límits de l'API Rest són de 450 KB i 500 KB per a ASAv5 i ASAv10, respectivament.

Per tant, tingueu en compte que les configuracions en execució grans poden produir excepcions en diverses situacions que requereixen molta memòria, com ara un gran nombre de sol·licituds concurrents o grans volums de sol·licituds. En aquestes situacions, les trucades GET/PUT/POST de Rest API poden començar a fallar amb 500 missatges d'error intern del servidor, i l'agent de Rest API es reiniciarà automàticament cada vegada. Les solucions alternatives a aquesta situació són passar a plataformes ASA/FPR o ASAV de memòria més alta o reduir la mida de la configuració en execució.

Baixeu i instal·leu l'agent de l'API REST

Mitjançant la CLI, seguiu aquests passos per baixar i instal·lar l'agent de l'API REST ASA en un ASA específic:

• Pas 1: A l'ASA desitjat, emet la còpia disk0: ordre per descarregar el paquet actual de l'API REST d'ASA cisco.com a la memòria flash de l'ASA.
  • Per exampLI: còpia tftp://10.7.0.80/asa-restapi-111-lfbff-k8.SPA disk0:
• Pas 2: Emet la imatge rest-api disk0:/ comanda per verificar i instal·lar el paquet.
  • Per exampLI: disc d'imatge rest-api0:/asa-restapi-111-lfbff-k8.SPA

L'instal·lador realitzarà comprovacions de compatibilitat i validació i després instal·larà el paquet. L'ASA no es reiniciarà.

Activeu l'agent de l'API REST

Seguiu aquests passos per habilitar l'Agent de l'API REST ASA en un ASA específic:

• Pas 1: Assegureu-vos que la imatge de programari correcta estigui instal·lada a l'ASA.
  • Consulteu la secció de l'API REST de la Matriu de compatibilitat ASA (https://www.cisco.com/c/en/us/td/docs/security/asa/compatibility/asamatrx.html#pgfId-131643) per determinar quina imatge ASA és necessària.
• Pas 2: Mitjançant la CLI, assegureu-vos que el servidor HTTP estigui habilitat a l'ASA i que els clients de l'API es puguin connectar a la interfície de gestió.
  • Per exampLI: Habilita el servidor http
  • http 0.0.0.0 0.0.0.0
• Pas 3: Amb la CLI, definiu l'autenticació HTTP per a les connexions de l'API. Per example: aaa autenticació http consola LOCAL
• Pas 4: Utilitzant la CLI, creeu una ruta estàtica a l'ASA per al trànsit de l'API. Per example: ruta 0.0.0.0 0.0.0.0 1
• Pas 5: Mitjançant la CLI, activeu l'Agent de l'API REST ASA a l'ASA. Per example: agent rest-api

Autenticació de l'API REST

Hi ha dues maneres d'autenticar-se: l'autenticació HTTP bàsica, que passa un nom d'usuari i una contrasenya a cada sol·licitud, o l'autenticació basada en testimonis amb transport HTTPS segur, que passa un testimoni creat prèviament amb cada sol·licitud. De qualsevol manera, l'autenticació es realitzarà per a cada sol·licitud. Consulteu la secció "Token_Authentication_API" a la guia Sobre l'ASA REST API v7.14(x) per obtenir informació addicional sobre l'autenticació basada en testimonis.

Nota: Es recomana l'ús de certificats emesos per l'Autoritat de Certificació (CA) a ASA, de manera que els clients de l'API REST poden validar els certificats del servidor ASA quan estableixen connexions SSL.

Autorització de comandaments

Si l'autorització d'ordres està configurada per utilitzar un servidor AAA extern (per exemple,ample, aaa comanda d'autorització ), llavors un usuari anomenat enable_1 ha d'existir en aquest servidor amb privilegis d'ordre complets. Si l'autorització d'ordres està configurada per utilitzar la base de dades LOCAL de l'ASA (ordre d'autorització aaa LOCAL), tots els usuaris de l'API REST han d'estar registrats a la base de dades LOCAL amb nivells de privilegis adequats per a les seves funcions:

• Es requereix un nivell de privilegi 3 o superior per invocar sol·licituds de supervisió.
• Es requereix un nivell de privilegi 5 o superior per invocar sol·licituds GET.
• El nivell de privilegi 15 és necessari per invocar les operacions PUT/POST/DELETE.

Configureu el vostre client de l'API REST

Seguiu aquests passos per instal·lar i configurar un client d'API REST al vostre navegador d'amfitrió local:

• Pas 1: Adquireixi i instal·leu un client d'API REST per al vostre navegador.
  • Per a Chrome, instal·leu el client REST de Google. Per al Firefox, instal·leu el complement RESTClient. Internet Explorer no és compatible.
• Pas 2: Inicieu la següent sol·licitud mitjançant el vostre navegador: https: /api/objects/networkobjects
  • Si rebeu una resposta sense error, heu arribat a l'agent de l'API REST que funciona a l'ASA.
  • Si teniu problemes amb la sol·licitud de l'agent, podeu habilitar la visualització de la informació de depuració a la consola CLI, tal com es descriu a Habilitació de la depuració de l'API REST a l'ASA.
• Pas 3: Opcionalment, podeu provar la vostra connexió a l'ASA realitzant una operació POST.

Per exampLI: Proporcioneu credencials d'autorització bàsiques ( ), o un testimoni d'autenticació (vegeu Autenticació de testimoni per obtenir informació addicional).

• Adreça de sol·licitud objectiu: https://<asa management ipaddress>/api/objects/networkobjects
• Tipus de contingut corporal: aplicació/json

Cos brut de l'operació:

Ara podeu utilitzar l'API REST ASA per configurar i supervisar l'ASA. Consulteu la documentació de l'API per obtenir descripcions de trucades i examples.

Sobre la restauració completa d'una configuració de còpia de seguretat

Restaurar una configuració de còpia de seguretat completa a l'ASA mitjançant l'API REST es tornarà a carregar l'ASA. Per evitar-ho, utilitzeu l'ordre següent per restaurar una configuració de còpia de seguretat:

• {
  • "ordres":["copiar /noconfirm disk0:/filenom> running-config”]
• }
  • Onfilenom> és backup.cfg o qualsevol nom que hàgiu utilitzat quan feu una còpia de seguretat de la configuració.

La consola de documentació i exportació de scripts de l'API

També podeu utilitzar la consola de documentació en línia de l'API REST (coneguda com a "Interfície d'usuari del document"), disponible a host:port/doc/ com a "sandbox" per conèixer i provar les trucades d'API directament a l'ASA. A més, podeu utilitzar el botó d'operació d'exportació a la interfície d'usuari del document per desar el mètode que es mostra, per exempleampli com a script de JavaScript, Python o Perl file al vostre amfitrió local. A continuació, podeu aplicar aquest script al vostre ASA i editar-lo per a l'aplicació a altres ASA i altres dispositius de xarxa. Això significava principalment com una eina educativa i d'arrencada.

JavaScript

• Utilitzant un JavaScript file requereix la instal·lació de node.js, que es pot trobar a http://nodejs.org/.
• Amb node.js, podeu executar un JavaScript file, normalment escrit per a un navegador, com un script de línia d'ordres. Simplement seguiu les instruccions d'instal·lació i, a continuació, executeu el vostre script amb el node script.js.

Python

• Els scripts de Python requereixen que instal·leu Python, disponible des de https://www.python.org/.
• Un cop hàgiu instal·lat Python, podeu executar el vostre script amb la contrasenya del nom d'usuari de python script.py.

Perl

L'ús dels scripts de Perl requereix una configuració addicional: necessiteu cinc components: Perl mateix i quatre biblioteques de Perl:

• Paquet Perl, que es troba a http://www.perl.org/
• Paquet::CPAN, que es troba a http://search.cpan.org/~andk/Bundle-CPAN-1.861/CPAN.pm
• DESCANS::Client, trobat a http://search.cpan.org/~mcrawfor/REST-Client-88/lib/REST/Client.pm
• MIME::Base64, trobada a http://perldoc.perl.org/MIME/Base64.html
• JSON, trobat a http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm

Aquí teniu un exampfitxer d'arrencada de Perl en un Macintosh:

• $ sudo perl -MCPAN e shell
• cpan> instal·la el paquet::CPAN
• cpan> instal·la REST:: Client
• cpan> instal·la MIME:: Base 64
• cpan> instal·la JSON

Després d'instal·lar les dependències, podeu executar el vostre script mitjançant la contrasenya del nom d'usuari perl script.pl.

Habilitació de la depuració de l'API REST a l'ASA

Si teniu problemes per configurar o connectar-vos a l'API REST a l'ASA, podeu utilitzar l'ordre CLI següent per habilitar la visualització dels missatges de depuració a la vostra consola. Utilitzeu la forma no de l'ordre per desactivar els missatges de depuració.
depurar rest-api [agent | cli | client | dimoni | procés | token-auth] [error | event] sense depuració rest-api

Descripció de la sintaxi

• agent: (Opcional) Habiliteu la informació de depuració de l'Agent de l'API REST.
• cli: (Opcional) Habiliteu els missatges de depuració per a les comunicacions de dimoni a agent de la CLI de l'API REST.
• client: (Opcional) Habiliteu la informació de depuració per a l'encaminament de missatges entre el client de l'API REST i l'agent de l'API REST.
• dimoni: (Opcional) Habiliteu els missatges de depuració per a les comunicacions de dimoni a agent de l'API REST.
• procés: (Opcional) Habiliteu la informació d'inici/atura de depuració del procés de l'agent de l'API REST.
• token-auth: (Opcional) Informació de depuració d'autenticació de testimoni de l'API REST.
• error: (Opcional) Utilitzeu aquesta paraula clau per limitar els missatges de depuració només als errors registrats per l'API.
• esdeveniment: (Opcional) Utilitzeu aquesta paraula clau per limitar els missatges de depuració només als esdeveniments registrats per l'API.

Pautes d'ús

Si no proporcioneu una paraula clau de component específica (és a dir, si simplement emeteu l'ordre debug rest-api), es mostren missatges de depuració per a tots els tipus de components. Si no proporcioneu ni la paraula clau d'esdeveniment ni la paraula clau d'error, es mostren els missatges d'esdeveniment i d'error per al component especificat. Per example, l'esdeveniment debug rest-api daemon només mostrarà missatges de depuració d'esdeveniments per a les comunicacions de l'API Daemon-to-Agent.

Ordres relacionades

Comandament/Descripció

• depurar HTTP; Utilitzeu aquesta comanda per view informació detallada sobre el trànsit HTTP.

Missatges Syslog relacionats amb l'API REST ASA

En aquesta secció es descriuen els missatges de registre del sistema relacionats amb l'API REST de l'ASA.

342001

• Missatge d'error: %ASA-7-342001: L'agent de l'API REST s'ha iniciat correctament.
  • Explicació: L'agent de l'API REST s'ha d'iniciar correctament abans que un client de l'API REST pugui configurar l'ASA.
  • Acció recomanada: Cap.

342002

• Missatge d'error: %ASA-3-342002: L'agent de l'API REST ha fallat, motiu: motiu
  • Explicació: L'agent de l'API REST podria fallar en iniciar-se o bloquejar-se per diversos motius, i s'especifica el motiu.
  • motiu: la causa de l'error de l'API REST

Acció recomanada: Les accions realitzades per resoldre el problema varien segons el motiu registrat. Per example, l'agent de l'API REST es bloqueja quan el procés Java s'esgota la memòria. Si això passa, cal que reinicieu l'agent de l'API REST. Si el reinici no té èxit, poseu-vos en contacte amb el TAC de Cisco per identificar la solució de la causa arrel.

342003

• Missatge d'error: %ASA-3-342003: S'ha rebut una notificació d'error de l'agent de l'API REST. L'agent es reiniciarà automàticament.
  • Explicació: S'ha rebut una notificació d'error de l'agent de l'API REST i s'està intentant reiniciar l'agent.
  • Acció recomanada: Cap.

342004

• Missatge d'error: %ASA-3-342004: no s'ha pogut reiniciar automàticament l'agent de l'API REST després de 5 intents infructuosos. Utilitzeu les ordres "sense agent rest-api" i "agent rest-api" per reiniciar manualment l'agent.
  • Explicació: L'agent de l'API REST no s'ha pogut iniciar després de molts intents.
  • Acció recomanada: Vegeu el syslog %ASA-3-342002 (si està registrat) per entendre millor el motiu de la fallada. Intenteu desactivar l'agent de l'API REST introduint l'ordre no rest-api agent i torneu a habilitar l'agent de l'API REST mitjançant l'ordre rest-api agent.

Documentació relacionada

Utilitzeu el següent enllaç per trobar més informació sobre l'ASA, i la seva configuració i gestió:

• Navegació per la documentació de la sèrie Cisco ASA: http://www.cisco.com/go/asadocs
• Utilitzeu el següent enllaç per view una llista de funcions ASA no admeses a l'ASAv: http://www.cisco.com/c/en/us/td/docs/security/asa/asa92/configuration/general/asa-general-cli/introasav.html#pgfId-1156883

Aquest document s'ha d'utilitzar juntament amb els documents disponibles a la secció "Documentació relacionada".
Cisco i el logotip de Cisco són marques comercials o marques comercials registrades de Cisco i/o les seves filials als EUA i altres països. A view una llista de marques comercials de Cisco, aneu a aquesta URL: Www.cisco.com/go/trademarks. Les marques comercials de tercers esmentades són propietat dels seus respectius propietaris. L'ús de la paraula soci no implica una relació de col·laboració entre Cisco i cap altra empresa. (1721R)
Les adreces i números de telèfon de protocol d'Internet (IP) utilitzats en aquest document no pretenen ser adreces i números de telèfon reals. Qualsevol exampEls fitxers, la sortida de visualització d'ordres, els diagrames de topologia de xarxa i altres figures incloses al document es mostren només amb finalitats il·lustratives.
Qualsevol ús d'adreces IP o números de telèfon reals en contingut il·lustratiu és involuntari i casual.

Cisco Systems, Inc.

• www.cisco.com

© 2014-2018 Cisco Systems, Inc. Tots els drets reservats.

Documents/Recursos

Aplicació CISCO ASA REST API [pdfGuia de l'usuari ASA REST API App, ASA, REST API App, API App, App

Referències

• Manual d'usuari