API Security Reports

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Além de usar relatórios de segurança na IU da Apigee, também é possível acessar todos os recursos desses relatórios pela API Security Reports. Nesta seção, descrevemos como usar a API Security Reporting.

Observação:os dados que fluem para o pipeline do Apigee Analytics têm um atraso de até 15 a 20 minutos em média. Como resultado, um relatório de segurança em que o horário de término é anterior a 20 minutos pode retornar resultados incorretos.

Parâmetros em chamadas de API de exemplo

As seções a seguir mostram exemplos de chamadas de API que usam a API Security Reporting. As chamadas de API contêm os seguintes parâmetros:

  • ORG é sua organização.
  • ENV é o ambiente em que você quer que o relatório seja calculado.
  • ENVGROUP é um grupo de ambiente que contém o ambiente.
  • REPORT_ID é o ID do relatório retornado por uma chamada para criar um relatório de segurança.
  • $TOKEN é a variável de ambiente de um token de acesso do OAuth.
  • timeRange é o período do relatório.

Criar um relatório de segurança

Para criar um relatório de segurança, insira um comando como este:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

em que Query.json é um modelo de consulta que define a consulta. Veja abaixo um exemplo de modelo de consulta.

{
  "dimensions": [
    "ax_resolved_client_ip",
  ],
  "metrics": [
    {
      "aggregation_function": "count_distinct",
      "name": "bot"
    },
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    },
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

A consulta tem os seguintes parâmetros:

  • Métricas:
    • bot Isso contabiliza o número de endereços IP distintos que foram identificados como origens de bots.

      função de agregação: count_distinct

    • bot_traffic O número total de solicitações de endereços IP que são as origens dos bots.

      função de agregação: sum

    Consulte Métricas e funções de agregação.

  • Dimensão: ax_resolved_client_ip. Isso agrupa o número de bots no relatório pelo endereço IP da origem.

    Consulte Dimensões.

  • Filtrar: environment.
  • groupByTimeUnit: minute
  • período: last7days Consulte Período.

Essa chamada de API retorna o mesmo relatório do exemplo de endereços IP do bot criado usando a IU da Apigee.

Intervalo de tempo

É o período do relatório. É possível definir o campo timeRange de uma das seguintes maneiras:

  • Especifique quanto tempo no passado o relatório deve ser estendido. As opções são as seguintes:
    "timeRange": "{last60minutes/last24hours/last7days}"
  • Especifique os horários de início e término do relatório no seguinte formato:
    "timeRange": {
            "start": "YYYY-MM-DDT00:00:00Z",
            "end": "YYYY-MM-DDT00:00:00Z"
            }

    start e end precisam estar no passado e podem ter, no máximo, um ano antes da data atual ao criar o relatório.

Exemplo de resposta

A consulta acima retorna uma resposta como esta:

{
  "self": "/organizations/ORG/environments/ENV/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "enqueued",
  "created": "2021-08-06T22:28:28Z"
}

A resposta contém o seguinte:

  • O ID do relatório, que pode ser usado para gerar o relatório quando ele for concluído. No exemplo acima, o ID do relatório é 3964675e-9934-4398-bff5-39dd93a67201.
  • "state": o estado do job de relatório, que pode ser um dos seguintes:
    • enqueued: o job de relatório acabou de ser criado, mas ainda não está em execução.
    • running: o job de relatório está em execução.
    • completed: o job de relatório foi concluído. Nessa etapa, você pode ver o relatório.
    • expired: o job de relatório expirou, e você não pode mais vê-lo.

Ver o status do relatório

Para ver o status de um relatório, envie uma solicitação como a seguinte:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID" \
       -X GET  -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

em que REPORT_ID é o ID do relatório. Consulte Parâmetros em exemplos de chamadas de API.

A resposta contém um resumo dos parâmetros do relatório, bem como o status atual do relatório. Neste exemplo, o status é "completed" para que você possa ver os resultados do relatório.

{
  "self": "/organizations/sense-staging-test/environments/local/securityReports/bd2f4fe0-a906-44c2-8dcb-2c618e4b565d",
  "state": "completed",
  "created": "2022-06-27T13:00:25-07:00",
  "updated": "2022-06-27T13:01:08-07:00",
  "result": {
    "self": "/organizations/sense-staging-test/environments/local/securityReports/bd2f4fe0-a906-44c2-8dcb-2c618e4b565d/result",
    "expires": "2022-07-04T13:01:08-07:00"
  },
  "resultRows": "848",
  "resultFileSize": "5.10 KB",
  "executionTime": "43 seconds",
  "queryParams": {
    "metrics": [
      "name:bot,func:count_distinct,alias:count_distinct_bot,op:,val:",
      "name:bot_traffic,func:sum,alias:sum_bot_traffic,op:,val:"
    ],
    "dimensions": [
      "ax_resolved_client_ip"
    ],
    "startTimestamp": "2022-06-20T20:00:25.098237292Z",
    "endTimestamp": "2022-06-27T20:00:25.098237292Z",
    "mimeType": "json",
    "timeUnit": "minute"
  },
  "displayName": "Sample Query Bot"
}

Veja o relatório

Para fazer o download do relatório de segurança, envie uma solicitação como esta:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H "Authorization: Bearer $TOKEN"

em que REPORT_ID é o ID do relatório. Consulte Parâmetros em exemplos de chamadas de API.

Isso retorna um arquivo que contém o relatório, com o nome no formato OfflineQueryResult-{ID}.zip. Ver o relatório:

  1. Unzip OfflineQueryResult-{ID}.zip.
  2. Digite gzip -d QueryResults-{ID}*.json.gz.
  3. Insira cat QueryResults-{ID}*.json
  4. .

Exemplo de tráfego de bots

O exemplo a seguir cria um relatório sobre bot_traffic:

{
  "dimensions": [
    "bot_reason"
  ],
   "metrics": [
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    }
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

A consulta tem os seguintes parâmetros:

  • Métrica: bot_traffic. Esse é o número total de solicitações de endereços IP que foram identificadas como origens de bot em intervalos de um minuto.

    Consulte Métricas e funções de agregação.

  • Dimensão: bot_reason. bot_reason pode ser qualquer combinação das regras de detecção para bots. Quando um bot é detectado, o bot_reason consiste no subconjunto de regras de detecção que correspondem ao padrão de tráfego do bot.

    Consulte Dimensões.

  • Filtrar: environment.
  • groupByTimeUnit: minute
  • timeRange: last7days

Essa chamada de API retorna o mesmo relatório do exemplo de endereços IP do bot criado usando a IU da Apigee.

Atraso nos dados de detecção de bots

Observação:a detecção de bots tem um atraso de processamento de cerca de 15 a 20 minutos, em média.

Criar um relatório de segurança para um grupo de ambiente

Usando a API Security Reports, é possível criar um relatório para dados em um grupo de ambiente, e não apenas em um ambiente. Para fazer isso, digite um comando como este:

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

e verifique se o modelo de consulta, Query.json, contém a seguinte linha:

"envgroup_hostname": "ENVGROUP"

em que ENVGROUP é o nome de um grupo de ambiente que contém o ambiente. Você encontra o nome do grupo de ambientes na IU da Apigee em Administrador > Ambientes > Grupos.

Observações:

  • As APIs Report no nível do grupo de ambientes só são compatíveis com a métrica message_count com a função de agregação sum.
  • As APIs de relatórios no nível do grupo de ambiente não oferecem suporte às dimensões bot_reason ou incident_id, mas oferecem suporte a todas as outras dimensões para relatórios de segurança.

Ver o status do relatório

Para ver o status de um relatório, insira um comando como este:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID" \
       -X GET  -H 'Content-type: application/json' -i \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

Isso retorna um resumo da solicitação de relatório e o estado atual do relatório. Veja um exemplo de resposta:

{
  "self": "/organizations/ngsaas-runtime-staging/environments/test/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "completed",
  "created": "2021-08-06T15:28:28-07:00",
  "updated": "2021-08-06T15:28:40-07:00",
  "result": {
    "self": "/organizations/ngsaas-runtime-staging/environments/test/securityReports/3964675e-9934-4398-bff5-39dd93a67201/result",
    "expires": "2021-08-13T15:28:40-07:00"
  },
  "resultRows": "60",
  "resultFileSize": "0.31 KB",
  "executionTime": "11 seconds",
  "queryParams": {
    "metrics": [
      "name:message_count,func:sum,alias:sum_message_count,op:,val:"
    ],
    "dimensions": [
      "apiproxy"
    ],
    "startTimestamp": "2021-08-06T21:28:28.570770570Z",
    "endTimestamp": "2021-08-06T22:28:28.570770570Z",
    "mimeType": "json",
    "timeUnit": "minute"
  }
}

Como o estado é "completed", você pode ver o relatório, conforme descrito a seguir.

Ver um relatório de segurança

Para ver um relatório de segurança, digite um comando como este:

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

Isso retorna um arquivo que contém o relatório, com o nome no formato OfflineQueryResult-{ID}.zip. Ver o relatório:

  1. Unzip OfflineQueryResult-{ID}.zip.
  2. Digite gzip -d QueryResults-{ID}*.json.gz.
  3. Insira cat QueryResults-{ID}*.json
  4. .

Métricas e funções de agregação

É possível usar as seguintes métricas e funções de agregação, que calculam as estatísticas de uma métrica, em um relatório.

Métrica Descrição Aggregation function
bot O número de endereços IP distintos para bots detectados em intervalos de um minuto. count_distinct
bot_traffic O número de mensagens de endereços IP de bots detectados em intervalos de um minuto. sum
message_count

Número total de chamadas de API processadas pela Apigee em intervalos de um minuto.

Observação: não é possível usar message_count com outras métricas no mesmo relatório.

sum
response_size Tamanho do payload de resposta retornado em bytes. sum, avg, min, max
bot_first_detected Data e hora em que o bot foi detectado pela primeira vez. Disponível apenas na API. min
bot_last_detected Data e hora em que o bot foi detectado pela última vez. Disponível apenas na API. max

Dimensões

As dimensões permitem agrupar valores de métricas com base em subconjuntos relacionados dos dados. A tabela a seguir descreve as dimensões específicas da segurança avançada da API:

Dimensão Descrição
bot_reason Pode ser qualquer combinação das regras de detecção de segurança. bot_reason consiste no subconjunto de regras de detecção a que o padrão de tráfego do bot corresponde.

incident_id (pré-lançamento) O UUID de um incidente de segurança, que é retornado por uma chamada para a API Incidents. Consulte Exemplo: Mais detalhes ou um incidente específico.
security_action A ação de segurança. Possivelmente, os valores são ALLOW, DENY ou FLAG.
security_action_name O nome da ação de segurança.
security_action_headers Cabeçalhos que podem ser usados para consultar uma ação de segurança da flag.

Observação: bot_reason e incident_id funcionam apenas com as seguintes métricas:

  • bot
  • bot_traffic
  • response_size

Além das dimensões descritas acima, a Segurança avançada de API também é compatível com as seguintes dimensões:

  • access_token
  • api_product
  • apiproxy
  • ax_dn_region
  • ax_edge_execution_fault_code
  • ax_geo_city
  • ax_geo_continent
  • ax_geo_country
  • ax_geo_region
  • ax_isp
  • ax_resolved_client_ip
  • ax_ua_agent_family
  • ax_ua_agent_type
  • ax_ua_agent_version
  • ax_ua_agent_category
  • ax_ua_os_family
  • bot_reason
  • client_id
  • developer
  • developer_app
  • developer_email
  • envgroup_hostname
  • environment
  • incident_id (pré-lançamento)
  • proxy_basepath
  • proxy_pathsuffix
  • request_uri
  • request_verb
  • response_status_code
  • target_host
  • target_url
  • useragent

Limitações dos relatórios de segurança

Consulte Limitações dos relatórios de segurança.