Como criar um detector de regex personalizado

Um detector de infoType personalizado de expressão regular (regex) permite que você crie seus próprios detectores para que a Proteção de dados sensíveis detecte correspondências com base em um padrão de expressão regular. Por exemplo, se você tiver números de registros médicos no formato ###-#-#####. será possível definir um padrão de regex como este:

[0-9]{3}-[0-9]{1}-[0-9]{5}

A Proteção de Dados Sensíveis corresponderia a itens como os seguintes:

012-4-56789

Anatomia de detectores de infoType personalizados de regex

Conforme resumido em Visão geral da API, para criar um detector de infoType regex personalizado, você define um objeto CustomInfoType que contém o seguinte:

• O nome que você quer dar ao detector de infoType personalizado, em um objeto InfoType.
• Um valor Likelihood opcional. Se você omitir esse campo, as correspondências de regex retornarão uma probabilidade padrão de VERY_LIKELY. Se você observar um detector de infoType regex personalizado exibindo muitos falsos positivos, tente reduzir a probabilidade básica e use regras de detecção para aumentar a probabilidade usando informações contextuais. Para saber mais, consulte Como personalizar a probabilidade de descoberta.
• DetectionRule ou regras de hotword opcionais. Essas regras ajustam a probabilidade de descobertas de acordo com determinada proximidade de hotwords especificadas. Saiba mais sobre regras de hotword em Como personalizar a probabilidade de descoberta.

• Um valor SensitivityScore opcional. Se você omitir esse campo, as correspondências com a expressão regular vão retornar um nível de sensibilidade padrão de HIGH.

  As pontuações de sensibilidade são usadas em perfis de dados. Ao criar perfis dos seus dados, a Proteção de dados sensíveis usa as pontuações de sensibilidade dos infoTypes para calcular o nível de sensibilidade.

• Um objeto Regex que consiste em um único padrão que define a expressão regular.

Como um objeto JSON, um detector de infoType personalizado de regex que inclui todos os componentes opcionais é semelhante ao seguinte:

{
  "customInfoTypes":[
    {
      "infoType":{
        "name":"CUSTOM_INFOTYPE_NAME"
      },
      "likelihood":"LIKELIHOOD_LEVEL",
      "detectionRules":[
        {
          "hotwordRule":{
            HOTWORD_RULE
          }
        },
      "sensitivityScore":{
          "score": "SENSITIVITY_SCORE"
        },
      ],
      "regex":{
        "pattern":"REGULAR_EXPRESSION_PATTERN"
      }
    }
  ],
  ...
}

Observação: também é possível criar um detector de regex personalizado fazendo referência a um StoredInfoType no campo storedType do objeto CustomInfoType, em vez de definir o campo regex. No entanto, essa abordagem exige que você primeiro crie um StoredInfoType do tipo Regex. Na maioria dos casos, é mais simples definir o objeto Regex diretamente no campo regex do objeto CustomInfoType.

Exemplo de regex: correspondência com números de registros médicos

O snippet e o código JSON a seguir em várias linguagens mostram um detector de infoType personalizado de expressão regular que instrui a Proteção de dados sensíveis a associar um número de registro médico (MRN) no texto de entrada "MRN do paciente 444-5-22222" e atribuir uma probabilidade a cada correspondência de POSSIBLE.

C#

Para saber como instalar e usar a biblioteca de cliente da Proteção de dados sensíveis, consulte Bibliotecas de cliente da Proteção de dados sensíveis.

Para autenticar na Proteção de dados sensíveis, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

using System;
using Google.Api.Gax.ResourceNames;
using Google.Cloud.Dlp.V2;

public class InspectDataWithCustomRegex
{
    public static InspectContentResponse InspectDataCustomRegex(
        string projectId,
        string text,
        string customRegex,
        InfoType infoType = null)
    {
        // Instantiate a client.
        var dlp = DlpServiceClient.Create();

        // Construct content item by setting the text.
        var contentItem = new ContentItem { Value = text };

        // Construct the custom regex detector.
        var customInfoType = new CustomInfoType
        {
            InfoType = infoType ?? new InfoType { Name = "C_MRN" },
            Regex = new CustomInfoType.Types.Regex { Pattern = customRegex }
        };

        // Construct Inspect Config.
        var inspectConfig = new InspectConfig
        {
            CustomInfoTypes = { customInfoType },
            IncludeQuote = true,
            MinLikelihood = Likelihood.Possible
        };

        // Construct the request.
        var request = new InspectContentRequest
        {
            ParentAsLocationName = new LocationName(projectId, "global"),
            Item = contentItem,
            InspectConfig = inspectConfig,
        };

        // Call the API.
        var response = dlp.InspectContent(request);

        // Inspect the results.
        var resultFindings = response.Result.Findings;

        Console.WriteLine($"Findings: {resultFindings.Count}");
        foreach (var f in resultFindings)
        {
            Console.WriteLine("Quote: " + f.Quote);
            Console.WriteLine("Info type: " + f.InfoType.Name);
            Console.WriteLine("Likelihood: " + f.Likelihood);
        }

        return response;
    }
}

Go

Para saber como instalar e usar a biblioteca de cliente da Proteção de dados sensíveis, consulte Bibliotecas de cliente da Proteção de dados sensíveis.

Para autenticar na Proteção de dados sensíveis, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import (
	"context"
	"fmt"
	"io"

	dlp "cloud.google.com/go/dlp/apiv2"
	"cloud.google.com/go/dlp/apiv2/dlppb"
)

// inspectWithCustomRegex inspect a data with custom regex pattern
func inspectWithCustomRegex(w io.Writer, projectID, textToInspect, customRegexPattern, infoTypeName string) error {
	//projectID := "my-project-id"
	//textToInspect := "Patients MRN 444-5-22222"
	//customRegexPattern := "[1-9]{3}-[1-9]{1}-[1-9]{5}"
	//infoTypeName := "C_MRN"

	ctx := context.Background()

	// Initialize a client once and reuse it to send multiple requests. Clients
	// are safe to use across goroutines. When the client is no longer needed,
	// call the Close method to cleanup its resources.
	client, err := dlp.NewClient(ctx)
	if err != nil {
		return err
	}

	// Closing the client safely cleans up background resources.
	defer client.Close()

	// Specify the type and content to be inspected.
	contentItem := &dlppb.ContentItem{
		DataItem: &dlppb.ContentItem_ByteItem{
			ByteItem: &dlppb.ByteContentItem{
				Type: dlppb.ByteContentItem_TEXT_UTF8,
				Data: []byte(textToInspect),
			},
		},
	}

	// Construct the custom regex detectors
	customInfoType := &dlppb.CustomInfoType{
		InfoType: &dlppb.InfoType{
			Name: infoTypeName,
		},
		// Specify the regex pattern the inspection will look for.
		Type: &dlppb.CustomInfoType_Regex_{
			Regex: &dlppb.CustomInfoType_Regex{
				Pattern: customRegexPattern,
			},
		},
		Likelihood: dlppb.Likelihood_POSSIBLE,
	}

	// Construct the Inspect request to be sent by the client.
	req := &dlppb.InspectContentRequest{
		Parent: fmt.Sprintf("projects/%s/locations/global", projectID),
		Item:   contentItem,
		// Construct the configuration for the Inspect request.
		InspectConfig: &dlppb.InspectConfig{
			CustomInfoTypes: []*dlppb.CustomInfoType{
				customInfoType,
			},
			IncludeQuote: true,
		},
	}

	// Send the request.
	resp, err := client.InspectContent(ctx, req)
	if err != nil {
		return err
	}

	// Parse the response and process results
	fmt.Fprintf(w, "Findings: %v\n", len(resp.Result.Findings))
	for _, v := range resp.GetResult().Findings {
		fmt.Fprintf(w, "Quote: %v\n", v.GetQuote())
		fmt.Fprintf(w, "Infotype Name: %v\n", v.GetInfoType().GetName())
		fmt.Fprintf(w, "Likelihood: %v\n", v.GetLikelihood())
	}
	return nil
}

Java

Para saber como instalar e usar a biblioteca de cliente da Proteção de dados sensíveis, consulte Bibliotecas de cliente da Proteção de dados sensíveis.

Para autenticar na Proteção de dados sensíveis, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import com.google.cloud.dlp.v2.DlpServiceClient;
import com.google.privacy.dlp.v2.ByteContentItem;
import com.google.privacy.dlp.v2.ByteContentItem.BytesType;
import com.google.privacy.dlp.v2.ContentItem;
import com.google.privacy.dlp.v2.CustomInfoType;
import com.google.privacy.dlp.v2.CustomInfoType.Regex;
import com.google.privacy.dlp.v2.Finding;
import com.google.privacy.dlp.v2.InfoType;
import com.google.privacy.dlp.v2.InspectConfig;
import com.google.privacy.dlp.v2.InspectContentRequest;
import com.google.privacy.dlp.v2.InspectContentResponse;
import com.google.privacy.dlp.v2.Likelihood;
import com.google.privacy.dlp.v2.LocationName;
import com.google.protobuf.ByteString;
import java.io.IOException;

public class InspectWithCustomRegex {

  public static void main(String[] args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String textToInspect = "Patients MRN 444-5-22222";
    String customRegexPattern = "[1-9]{3}-[1-9]{1}-[1-9]{5}";
    inspectWithCustomRegex(projectId, textToInspect, customRegexPattern);
  }

  // Inspects a BigQuery Table
  public static void inspectWithCustomRegex(
      String projectId, String textToInspect, String customRegexPattern) throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (DlpServiceClient dlp = DlpServiceClient.create()) {
      // Specify the type and content to be inspected.
      ByteContentItem byteItem =
          ByteContentItem.newBuilder()
              .setType(BytesType.TEXT_UTF8)
              .setData(ByteString.copyFromUtf8(textToInspect))
              .build();
      ContentItem item = ContentItem.newBuilder().setByteItem(byteItem).build();

      // Specify the regex pattern the inspection will look for.
      Regex regex = Regex.newBuilder().setPattern(customRegexPattern).build();

      // Construct the custom regex detector.
      InfoType infoType = InfoType.newBuilder().setName("C_MRN").build();
      CustomInfoType customInfoType =
          CustomInfoType.newBuilder().setInfoType(infoType).setRegex(regex).build();

      // Construct the configuration for the Inspect request.
      InspectConfig config =
          InspectConfig.newBuilder()
              .addCustomInfoTypes(customInfoType)
              .setIncludeQuote(true)
              .setMinLikelihood(Likelihood.POSSIBLE)
              .build();

      // Construct the Inspect request to be sent by the client.
      InspectContentRequest request =
          InspectContentRequest.newBuilder()
              .setParent(LocationName.of(projectId, "global").toString())
              .setItem(item)
              .setInspectConfig(config)
              .build();

      // Use the client to send the API request.
      InspectContentResponse response = dlp.inspectContent(request);

      // Parse the response and process results
      System.out.println("Findings: " + response.getResult().getFindingsCount());
      for (Finding f : response.getResult().getFindingsList()) {
        System.out.println("\tQuote: " + f.getQuote());
        System.out.println("\tInfo type: " + f.getInfoType().getName());
        System.out.println("\tLikelihood: " + f.getLikelihood());
      }
    }
  }
}

Node.js

Para saber como instalar e usar a biblioteca de cliente da Proteção de dados sensíveis, consulte Bibliotecas de cliente da Proteção de dados sensíveis.

Para autenticar na Proteção de dados sensíveis, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

// Imports the Google Cloud Data Loss Prevention library
const DLP = require('@google-cloud/dlp');

// Instantiates a client
const dlp = new DLP.DlpServiceClient();

// The project ID to run the API call under
// const projectId = 'my-project';

// The string to inspect
// const string = 'Patients MRN 444-5-22222';

// The regex pattern to match for
// const customRegex = '[1-9]{3}-[1-9]{1}-[1-9]{5}';

async function inspectWithCustomRegex() {
  // Construct item to inspect
  const item = {
    byteItem: {
      type: DLP.protos.google.privacy.dlp.v2.ByteContentItem.BytesType
        .TEXT_UTF8,
      data: Buffer.from(string, 'utf-8'),
    },
  };

  // Construct the custom regex detector.
  const customInfoTypes = [
    {
      infoType: {
        name: 'C_MRN',
      },
      likelihood: DLP.protos.google.privacy.dlp.v2.Likelihood.POSSIBLE,
      regex: {
        pattern: customRegex,
      },
    },
  ];

  // Construct request
  const request = {
    parent: `projects/${projectId}/locations/global`,
    inspectConfig: {
      customInfoTypes: customInfoTypes,
      includeQuote: true,
    },
    item: item,
  };

  // Run request
  const [response] = await dlp.inspectContent(request);
  const findings = response.result.findings;
  if (findings.length > 0) {
    console.log('Findings: \n');
    findings.forEach(finding => {
      console.log(`InfoType: ${finding.infoType.name}`);
      console.log(`\tQuote: ${finding.quote}`);
      console.log(`\tLikelihood: ${finding.likelihood} \n`);
    });
  } else {
    console.log('No findings.');
  }
}
inspectWithCustomRegex();

PHP

Para saber como instalar e usar a biblioteca de cliente da Proteção de dados sensíveis, consulte Bibliotecas de cliente da Proteção de dados sensíveis.

Para autenticar na Proteção de dados sensíveis, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

use Google\Cloud\Dlp\V2\Client\DlpServiceClient;
use Google\Cloud\Dlp\V2\ContentItem;
use Google\Cloud\Dlp\V2\CustomInfoType;
use Google\Cloud\Dlp\V2\CustomInfoType\Regex;
use Google\Cloud\Dlp\V2\InfoType;
use Google\Cloud\Dlp\V2\InspectConfig;
use Google\Cloud\Dlp\V2\InspectContentRequest;
use Google\Cloud\Dlp\V2\Likelihood;

/**
 * Inspect data with a custom regex
 * Regex example: Matching medical record numbers. The following sample uses a regular expression custom infoType detector that instructs Cloud DLP to match a medical record number (MRN) in the input text "Patient's MRN 444-5-22222," and then assigns each match a likelihood of POSSIBLE.
 *
 * @param string $projectId         The Google Cloud project id to use as a parent resource.
 * @param string $textToInspect     The string to inspect.
 */
function inspect_custom_regex(
    // TODO(developer): Replace sample parameters before running the code.
    string $projectId,
    string $textToInspect = 'Patients MRN 444-5-22222'
): void {
    // Instantiate a client.
    $dlp = new DlpServiceClient();

    $parent = "projects/$projectId/locations/global";

    // Specify what content you want the service to Inspect.
    $item = (new ContentItem())
        ->setValue($textToInspect);

    // Specify the regex pattern the inspection will look for.
    $customRegexPattern = '[1-9]{3}-[1-9]{1}-[1-9]{5}';

    // Construct the custom regex detector.
    $cMrnDetector = (new InfoType())
        ->setName('C_MRN');
    $customInfoType = (new CustomInfoType())
        ->setInfoType($cMrnDetector)
        ->setRegex((new Regex())
            ->setPattern($customRegexPattern))
        ->setLikelihood(Likelihood::POSSIBLE);

    // Construct the configuration for the Inspect request.
    $inspectConfig = (new InspectConfig())
        ->setCustomInfoTypes([$customInfoType])
        ->setIncludeQuote(true);

    // Run request
    $inspectContentRequest = (new InspectContentRequest())
        ->setParent($parent)
        ->setInspectConfig($inspectConfig)
        ->setItem($item);
    $response = $dlp->inspectContent($inspectContentRequest);

    // Print the results
    $findings = $response->getResult()->getFindings();
    if (count($findings) == 0) {
        printf('No findings.' . PHP_EOL);
    } else {
        printf('Findings:' . PHP_EOL);
        foreach ($findings as $finding) {
            printf('  Quote: %s' . PHP_EOL, $finding->getQuote());
            printf('  Info type: %s' . PHP_EOL, $finding->getInfoType()->getName());
            printf('  Likelihood: %s' . PHP_EOL, Likelihood::name($finding->getLikelihood()));
        }
    }
}

Python

Para saber como instalar e usar a biblioteca de cliente da Proteção de dados sensíveis, consulte Bibliotecas de cliente da Proteção de dados sensíveis.

Para autenticar na Proteção de dados sensíveis, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

import google.cloud.dlp


def inspect_data_with_custom_regex_detector(
    project: str,
    content_string: str,
) -> None:
    """Uses the Data Loss Prevention API to analyze string with medical record
       number custom regex detector

    Args:
        project: The Google Cloud project id to use as a parent resource.
        content_string: The string to inspect.

    Returns:
        None; the response from the API is printed to the terminal.
    """

    # Instantiate a client.
    dlp = google.cloud.dlp_v2.DlpServiceClient()

    # Construct a custom regex detector info type called "C_MRN",
    # with ###-#-##### pattern, where each # represents a digit from 1 to 9.
    # The detector has a detection likelihood of POSSIBLE.
    custom_info_types = [
        {
            "info_type": {"name": "C_MRN"},
            "regex": {"pattern": "[1-9]{3}-[1-9]{1}-[1-9]{5}"},
            "likelihood": google.cloud.dlp_v2.Likelihood.POSSIBLE,
        }
    ]

    # Construct the configuration dictionary with the custom regex info type.
    inspect_config = {
        "custom_info_types": custom_info_types,
        "include_quote": True,
    }

    # Construct the `item`.
    item = {"value": content_string}

    # Convert the project id into a full resource id.
    parent = f"projects/{project}"

    # Call the API.
    response = dlp.inspect_content(
        request={"parent": parent, "inspect_config": inspect_config, "item": item}
    )

    # Print out the results.
    if response.result.findings:
        for finding in response.result.findings:
            print(f"Quote: {finding.quote}")
            print(f"Info type: {finding.info_type.name}")
            print(f"Likelihood: {finding.likelihood}")
    else:
        print("No findings.")

REST

Consulte o Início rápido do JSON para ver mais informações sobre o uso da API DLP com o JSON.

Entrada JSON:

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

{
  "item":{
    "value":"Patients MRN 444-5-22222"
  },
  "inspectConfig":{
    "customInfoTypes":[
      {
        "infoType":{
          "name":"C_MRN"
        },
        "regex":{
          "pattern":"[1-9]{3}-[1-9]{1}-[1-9]{5}"
        },
        "likelihood":"POSSIBLE"
      }
    ]
  }
}

Saída JSON:

{
  "result":{
    "findings":[
      {
        "infoType":{
          "name":"C_MRN"
        },
        "likelihood":"POSSIBLE",
        "location":{
          "byteRange":{
            "start":"13",
            "end":"24"
          },
          "codepointRange":{
            "start":"13",
            "end":"24"
          }
        },
        "createTime":"2018-11-30T01:29:37.799Z"
      }
    ]
  }
}

Usando o detector de infoType personalizado com o nome C_MRN e seu regex personalizado, a Proteção de dados sensíveis identificou corretamente o número do registro médico e atribuiu a ele uma certeza POSSIBLE, conforme especificado.

Como personalizar a probabilidade de correspondência baseia-se neste exemplo para incluir palavras de contexto.