Visão geral da descoberta de APIs Shadow

Visão geral

Visualização — Shadow API Discovery

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos de serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

A descoberta de APIs Shadow da Apigee encontra APIs Shadow (também conhecidas como APIs não documentadas) na sua infraestrutura em nuvem. As APIs Shadow representam um risco de segurança para o sistema, já que podem ser desprotegidas, não monitoradas e não ter manutenção.

O uso da descoberta de APIs Shadow não afeta de maneira significativa nem diminui o tráfego no ambiente de execução.

As instruções nesta página para configurar e ver os resultados das observações da API são baseadas na interface da Apigee no console do Cloud. Também é possível usar as APIs de gerenciamento da Apigee (APIM) para gerenciar a descoberta de APIs Shadow. Consulte as APIs de gerenciamento da descoberta de APIs Shadow.

Ativar a descoberta de APIs Shadow

A descoberta de APIs Shadow faz parte do complemento Apigee Advanced API Security. Para a descoberta de APIs Shadow, o complemento é aplicável a cada organização. Para clientes de assinatura, ele está disponível na organização da Apigee. No entanto, os clientes de pagamento por uso precisam ativar o complemento em pelo menos um ambiente. A descoberta de APIs Shadow não está disponível para ambientes de avaliação da Apigee.

Para usar esse recurso, é necessário ativar o complemento. Se você é um cliente de assinatura, pode ativar o complemento para sua organização. Consulte Gerenciar organizações da Segurança avançada da API por assinatura se quiser mais detalhes. Se você é um cliente de pagamento por uso, ative o complemento nos seus ambientes qualificados. Para mais informações, consulte Gerenciar o complemento Segurança avançada da API.

Importante: os jobs ativos da descoberta de APIs Shadow também geram custos com base no volume de tráfego monitorado. Para mais informações sobre custos, consulte a seção "Como usar um back-end do Private Service Connect (balanceador de carga) para acessar um serviço publicado" das Regras de encaminhamento do PSC. Para eliminar esses custos, desative os jobs da descoberta de APIs Shadow.

Permissões e papéis necessários para a descoberta de APIs Shadow

A tabela abaixo mostra os papéis necessários para realizar tarefas relacionadas à descoberta de APIs Shadow.

Tarefa	Papéis necessários
Ativar ou desativar a Segurança avançada da API	Administrador da organização da Apigee (roles/apigee.admin)
Criar jobs e origens de observação	Administrador do gerenciamento de APIs (roles/apim.admin)
Ver observações	Leitor do gerenciamento de APIs (roles/apim.viewer)

Adicionar a permissão para o P4SA

Adicione um papel à conta de serviço por produto e por projeto (P4SA, na sigla em inglês) do seu projeto para ativar os jobs de observação. Adicione o papel Agente de serviço da descoberta de APIs do APIM em [e-mail]:

gcloud projects add-iam-policy-binding PROJECT_ID \
--member="serviceAccount:[e-mail]" \
--role="roles/apim.apiDiscoveryServiceAgent"

Acessar a descoberta de APIs Shadow no console da Apigee

Para acessar a descoberta de APIs Shadow no console da Apigee:

1. Faça login na interface da Apigee no console do Cloud.
2. Acesse Observação de API > API Shadow.
3. A página principal mostra todas as observações de API que já foram geradas. Selecione as guias Observações de API e Jobs de observação para alternar entre ver os resultados e criar jobs de observação.

Criar jobs de observação

Os jobs de observação fornecem as instruções que a descoberta de APIs Shadow precisa para procurar essas APIs. Siga estas etapas para criar um job de observação. Lembre-se dos comportamentos e limitações que se aplicam à criação de jobs de observação.

1. Selecione a guia Jobs de observação e clique em Criar job de observação.
2. Selecione uma ou mais Origens de observação.
   ou
3. Clique em Criar origem de observação na parte inferior da lista Origens de observação para criar novos locais de origem, se necessário. O processo de criação da origem de observação pode levar vários minutos.
   
   Nome da origem: um nome especificado para identificar a origem.
   Local: um local a ser observado. Incluir mais regiões de origem permite uma visão mais ampla das APIs em toda a infraestrutura. Consulte as práticas recomendadas. Apenas uma origem de observação pode ser criada em um local.
   Rede e sub-rede: a rede VPC e a sub-rede. A sub-rede precisa estar na mesma região que o local da origem de observação.
   
4. Crie um job de observação. Forneça um nome ao job de observação, que precisa ser exclusivo para cada local. Selecione um local que especifica onde ocorrerá a agregação e o processamento de dados. Todos os dados coletados nas regiões de origem são processados e acessados por essa região, de acordo com as políticas de residência de dados do Google. A criação de um novo job de observação pode levar alguns minutos para ser concluída.
5. Ativar job de observação (opcional). É possível ativar o job ao criá-lo. Nesse caso, ele começará a observação imediatamente. Se você não ativar o job imediatamente, será possível ativar o job de observação mais tarde na lista de jobs de observação.

Ativar, desativar e excluir jobs de observação

Para alterar se um job de observação existente está ativado (ativo), selecione Ativar ou Desativar no menu Ações na linha de desse job na página Jobs de observação.

Para excluir um job de observação existente, selecione Excluir no menu Ações desse job. A exclusão de um job também remove os resultados de observação associados a ele. Portanto, se você quiser preservar os resultados enquanto interrompe o job, desative-o em vez de excluí-lo. Jobs ativos não podem ser excluídos. Desative os jobs ativos primeiro se precisar excluí-los.

Observação: não é possível editar um job de observação no momento. Consulte Comportamentos e limitações.

Ver observações de API

Para ver as observações de API dos jobs de observação ativados, escolha a guia Observações de API e, em seguida, selecione o Job de observação na lista.

Observação: os jobs de observação não geram resultados imediatamente e estão sujeitos a limitações. Consulte Comportamentos e limitações para mais detalhes.

A lista de observações mostra estes valores:

• Nome do host: o nome do host da API. Clique no nome do host para ver os detalhes da observação.
• Operações de API: o número de operações de API (como solicitações GET ou PUT) observadas.
• IPs de servidor: IPs de servidores que hospedam as APIs descobertas.
• Local de origem: os locais de origem em que o tráfego foi observado.
• Último evento detectado (UTC): a data e a hora em que a solicitação mais recente à API foi detectada.

Mais detalhes da observação

Depois de clicar no nome do host na lista de observações, você verá a página de detalhes da observação.

Esta página inclui as seguintes informações sobre a observação.

• A caixa de resumo na parte de cima da página mostra:
  • ID da observação de API: é um identificador específico da Apigee.
  • Operações de API: consulte Ver observações de API para ver uma descrição desse campo.
  • Horário de criação (UTC): a data e a hora em que o job de observação foi criado.
  • Horário do último evento detectado: consulte Ver observações de API para ver uma descrição desse campo.
• Uma tabela das operações específicas de API detectadas nessa descoberta de APIs. Para cada solicitação, as seguintes informações são mostradas:
  • Caminho: o caminho da solicitação.
  • Método: o método da solicitação (como GET, PUT etc.).
  • Contagem: o número de solicitações para esse caminho com o método.
  • Solicitação de transação: o corpo da solicitação dos dados de tráfego. Inclui os cabeçalhos da solicitação e as contagens de transações correspondentes para essa operação de API.
  • Cabeçalhos de resposta da transação: os cabeçalhos de resposta dos dados de tráfego. Inclui os cabeçalhos de resposta e as contagens de transações correspondentes para essa operação de API.
  • Códigos de resposta da transação: os códigos de resposta e as contagens correspondentes de respostas com esse código para a operação de API.
  • Visto pela primeira vez (UTC): a primeira data e hora em que a solicitação para essa operação de API foi observada.
  • Visto pela última vez (UTC): a data e a hora mais recente em que a solicitação para a operação de API foi observada.

Práticas recomendadas

Recomendamos estas práticas ao trabalhar com a descoberta de APIs Shadow:

• Siga as regras de residência de dados da sua organização para garantir conformidade com todas as regulamentações e leis aplicáveis.
• Agregue o maior número possível de regiões de origem para conseguir a melhor correlação entre regiões. Incluir mais regiões de origem nos jobs de observação resulta em uma visão mais ampla das APIs em toda a infraestrutura.

Comportamentos e limitações

Esta seção lista os comportamentos e as limitações que se aplicam à descoberta de APIs Shadow:

• O uso da descoberta de APIs Shadow não garante a observação de 100% do tráfego ou a descoberta de todas as APIs Shadow.
• A descoberta de APIs Shadow encontra essas APIs apenas na sua infraestrutura do Google Cloud.
• No momento, a descoberta de APIs Shadow é compatível apenas com balanceadores de carga de aplicativo regionais.
• A descoberta de APIs Shadow encontra APIs de protocolo HTTP, não gRPC.
• Aviso: a descoberta de APIs Shadow é compatível com balanceadores de carga em uma só rede por projeto. Se você ativar a descoberta de APIs Shadow em um projeto com várias redes, poderá notar um comportamento inesperado.
• Aviso: ativar a descoberta de APIs Shadow pode causar um aumento na latência das chamadas do balanceador de carga em todas as redes no projeto.
• Pode levar até 60 minutos para que um job de observação recém-ativado detecte o tráfego.
• É preciso que haja tráfego fluindo pelos balanceadores de carga nos projetos observados para detectar APIs Shadow. A descoberta de APIs Shadow precisa ao menos de alguns minutos a algumas horas de detecção de tráfego, dependendo do volume do tráfego. O tráfego esparso requer tempos de observação mais longos antes que os resultados fiquem disponíveis.
• Para cada região, há um limite de uma única origem de observação e, no máximo, três jobs de observação. Se você precisar de mais de três jobs de observação, entre em contato com o suporte da Apigee para discutir o caso de uso.
• Os jobs de observação podem ser criados e desativados ou excluídos, mas não editados. Se você precisar alterar um job de observação, exclua-o e recrie-o.
• No momento, apenas algumas regiões são compatíveis com jobs da descoberta de APIs Shadow.