Como criar um detector de dicionário personalizado armazenado

Os detectores de dicionários personalizados normais são suficientes quando você tem uma lista de várias dezenas de milhares de palavras ou frases confidenciais nas quais você quer verificar o conteúdo. Se você tiver várias palavras ou frases para procurar ou se sua lista de palavras ou frases for alterada com frequência, crie um dicionário personalizado armazenado, que você pode usar para procurar até dezenas de milhões de palavras ou frases.

Este tópico descreve como criar e recriar dicionários personalizados armazenados e abrange vários cenários de erro.

Anatomia de um dicionário personalizado armazenado

Provavelmente você já sabe como criar um infoType personalizado de dicionário regular ou um infoType personalizado de regex: configure o infoType personalizado e use-o ao configurar a verificação de inspeção ou desidentificação. Dicionários personalizados armazenados diferem desses infoTypes personalizados, já que cada dicionário personalizado armazenado tem dois componentes:

  • Uma lista de frases que você cria e define. Essa lista é armazenada como um arquivo de texto no Cloud Storage ou como uma coluna em uma tabela do BigQuery.
  • Os arquivos de dicionário gerados, que são criados pelo Cloud DLP com base na sua lista de frases. Os arquivos de dicionário são armazenados no Cloud Storage e compostos por uma cópia dos dados da frase de origem e dos filtros de Bloom, que ajudam na pesquisa e na correspondência. Não é possível editar esses arquivos diretamente.

Criar um novo dicionário personalizado armazenado

Esta seção descreve como criar, editar e recriar um dicionário personalizado armazenado.

Criar uma lista de frases

O primeiro passo para criar um dicionário personalizado armazenado é criar uma lista de palavras e frases. Você tem duas opções:

  • Insira um arquivo de texto com cada palavra ou frase em sua própria linha em um bucket do Cloud Storage.
  • Atribua uma coluna de uma tabela do BigQuery como o contêiner das frases. Mantenha uma frase por linha na coluna. É possível usar uma tabela atual do BigQuery, desde que todas as palavras e frases do dicionário estejam em uma única coluna.

Ao montar uma lista de termos, existe a possibilidade de que ela fique grande demais para o Cloud DLP processar. Se for exibida uma mensagem de erro, consulte Como solucionar erros, mais adiante neste tópico.

Criar o dicionário

Depois de criar sua lista de termos, use o Cloud DLP para criar um dicionário:

Console

  1. Crie uma nova pasta para o dicionário em um bucket do Cloud Storage. O Cloud DLP criará pastas contendo os arquivos de dicionário no local especificado por você.
  2. No Console do Cloud, abra o Cloud DLP.

    Acessar a IU do Cloud DLP

  3. No menu Criar, escolha InfoType armazenado.

    Captura de tela da IU do DLP com o menu Criar > InfoType armazenado selecionado.

    Como alternativa, clique no seguinte botão:

    Criar novo infoType

A página "Criar infoType" contém as seguintes seções:

Configurar infoType

A seção Configurar infoType é onde você nomeia e descreve o infoType do dicionário personalizado armazenado.

  • No campo ID do InfoType, insira um identificador para o infoType personalizado. É assim que você se refere ao infoType ao configurar os jobs de inspeção e de desidentificação. É possível usar letras, números, hifens e sublinhados no nome.
  • No campo Nome de exibição do InfoType, insira um nome para seu infoType personalizado. É possível usar espaços e pontuação no nome.
  • No campo Descrição, insira uma descrição para que o infoType personalizado possa detectar.

Escolher local dos dados

Na seção Escolher localizador de dados você especifica onde encontrar a lista de palavras e frases a partir das quais o dicionário personalizado armazenado será criado.

  • Escolha BigQuery se as palavras e frases a serem pesquisadas estiverem listadas em uma tabela do BigQuery. Lembre-se de que é possível designar, no máximo, uma coluna da tabela. Digite o ID do projeto, o ID do conjunto de dados e o ID da tabela nos campos especificados. No campo Nome, insira o identificador da coluna.
  • Escolha o Google Cloud Storage, se as palavras e frases a serem pesquisadas estiverem listadas em um arquivo de texto no Cloud Storage. Digite o caminho do arquivo no campo especificado.

A seção final é onde você especifica um local para o Cloud DLP salvar o dicionário personalizado compactado armazenado.

No campo bucket ou pasta de saída, insira o caminho em que você quer que o dicionário seja salvo.

Clique em Criar para criar o dicionário personalizado armazenado. A tela de detalhes do infoType é exibida.

Quando o status for "Pronto", o dicionário personalizado armazenado é gerado e o novo infoType personalizado está pronto para uso.

Protocolo

  1. Crie uma nova pasta para o dicionário em um bucket do Cloud Storage. O Cloud DLP criará pastas contendo os arquivos de dicionário no local especificado por você.
  2. Use o método storedInfoTypes.create da API Cloud DLP para criar o dicionário. O método create utiliza os seguintes parâmetros:
    • Um objeto StoredInfoTypeConfig, que contém a configuração armazenada do infoType. Ele inclui:
      • description: uma descrição do dicionário.
      • displayName: o nome que você quer dar ao dicionário.
      • LargeCustomDictionaryConfig: contém a configuração do dicionário personalizado armazenado. Ele inclui:
        • BigQueryField: especificado se a lista de termos estiver armazenada no BigQuery. Inclui uma referência à tabela em que sua lista está armazenada, além do campo que contém cada frase do dicionário.
        • CloudStorageFileSet: especificado se a lista de termos estiver armazenada no Cloud Storage. Inclui o URL ao local de origem no Cloud Storage, no seguinte formato: "gs://[PATH_TO_GS]". Não há suporte para caracteres curinga.
        • outputPath: o caminho para o local em um bucket do Cloud Storage para armazenar o dicionário criado.
    • storedInfoTypeId: o identificador do infoType personalizado armazenado. Esse valor é como você fará referência ao infoType armazenado ao reconstruí-lo, excluí-lo ou usá-lo em um job de inspeção ou desidentificação. Se deixar esse campo em branco, o sistema gerará um identificador para você.

Veja a seguir o JSON de exemplo que, quando é enviado para o método storedInfoTypes.create, cria um novo dicionário personalizado armazenado. Neste exemplo, instruímos o Cloud DLP a criar um dicionário personalizado armazenado. Para isso, utilizamos uma lista de termos com todos os nomes de usuário do GitHub usados em confirmações (bigquery-public-data.samples.github_nested), disponível publicamente no banco de dados do BigQuery. O caminho de saída do dicionário criado é definido como um bucket do Cloud Storage chamado dlptesting, e o dicionário personalizado armazenado recebeu o nome github-usernames.

Entrada JSON:

POST https://dlp.googleapis.com/v2/projects/[PROJECT_ID]/storedInfoTypes?key={YOUR_API_KEY}

{
  "config":{
    "displayName":"GitHub usernames",
    "description":"Dictionary of github usernames used in commits",
    "largeCustomDictionary":{
      "outputPath":{
        "path":"gs://[PATH_TO_GS]"
      },
      "bigQueryField":{
        "table":{
          "datasetId":"samples",
          "projectId":"bigquery-public-data",
          "tableId":"github_nested"
        }
      }
    }
  },
  "storedInfoTypeId":"github-usernames"
}

Recriar o dicionário

Se você quiser adicionar ou remover termos ou frases do dicionário, primeiro atualize a lista de termos de origem e, em seguida, instrua o Cloud DLP a atualizar o dicionário.

  1. Atualize a lista atual de termos de origem no Cloud Storage ou no BigQuery. Adicione, remova ou altere os termos ou frases conforme necessário.
  2. "Recrie" uma nova versão do dicionário usando o Console do Cloud ou o método storedInfoTypes.patch do Cloud DLP. Isso cria uma nova versão do dicionário, que substituirá a antiga.

Para recriar o dicionário personalizado armazenado:

Console

  1. Atualize e salve sua lista de termos no Cloud Storage ou no BigQuery.
  2. No Console do Cloud, abra o Cloud DLP.
  3. Clique na guia Configurações e em InfoTypes.
  4. Na tela infoTypes, clique na guia Personalizar. Seus infoTypes personalizados armazenados aparecem aqui.

    Acessar a lista de infoTypes personalizados

  5. Clique na linha com o infoType armazenado que você quer atualizar.

  6. Na tela de detalhes do infoType, clique em Reconstruir dados.

O Cloud DLP recria o dicionário personalizado armazenado com as alterações feitas na lista de termos de origem. Depois que o status do infoType personalizado estiver "Pronto", você poderá usá-lo. Todos os modelos ou gatilhos de jobs que usam o infoType personalizado usarão automaticamente o infoType personalizado reconstruído.

Protocolo

Se a única coisa que você está tentando fazer é adicionar novos termos ou excluir ou alterar termos presentes no dicionário personalizado armazenado, você só precisa chamar o método storedInfoTypes.patch para reconstruir o dicionário. Certifique-se de preencher o campo name com o nome do recurso da organização, do projeto e do infoType personalizado armazenado a ser recriado. Você forneceu o nome do infoType armazenado quando ele foi criado no parâmetro storedInfoTypeId. Se você não se lembrar do identificador do infoType personalizado armazenado que quer recriar, chame o método storedInfoTypes.list para visualizar uma lista de todos os infoTypes armazenados no momento.

Os seguintes padrões representam entradas válidas para o campo name:

  • organizations/[ORG_ID]/storedInfoTypes/[STORED_INFOTYPE_ID]
  • projects/[PROJECT_ID]/storedInfoTypes/[STORED_INFOTYPE_ID]

Quando você recria um dicionário personalizado armazenado para uma nova versão, a versão antiga do dicionário personalizado armazenado é excluída. Quando o Cloud DLP está atualizando o dicionário personalizado armazenado, o status dele é "pendente". Enquanto o dicionário estiver nesse status, a versão antiga continuará existindo. Todas as verificações que forem executadas durante a recriação do dicionário serão feitas usando a versão antiga do dicionário.

É possível alterar a lista de termos de origem referente a um dicionário personalizado armazenado atual de um armazenado em uma tabela do BigQuery para um armazenado em um bucket do Cloud Storage, e vice-versa. Use o método storedInfoTypes.patch, mas inclua um objeto CloudStorageFileSet em LargeCustomDictionaryConfig que antes continha um objeto BigQueryField, ou vice-versa. Você também precisa especificar o parâmetro updateMask do dicionário personalizado armazenado que você reconstruiu, no formato FieldMask. Por exemplo, o JSON a seguir, quando enviado ao método storedInfoTypes.patch, declara no parâmetro updateMask que o URL do caminho do Cloud Storage foi atualizado (large_custom_dictionary.cloud_storage_file_set.url):

PATCH https://dlp.googleapis.com/v2/projects/[PROJECT_ID]/storedInfoTypes/github-usernames?key={YOUR_API_KEY}

{
  "config":{
    "largeCustomDictionary":{
      "cloudStorageFileSet":{
        "url":"gs://[BUCKET_NAME]/[PATH_TO_FILE]"
      }
    }
  },
  "updateMask":"large_custom_dictionary.cloud_storage_file_set.url"
}

Verificar conteúdo usando detectores de dicionários personalizados armazenados

A verificação de conteúdo com um detector de dicionário personalizado armazenado é semelhante à verificação usando qualquer outro detector de infoType personalizado.

Console

É possível usar um detector de dicionário personalizado ao criar um novo job, gatilho de job ou modelo. Na seção Configurar detecção do job ou do fluxo de trabalho da criação de modelos, é possível especificar o infoType do dicionário personalizado armazenado na sub-seção infoTypes personalizado:

  1. Clique em Adicionar infoType personalizado e em InfoType armazenado.

    Captura de tela do fluxo de trabalho do gatilho da criação de job de IU do DLP, na seção infoType personalizados.

  2. Na seção Adicionar infoType personalizado, digite um nome de infoType no campo InfoType. É possível usar letras, números e sublinhados.

  3. Clique no campo Nome do infoType armazenado, e um menu aparecerá abaixo do campo com os caminhos para seu dicionário personalizado infoTypes armazenado, como mostrado aqui:

    Captura de tela do fluxo de trabalho do gatilho de criação de jobs da IU do DLP, na seção adicionar infoType personalizado.

  4. Escolha o dicionário personalizado armazenado e clique em Concluído.

O infoType personalizado que você adicionou é mostrado como na captura de tela a seguir. Você pode adicionar outros infoTypes personalizados, se quiser.

Captura de tela do fluxo de trabalho do gatilho de criação de jobs da IU do DLP, com o infoType personalizado adicionado.

Agora você pode continuar com o job, o gatilho de jobs ou o processo de criação do modelo.

Protocolo

O JSON a seguir, quando enviado ao método content.inspect, verifica o snippet de texto fornecido usando o detector de dicionário personalizado armazenado especificado. Observe que o parâmetro infoType é obrigatório porque todos os infoTypes personalizados, incluindo dicionários personalizados armazenados, precisam ter um nome que não seja conflitante com infoTypes incorporados ou outros infoTypes personalizados. O parâmetro storedType contém o caminho completo do recurso do infoType armazenado.

Entrada JSON:

POST https://dlp.googleapis.com/v2/projects/[PROJECT_ID]/content:inspect?key={YOUR_API_KEY}

{
  "inspectConfig":{
    "customInfoTypes":[
      {
        "infoType":{
          "name":"GITHUB_LOGINS"
        },
        "storedType":{
          "name":"projects/[PROJECT_ID]/storedInfoTypes/github-logins"
        }
      }
    ]
  },
  "item":{
    "value":"The commit was made by githubuser."
  }
}

Como solucionar erros

Ao tentar criar um dicionário armazenado personalizado, é possível que seja exibido um erro explicando que o Cloud DLP não pode criar um dicionário a partir da sua lista de termos baseada no Cloud Storage. Estas são algumas causas prováveis:

  • Você atingiu o limite máximo para dicionários personalizados armazenados. Dependendo do problema, há várias soluções alternativas:
    • Se você atingir o limite máximo de um único dicionário personalizado armazenado no Cloud Storage (200 MB), tente dividir o arquivo em vários. Ainda é possível usar esses arquivos para montar um único dicionário personalizado, desde que o tamanho total deles não exceda o tamanho máximo combinado para todos os arquivos de dicionários personalizados armazenados no Cloud Storage (1 GB).
    • O BigQuery não tem os mesmos limites que o Cloud Storage. Pense na possibilidade de mover os termos para uma tabela do BigQuery, mas esteja ciente do tamanho máximo da coluna do dicionário personalizado armazenado no BigQuery (1 GB) e do número máximo de linhas (5.000.000).
    • Se o arquivo de lista de termos exceder todos os limites aplicáveis para listas de termos de origem de dicionários personalizados armazenados, será necessário dividir o arquivo de lista de termos em vários no Cloud Storage, criar um dicionário para cada arquivo e gerar um job de verificação separado para cada dicionário.
  • Falta pelo menos uma letra ou um número em um ou mais dos termos. O Cloud DLP não pode procurar termos que sejam compostos exclusivamente por espaços ou símbolos. Eles precisam ter pelo menos uma letra ou um número. Analise sua lista e veja se há alguns desses termos incluídos e, em seguida, corrija-os ou exclua-os.
  • A lista de termos contém uma frase com muitos "componentes". Um componente, neste contexto, é uma sequência contínua composta apenas de letras, de números ou de caracteres que não são letras nem números, como espaços ou símbolos. Analise sua lista e veja se há alguns desses termos incluídos e, em seguida, corrija-os ou exclua-os.
  • A conta de serviço de DLP não tem acesso aos dados de origem do dicionário ou ao bucket do Cloud Storage para armazenar arquivos de dicionário. Para corrigir esse problema, conceda o papel de administrador do Cloud Storage ou os papéis dataOwner e jobUser do BigQuery à conta de serviço de DLP.

Visão geral da API

Um dicionário personalizado armazenado é considerado um infoType armazenado devido ao seu tamanho e à sua complexidade. Atualmente, os dicionários personalizados armazenados são o único tipo de infoType armazenado.

Um infoType armazenado é representado no Cloud DLP pelo objeto StoredInfoType. e acompanhado pelos seguintes objetos relacionados:

  • StoredInfoTypeConfig contém a configuração do infoType armazenado, que inclui detalhes como nome e descrição.
  • StoredInfoTypeVersion contém mais informações sobre o infoType armazenado, como data e hora de criação e as últimas cinco mensagens de erro ocorridas quando a versão atual do infoType armazenado foi criada.
  • StoredInfoTypeState contém o estado da versão mais atual e quaisquer versões pendentes do infoType armazenado. As informações de estado avisam se o infoType armazenado está sendo recriado, está pronto para uso ou é inválido.

Use os métodos a seguir para editar ou excluir um infoType armazenado:

  • storedInfoTypes.create: cria um novo infoType armazenado, conforme o StoredInfoTypeConfig especificado.
  • storedInfoTypes.patch: recria o infoType armazenado com um novo StoredInfoTypeConfig especificado. Se nada foi especificado, cria uma nova versão do infoType armazenado com o StoredInfoTypeConfig atual.
  • storedInfoTypes.get: recupera o StoredInfoTypeConfig e todas as versões pendentes do infoType armazenado especificado.
  • storedInfoTypes.list: lista todos os infoTypes armazenados no momento.
  • storedInfoTypes.delete: exclui o infoType armazenado especificado.

Além das APIs de infoType armazenados descritas aqui, o objeto a seguir aplica-se especificamente aos dicionários personalizados armazenados:

  • LargeCustomDictionaryConfig especifica estas opções:
    • o local no Cloud Storage ou no BigQuery em que sua lista de frases está armazenada;
    • o local no Cloud Storage para armazenar os arquivos de dicionários gerados.

Especificações de correspondência de dicionário

Veja a seguir orientações sobre como o Cloud DLP combina palavras e frases do dicionário. As observações abaixo se aplicam a dicionários personalizados tanto armazenados como regulares:

  • As palavras do dicionário são indiferentes a maiúsculas. Se o dicionário incluir Abby, ele corresponderá a abby, ABBY, Abby e assim por diante.
  • Todos os caracteres, tanto nos dicionários quanto no conteúdo que será verificado, diferentes de letras e dígitos contidos no Plano Multilíngue Básico Unicode são considerados espaços em branco durante a verificação de correspondências. Se o dicionário procurar por Abby Abernathy, ele corresponderá a abby abernathy, Abby, Abernathy, Abby (ABERNATHY) e assim por diante.
  • Os caracteres ao redor das correspondências precisam ser de um tipo diferente (letras ou dígitos) dos caracteres adjacentes da palavra. Se o dicionário procurar Abi, ele corresponderá aos três primeiros caracteres de Abi904, mas não de Abigail.
  • As palavras do dicionário que contêm um grande número de caracteres que não são letras ou dígitos podem retornar descobertas inesperadas, porque esses caracteres são tratados como espaços em branco.