Merge pull request #123 from GreenmaskIO/feat/ip-transformer

Feat/ip transformer

docs/built_in_transformers/standard_transformers/index.md

@@ -31,8 +31,7 @@ Standard transformers are ready-to-use methods that require no customization and
 1. [RandomMacAddress](random_mac_address.md) — generates a random MAC address.
 1. [RandomDomainName](random_domain_name.md) — generates a random domain name.
 1. [RandomURL](random_url.md) — generates a random URL.
-1. [RandomIPv4](random_ipv4.md) — generates a random IPv4 address.
-1. [RandomIPv6](random_ipv6.md) — generates a random IPv6 address.
+1. [RandomIP](random_ip.md) — generates a random IPv4 or IPv6 addresses.
 1. [RandomWord](random_word.md) — generates a random word.
 1. [RandomSentence](random_sentence.md) — generates a random sentence.
 1. [RandomParagraph](random_paragraph.md) — generates a random paragraph.

docs/built_in_transformers/standard_transformers/random_ip.md

@@ -0,0 +1,75 @@
+The `RandomIp` transformer is designed to populate specified database columns with random IP v4 or V6 addresses. 
+This utility is essential for applications requiring the simulation of network data, testing systems that utilize IP 
+addresses, or anonymizing real IP addresses in datasets.
+
+## Parameters
+
+| Name      | Description                                        | Default  | Required | Supported DB types  |
+|-----------|----------------------------------------------------|----------|----------|---------------------|
+| column    | The name of the column to be affected              |          | Yes      | text, varchar, inet |
+| subnet | Subnet for generating random ip in V4 or V6 format | `false`  | No       | -                   |
+| engine | The engine used for generating the values [random, hash]. Use hash for deterministic generation | `random`         |No          |-                    |
+
+## Dynamic parameters
+
+| Name       | Supported types     |
+|------------|---------------------|
+| subnet     | cidr, text, varchar |
+
+## Description
+
+Utilizing a robust algorithm or library for generating IP addresses, the `RandomIp` transformer injects random IPv4 
+or IPv6 addresses into the designated database column, depending on the provided subnet. The transformer automatically 
+detects whether to generate an IPv4 or IPv6 address based on the subnet version specified.
+
+
+## Example: Generate a Random IPv4 Address for a 192.168.1.0/24 Subnet
+
+This example demonstrates how to configure the RandomIp transformer to inject a random IPv4 address into the 
+ip_address column for entries in the `192.168.1.0/24` subnet:
+
+```sql title="Create table ip_networks and insert data"
+CREATE TABLE ip_networks
+(
+    id         SERIAL PRIMARY KEY,
+    ip_address INET,
+    network    CIDR
+);
+
+INSERT INTO ip_networks (ip_address, network)
+VALUES ('192.168.1.10', '192.168.1.0/24'),
+       ('10.0.0.5', '10.0.0.0/16'),
+       ('172.16.254.3', '172.16.0.0/12'),
+       ('192.168.100.14', '192.168.100.0/24'),
+       ('2001:0db8:85a3:0000:0000:8a2e:0370:7334', '2001:0db8:85a3::/64'); -- An IPv6 address and network
+
+```
+
+```yaml title="RandomPerson transformer example"
+- schema: public
+  name: ip_networks
+  transformers:
+    - name: "RandomIp"
+      params: 
+        subnet: "192.168.1.0/24"
+        column: "ip_address"
+        engine: "random"
+```
+
+## Example: Generate a Random IP Based on the Dynamic Subnet Parameter
+
+This configuration illustrates how to use the RandomIp transformer dynamically, where it reads the subnet information 
+from the network column of the database and generates a corresponding random IP address:
+
+```yaml title="RandomPerson transformer example with dynamic mode"
+- schema: public
+  name: ip_networks
+  transformers:
+    - name: "RandomIp"
+      params:
+        column: "ip_address"
+        engine: "random"
+      dynamic_params:
+        subnet:
+          column: "network"
+```

internal/db/postgres/transformers/random_ip.go

@@ -0,0 +1,158 @@
+// Copyright 2023 Greenmask
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package transformers
+
+import (
+	"context"
+	"fmt"
+	"net"
+
+	"github.com/greenmaskio/greenmask/internal/db/postgres/transformers/utils"
+	"github.com/greenmaskio/greenmask/internal/generators/transformers"
+	"github.com/greenmaskio/greenmask/pkg/toolkit"
+)
+
+var RandomIpDefinition = utils.NewTransformerDefinition(
+	utils.NewTransformerProperties("RandomIp", "Generate V4 or V6 IP in the provided subnet"),
+
+	NewIpTransformer,
+
+	toolkit.MustNewParameterDefinition(
+		"column",
+		"Column name",
+	).SetIsColumn(toolkit.NewColumnProperties().
+		SetAffected(true).
+		SetAllowedColumnTypes("text", "varchar", "inet"),
+	).SetRequired(true),
+
+	toolkit.MustNewParameterDefinition(
+		"subnet",
+		"Subnet for generating random ip in V4 or V6 format",
+	).SetRequired(true).
+		SetCastDbType("cidr").
+		SetDynamicMode(
+			toolkit.NewDynamicModeProperties().
+				SetCompatibleTypes("cidr", "text", "varchar"),
+		),
+
+	engineParameterDefinition,
+)
+
+type RandomIp struct {
+	columnName      string
+	affectedColumns map[int]string
+	columnIdx       int
+	dynamicMode     bool
+	t               *transformers.IpAddress
+	subnetParam     toolkit.Parameterizer
+}
+
+func NewIpTransformer(ctx context.Context, driver *toolkit.Driver, parameters map[string]toolkit.Parameterizer) (utils.Transformer, toolkit.ValidationWarnings, error) {
+
+	subnetParam := parameters["subnet"]
+
+	var columnName, engine string
+	var subnet *net.IPNet
+	var dynamicMode bool
+	p := parameters["column"]
+	if err := p.Scan(&columnName); err != nil {
+		return nil, nil, fmt.Errorf(`unable to scan "column" param: %w`, err)
+	}
+
+	idx, _, ok := driver.GetColumnByName(columnName)
+	if !ok {
+		return nil, nil, fmt.Errorf("column with name %s is not found", columnName)
+	}
+	affectedColumns := make(map[int]string)
+	affectedColumns[idx] = columnName
+
+	p = parameters["engine"]
+	if err := p.Scan(&engine); err != nil {
+		return nil, nil, fmt.Errorf(`unable to scan "engine" param: %w`, err)
+	}
+
+	if subnetParam.IsDynamic() {
+		dynamicMode = true
+	} else {
+		subnet = &net.IPNet{}
+		if err := subnetParam.Scan(subnet); err != nil {
+			return nil, nil, fmt.Errorf(`unable to scan "subnet" param: %w`, err)
+		}
+	}
+
+	t, err := transformers.NewIpAddress(subnet)
+	if err != nil {
+		return nil, nil, fmt.Errorf("unable to create ip transformer: %w", err)
+	}
+	g, err := getGenerateEngine(ctx, engine, t.GetRequiredGeneratorByteLength())
+	if err != nil {
+		return nil, nil, fmt.Errorf("unable to get generator: %w", err)
+	}
+	if err = t.SetGenerator(g); err != nil {
+		return nil, nil, fmt.Errorf("unable to set generator: %w", err)
+	}
+
+	return &RandomIp{
+		columnName:      columnName,
+		affectedColumns: affectedColumns,
+		columnIdx:       idx,
+		t:               t,
+		subnetParam:     subnetParam,
+		dynamicMode:     dynamicMode,
+	}, nil, nil
+}
+
+func (rbt *RandomIp) GetAffectedColumns() map[int]string {
+	return rbt.affectedColumns
+}
+
+func (rbt *RandomIp) Init(ctx context.Context) error {
+	return nil
+}
+
+func (rbt *RandomIp) Done(ctx context.Context) error {
+	return nil
+}
+
+func (rbt *RandomIp) Transform(ctx context.Context, r *toolkit.Record) (*toolkit.Record, error) {
+
+	val, err := r.GetRawColumnValueByIdx(rbt.columnIdx)
+	if err != nil {
+		return nil, fmt.Errorf("unable to scan value: %w", err)
+	}
+
+	var subnet *net.IPNet
+	if rbt.dynamicMode {
+		subnet = &net.IPNet{}
+		if err = rbt.subnetParam.Scan(subnet); err != nil {
+			return nil, fmt.Errorf(`unable to scan "subnet" param: %w`, err)
+		}
+	}
+
+	ipVal, err := rbt.t.Generate(val.Data, subnet)
+	if err != nil {
+		return nil, fmt.Errorf("unable to transform value: %w", err)
+	}
+
+	newRawValue := toolkit.NewRawValue([]byte(ipVal.String()), false)
+	if err = r.SetRawColumnValueByIdx(rbt.columnIdx, newRawValue); err != nil {
+		return nil, fmt.Errorf("unable to set new value: %w", err)
+	}
+	return r, nil
+}
+
+func init() {
+	utils.DefaultTransformerRegistry.MustRegister(RandomIpDefinition)
+}

internal/db/postgres/transformers/random_ip_test.go

@@ -0,0 +1,77 @@
+package transformers
+
+import (
+	"context"
+	"github.com/greenmaskio/greenmask/internal/db/postgres/transformers/utils"
+	"github.com/greenmaskio/greenmask/pkg/toolkit"
+	"github.com/stretchr/testify/require"
+	"testing"
+)
+
+func TestRandomIpTransformer_Transform_random_dynamic(t *testing.T) {
+
+	tests := []struct {
+		name          string
+		columnName    string
+		params        map[string]toolkit.ParamsValue
+		dynamicParams map[string]*toolkit.DynamicParamValue
+		record        map[string]*toolkit.RawValue
+		expected      string
+	}{
+		{
+			name:       "IPv4 dynamic test",
+			columnName: "data",
+			record: map[string]*toolkit.RawValue{
+				"data":  toolkit.NewRawValue([]byte("192.168.1.10"), false),
+				"data2": toolkit.NewRawValue([]byte("192.168.1.0/30"), false),
+			},
+			params: map[string]toolkit.ParamsValue{
+				"engine": toolkit.ParamsValue("random"),
+			},
+			dynamicParams: map[string]*toolkit.DynamicParamValue{
+				"subnet": {
+					Column: "data2",
+				},
+			},
+			expected: "192.168.1.[1,2]",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+
+			driver, record := toolkit.GetDriverAndRecord(tt.record)
+
+			tt.params["column"] = toolkit.ParamsValue(tt.columnName)
+			def, ok := utils.DefaultTransformerRegistry.Get("RandomIp")
+			require.True(t, ok)
+
+			transformer, warnings, err := def.Instance(
+				context.Background(),
+				driver,
+				tt.params,
+				tt.dynamicParams,
+			)
+			require.NoError(t, err)
+			require.Empty(t, warnings)
+
+			err = transformer.Transformer.Init(context.Background())
+			require.NoError(t, err)
+
+			for _, dp := range transformer.DynamicParameters {
+				dp.SetRecord(record)
+			}
+
+			r, err := transformer.Transformer.Transform(
+				context.Background(),
+				record,
+			)
+			require.NoError(t, err)
+
+			rawVal, err := r.GetRawColumnValueByName(tt.columnName)
+			require.NoError(t, err)
+			require.False(t, rawVal.IsNull)
+			require.Regexp(t, tt.expected, string(rawVal.Data))
+		})
+	}
+}