Esta página foi traduzida pela API Cloud Translation.

API Security Reports

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Além de usar os relatórios de segurança na IU do Apigee, também pode aceder a todas as funcionalidades de relatórios de segurança através da API security reports. Esta secção descreve como usar a API de relatórios de segurança.

Nota: os dados que fluem para o pipeline do Apigee Analytics têm um atraso de 15 a 20 minutos, em média. Como resultado, um relatório de segurança cuja hora de fim seja inferior a 20 minutos no passado pode devolver resultados incorretos.

Parâmetros em exemplos de chamadas API

As secções seguintes dão exemplos de chamadas API que usam a API security reports. As chamadas da API contêm os seguintes parâmetros:

ORG é a sua organização.
ENV é o ambiente no qual quer que o relatório seja calculado.
ENVGROUP é um grupo de ambientes que contém o ambiente.
REPORT_ID é o ID do relatório devolvido por uma chamada para criar um relatório de segurança.
$TOKEN é a variável de ambiente para uma chave de acesso OAuth.
timeRange é o intervalo de tempo do relatório.

Crie um relatório de segurança

Para criar um relatório de segurança, introduza um comando como o seguinte:

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"

onde Query.json é um modelo de consulta que define a consulta. Segue-se um exemplo de um 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. Isto 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 pedidos de endereços IP que são as origens de bots.
  
  Função de agregação: sum
Consulte Métricas e funções de agregação.
Dimensão: ax_resolved_client_ip. Isto agrupa as contagens de bots no relatório pelo endereço IP da respetiva origem.
Consulte Dimensões.
Filtro: environment.
groupByTimeUnit: minute
timeRange: last7days. Consulte o Intervalo de tempo.

Tenha em atenção que esta chamada API devolve o mesmo relatório que o exemplo de relatório de endereços IP de bots criado com a IU do Apigee.

Intervalo de tempo

O intervalo de tempo do relatório. Pode definir o campo timeRange de uma das seguintes formas:

Especifique a duração do relatório no passado. As opções são:
```
"timeRange": "{last60minutes/last24hours/last7days}"
```
Especifique uma hora de início e de fim para o relatório no seguinte formato:
```
"timeRange": {
        "start": "YYYY-MM-DDT00:00:00Z",
        "end": "YYYY-MM-DDT00:00:00Z"
        }
```
Ambas as datas start e end têm de ser no passado e podem ser, no máximo, 1 ano antes da data atual quando cria o relatório.

Exemplo de resposta

A consulta acima devolve uma resposta semelhante à seguinte:

{
  "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 usar para obter o relatório assim que estiver concluído. No exemplo acima, o ID do relatório é 3964675e-9934-4398-bff5-39dd93a67201.
"state": o estado da tarefa de relatório, que pode ser um dos seguintes:
- enqueued: a tarefa de relatório foi criada, mas ainda não está em execução.
- running: a tarefa de relatório está em execução.
- completed: a tarefa de relatório está concluída. Nesta fase, pode ver o relatório.
- expired: a tarefa de relatório expirou e já não pode ver o relatório.

Obtenha o estado do relatório

Para obter o estado de um relatório, envie um pedido como o 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"

onde REPORT_ID é o ID do relatório. Consulte os parâmetros em exemplos de chamadas da API.

A resposta contém um resumo dos parâmetros do relatório, bem como o estado atual do relatório. Neste exemplo, o estado é "completed", pelo que pode 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"
}

Obter relatório

Para transferir o relatório de segurança, envie um pedido como o seguinte:

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

onde REPORT_ID é o ID do relatório. Consulte os parâmetros nos exemplos de chamadas da API.

Isto devolve um ficheiro que contém o relatório, cujo nome tem o formato OfflineQueryResult-{ID}.zip. Para ver o relatório:

Descomprimir OfflineQueryResult-{ID}.zip.
Introduza gzip -d QueryResults-{ID}*.json.gz.
Introduza cat QueryResults-{ID}*.json

Exemplo de tráfego de bots

O exemplo seguinte 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. Este é o número total de pedidos de endereços IP que foram identificados como origens de bots, 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 deteção para bots. Quando é detetado um bot, bot_reason consiste no subconjunto das regras de deteção com as quais o padrão de tráfego do bot correspondeu.

Consulte Dimensões.
Filtro: environment.
groupByTimeUnit: minute
timeRange: last7days

Tenha em atenção que esta chamada API devolve o mesmo relatório que o exemplo de relatório de endereços IP de bots criado com a IU do Apigee.

Atraso nos dados de deteção de bots

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

Crie um relatório de segurança para um grupo de ambientes

Com a API de relatórios de segurança, pode criar um relatório para dados num grupo de ambientes (em vez de apenas um ambiente). Para isso, introduza um comando como o seguinte:

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 certifique-se de que o modelo de consulta, Query.json, contém a seguinte linha:

"envgroup_hostname": "ENVGROUP"

em que ENVGROUP é o nome de um grupo de ambientes que contém o ambiente. Pode encontrar o nome do grupo de ambientes na IU do Apigee acedendo a Administração > Ambientes > Grupos.

Notas:

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

Obtenha o estado do relatório

Para saber o estado de um relatório, introduza um comando como o seguinte:

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"

Esta ação devolve um resumo do pedido de relatório e o estado atual do relatório. Segue-se 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"
  }
}

Uma vez que o estado é "completed", já pode ver o relatório, conforme descrito em seguida.

Visualizar um relatório de segurança

Para ver um relatório de segurança, introduza um comando como o seguinte:

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"

Isto devolve um ficheiro que contém o relatório, cujo nome tem o formato OfflineQueryResult-{ID}.zip. Para ver o relatório:

Descomprimir OfflineQueryResult-{ID}.zip.
Introduza gzip -d QueryResults-{ID}*.json.gz.
Introduza cat QueryResults-{ID}*.json

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

Pode usar as seguintes métricas e funções de agregação, que calculam estatísticas a partir de uma métrica, para um relatório.

Métrica	Descrição	`Aggregation function`
`bot`	O número de endereços IP distintos para bots detetados em intervalos de 1 minuto.	`count_distinct`
`bot_traffic`	O número de mensagens de endereços IP de bots detetados em intervalos de um minuto.	`sum`
`message_count`	O número total de chamadas de API processadas pelo Apigee em intervalos de 1 minuto. Nota: `message_count` não pode ser usada com outras métricas no mesmo relatório.	`sum`
`response_size`	Tamanho do payload de resposta devolvido em bytes.	`sum`, `avg`, `min`, `max`
`bot_first_detected`	Data e hora em que o bot foi detetado pela primeira vez. Disponível apenas através da API.	`min`
`bot_last_detected`	Data e hora em que o bot foi detetado pela última vez. Disponível apenas através da API.	`max`

Dimensões

As dimensões permitem agrupar valores de métricas com base em subconjuntos de dados relacionados. A tabela seguinte 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 deteção de segurança. `bot_reason` consiste no subconjunto das regras de deteção que corresponderam ao padrão de tráfego do bot.
`incident_id` (pré-visualização)	O UUID de um incidente de segurança, que é devolvido por uma chamada à API Incidents. Consulte Exemplo: obter detalhes ou um incidente específico.
`security_action`	A ação de segurança. Os valores possíveis são `ALLOW`, `DENY` ou `FLAG`.
`security_action_name`	O nome da ação de segurança.
`security_action_headers`	Cabeçalhos que pode usar para consultar uma ação de segurança de flag.

Nota: bot_reason e incident_id só funcionam com as seguintes métricas:

bot
bot_traffic
response_size

Além das dimensões descritas acima, a segurança avançada da API também suporta 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é-visualização)
proxy_basepath
proxy_pathsuffix
request_uri
request_verb
response_status_code
target_host
target_url
useragent

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

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