Implantar verificação automatizada de malware para arquivos enviados para o Cloud Storage

Neste documento, descrevemos como implantar a arquitetura em Automatizar a verificação de malware para arquivos enviados ao Cloud Storage.

Este guia de implantação pressupõe que você esteja familiarizado com a funcionalidade básica das seguintes tecnologias:

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

Arquitetura

O diagrama a seguir mostra a arquitetura de implantação criada neste documento:

O diagrama mostra os dois pipelines a seguir que são gerenciados por essa arquitetura:

• Pipeline de verificação de arquivos, que verifica se um arquivo enviado contém malware.
• Pipeline de atualização do espelho de banco de dados de malware do ClamAV, que mantém um espelho atualizado do banco de dados de malware usado pelo ClamAV.

Para mais informações sobre a arquitetura, consulte Automatizar a verificação de malware para arquivos enviados ao Cloud Storage.

Objetivos

• Crie um espelho do banco de dados de definições de malware do ClamAV em um bucket do Cloud Storage.

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

  • Verificar arquivos em um bucket do Cloud Storage em busca de malware usando o ClamAV e mover os arquivos verificados para buckets limpos ou em quarentena com base no resultado da verificação.
  • Manter um espelho do banco de dados de definições de malware do ClamAV no Cloud Storage.

• Crie um gatilho do Eventarc para acionar o serviço de verificação de malware quando um arquivo for enviado ao Cloud Storage.

• Crie um job do Cloud Scheduler para acionar o serviço de verificação de malware para atualizar o espelho do banco de dados de definições de malware 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 custo baseada na projeção de uso deste tutorial, 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 implantação, todos os comandos serão executados no Cloud Shell.

Implantar a arquitetura

É possível implantar a arquitetura descrita neste documento usando um dos seguintes métodos:

• Usar o Cloud Shell: use esse método se quiser ver como cada componente da solução é implantado e configurado usando a ferramenta de linha de comando Google Cloud CLI.

  Para usar esse método de implantação, siga as instruções em Implantar usando o Cloud Shell.

• Usar a CLI do Terraform: use esse método se quiser implantar a solução com o mínimo possível de etapas manuais. Esse método depende do Terraform para implantar e configurar os componentes individuais.

  Para usar esse método de implantação, siga as instruções em Implantar usando a CLI do Terraform.

Implantar usando o Cloud Shell

Para implantar manualmente a arquitetura descrita neste documento, siga as etapas nas subseções a seguir.

Preparar o ambiente

Nesta seção, você atribui configurações aos valores usados na implantação, como região e zona. Nesta implantação, você usa us-central1 como a região do serviço do Cloud Run e us como o local do gatilho do Eventarc e dos buckets do Cloud Storage.

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

   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 pela ID do seu projeto.

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

   gcloud config set project "${PROJECT_ID}"
   

3. Crie três buckets 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 buckets sejam exclusivos.

   Esses três buckets contêm os arquivos enviados em vários estágios durante o pipeline de verificação do arquivo:

   • unscanned-PROJECT_ID: armazena os arquivos antes de serem verificados. Seus usuários fazem upload dos arquivos para esse bucket.

   • quarantined-PROJECT_ID: armazena os arquivos que o serviço de verificação de malware verificou e contêm malware.

   • clean-PROJECT_ID: armazena os arquivos que o serviço de verificação de malware verificou e encontrou não infectado.

4. Crie um quarto bucket do Cloud Storage:

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

   ${PROJECT_ID} é usado para garantir que o nome do bucket seja exclusivo.

   Esse bucket cvd-mirror-PROJECT_ID é usado para manter um espelho local do banco de dados de definições de malware, o que impede que a limitação de taxa seja acionada pela CDN do ClamAV.

Configurar uma conta de serviço para o serviço de verificação de malware

Nesta seção, você cria uma conta de serviço para usar com o serviço de verificação de malware. Em seguida, conceda os papéis apropriados à conta de serviço para que ela tenha permissões de leitura e gravação nos buckets do Cloud Storage. Os papéis garantem que a conta tenha permissões mínimas e que tenha acesso apenas aos recursos necessários.

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

   gcloud iam service-accounts create ${SERVICE_NAME}
   

2. Conceda o papel Administrador de objetos aos buckets, permitindo que o serviço leia e exclua documentos do bucket não verificado e grave arquivos nos buckets 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 o papel de gravador de métricas, que permite que o serviço grave métricas no Monitoring:

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

Criar o serviço de verificação de malware no Cloud Run

Nesta seção, você implantará o serviço de verificação de malware no Cloud Run. O serviço é executado em um contêiner do Docker que contém o seguinte:

• Um Dockerfile para criar uma imagem de contêiner com o serviço, o ambiente de execução do Node.js, o SDK do GCloud e os binários do ClamAV.
• Os arquivos TypeScript do serviço do Cloud Run com detecção de malware.
• Um arquivo de configuração config.json para especificar os nomes de bucket do Cloud Storage.
• Um updateCvdMirror.sh para atualizar o espelho do banco de dados de definições de malware do ClamAV no Cloud Storage.
• Um script de shell bootstrap.sh para executar os serviços necessários na inicialização da instância.

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

1. No Cloud Shell, clone o repositório do GitHub que contém os arquivos 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 arquivo de configuração config.json com base no arquivo 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 dar aos buckets do Cloud Storage nomes exclusivos baseados no ID do projeto.

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

   cat config.json
   

5. Execute um preenchimento inicial do espelho do banco de dados de malware do ClamAV no Cloud Storage:

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

   Esses comandos executam uma instalação local da ferramenta CVDUpdate e, em seguida, executam o script updateCvdMirror.sh, que usa CVDUpdate para copiar o banco de dados de malware do ClamAV para o bucket cvd-mirror-PROJECT_ID criado anteriormente.

   É possível verificar o conteúdo do bucket espelhado:

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

   O bucket precisa conter vários arquivos CVD que contenham o banco de dados completo de malware, vários arquivos .cdiff que contenham as atualizações diferenciais diárias e dois arquivos JSON com informações de configuração e estado.

6. Crie e implante o serviço do Cloud Run usando a conta de serviço que você 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 uma vCPU e 4 GiB de RAM. Esse tamanho é aceitável para esta implantação. No entanto, em um ambiente de produção, convém escolher um tamanho de CPU e memória maior para a instância e um parâmetro --max-instances maior. Os tamanhos de recursos que podem ser necessários dependem da quantidade de tráfego que o serviço precisa processar.

   O comando inclui as seguintes especificações:

   • O parâmetro --concurrency especifica o número de solicitações simultâneas que cada instância pode processar.
   • O parâmetro --no-cpu-throttling permite que a instância execute operações em segundo plano, como atualizar definições de malware.
   • O parâmetro --cpu-boost dobra o número de vCPUs na inicialização da instância para reduzir a latência de inicialização.
   • O parâmetro --min-instances 1 mantém pelo menos uma instância ativa, já que o tempo de inicialização de cada instância é relativamente alto.
   • O parâmetro --max-instances 5 impede que o serviço seja escalonado verticalmente em demasia.

7. Quando solicitado, digite Y para criar e implantar o serviço. A criação e a implantação levam cerca de 10 minutos. Quando elas forem concluídas, a seguinte mensagem será exibida:

   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 da saída do comando de implantação em uma variável de shell. Você usará o valor posteriormente ao criar um job 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}
   

   A saída será semelhante ao exemplo a seguir. Ele mostra a versão do serviço malware-scanner, do ClamAV e das definições de malware 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 do Cloud Run requer que todas as invocações sejam autenticadas, e as identidades de autenticação precisam ter a permissão run.routes.invoke no serviço. Adicione a permissão na próxima seção.

Criar um gatilho do Eventarc no Cloud Storage

Nesta seção, você adicionará permissões para permitir que o Eventarc capture eventos do Cloud Storage e um gatilho para enviar esses eventos para o serviço malware-scanner do Cloud Run.

1. Se você estiver usando um projeto criado antes de 8 de abril de 2021, adicione o papel 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'
   

   Essa adição de papel é necessária apenas para projetos mais antigos e permite que o Pub/Sub invoque o serviço do Cloud Run.

2. No Cloud Shell, conceda o papel de Editor 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 receptor 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 gatilho do Eventarc para capturar o evento do objeto finalizado no bucket do Cloud Storage não verificado e enviá-lo ao serviço do Cloud Run. O gatilho usa a conta de serviço malware-scanner para 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 você receber um dos seguintes erros, aguarde um minuto e 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 assinatura subjacente do Pub/Sub usada pelo gatilho do Eventarc. O valor padrão de 10 segundos é muito curto para arquivos grandes ou cargas altas.

   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 gatilho seja criado imediatamente, pode levar até dois minutos para que ele funcione.

Criar um job do Cloud Scheduler para acionar atualizações de espelho do banco de dados ClamAV

• Crie um job do Cloud Scheduler que execute uma solicitação POST HTTP no serviço do Cloud Run com um comando para atualizar o espelho do banco de dados de definições de malware. Para evitar que muitos clientes usem o mesmo horário, a ClamAV exige que você programe o job em 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 de linha de comando --schedule define quando o job é executado usando o formato de string unix-cron. O valor fornecido indica que o job precisa ser executado no minuto específico gerado aleatoriamente a cada duas horas.

Esse job só atualiza o espelho do ClamAV no Cloud Storage. Em cada instância do Cloud Run, o daemon de ClamAV é verificado pelo espelho a cada 30 minutos para novas definições e atualiza o daemon do ClamAV.

Implantar usando a CLI do Terraform

Nesta seção, descrevemos como implantar a arquitetura descrita neste documento usando a CLI do Terraform.

Clonar o repositório do GitHub

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

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

Prepare o ambiente

Nesta seção, você atribui configurações aos valores usados na implantação, como região e zona. Nesta implantação, você usa us-central1 como a região do serviço do Cloud Run e us como o local do gatilho do Eventarc e dos buckets do Cloud Storage.

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

   REGION=us-central1
   LOCATION=us
   PROJECT_ID=PROJECT_ID
   

   Substitua PROJECT_ID pela ID do seu projeto.

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

   gcloud config set project "${PROJECT_ID}"
   

3. Crie o arquivo de configuração config.json com base no arquivo 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 dar aos buckets do Cloud Storage nomes exclusivos baseados no ID do projeto.

4. Opcional: veja o arquivo 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 arquivo de configuração config.json é transmitido ao Terraform usando a variável TF_VAR_config_json para que o Terraform saiba quais buckets do Cloud Storage criar. O valor dessa 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
   

Implantar a infraestrutura base

1. No Cloud Shell, execute os seguintes comandos para implantar a infraestrutura básica:

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

   Responda yes quando solicitado.

   Esse script do Terraform realiza as seguintes tarefas:

   • Cria as contas de serviço
   • Cria o Artifact Registry
   • Cria os buckets do Cloud Storage
   • Define as funções e permissões adequadas
   • Executa um preenchimento inicial do bucket do Cloud Storage que contém o espelho do banco de dados de definições de malware do ClamAV.

Criar o contêiner para o serviço

1. No Cloud Shell, execute os comandos a seguir para iniciar um job do Cloud Build e criar a imagem do contêiner 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 build seja concluída.

Implantar e acionar o serviço

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

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

   Responda yes quando solicitado.

   A implantação e a inicialização do serviço podem levar alguns minutos.

   Esse script do Terraform realiza as seguintes tarefas:

   • Implanta o serviço do Cloud Run usando a imagem de contêiner que você acabou de criar.
   • Configura os gatilhos do Eventarc nos buckets do Cloud Storage unscanned. Embora o gatilho seja criado imediatamente, pode levar até dois minutos para que ele funcione por completo.
   • Cria o job do Cloud Scheduler para atualizar o espelho de definições de malware do ClamAV.

   Se a implantação falhar com um dos seguintes erros, aguarde um minuto e execute o comando terraform apply novamente para tentar criar o gatilho 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 uso, 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}"
   

   A saída será semelhante ao exemplo a seguir. Ele mostra a versão do serviço malware-scanner, do ClamAV e das definições de malware 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
   

Fazer o upload de arquivos para testar o pipeline

Para testar o pipeline, faça upload de um arquivo limpo (sem malware) e um arquivo de teste que imite um arquivo infectado:

1. Crie um arquivo de texto de amostra ou use um atual não infectado para testar os processos do pipeline.

2. No Cloud Shell, copie o arquivo de dados de amostra para o bucket não verificado:

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

   Substitua FILENAME pelo nome do arquivo de texto não infectado. O serviço de verificação de malware inspeciona cada documento e o transfere para um bucket apropriado. Esse arquivo é movido para o bucket limpo.

3. Aguarde alguns segundos para o pipeline processar o arquivo e verifique o bucket limpo para ver se o arquivo processado está lá:

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

   Verifique se o arquivo foi removido do bucket não verificado:

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

4. Faça upload de um arquivo chamado eicar-infected.txt que contenha a assinatura de teste antimalware padrão da EICAR no bucket não verificado:

   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"
   

   Essa string de texto tem uma assinatura que aciona verificadores de malware para fins de teste. Esse arquivo de teste é amplamente usado. Ele não é um malware real e é inofensivo para sua estação de trabalho. Se você tentar criar um arquivo que contenha essa string em um computador com um verificador de malware instalado, será possível acionar um alerta.

5. Aguarde alguns segundos e verifique o bucket em quarentena para ver se o documento passou pelo pipeline.

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

   O serviço também registra uma entrada do Logging quando um arquivo infectado por malware é detectado.

   Verifique se o arquivo foi removido do bucket não verificado:

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

Testar o mecanismo de atualização do banco de dados de definições de malware

• No Cloud Shell, é possível acionar a verificação de atualizações forçando a execução do job do Cloud Scheduler:

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

  Os resultados desse comando são mostrados apenas nos registros detalhados.

Monitorar o serviço

É possível monitorar o serviço usando o Cloud Logging e o Cloud Monitoring.

Ver registros detalhados

1. No console do Google Cloud , acesse a página "Explorador de registros" do Cloud Logging.

   Acessar o Explorador de registros

2. Se o filtro Campos de registro não for exibido, clique em Campos de registro.

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

4. Na seção Nome do serviço do filtro Campos de registro, clique em scanner de malware.

Os resultados da consulta mostram os registros do serviço, incluindo várias linhas que mostram as solicitações de verificação e o status dos dois arquivos enviados:

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)

A saída mostra a versão do ClamAV e a revisão da assinatura do banco de dados de malware, junto com o nome do malware do arquivo de teste infectado. É possível usar essas mensagens de registro para configurar alertas quando um vírus for encontrado ou para quando houver falhas durante a verificação.

A saída também mostra as definições de malware espelham os registros de atualização:

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

Se o espelho foi atualizado, a saída mostra linhas adicionais:

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

Os registros 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 o banco de dados tiver sido atualizado, as linhas de registro do novo registro serão semelhantes às seguintes:

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

Mostrar métricas

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

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

É possível ver essas métricas no explorador de métricas do Cloud Monitoring:

1. No console Google Cloud , acesse a página Metrics Explorer do Cloud Monitoring.

   Acessar o Metrics Explorer

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

3. Expanda o recurso Tarefa genérica.

4. Abra 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 arquivo limpo foi verificado.

Você pode usar métricas para monitorar o pipeline e criar alertas para quando o malware for detectado ou quando os arquivos falharem no processamento.

As métricas geradas têm os seguintes rótulos, que você pode usar para filtragem e agregação para visualizar detalhes mais refinados com o Metrics Explorer

• source_bucket
• destination_bucket
• clam_version
• cloud_run_revision

Na métrica ignored_files, os seguintes rótulos reason definem por que os arquivos são ignorados:

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

Configuração avançada

As seções a seguir descrevem como configurar o scanner com parâmetros mais avançados.

Lidar com vários buckets

O serviço de verificação de malware verifica arquivos de vários buckets de origem e envia os arquivos para separar buckets limpos e em quarentena. Embora essa configuração avançada esteja fora do escopo desta implantação, veja a seguir um resumo das etapas necessárias:

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

2. Conceda os papéis apropriados à conta de serviço malware-scanner em cada bucket.

3. Edite o arquivo de configuração config.json para especificar os nomes dos buckets de 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 buckets não verificados, crie um gatilho do Eventarc. Crie um nome de gatilho exclusivo para cada bucket.

   O bucket do Cloud Storage precisa estar no mesmo projeto e região que o gatilho do Eventarc.

Se você estiver usando a implantação do Terraform, as etapas nesta seção serão aplicadas automaticamente quando você transmitir o arquivo de configuração config.json atualizado na variável de configuração do Terraform TF_VAR_config_json.

Como ignorar arquivos temporários

Alguns serviços de upload, como SFTP para gateways do Cloud Storage, criam um ou mais arquivos temporários durante o processo de upload. Esses serviços renomeiam os arquivos para o nome final quando o upload é concluído.

O comportamento normal do scanner é verificar e mover todos os arquivos, incluindo esses arquivos temporários assim que são gravados. Isso pode fazer com que o serviço de upload falhe quando não consegue encontrar os arquivos temporários.

A seção fileExclusionPatterns do arquivo de configuração config.json permite usar expressões regulares para especificar uma lista de padrões de nome de arquivo a serem ignorados. Todos os arquivos que correspondem a essas expressões regulares permanecem no bucket unscanned.

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

O exemplo de código a seguir mostra um arquivo de configuração config.json com a lista fileExclusionPatterns definida para ignorar arquivos 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 caracteres \ na expressão regular, porque eles precisam ser inseridos como escape no arquivo JSON com outro \. Por exemplo, para especificar um . literal em uma expressão regular, o símbolo precisa de escape duas vezes: uma para a expressão regular e outra para o texto no arquivo JSON. Portanto, ele se torna \\., como na última linha do exemplo de código anterior.

Ignorar arquivos de comprimento zero

Assim como os arquivos temporários, alguns serviços de upload criam um arquivo de comprimento zero no Cloud Storage e o atualizam mais tarde com mais conteúdo.

Esses arquivos também podem ser ignorados definindo o parâmetro config.json ignoreZeroLengthFiles 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 essa regra é acionada, a métrica ignored-files é incrementada, e uma mensagem é registrada para indicar que um arquivo de comprimento zero foi ignorado.

Tamanho máximo do arquivo de verificação

O tamanho máximo padrão do arquivo de verificação é de 500 MiB. Isso é escolhido porque leva aproximadamente 5 minutos para verificar um arquivo desse tamanho.

Arquivos maiores que 500 MiB são ignorados e permanecem no bucket unscanned. A métrica files-ignored é incrementada e uma mensagem é registrada.

Se você precisar aumentar esse limite, atualize os seguintes limites para que eles acomodem os novos valores máximos de tamanho de arquivo e duração da verificação:

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

Limpar

A seção a seguir explica como evitar cobranças futuras para o projeto doGoogle Cloud usado nesta implantação.

Excluir o projeto do Google Cloud

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados nesta implantação, exclua o projeto do Google Cloud .

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

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.

A seguir

• Veja a documentação do Cloud Storage.
• Para mais arquiteturas de referência, diagramas e práticas recomendadas, confira a Central de arquitetura do Cloud.