Visão geral da descoberta de APIs Shadow

Visão geral

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 da API Shadow não afeta nem diminui significativamente o tráfego de tempo de execução. No entanto, as latências de cauda de tráfego por meio de balanceadores de carga observados podem ser afetadas de maneira notável.

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, ative 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.

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)

Acessar a descoberta de APIs Shadow no console da Apigee

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

Faça login na interface da Apigee no console do Cloud.
Acesse Observação de API > API Shadow.
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.

Selecione a guia Jobs de observação e clique em Criar job de observação.
Selecione uma ou mais Fontes de observação ou 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.

As origens de observação incluem:
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.
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.
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.

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.

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.
Locais 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.
Tags: uma lista das tags que você ou outra pessoa criou para marcar essa observação. Consulte Usar tags para mais informações.
Ações: outras ações disponíveis para cada observação.

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.

Detalhes do job de observação da descoberta da API Shadow

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.
- Tags: use tags para organizar os resultados do job de observação.
- 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.

Usar tags

As tags permitem categorizar os resultados das observações. As tags são metadados e servem apenas para acompanhamento. Elas não mudam nada nos resultados de observação nem acionam ações. Por exemplo, adicionar um alerta do tipo "Requer atenção" faz criar avisos ou alertas. Os novos resultados da observação não têm tags.

As tags têm as seguintes características:

É possível adicionar a mesma tag a vários resultados de observação.
Os nomes das tags podem incluir letras maiúsculas e minúsculas, números e caracteres especiais, incluindo espaços.
Depois que uma tag é criada, o nome não pode ser alterado. Remova e recrie a tag para renomeá-la.
A remoção de uma tag de todas as observações exclui o item do sistema.

É possível gerenciar tags na lista de observações ou na página de detalhes da observação.

Para gerenciar tags na lista de observações de API:

Confira as tags na coluna Tags da lista de observações.
Para gerenciar as tags de um resultado, selecione Gerenciar tags no menu Ações na linha desse resultado.
Para gerenciar as tags de um ou mais resultados ao mesmo tempo, selecione vários resultados na lista e em Gerenciar tags na parte superior da lista.

Para gerenciar tags nos detalhes de observação da API:

Veja as tags na seção Tags.
Para adicionar ou gerenciar tags, escolha Gerenciar tags na parte de cima da página.

No painel lateral Gerenciar tags, selecione tags atuais ou adicione novas. Para remover tags, desmarque-as. Clique em Salvar para salvar as novas tags.

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 trabalhos de observação, entre em contato Google Cloud Customer Care, 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. Consulte a lista de regiões compatíveis com esta solicitação:
```
curl -H "Authorization: Bearer $(gcloud auth print-access-token)"
https://apim.googleapis.com/v1alpha/projects/{PROJECT}/locations
```