Implemente a análise automatizada de software malicioso para ficheiros carregados no Cloud Storage

Last reviewed 2024-12-02 UTC

Este documento descreve como implementar a arquitetura em Automatize a análise de software malicioso para ficheiros carregados para o Cloud Storage.

Este guia de implementação pressupõe que conhece a funcionalidade básica das seguintes tecnologias:

• Cloud Storage
• Cloud Run
• Cloud Scheduler
• Eventarc
• Docker
• Node.js

Arquitetura

O diagrama seguinte mostra a arquitetura de implementação que cria neste documento:

O diagrama mostra os dois pipelines seguintes que são geridos por esta arquitetura:

• Pipeline de análise de ficheiros, que verifica se um ficheiro carregado contém software malicioso.
• Pipeline de atualização da replicação da base de dados de software malicioso do ClamAV, que mantém uma replicação atualizada da base de dados de software malicioso que o ClamAV usa.

Para mais informações sobre a arquitetura, consulte o artigo Automatize a análise de software malicioso para ficheiros carregados para o Cloud Storage.

Objetivos

• Crie uma imagem espelhada da base de dados de definições de software malicioso do ClamAV num contentor do Cloud Storage.

• Crie um serviço do Cloud Run com as seguintes funções:

  • Analisar ficheiros num contentor do Cloud Storage à procura de software malicioso através do ClamAV e mover os ficheiros analisados para contentores limpos ou em quarentena com base no resultado da análise.
  • Manter uma imagem espelhada da base de dados de definições de software malicioso do ClamAV no Cloud Storage.

• Crie um acionador do Eventarc para acionar o serviço de análise de software malicioso quando um ficheiro é carregado para o Cloud Storage.

• Crie uma tarefa do Cloud Scheduler para acionar o serviço de análise de software malicioso e atualizar a imagem espelhada da base de dados de definições de software malicioso no Cloud Storage.

Custos

Esta arquitetura usa os seguintes componentes faturáveis do Google Cloud:

• Cloud Storage
• Cloud Run
• Eventarc

Para gerar uma estimativa de custos com base na sua utilização projetada, use a calculadora de preços.

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry, Cloud Build, Resource Manager, Cloud Scheduler, Eventarc, Logging, Monitoring, Pub/Sub, Cloud Run, and Service Usage APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry, Cloud Build, Resource Manager, Cloud Scheduler, Eventarc, Logging, Monitoring, Pub/Sub, Cloud Run, and Service Usage APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Nesta implementação, executa todos os comandos a partir do Cloud Shell.

Implemente a arquitetura

Pode implementar a arquitetura descrita neste documento através de um dos seguintes métodos:

• Usar a Cloud Shell: use este método se quiser ver como cada componente da solução é implementado e configurado através da ferramenta de linha de comandos Google Cloud CLI.

  Para usar este método de implementação, siga as instruções em Implemente através da Cloud Shell.

• Usar a CLI do Terraform: use este método se quiser implementar a solução com o menor número possível de passos manuais. Este método baseia-se no Terraform para implementar e configurar os componentes individuais.

  Para usar este método de implementação, siga as instruções em Implemente através da CLI do Terraform.

Implemente através do Cloud Shell

Para implementar manualmente a arquitetura descrita neste documento, conclua os passos nas subsecções seguintes.

Prepare o seu ambiente

Nesta secção, atribui definições para valores usados em toda a implementação, como região e zona. Nesta implementação, usa us-central1 como a região para o serviço do Cloud Run e us como a localização para o acionador do Eventarc e os contentores do Cloud Storage.

1. No Cloud Shell, defina variáveis de shell comuns, incluindo a região e a localização:

   REGION=us-central1
   LOCATION=us
   PROJECT_ID=PROJECT_ID
   SERVICE_NAME="malware-scanner"
   SERVICE_ACCOUNT="${SERVICE_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"
   

   Substitua PROJECT_ID pelo ID do seu projeto.

2. Inicialize o ambiente gcloud com o ID do seu projeto:

   gcloud config set project "${PROJECT_ID}"
   

3. Crie três contentores do Cloud Storage com nomes exclusivos:

   gcloud storage buckets create "gs://unscanned-${PROJECT_ID}" --location="${LOCATION}"
   gcloud storage buckets create "gs://quarantined-${PROJECT_ID}" --location="${LOCATION}"
   gcloud storage buckets create "gs://clean-${PROJECT_ID}" --location="${LOCATION}"
   

   ${PROJECT_ID} é usado para garantir que os nomes dos contentores são exclusivos.

   Estes três contentores contêm os ficheiros carregados em várias fases durante o pipeline de análise de ficheiros:

   • unscanned-PROJECT_ID: retém ficheiros antes de serem analisados. Os seus utilizadores carregam os respetivos ficheiros para este contentor.

   • quarantined-PROJECT_ID: contém ficheiros que o serviço de análise de software malicioso analisou e considerou conter software malicioso.

   • clean-PROJECT_ID: contém ficheiros que o serviço de análise de software malicioso analisou e considerou não estarem infetados.

4. Crie um quarto contentor do Cloud Storage:

   gcloud storage buckets create "gs://cvd-mirror-${PROJECT_ID}" --location="${LOCATION}"
   

   ${PROJECT_ID} é usado para garantir que o nome do contentor é único.

   Este contentor cvd-mirror-PROJECT_ID é usado para manter uma réplica local da base de dados de definições de software malicioso, o que impede que a limitação de taxa seja acionada pela RFC do ClamAV.

Configure uma conta de serviço para o serviço de análise de software malicioso

Nesta secção, cria uma conta de serviço para usar no serviço de análise de software malicioso. Em seguida, concede as funções adequadas à conta de serviço para que tenha autorizações de leitura e escrita nos contentores do Cloud Storage. As funções garantem que a conta tem autorizações mínimas e que só tem acesso aos recursos de que precisa.

1. Crie a conta de serviço malware-scanner:

   gcloud iam service-accounts create ${SERVICE_NAME}
   

2. Conceda a função de administrador de objetos aos contentores. A função permite que o serviço leia e elimine ficheiros do contentor não analisado e escreva ficheiros nos contentores em quarentena e limpos.

   gcloud storage buckets add-iam-policy-binding "gs://unscanned-${PROJECT_ID}" \
       --member="serviceAccount:${SERVICE_ACCOUNT}" --role=roles/storage.objectAdmin
   gcloud storage buckets add-iam-policy-binding "gs://clean-${PROJECT_ID}" \
       --member="serviceAccount:${SERVICE_ACCOUNT}" --role=roles/storage.objectAdmin
   gcloud storage buckets add-iam-policy-binding "gs://quarantined-${PROJECT_ID}" \
       --member="serviceAccount:${SERVICE_ACCOUNT}" --role=roles/storage.objectAdmin
   gcloud storage buckets add-iam-policy-binding "gs://cvd-mirror-${PROJECT_ID}" \
       --member="serviceAccount:${SERVICE_ACCOUNT}" --role=roles/storage.objectAdmin
   

3. Conceda a função Metric Writer, que permite ao serviço escrever métricas no Monitoring:

   gcloud projects add-iam-policy-binding \
         "${PROJECT_ID}" \
         --member="serviceAccount:${SERVICE_ACCOUNT}" \
         --role=roles/monitoring.metricWriter
   

Crie o serviço de análise de software malicioso no Cloud Run

Nesta secção, implementa o serviço de análise de software malicioso no Cloud Run. O serviço é executado num contentor Docker que contém o seguinte:

• A Dockerfile para criar uma imagem de contentor com o serviço, o tempo de execução do Node.js, o Google Cloud SDK e os binários do ClamAV.
• Os ficheiros TypeScript para o serviço Cloud Run do analisador de software malicioso.
• Um ficheiro de configuração config.json para especificar os nomes dos contentores do Cloud Storage.
• Um updateCvdMirror.sh script de shell para atualizar a base de dados de definições de software malicioso do ClamAV no Google Cloud Storage.
• Um bootstrap.sh script de shell para executar os serviços necessários no arranque da instância.

Para implementar o serviço, faça o seguinte:

1. No Cloud Shell, clone o repositório do GitHub que contém os ficheiros de código:

   git clone https://github.com/GoogleCloudPlatform/docker-clamav-malware-scanner.git
   

2. Altere para o diretório cloudrun-malware-scanner:

   cd docker-clamav-malware-scanner/cloudrun-malware-scanner
   

3. Crie o ficheiro de configuração config.json com base no ficheiro de modelo config.json.tmpl no repositório do GitHub:

   sed "s/-bucket-name/-${PROJECT_ID}/" config.json.tmpl > config.json
   

   O comando anterior usa uma operação de pesquisa e substituição para atribuir aos contentores do Cloud Storage nomes únicos baseados no ID do projeto.

4. Opcional: veja o ficheiro de configuração atualizado:

   cat config.json
   

5. Faça um preenchimento inicial da réplica da base de dados de software malicioso do ClamAV no Cloud Storage:

   python3 -m venv pyenv
   . pyenv/bin/activate
   pip3 install crcmod cvdupdate
   ./updateCvdMirror.sh "cvd-mirror-${PROJECT_ID}"
   deactivate
   

   Estes comandos executam uma instalação local da ferramenta CVDUpdate e, em seguida, executam o script updateCvdMirror.sh, que usa CVDUpdate para copiar a base de dados de software malicioso do ClamAV para o contentor cvd-mirror-PROJECT_ID que criou anteriormente.

   Pode verificar o conteúdo do contentor de replicação:

   gcloud storage ls "gs://cvd-mirror-${PROJECT_ID}/cvds"
   

   O contentor deve conter vários ficheiros CVD que contêm a base de dados de software malicioso completa, vários ficheiros .cdiff que contêm as atualizações diferenciais diárias e dois ficheiros JSON com informações de configuração e estado.

6. Crie e implemente o serviço do Cloud Run com a conta de serviço que criou anteriormente:

   gcloud beta run deploy "${SERVICE_NAME}" \
     --source . \
     --region "${REGION}" \
     --no-allow-unauthenticated \
     --memory 4Gi \
     --cpu 1 \
     --concurrency 20 \
     --min-instances 1 \
     --max-instances 5 \
     --no-cpu-throttling \
     --cpu-boost \
     --timeout 300s \
     --service-account="${SERVICE_ACCOUNT}"
   

   O comando cria uma instância do Cloud Run com 1 vCPU e usa 4 GiB de RAM. Este tamanho é aceitável para esta implementação. No entanto, num ambiente de produção, é recomendável escolher um tamanho de CPU e memória maior para a instância e um parâmetro --max-instances maior. Os tamanhos dos recursos de que pode precisar dependem da quantidade de tráfego que o serviço tem de processar.

   O comando inclui as seguintes especificações:

   • O parâmetro --concurrency especifica o número de pedidos simultâneos que cada instância pode processar.
   • O parâmetro --no-cpu-throttling permite que a instância realize operações em segundo plano, como atualizar definições de software malicioso.
   • O parâmetro --cpu-boost duplica o número de vCPUs no arranque da instância para reduzir a latência do arranque.
   • O parâmetro --min-instances 1 mantém, pelo menos, uma instância ativa, porque o tempo de início de cada instância é relativamente elevado.
   • O parâmetro --max-instances 5 impede que o serviço seja dimensionado para um valor demasiado elevado.

7. Quando lhe for pedido, introduza Y para criar e implementar o serviço. A compilação e a implementação demoram cerca de 10 minutos. Quando estiver concluída, é apresentada a seguinte mensagem:

   Service [malware-scanner] revision [malware-scanner-UNIQUE_ID] has been deployed and is serving 100 percent of traffic.
   Service URL: https://malware-scanner-UNIQUE_ID.a.run.app
   

8. Armazene o valor Service URL do resultado do comando de implementação numa variável de shell. Vai usar o valor mais tarde quando criar uma tarefa do Cloud Scheduler.

   SERVICE_URL="SERVICE_URL"
   

9. Opcional: para verificar o serviço em execução e a versão do ClamAV, execute o seguinte comando:

   curl -D - -H "Authorization: Bearer $(gcloud auth print-identity-token)"  \
       ${SERVICE_URL}
   

   O resultado tem o seguinte aspeto. Mostra a versão do serviço de análise de software malicioso, a versão do ClamAV e a versão das definições de software malicioso com a data da última atualização.

   gcs-malware-scanner version 3.2.0
   Using Clam AV version: ClamAV 1.4.1/27479/Fri Dec  6 09:40:14 2024
   

O serviço Cloud Run requer que todas as invocações sejam autenticadas e que as identidades de autenticação tenham a autorização run.routes.invoke no serviço. Adiciona a autorização na secção seguinte.

Crie um acionador do Eventarc do Cloud Storage

Nesta secção, adiciona autorizações para permitir que o Eventarc capture eventos do Cloud Storage e crie um acionador para enviar estes eventos para o serviço malware-scanner do Cloud Run.

1. Se estiver a usar um projeto existente criado antes de 8 de abril de 2021, adicione a função iam.serviceAccountTokenCreator à conta de serviço do Pub/Sub:

   PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
   PUBSUB_SERVICE_ACCOUNT="service-${PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com"
   gcloud projects add-iam-policy-binding ${PROJECT_ID} \
       --member="serviceAccount:${PUBSUB_SERVICE_ACCOUNT}"\
       --role='roles/iam.serviceAccountTokenCreator'
   

   Esta adição de função só é necessária para projetos mais antigos e permite que o Pub/Sub invoque o serviço do Cloud Run.

2. No Cloud Shell, conceda a função de publicador do Pub/Sub à conta de serviço do Cloud Storage:

   STORAGE_SERVICE_ACCOUNT=$(gcloud storage service-agent --project="${PROJECT_ID}")
   
   gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
     --member "serviceAccount:${STORAGE_SERVICE_ACCOUNT}" \
     --role "roles/pubsub.publisher"
   

3. Permita que a conta de serviço malware-scanner invoque o serviço do Cloud Run e atue como um recetor de eventos do Eventarc:

   gcloud run services add-iam-policy-binding "${SERVICE_NAME}" \
     --region="${REGION}" \
     --member "serviceAccount:${SERVICE_ACCOUNT}" \
     --role roles/run.invoker
   gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
     --member "serviceAccount:${SERVICE_ACCOUNT}" \
     --role "roles/eventarc.eventReceiver"
   

4. Crie um acionador do Eventarc para capturar o evento de objeto finalizado no contentor do Cloud Storage não analisado e enviá-lo para o seu serviço do Cloud Run. O acionador usa a conta de serviço malware-scanner para a autenticação:

   BUCKET_NAME="unscanned-${PROJECT_ID}"
   gcloud eventarc triggers create "trigger-${BUCKET_NAME}-${SERVICE_NAME}" \
     --destination-run-service="${SERVICE_NAME}" \
     --destination-run-region="${REGION}" \
     --location="${LOCATION}" \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=${BUCKET_NAME}" \
     --service-account="${SERVICE_ACCOUNT}"
   

   Se receber um dos seguintes erros, aguarde um minuto e, em seguida, execute os comandos novamente:

   ERROR: (gcloud.eventarc.triggers.create) INVALID_ARGUMENT: The request was invalid: Bucket "unscanned-PROJECT_ID" was not found. Please verify that the bucket exists.
   

   ERROR: (gcloud.eventarc.triggers.create) FAILED_PRECONDITION: Invalid resource state for "": Permission denied while using the Eventarc Service Agent. If you recently started to use Eventarc, it may take a few minutes before all necessary permissions are propagated to the Service Agent. Otherwise, verify that it has Eventarc Service Agent role.
   

5. Altere o prazo de confirmação da mensagem para cinco minutos na subscrição do Pub/Sub subjacente que é usada pelo acionador do Eventarc. O valor predefinido de 10 segundos é demasiado curto para ficheiros grandes ou cargas elevadas.

   SUBSCRIPTION_NAME=$(gcloud eventarc triggers describe \
       "trigger-${BUCKET_NAME}-${SERVICE_NAME}" \
       --location="${LOCATION}" \
       --format="get(transport.pubsub.subscription)")
   gcloud pubsub subscriptions update "${SUBSCRIPTION_NAME}" --ack-deadline=300
   

   Embora o acionador seja criado imediatamente, pode demorar até dois minutos para que fique totalmente funcional.

Crie uma tarefa do Cloud Scheduler para acionar atualizações de replicação da base de dados do ClamAV

• Crie uma tarefa do Cloud Scheduler que execute um pedido HTTP POST no serviço do Cloud Run com um comando para atualizar a réplica da base de dados de definições de software malicioso. Para evitar que demasiados clientes usem o mesmo intervalo de tempo, o ClamAV requer que agende a tarefa para um minuto aleatório entre 3 e 57, evitando múltiplos de 10.

  while : ; do
    # set MINUTE to a random number between 3 and 57
    MINUTE="$((RANDOM%55 + 3))"
    # exit loop if MINUTE isn't a multiple of 10
    [[ $((MINUTE % 10)) != 0 ]] && break
  done
  
  gcloud scheduler jobs create http \
      "${SERVICE_NAME}-mirror-update" \
      --location="${REGION}" \
      --schedule="${MINUTE} */2 * * *" \
      --oidc-service-account-email="${SERVICE_ACCOUNT}" \
      --uri="${SERVICE_URL}" \
      --http-method=post \
      --message-body='{"kind":"schedule#cvd_update"}' \
      --headers="Content-Type=application/json"
  

  O argumento da linha de comandos --schedule define quando a tarefa é executada usando o formato de string unix-cron. O valor indicado significa que a tarefa deve ser executada no minuto específico gerado aleatoriamente a cada duas horas.

Esta tarefa apenas atualiza a réplica do ClamAV no Cloud Storage. O daemon freshclam do ClamAV em cada instância do Cloud Run verifica o espelho a cada 30 minutos para novas definições e atualiza o daemon do ClamAV.

Faça a implementação através da CLI do Terraform

Esta secção descreve a implementação da arquitetura descrita neste documento através da CLI do Terraform.

Clone o repositório do GitHub

1. No Cloud Shell, clone o repositório do GitHub que contém o código e os ficheiros Terraform:

   git clone https://github.com/GoogleCloudPlatform/docker-clamav-malware-scanner.git
   

Prepare o ambiente

Nesta secção, atribui definições para valores usados em toda a implementação, como região e zona. Nesta implementação, usa us-central1 como a região para o serviço do Cloud Run e us como a localização para o acionador do Eventarc e os contentores do Cloud Storage.

1. No Cloud Shell, defina variáveis de shell comuns, incluindo a região e a localização:

   REGION=us-central1
   LOCATION=us
   PROJECT_ID=PROJECT_ID
   

   Substitua PROJECT_ID pelo ID do seu projeto.

2. Inicialize o ambiente gcloud CLI com o ID do seu projeto:

   gcloud config set project "${PROJECT_ID}"
   

3. Crie o ficheiro de configuração config.json com base no ficheiro de modelo config.json.tmpl no repositório do GitHub:

   sed "s/-bucket-name/-${PROJECT_ID}/" \
     docker-clamav-malware-scanner/cloudrun-malware-scanner/config.json.tmpl \
     > docker-clamav-malware-scanner/cloudrun-malware-scanner/config.json
   

   O comando anterior usa uma operação de pesquisa e substituição para atribuir aos contentores do Cloud Storage nomes únicos baseados no ID do projeto.

4. Opcional: veja o ficheiro de configuração atualizado:

   cat docker-clamav-malware-scanner/cloudrun-malware-scanner/config.json
   

5. Configure as variáveis do Terraform. O conteúdo do ficheiro de configuração é transmitido ao Terraform através da variável TF_VAR_config_json, para que o Terraform saiba que contentores do Cloud Storage deve criar.config.json O valor desta variável também é transmitido ao Cloud Run para configurar o serviço.

   TF_VAR_project_id=$PROJECT_ID
   TF_VAR_region=us-central1
   TF_VAR_bucket_location=us
   TF_VAR_config_json="$(cat docker-clamav-malware-scanner/cloudrun-malware-scanner/config.json)"
   TF_VAR_create_buckets=true
   export TF_VAR_project_id TF_VAR_region TF_VAR_bucket_location TF_VAR_config_json TF_VAR_create_buckets
   

Implemente a infraestrutura base

1. No Cloud Shell, execute os seguintes comandos para implementar a infraestrutura base:

   gcloud services enable \
     cloudresourcemanager.googleapis.com \
     serviceusage.googleapis.com
   cd docker-clamav-malware-scanner/terraform/infra
   terraform init
   terraform apply
   

   Responda yes quando lhe for pedido.

   Este script do Terraform realiza as seguintes tarefas:

   • Cria as contas de serviço
   • Cria o Artifact Registry
   • Cria os contentores do Cloud Storage
   • Define as funções e as autorizações adequadas
   • Realiza um preenchimento inicial do contentor do Cloud Storage que contém a imagem espelhada da base de dados de definições de software malicioso do ClamAV

Crie o contentor para o serviço

1. No Cloud Shell, execute os seguintes comandos para iniciar uma tarefa do Cloud Build para criar a imagem de contentor para o serviço:

   cd ../../cloudrun-malware-scanner
   gcloud builds submit \
     --region="$TF_VAR_region" \
     --config=cloudbuild.yaml \
     --service-account="projects/$PROJECT_ID/serviceAccounts/malware-scanner-build@$PROJECT_ID.iam.gserviceaccount.com" \
     .
   

   Aguarde alguns minutos até que a compilação esteja concluída.

Implemente o serviço e o acionador

1. No Cloud Shell, execute os seguintes comandos para implementar o serviço do Cloud Run:

   cd ../terraform/service/
   terraform init
   terraform apply
   

   Responda yes quando lhe for pedido.

   A implementação e o início do serviço podem demorar vários minutos.

   Este script do Terraform realiza as seguintes tarefas:

   • Implementa o serviço do Cloud Run através da imagem do contentor que acabou de criar.
   • Configura os acionadores do Eventarc nos contentores do unscanned Cloud Storage. Embora o acionador seja criado imediatamente, pode demorar até dois minutos para que fique totalmente funcional.
   • Cria a tarefa do Cloud Scheduler para atualizar para a replicação das definições de software malicioso do ClamAV.

   Se a implementação falhar com um dos seguintes erros, aguarde um minuto e, em seguida, execute novamente o comando terraform apply para tentar criar o acionador do Eventarc.

   Error: Error creating Trigger: googleapi: Error 400: Invalid resource state for "": The request was invalid: Bucket "unscanned-PROJECT_ID" was not found. Please verify that the bucket exists.
   

   Error: Error creating Trigger: googleapi: Error 400: Invalid resource state for "": Permission denied while using the Eventarc Service Agent. If you recently started to use Eventarc, it may take a few minutes before all necessary permissions are propagated to the Service Agent. Otherwise, verify that it has Eventarc Service Agent role..
   

2. Opcional: para verificar o serviço em execução e a versão do ClamAV em utilização, execute os seguintes comandos:

   MALWARE_SCANNER_URL="$(terraform output -raw cloud_run_uri)"
   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)"  \
     "${MALWARE_SCANNER_URL}"
   

   O resultado tem o seguinte aspeto. Mostra a versão do serviço de análise de software malicioso, a versão do ClamAV e a versão das definições de software malicioso com a data da última atualização.

   gcs-malware-scanner version 3.2.0
   Using Clam AV version: ClamAV 1.4.1/27479/Fri Dec  6 09:40:14 2024
   

Teste o pipeline carregando ficheiros

Para testar o pipeline, carregue um ficheiro limpo (sem software malicioso) e um ficheiro de teste que imita um ficheiro infetado:

1. Crie um ficheiro de texto de exemplo ou use um ficheiro limpo existente para testar os processos do pipeline.

2. No Cloud Shell, copie o ficheiro de dados de amostra para o contentor não analisado:

   gcloud storage cp FILENAME "gs://unscanned-${PROJECT_ID}"
   

   Substitua FILENAME pelo nome do ficheiro de texto limpo. O serviço de análise de software malicioso inspeciona cada ficheiro e move-o para um contentor adequado. Este ficheiro é movido para o contentor limpo.

3. Aguarde alguns segundos para que o pipeline processe o ficheiro e, em seguida, verifique o contentor limpo para ver se o ficheiro processado está lá:

   gcloud storage ls "gs://clean-${PROJECT_ID}" --recursive
   

   Pode verificar se o ficheiro foi removido do contentor não analisado:

   gcloud storage ls "gs://unscanned-${PROJECT_ID}" --recursive
   

4. Carregue um ficheiro denominado eicar-infected.txt que contenha a assinatura de teste anti-software malicioso padrão EICAR para o seu contentor não analisado:

   echo -e 'X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*' \
       | gcloud storage cp - "gs://unscanned-${PROJECT_ID}/eicar-infected.txt"
   

   Esta string de texto tem uma assinatura que aciona os analisadores de software malicioso para fins de teste. Este ficheiro de teste é um teste amplamente usado. Não é software malicioso real e é inofensivo para a sua estação de trabalho. Se tentar criar um ficheiro que contenha esta string num computador com um verificador de software malicioso instalado, pode acionar um alerta.

5. Aguarde alguns segundos e, em seguida, verifique o contentor em quarentena para ver se o ficheiro passou com êxito pelo pipeline:

   gcloud storage ls "gs://quarantined-${PROJECT_ID}" --recursive
   

   O serviço também regista uma entrada de registo de registo quando é detetado um ficheiro infetado com software malicioso.

   Pode verificar se o ficheiro foi removido do contentor não analisado:

   gcloud storage ls "gs://unscanned-${PROJECT_ID}" --recursive
   

Teste o mecanismo de atualização da base de dados de definições de software malicioso

• No Cloud Shell, acione a verificação de atualizações forçando a execução da tarefa do Cloud Scheduler:

  gcloud scheduler jobs run "${SERVICE_NAME}-mirror-update" --location="${REGION}"
  

  Os resultados deste comando só são apresentados nos registos detalhados.

Monitorize o serviço

Pode monitorizar o serviço através do Cloud Logging e do Cloud Monitoring.

Veja registos detalhados

1. Na Google Cloud consola, aceda à página Explorador de registos do Cloud Logging.

   Aceda ao Explorador de registos

2. Se o filtro Campos de registo não for apresentado, clique em Campos de registo.

3. No filtro Campos de registo, clique em Revisão do Cloud Run.

4. Na secção Nome do serviço do filtro Campos de registo, clique em malware-scanner.

Os resultados da consulta de registos mostram os registos do serviço, incluindo várias linhas que mostram os pedidos de análise e o estado dos dois ficheiros que carregou:

Scan request for gs://unscanned-PROJECT_ID/FILENAME, (##### bytes) scanning with clam ClamAV CLAMAV_VERSION_STRING
Scan status for gs://unscanned-PROJECT_ID/FILENAME: CLEAN (##### bytes in #### ms)
...
Scan request for gs://unscanned-PROJECT_ID/eicar-infected.txt, (69 bytes) scanning with clam ClamAV CLAMAV_VERSION_STRING
Scan status for gs://unscanned-PROJECT_ID/eicar-infected.txt: INFECTED stream: Eicar-Signature FOUND (69 bytes in ### ms)

O resultado mostra a versão do ClamAV e a revisão da assinatura da base de dados de software malicioso, juntamente com o nome do software malicioso para o ficheiro de teste infetado. Pode usar estas mensagens de registo para configurar alertas para quando for encontrado software malicioso ou quando ocorrerem falhas durante a análise.

A saída também mostra os registos de atualização da sincronização das definições de software malicioso:

Starting CVD Mirror update
CVD Mirror update check complete. output: ...

Se o espelho tiver sido atualizado, o resultado mostra linhas adicionais:

CVD Mirror updated: DATE_TIME - INFO: Downloaded daily.cvd. Version: VERSION_INFO

Os registos de atualização do Freshclam aparecem a cada 30 minutos:

DATE_TIME -> Received signal: wake up
DATE_TIME -> ClamAV update process started at DATE_TIME
DATE_TIME -> daily.cvd database is up-to-date (version: VERSION_INFO)
DATE_TIME -> main.cvd database is up-to-date (version: VERSION_INFO)
DATE_TIME -> bytecode.cvd database is up-to-date (version: VERSION_INFO)

Se a base de dados tiver sido atualizada, as linhas do registo do freshclam são semelhantes às seguintes:

DATE_TIME -> daily.cld updated (version: VERSION_INFO)

Ver métricas

O serviço gera as seguintes métricas para fins de monitorização e alerta:

• Número de ficheiros limpos processados:
  workload.googleapis.com/googlecloudplatform/gcs-malware-scanning/clean-files
• Número de ficheiros infetados processados:
  workload.googleapis.com/googlecloudplatform/gcs-malware-scanning/infected-files
• Número de ficheiros ignorados e não verificados:
  workload.googleapis.com/googlecloudplatform/gcs-malware-scanning/ignored-files
• Tempo gasto na análise de ficheiros:
  workload.googleapis.com/googlecloudplatform/gcs-malware-scanning/scan-duration
• Número total de bytes analisados:
  workload.googleapis.com/googlecloudplatform/gcs-malware-scanning/bytes-scanned
• Número de análises de software malicioso com falha:
  workload.googleapis.com/googlecloudplatform/gcs-malware-scanning/scans-failed
• Número de verificações de atualizações do CVD Mirror:
  workload.googleapis.com/googlecloudplatform/gcs-malware-scanning/cvd-mirror-updates

Pode ver estas métricas no explorador de métricas do Cloud Monitoring:

1. Na Google Cloud consola, aceda à página Explorador de métricas do Cloud Monitoring.

   Aceda ao Metrics Explorer

2. Clique no campo Selecionar uma métrica e introduza a string de filtro malware.

3. Expanda o recurso Generic Task.

4. Expanda a categoria Googlecloudplatform.

5. Selecione a métrica googlecloudplatform/gcs-malware-scanning/clean-files. O gráfico mostra um ponto de dados que indica quando o ficheiro limpo foi analisado.

Pode usar métricas para monitorizar o pipeline e criar alertas para quando for detetado software malicioso ou quando o processamento de ficheiros falhar.

As métricas geradas têm as seguintes etiquetas, que pode usar para filtragem e agregação para ver detalhes mais detalhados com o explorador de métricas:

• source_bucket
• destination_bucket
• clam_version
• cloud_run_revision

Na métrica ignored_files, as seguintes etiquetas reason definem o motivo pelo qual os ficheiros são ignorados:

• ZERO_LENGTH_FILE: se o valor de configuração ignoreZeroLengthFiles estiver definido e o ficheiro estiver vazio.
• FILE_TOO_LARGE: quando o ficheiro excede o tamanho máximo de análise de 500 MiB.
• REGEXP_MATCH: quando o nome do ficheiro corresponde a um dos padrões definidos em fileExclusionPatterns.
• FILE_SIZE_MISMATCH: se o tamanho do ficheiro mudar enquanto está a ser examinado.

Configuração avançada

As secções seguintes descrevem como pode configurar o scanner com parâmetros mais avançados.

Faça a gestão de vários contentores

O serviço de análise de software malicioso pode analisar ficheiros de vários contentores de origem e enviar os ficheiros para contentores limpos e em quarentena separados. Embora esta configuração avançada esteja fora do âmbito desta implementação, segue-se um resumo dos passos necessários:

1. Crie contentores do Cloud Storage não analisados, limpos e em quarentena com nomes exclusivos.

2. Conceda as funções adequadas à conta de serviço malware-scanner em cada contentor.

3. Edite o ficheiro de configuração config.json para especificar os nomes dos contentores para cada configuração:

   {
     "buckets": [
       {
         "unscanned": "unscanned-bucket-1-name",
         "clean": "clean-bucket-1-name",
         "quarantined": "quarantined-bucket-1-name"
       },
       {
         "unscanned": "unscanned-bucket-2-name",
         "clean": "clean-bucket-2-name",
         "quarantined": "quarantined-bucket-2-name"
       }
     ],
     "ClamCvdMirrorBucket": "cvd-mirror-bucket-name"
   }
   

4. Para cada um dos contentores não analisados, crie um acionador do Eventarc. Certifique-se de que cria um nome de acionador exclusivo para cada contentor.

   O contentor do Cloud Storage tem de estar no mesmo projeto e região que o acionador do Eventarc.

Se estiver a usar a implementação do Terraform, os passos nesta secção são aplicados automaticamente quando passa o ficheiro de configuração config.json atualizado na variável de configuração do Terraform TF_VAR_config_json.

Ignorar ficheiros temporários

Alguns serviços de carregamento, como o SFTP para gateways do Cloud Storage, criam um ou mais ficheiros temporários durante o processo de carregamento. Estes serviços mudam o nome destes ficheiros para o nome do ficheiro final quando o carregamento está concluído.

O comportamento normal do analisador é analisar e mover todos os ficheiros, incluindo estes ficheiros temporários, assim que são escritos, o que pode fazer com que o serviço de carregamento falhe quando não consegue encontrar os respetivos ficheiros temporários.

A secção fileExclusionPatterns do ficheiro de configuração config.json permite-lhe usar expressões regulares para especificar uma lista de padrões de nomes de ficheiros a ignorar. Todos os ficheiros que correspondam a estas expressões regulares são deixados no contentor unscanned.

Quando esta regra é acionada, o contador ignored-files é incrementado e é registada uma mensagem para indicar que o ficheiro correspondente ao padrão foi ignorado.

O seguinte exemplo de código mostra um ficheiro de configuração config.json com a lista fileExclusionPatterns definida para ignorar ficheiros que terminam em .tmp ou que contêm a string .partial_upload..

{
  "buckets": [
    {
      "unscanned": "unscanned-bucket-name",
      "clean": "clean-bucket-name",
      "quarantined": "quarantined-bucket-name"
    },
  ],
  "ClamCvdMirrorBucket": "cvd-mirror-bucket-name",
  "fileExclusionPatterns": [
    "\\.tmp$",
    "\\.partial_upload\\."
  ]
}

Tenha cuidado ao usar carateres \ na expressão regular, uma vez que têm de ser ignorados no ficheiro JSON com outro \. Por exemplo, para especificar um . literal numa expressão regular, o símbolo tem de ser escapado duas vezes: uma vez para a expressão regular e outra para o texto no ficheiro JSON, tornando-se, por isso, \\., como na última linha do exemplo de código anterior.

Ignore ficheiros de comprimento zero

Tal como os ficheiros temporários, alguns serviços de carregamento criam um ficheiro de comprimento zero no Cloud Storage e, em seguida, atualizam este ficheiro mais tarde com mais conteúdo.

Estes ficheiros também podem ser ignorados definindo o parâmetro config.jsonignoreZeroLengthFiles como true, por exemplo:

{
  "buckets": [
    {
      "unscanned": "unscanned-bucket-name",
      "clean": "clean-bucket-name",
      "quarantined": "quarantined-bucket-name"
    },
  ],
  "ClamCvdMirrorBucket": "cvd-mirror-bucket-name",
  "ignoreZeroLengthFiles": true
}

Quando esta regra é acionada, a métrica ignored-files é incrementada e é registada uma mensagem para indicar que um ficheiro de comprimento zero foi ignorado.

Tamanho máximo do ficheiro de análise

O tamanho máximo predefinido do ficheiro de análise é de 500 MiB. Esta opção é escolhida porque demora aproximadamente 5 minutos a analisar um ficheiro deste tamanho.

Os ficheiros com um tamanho superior a 500 MiB são ignorados e permanecem no contentor unscanned. A métrica files-ignored é incrementada e é registada uma mensagem.

Se precisar de aumentar este limite, atualize os seguintes limites para que acomodem os novos valores máximos de tamanho do ficheiro e duração da digitalização:

• O tempo limite do pedido do serviço do Cloud Run é de 5 minutos
• O prazo de confirmação da mensagem de subscrição do Pub/Sub é de 5 minutos
• O código do Scanner tem uma MAX_FILE_SIZE constante de 500 MiB.
• A configuração do serviço ClamAV tem definições de StreamMaxLength, MaxScanSize e MaxFileSize de 512 MB. Estas definições são definidas pelo bootstrap.sh script.

Limpar

A secção seguinte explica como pode evitar cobranças futuras para o Google Cloud projeto que usou nesta implementação.

Elimine o Google Cloud projeto

Para evitar incorrer em cobranças na sua Google Cloud conta pelos recursos usados nesta implementação, pode eliminar o Google Cloud projeto.

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

O que se segue?

• Explore a documentação do Cloud Storage.
• Para ver mais arquiteturas de referência, diagramas e práticas recomendadas, explore o Centro de arquitetura na nuvem.