Demonstre a navegação por meio do API-Explorer do Secure Firewall

Introdução

Este documento descreve a navegação por meio do explorador da Interface de Programação de Aplicativos (API) do Cisco FMC e do Cisco FDM.

Pré-requisitos

Entendimento básico da API REST.

Requisitos

Para esta demonstração, é necessário ter acesso à GUI do Firepower Management Center (FMC) com pelo menos um dispositivo gerenciado por esse Firepower Management Center (FMC). Para a parte FDM desta demonstração, é necessário ter um Firepower Threat Defense (FTD) gerenciado localmente para ter acesso à GUI do FDM.

Componentes Utilizados

• FMCv
• FTDv
• FTDv Gerenciado localmente

As informações neste documento foram criadas a partir de dispositivos em um ambiente de laboratório específico. Todos os dispositivos utilizados neste documento foram iniciados com uma configuração (padrão) inicial. Se a rede estiver ativa, certifique-se de que você entenda o impacto potencial de qualquer comando.

Revisar a navegação pelo FMC API Explorer

Para acessar o FMC API explorer, navegue até o próximo URL:

https://<FMC_mgmt_IP>/api/api-explorer

Você deve fazer login com as mesmas credenciais usadas para a GUI do FMC. Essas credenciais são inseridas em uma janela semelhante à seguinte quando você insere os URLs do explorador de API.

Após o login, é visto que as consultas de API são divididas por categorias correspondentes às possíveis chamadas que você pode fazer usando APIs.

Quando você clica em uma categoria, ela é expandida, mostrando as diferentes chamadas disponíveis para essa categoria. Essas chamadas são mostradas junto com seus respectivos métodos REST e o Universal Resource Identifier (URI) dessa chamada.

No próximo exemplo, você faz uma solicitação para ver as políticas de acesso configuradas no FMC. Clique no método correspondente para expandi-lo e, em seguida, clique no botão Try it out.

É importante enfatizar que você pode parametrizar suas consultas com os parâmetros disponíveis em cada chamada de API. Somente aqueles com asteriscos vermelhos são obrigatórios, os outros podem ser deixados vazios.

Por exemplo, o domainUID é obrigatório para todas as chamadas de API, mas no Explorador de API isso é preenchido automaticamente.

A próxima etapa é clicar em Executar para fazer essa chamada.

Antes de clicar em Executar, você poderá ver exemplos de respostas às chamadas para ter uma ideia das respostas possíveis, dependendo se a solicitação está correta ou não.

Depois que a chamada de API é executada, você obtém, junto com o payload de resposta, o código de resposta. Nesse caso, 200, que corresponde a um pedido OK. Você também obtém a cURL e a URL da chamada que acabou de fazer. Essas informações serão úteis se você quiser fazer essa chamada com um software/cliente externo.

A resposta obtida retorna os ACPs configurados no FMC junto com seu objectID. Nesse caso, você pode ver essas informações na caixa vermelha na próxima imagem:

Este objectID é o valor inserido em chamadas que requerem referência a este ACP. Por exemplo, para criar uma regra neste ACP.

Os URIs que contêm valores entre chaves {} são valores necessários para fazer essa chamada.  Lembre-se de que domainUID é o único valor preenchido automaticamente.

Os valores necessários para essas chamadas são especificados na descrição da chamada. Para criar regras para um ACP, é necessário o policyID, como você pode ver na próxima imagem:

Essa policyID é inserida no campo especificado como containerUID, outro campo obrigatório para métodos POST é o corpo da carga ou da solicitação. Você pode usar os exemplos fornecidos para modificar de acordo com suas necessidades.

Exemplo de carga útil modificada:

{ "action": "ALLOW", "enabled": true, "type": "AccessRule", "name": "Testing API rule", "sendEventsToFMC": false, "logFiles": false, "logBegin": false, "logEnd": false, "sourceZones": { "objects": [ { "name": "Inside_Zone", "id": "8c1c58ec-8d40-11ed-b39b-f2bc2b448f0d", "type": "SecurityZone" } ] }, "destinationZones": { "objects": [ { "name": "Outside_Zone", "id": "c5e0a920-8d40-11ed-994a-900c72fc7112", "type": "SecurityZone" } ] }, "newComments": [ "comment1", "comment2" ] }

Depois de executar a chamada anterior, você obtém um código de resposta 201, indicando que a solicitação foi bem-sucedida e levou à criação do recurso.

Finalmente, você deve fazer uma implantação para que essas alterações entrem em vigor no FTD cujo ACP foi modificado.

Para isso, você precisa obter a lista de dispositivos que têm alterações prontas para serem implantadas.

O exemplo contém um par de dispositivos configurados em Alta Disponibilidade. Você deve obter a ID deste HA, caso seja um dispositivo autônomo, você deve obter a ID desse dispositivo.

A consulta necessária para obter a ID do dispositivo do HA é a seguinte:

Com o ID do dispositivo e o número da versão de implantação, você pode modificar o payload do próximo exemplo de chamada para fazer a chamada para executar essa implantação.

Uma vez executada esta chamada, se tudo estiver correto, você obterá uma resposta com o código 202.

Revise a Navegação por meio do FDM API Explorer

Para acessar o API Explorer do FDM, é possível usar um botão na GUI do FDM para ir diretamente para ele, como mostrado na imagem a seguir:

No API Explorer, você observa que as consultas também são divididas em categorias.

Para expandir uma categoria, você deve clicar nela e, em seguida, pode expandir cada uma das operações clicando em qualquer uma delas. A primeira coisa encontrada dentro de cada operação é um exemplo de uma resposta OK para essa chamada.

Em seguida, você verá os parâmetros disponíveis para restringir as respostas da chamada feita. Lembre-se de que somente os campos marcados como obrigatórios são obrigatórios para fazer essa chamada.

Finalmente, você encontrará os possíveis códigos de resposta que essa chamada pode retornar.

Para fazer essa chamada, clique em Try It Out. Para encontrar esse botão, você deve rolar para baixo até encontrar esse botão, pois ele está localizado na parte inferior de cada chamada.

Quando você clica no botão Try It Out, se for uma chamada que não requer mais campos, ela é executada imediatamente e fornece a resposta.

Troubleshooting

Cada chamada gera um código de resposta HTTP e um corpo de resposta. Isso ajuda a identificar onde o erro está.

O próximo é um erro comum que ocorre quando a sessão expira, indicando que o token é inválido porque expirou.

A seguir estão exemplos de códigos de resposta HTTP que as chamadas podem retornar:

• Série 2xx: sucesso. Existem vários códigos de status: 200 (GET e PUT), 201 (POST), 202, 204 (DELETE). Indicam uma chamada à API bem-sucedida.
• Série 30x: redirecionamento. Pode ser usado quando um cliente originalmente usou HTTP e foi redirecionado para HTTPS.
• Série 4xx: falha do lado do cliente na chamada API enviada do cliente para o servidor. Dois exemplos incluem um código de status 401, indicando que a sessão não está autenticada, e um código 403, indicando uma tentativa de acesso proibido.
• Série 5xx: falha no servidor, dispositivo ou no lado do serviço. Isso pode ser o resultado de o serviço API do dispositivo estar desabilitado ou inacessível pela rede IP