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:

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

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:

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

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.