Aplicación CISCO ASA REST API

Instrucións de uso do produto

Acabadoview

Co lanzamento da API ASA REST de Cisco, agora tes outra opción lixeira e fácil de usar para configurar e xestionar Cisco ASA individuais. A API REST de ASA é unha interface de programación de aplicacións (API) baseada nos principios RESTful. Pódese descargar e activar rapidamente en calquera ASA onde se estea executando a API. Cisco Systems, Inc.

www.cisco.com

Solicitudes e respostas da API ASA REST

Despois de instalar un cliente REST no seu navegador, pode contactar co axente REST específico de ASA e utilizar métodos HTTP estándar para acceder á información de configuración actual e emitir parámetros de configuración adicionais.

Atención: Cando a API REST está activada nun ASA, as conexións doutros protocolos de xestión de seguranza non se bloquean. Isto significa que outros que usan CLI, ASDM ou Security Manager poderían estar alterando a configuración ASA mentres ti fai o mesmo.

Estrutura de solicitude

A API ASA REST ofrécelle acceso mediante programación para xestionar ASA individuais mediante unha API de transferencia de estado de representación (REST). A API permite que os clientes externos realicen operacións CRUD (Crear, Ler, Actualizar, Eliminar) en recursos ASA. Todas as solicitudes de API envíanse a través de HTTPS ao ASA e devólvese unha resposta.

onde as propiedades do obxecto son:

Propiedade	Tipo	Descrición
mensaxes	Lista de dicionarios	Lista de mensaxes de erro ou aviso
código	Corda	Mensaxe detallada correspondente a Erro/Aviso/Información
detalles	Corda	Mensaxe detallada correspondente a Erro/Aviso/Información

Nota: Os cambios realizados polas chamadas da API REST non se conservan na configuración de inicio, senón que se asignan só á configuración en execución. Para gardar os cambios na configuración de inicio, pode usar a solicitude da API de escritura mem POST. Para obter máis información, consulte a entrada da API de memoria de escritura na táboa de contidos Acerca da API REST de ASA.

Instale e configure o axente e cliente da API REST ASA

Nota: O axente da API REST é unha aplicación baseada en Java. O Java Runtime Environment (JRE) está incluído no paquete do axente da API REST.

Acabadoview

Existen varias opcións dispoñibles para configurar e xestionar Cisco ASA individuais:

• Interface de liña de comandos (CLI): envía comandos de control directamente ao ASA a través dunha consola conectada.
• Adaptive Security Device Manager (ASDM): unha aplicación de xestión integrada cunha interface gráfica de usuario que pode usar para configurar, xestionar e supervisar un ASA.
• Cisco Security Manager: aínda que está destinada a redes medianas e grandes de moitos dispositivos de seguridade, esta aplicación gráfica pódese usar para configurar, xestionar e supervisar ASA individuais.

Co lanzamento da API ASA REST de Cisco, agora tes outra opción lixeira e fácil de usar. Esta é unha interface de programación de aplicacións (API), baseada nos principios "RESTful", que pode descargar e activar rapidamente en calquera ASA no que se estea executando a API.

Despois de instalar un cliente REST no seu navegador, pode contactar co axente REST específico de ASA e utilizar métodos HTTP estándar para acceder á información de configuración actual e emitir parámetros de configuración adicionais.

Atención: Cando a API REST está activada nun ASA, as conexións doutros protocolos de xestión de seguranza non se bloquean. Isto significa que outros que usan CLI, ASDM ou Security Manager poderían estar alterando a configuración ASA mentres ti fai o mesmo.

Solicitudes e respostas da API ASA REST

A API REST de ASA ofrécelle acceso mediante programación para xestionar ASA individuais mediante unha API de transferencia de estado de representación (REST). A API permite que os clientes externos realicen operacións CRUD (Crear, Ler, Actualizar, Eliminar) en recursos ASA; baséase no protocolo HTTPS e na metodoloxía REST. Todas as solicitudes de API envíanse a través de HTTPS ao ASA e devólvese unha resposta. Esta sección ofrece un sobreview de como se estruturan as solicitudes e as respostas esperadas,

Estrutura de solicitude

Os métodos de solicitude dispoñibles son:

• GET: recupera datos do obxecto especificado.
• PUT – Engade a información proporcionada ao obxecto especificado; devolve un erro 404 Resource Not Found se o obxecto non existe.
• POST: crea o obxecto coa información proporcionada.
• DELETE: elimina o obxecto especificado.
• PATCH: aplica modificacións parciais ao obxecto especificado.

Estrutura de resposta

• Cada solicitude produce unha resposta HTTPS do ASA coas cabeceiras estándar, o contido da resposta e o código de estado.

A estrutura de resposta pode ser:

• LOCALIZACIÓN: ID de recurso recentemente creado; só para POST: contén o novo ID de recurso (como representación do URI).
• CONTENT-TYPE: tipo de medio que describe o corpo da mensaxe de resposta; describe a representación e sintaxe do corpo da mensaxe de resposta.

Cada resposta inclúe un código de erro ou estado HTTP. Os códigos dispoñibles están dentro destas categorías:

• 20x: un código de dúascentas series indica un funcionamento exitoso, incluíndo:
  • 200 OK: resposta estándar para solicitudes exitosas.
  • 201 Creado: solicitude completada; novo recurso creado.
  • 202 Aceptado: aceptouse a solicitude, pero o procesamento non completo.
  • 204 Sen contido: o servidor procesou correctamente a solicitude; non se devolve ningún contido.
• 4xx: un código de catrocentas series indica un erro no lado do cliente, incluíndo:
  • 400 Solicitude incorrecta: parámetros de consulta non válidos, incluídos os parámetros non recoñecidos, os parámetros que faltan ou os valores non válidos.
  • 404 Non atopado: o proporcionado URL non coincide cun recurso existente. Por example, un HTTP DELETE pode fallar porque o recurso non está dispoñible.
  • 405 Método non permitido: presentouse unha solicitude HTTP que non está permitida no recurso; por example, un POST nun recurso de só lectura.
• 5xx: un código de cincocentas series indica un erro no servidor.

No caso dun erro, ademais do código de erro, a resposta de retorno pode incluír un obxecto de erro que conteña máis detalles sobre o erro. O esquema de resposta de erro/advertencia JSON é o seguinte:

onde as propiedades do obxecto son:

Propiedade	Tipo	Descrición
mensaxes	Lista de dicionarios	Lista de mensaxes de erro ou aviso
código	Corda	Código de erro/aviso/información
detalles	Corda	Mensaxe detallada correspondente a Erro/Aviso/Información

Nota: Os cambios na configuración ASA feitas polas chamadas da API REST non se conservan na configuración de inicio; é dicir, os cambios son asignados só á configuración en execución. Para gardar os cambios na configuración de inicio, pode PUBLICAR unha solicitude da API writemem; para obter máis información, siga a entrada "Escribir API de memoria" na táboa de contidos Acerca da API REST de ASA.

Instale e configure o axente e cliente da API REST ASA

• O axente da API REST publícase individualmente con outras imaxes ASA activadas cisco.com. Para os ASA físicos, o paquete da API REST debe descargarse no flash do dispositivo e instalarse mediante o comando "rest-api image". O axente da API REST habilitarase mediante o comando "axente de API de resto".
• Cun ASA virtual (ASAv), a imaxe da API REST debe descargarse na partición "boot:". A continuación, debes emitir o comando "rest-api image", seguido do comando "rest-api agent", para acceder e habilitar o axente da API REST.
• Para obter información sobre os requisitos e compatibilidade do software e hardware da API REST, consulte a matriz de compatibilidade de Cisco ASA.
• Podes descargar o paquete de API REST adecuado para o teu ASA ou ASAv desde software.cisco.com/download/home. Localice o modelo específico de Adaptive Security Appliance (ASA) e, a continuación, escolla Adaptive Security Appliance REST API Plugin.

Nota: O axente da API REST é unha aplicación baseada en Java. O Java Runtime Environment (JRE) está incluído no paquete do axente da API REST.

Pautas de uso

Importante Debe incluír a cabeceira User-Agent: REST API Agent en todas as chamadas de API e scripts existentes. Use -H 'User-Agent: REST API Agent' para CURL mando. No modo multicontexto, os comandos do axente da API REST só están dispoñibles no contexto do sistema.

Tamaño máximo de configuración admitido

A API ASA Rest é unha aplicación "integrada" que se executa dentro do ASA físico e, como tal, ten unha limitación na memoria que se lle asigna. O tamaño máximo de configuración en execución admitida aumentou durante o ciclo de lanzamento ata aproximadamente 2 MB en plataformas recentes como 5555 e 5585. A API ASA Rest tamén ten restricións de memoria nas plataformas ASA virtuais. A memoria total do ASAv5 pode ser de 1.5 GB, mentres que no ASAv10 é de 2 GB. Os límites da API Rest son 450 KB e 500 KB para ASAv5 e ASAv10, respectivamente.

Polo tanto, teña en conta que as grandes configuracións en execución poden producir excepcións en varias situacións de uso intensivo de memoria, como un gran número de solicitudes simultáneas ou grandes volumes de solicitudes. Nestas situacións, as chamadas GET/PUT/POST da API de Rest poden comezar a fallar con 500 mensaxes de erro do servidor interno, e o axente da API Rest reiniciarase automaticamente cada vez. As solucións para esta situación son mover a plataformas ASA/FPR ou ASAV de maior memoria ou reducir o tamaño da configuración en execución.

Descarga e instala o axente da API REST

Usando a CLI, siga estes pasos para descargar e instalar o axente da API REST de ASA nun ASA específico:

• Paso 1: No ASA desexado, emita a copia disk0: comando para descargar o paquete actual da API ASA REST cisco.com á memoria flash da ASA.
  • Por exampLe: copia tftp://10.7.0.80/asa-restapi-111-lfbff-k8.SPA disk0:
• Paso 2: Emita o disco de imaxe rest-api0:/ comando para verificar e instalar o paquete.
  • Por exampLe: rest-api image disk0:/asa-restapi-111-lfbff-k8.SPA

O instalador realizará comprobacións de compatibilidade e validación e, a continuación, instalará o paquete. O ASA non se reiniciará.

Activa o axente da API REST

Siga estes pasos para activar o axente da API REST de ASA nun ASA específico:

• Paso 1: Asegúrese de que a imaxe de software correcta está instalada no ASA.
  • Consulte a sección API REST da Matriz de compatibilidade ASA (https://www.cisco.com/c/en/us/td/docs/security/asa/compatibility/asamatrx.html#pgfId-131643) para determinar que imaxe ASA é necesaria.
• Paso 2: Usando a CLI, asegúrese de que o servidor HTTP estea activado no ASA e de que os clientes da API poidan conectarse á interface de xestión.
  • Por exampLe: Habilitar o servidor http
  • http 0.0.0.0 0.0.0.0
• Paso 3: Usando a CLI, define a autenticación HTTP para as conexións da API. Por example: aaa autenticación http consola LOCAL
• Paso 4: Usando a CLI, cree unha ruta estática no ASA para o tráfico da API. Por example: ruta 0.0.0.0 0.0.0.0 1
• Paso 5: Usando a CLI, active o axente da API REST de ASA no ASA. Por example: axente de resto-api

Autenticación da API REST

Hai dúas formas de autenticarse: a autenticación HTTP básica, que pasa un nome de usuario e un contrasinal en cada solicitude, ou a autenticación baseada en tokens con transporte HTTPS seguro, que pasa un token creado previamente con cada solicitude. De calquera xeito, realizarase a autenticación para cada solicitude. Consulte a sección "Token_Authentication_API" na guía Acerca da ASA REST API v7.14(x) para obter información adicional sobre a autenticación baseada en Token.

Nota: Recoméndase o uso de certificados emitidos pola autoridade de certificación (CA) en ASA, polo que os clientes da API REST poden validar os certificados do servidor ASA ao establecer conexións SSL.

Autorización de mando

Se a autorización de comandos está configurada para usar un servidor AAA externo (por exemploample, comando de autorización aaa ), entón un usuario chamado enable_1 debe existir nese servidor con privilexios de comando completos. Se a autorización de comandos está configurada para usar a base de datos LOCAL de ASA (comando de autorización aaa LOCAL), todos os usuarios da API REST deben estar rexistrados na base de datos LOCAL con niveis de privilexios adecuados para as súas funcións:

• Requírese un nivel de privilexio 3 ou superior para invocar solicitudes de supervisión.
• Requírese un nivel de privilexio 5 ou superior para invocar solicitudes GET.
• O nivel de privilexio 15 é necesario para invocar operacións PUT/POST/DELETE.

Configura o teu cliente da API REST

Siga estes pasos para instalar e configurar un cliente da API REST no seu navegador de host local:

• Paso 1: Adquire e instale un cliente da API REST para o seu navegador.
  • Para Chrome, instala o cliente REST de Google. Para Firefox, instala o complemento RESTClient. Internet Explorer non é compatible.
• Paso 2: Inicie a seguinte solicitude usando o seu navegador: https: /api/objects/networkobjects
  • Se recibe unha resposta sen erro, chegou ao axente da API REST que funciona no ASA.
  • Se tes problemas coa solicitude do axente, podes activar a visualización da información de depuración na consola da CLI, como se describe en Activación da depuración da API REST no ASA.
• Paso 3: Opcionalmente, pode probar a súa conexión co ASA realizando unha operación POST.

Por exampLe: Proporcione credenciais de autorización básicas ( ), ou un token de autenticación (consulte Autenticación de token para obter información adicional).

• Enderezo de solicitude de destino: https://<asa management ipaddress>/api/objects/networkobjects
• Tipo de contido corporal: aplicación/json

Corpo bruto da operación:

Agora podes usar a API REST de ASA para configurar e supervisar o ASA. Consulte a documentación da API para obter descricións de chamadas e, por exemploamples.

Acerca da restauración completa dunha configuración de copia de seguranza

Restaurar unha configuración de copia de seguranza completa no ASA mediante a API REST volverá cargar o ASA. Para evitar isto, use o seguinte comando para restaurar unha configuración de copia de seguranza:

• {
  • "comandos":["copiar /noconfirm disk0:/filenome> running-config”]
• }
  • Ondefilenome> é backup.cfg ou calquera nome que utilizaches ao facer unha copia de seguranza da configuración.

A consola de documentación e os scripts da API de exportación

Tamén pode usar a consola de documentación en liña da API REST (denominada "Interfaz de usuario do documento"), dispoñible en host:port/doc/ como un "sandbox" para coñecer e probar as chamadas da API directamente no ASA. Ademais, pode usar o botón Exportar Operación na IU do documento para gardar o método mostrado, por exemploampcomo un script JavaScript, Python ou Perl file ao teu anfitrión local. Despois podes aplicar este script ao teu ASA e editalo para a súa aplicación noutros ASA e outros dispositivos de rede. Isto significou principalmente como unha ferramenta educativa e de arranque.

JavaScript

• Usando un JavaScript file require a instalación de node.js, que se pode atopar en http://nodejs.org/.
• Usando node.js, pode executar un JavaScript file, normalmente escrito para un navegador, como un script de liña de comandos. Simplemente siga as instrucións de instalación e, a continuación, execute o seu script co nodo script.js.

Python

• Os scripts de Python requiren que instales Python, dispoñible desde https://www.python.org/.
• Unha vez que instale Python, pode executar o seu script co contrasinal do nome de usuario de python script.py.

Perl

O uso dos scripts de Perl require unha configuración adicional; precisa de cinco compoñentes: o propio Perl e catro bibliotecas de Perl:

• Paquete Perl, atopado en http://www.perl.org/
• Paquete::CPAN, atopado en http://search.cpan.org/~andk/Bundle-CPAN-1.861/CPAN.pm
• DESCANSO::Cliente, atopado en http://search.cpan.org/~mcrawfor/REST-Client-88/lib/REST/Client.pm
• MIME::Base64, atopada en http://perldoc.perl.org/MIME/Base64.html
• JSON, atopado en http://search.cpan.org/~makamaka/JSON-2.90/lib/JSON.pm

Aquí está un exampficheiro de arranque de Perl nun Macintosh:

• $ sudo perl -MCPAN e shell
• cpan> instalar paquete::CPAN
• cpan> instalar REST:: Cliente
• cpan> instalar MIME:: Base 64
• cpan> instalar JSON

Despois de instalar as dependencias, pode executar o seu script usando o contrasinal do nome de usuario perl script.pl.

Activando a depuración da API REST no ASA

Se tes problemas para configurar ou conectarte á API REST no ASA, podes usar o seguinte comando da CLI para activar a visualización das mensaxes de depuración na túa consola. Use a forma no do comando para desactivar as mensaxes de depuración.
depurar rest-api [axente | cli | cliente | demo | proceso | token-auth] [erro | evento] sen depuración rest-api

Descrición da sintaxe

• axente: (Opcional) Activa a información de depuración do axente da API REST.
• cli: (Opcional) Activa as mensaxes de depuración para as comunicacións de daemon a axente da CLI da API REST.
• cliente: (Opcional) Activa a información de depuración para o enrutamento de mensaxes entre o cliente da API REST e o axente da API REST.
• daemon: (Opcional) Activa as mensaxes de depuración para as comunicacións de daemon a axente da API REST.
• proceso: (Opcional) Activar a información de inicio/deter depuración do proceso do axente da API REST.
• token-auth: (Opcional) Información de depuración de autenticación de token da API REST.
• erro: (Opcional) Use esta palabra clave para limitar as mensaxes de depuración só aos erros rexistrados pola API.
• evento: (Opcional) Use esta palabra clave para limitar as mensaxes de depuración só aos eventos rexistrados pola API.

Pautas de uso

Se non fornece unha palabra clave de compoñente específica (é dicir, se simplemente emite o comando debug rest-api), as mensaxes de depuración móstranse para todos os tipos de compoñentes. Se non fornece nin a palabra clave de evento nin de erro, móstranse tanto as mensaxes de evento como de erro para o compoñente especificado. Por example, o evento debug rest-api daemon mostrará só mensaxes de depuración de eventos para as comunicacións API Daemon-to-Agent.

Comandos relacionados

Comando/Descrición

• depurar HTTP; Use este comando para view información detallada sobre o tráfico HTTP.

Mensaxes Syslog relacionadas coa API ASA REST

Nesta sección descríbense as mensaxes de rexistro do sistema relacionadas coa API ASA REST.

342001

• Mensaxe de erro: %ASA-7-342001: o axente da API REST iniciouse correctamente.
  • Explicación: O axente da API REST debe iniciarse correctamente antes de que un cliente da API REST poida configurar o ASA.
  • Acción recomendada: Ningún.

342002

• Mensaxe de erro: %ASA-3-342002: Fallou o axente da API REST, motivo: motivo
  • Explicación: O axente da API REST pode fallar ao iniciarse ou fallar por varios motivos, e o motivo especifícase.
  • motivo: a causa do fallo da API REST

Acción recomendada: As accións realizadas para resolver o problema varían segundo o motivo rexistrado. Por example, o axente da API REST falla cando o proceso Java queda sen memoria. Se isto ocorre, cómpre reiniciar o axente da API REST. Se o reinicio non se realiza correctamente, póñase en contacto co TAC de Cisco para identificar a corrección da causa raíz.

342003

• Mensaxe de erro: %ASA-3-342003: Recibiuse a notificación de fallo do axente da API REST. O axente reiniciarase automaticamente.
  • Explicación: Recibiuse unha notificación de fallo do axente da API REST e estase tentando reiniciar o axente.
  • Acción recomendada: Ningún.

342004

• Mensaxe de erro: %ASA-3-342004: non se puido reiniciar automaticamente o axente da API REST despois de 5 intentos infrutuosos. Use os comandos "sen axente rest-api" e "axente de resto-api" para reiniciar manualmente o axente.
  • Explicación: O axente da API REST non se puido iniciar despois de moitos intentos.
  • Acción recomendada: Consulte o syslog %ASA-3-342002 (se se rexistrou) para comprender mellor o motivo do fallo. Tenta desactivar o axente da API REST introducindo o comando no rest-api agent e volva habilitar o axente da API REST mediante o comando rest-api agent.

Documentación relacionada

Use a seguinte ligazón para atopar máis información sobre o ASA, e a súa configuración e xestión:

• Navegación pola documentación da serie Cisco ASA: http://www.cisco.com/go/asadocs
• Use a seguinte ligazón para view unha lista de funcións ASA non admitidas no ASAv: http://www.cisco.com/c/en/us/td/docs/security/asa/asa92/configuration/general/asa-general-cli/introasav.html#pgfId-1156883

Este documento debe utilizarse xunto cos documentos dispoñibles na sección "Documentación relacionada".
Cisco e o logotipo de Cisco son marcas comerciais ou marcas rexistradas de Cisco e/ou das súas filiales nos EUA e noutros países. Para view unha lista de marcas comerciais de Cisco, vaia a esta URL: www.cisco.com/go/trademarks. As marcas rexistradas de terceiros mencionadas son propiedade dos seus respectivos propietarios. O uso da palabra socio non implica unha relación de colaboración entre Cisco e ningunha outra empresa. (1721R)
Calquera enderezo e número de teléfono de protocolo de Internet (IP) utilizados neste documento non pretenden ser enderezos e números de teléfono reais. Calquera exampOs ficheiros, a saída de visualización de comandos, os diagramas de topoloxía de rede e outras figuras incluídas no documento móstranse só con fins ilustrativos.
Calquera uso de enderezos IP ou números de teléfono reais en contido ilustrativo é non intencionado e casual.

Cisco Systems, Inc.

• www.cisco.com

© 2014-2018 Cisco Systems, Inc. Todos os dereitos reservados.

Documentos/Recursos

Aplicación CISCO ASA REST API [pdfGuía do usuario Aplicación API ASA REST, ASA, aplicación API REST, aplicación API, aplicación

Referencias

• Manual de usuario