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 estes:

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, defina um objeto CustomInfoType que contenha 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 vão retornar 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.

  Os escores de sensibilidade são usados em perfis de dados. Ao criar o perfil dos seus dados, a Proteção de Dados Sensíveis usa as pontuações de sensibilidade dos infoTypes para calcular o nível de confidencialidade.

• 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 existente no campo storedType do objeto CustomInfoType, em vez de definir o campo regex. No entanto, essa abordagem exige que você crie primeiro uma 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 corresponder um número de registro médico (MRN) no texto de entrada "MRN do paciente 444-5-22222" e atribuir uma probabilidade de POSSIBLE a cada correspondência.

C#

Para saber como instalar e usar a biblioteca de cliente para a Proteção de dados sensíveis, consulte Bibliotecas de cliente para a 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 para a Proteção de dados sensíveis, consulte Bibliotecas de cliente para a 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 para a Proteção de dados sensíveis, consulte Bibliotecas de cliente para a 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 para a Proteção de dados sensíveis, consulte Bibliotecas de cliente para a 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 para a Proteção de dados sensíveis, consulte Bibliotecas de cliente para a 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 para a Proteção de dados sensíveis, consulte Bibliotecas de cliente para a 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"
      }
    ]
  }
}

A saída mostra que, usando o detector de infoType personalizado com o nome C_MRN e o 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.