Configuration JSON object

The Obfusware configuration JSON object declares properties that manage the operation of the Obfusware software. Obfusware requires a minimum of 1 JSON configuration object to operate but allows multiple JSON configuration objects to supplement the initial configuration. The configuration JSON defines 5 distinct property groups.

1. Configuration meta data
2. Obfusware license information
3. Statistics configuration
4. Data Masker configuration
5. Masking Schema configuration

Configuration meta-data [required]

The meta-data is composed of 2 properties.

1. The name property
   Defines the name of the configuration. The name is used to differentiate between JSON configuration objects, which can be useful when discussing configuration issues. The name property is also used when logging about configuration issues.

   • name: name
   • type: string
   • required
   • default: <null>

2. The description property
   Describes the configuration object providing information such as its purpose. The description property does not effect Obfusware operation and is purely informational for Obfusware administrators or operators.

   • name: description
   • type: string
   • optional
   • default: <null>

Example meta-data JSON properties

    "name": "Configuration Name",
    "description": "Description of the configuration",

Obfusware license information [optional]

The Obfusware license is contained in a file. The license property group indicated the full path to the license file using the license property.

• name: license
• type: string (filepath)
• required
• default: "s3://obfusware-<aws-account-number>-<aws-region>/<version>/obfusware-license.lic"

Example license JSON property

    "license": "s3://obfusware-obfusware-381492123456-us-east-1/3.0/obfusware-license.lic",

Statistics configuration [optional]

The statistics configuration group defines the collection and reporting of statistical information about Obfusware masking jobs. The statistics configuration is defined by a statistics JSON object with 3 properties.

1. The sample property
   Obfusware statistics are gathered by sampling the results of masking operations. The sample property defines the rate of sampling. A sample is taken every <sample-property> times a masking operation occurs. For example: If the property is sample: 1, then every single (i.e. 1) masking operation is sampled. If the property is sample: 5, then every 5th (i.e. 1) operation is sampled. Statistics sampling execution is overhead for each masking operations, so limiting the sampling rate can have a postive impact of performance, but the statistics operations are very efficient, so in the normal couse of events their overall impact is negligible.

   • name: sample
   • type: number
   • optional
   • default: 1

2. The abortFailureRate property
   One important statistic is the failure rate of masking operations. Masking operations will generally not fail unless there is an issue with data types, representations, or formats. For large masking jobs, it is a potential waste of time and money to let the job continue if there are significant errors. The abortFailureRate property defines the failure rate which will trigger an abort of the masking job. If the failure rate exceeds the value of the abortFailureRate property, the masking job is aborted.

   • name: abortFailureRate
   • type: number (percentage)
   • optional
   • default: 100

3. The logReport property
   At the completion of an Obfusware masking job, a statistical report is logged. The logReport property controls the logging of the report. If the property is false, then the report is not logged.

   • name: logReport
   • type: boolean
   • optional
   • default: true

Example Statistics JSON properties

    "statistics": {
        "sample": 1,
        "abortFailureRate": 100,
        "logReport": true
    },

Data Masker configuration [optional]

The data masker configuration group defines a maskingObjects JSON list of data maskers object configurations (See: Data Masker Configuration Properties ). Obfusware has a default set of data maskers pre-defined (See Default Maskers ). These data maskers do not need to be configured. If a data masker is defined with the same name as a default

Example Data Masker JSON list property

    "maskingObjects": [
        {
            "name": "US555TelephoneMasker",
			"algorithm": "USTelephone",
			"description": "Generates a new telephone number, replacing the exchange with '555' and the final digits with a new sequence of digits",
			"maskExchange": "DISCRETE",
			"exchangeDiscrete": "555",
			"maskExtension": "NONE"
        },
        {
            "name": "USLastNameMasker",
			"algorithm": "HashList",
			"description": "Replaces original string data with a realistic, culturally USA, last name",
			"trimWhiteSpace": true,
			"csvFile": "obfusware/maskingdata/us-addresses.csv",
			"index": 1
        }
    ]

Masking Schema configuration [optional]

The masking schema configuration group defines a maskingSchema JSON object. The maskingSchema object contains 1 or more table masking schemas. A table masking schema is a list of column masking objects. A Column masking object has 3 properties.

Table Masking Schema property [required]

A table masking schema property consists of a table name and a list of column masking objects.

        "tablename": [
            *\<column masking object1\>*,
            *\<column masking object2\>*,
            ...
            *\<column masking object1n\>*
        ]

DEFAULT table name

The DEFAULT table name is used when there is not a defined table with a name. For example, If a simple standalone file, such as a csv file, is being masked.

Column Masking object

The column masking object has 3 properties: a column in the table to mask, a key column to be used when masking, and a data masker to mask the column.

1. The column property
   The name of the column to be masked.

   • name: column
   • type: string
   • required
   • default: <null>

2. The keyColumn property
   The name of the column to be used as the key when the column is masked.

   • name: keyColumn
   • type: string
   • optional
   • default: <null>

3. The maskerName property
   The name of the masker to be used to mask the selected column.

   • name: maskerName
   • type: string
   • required
   • default: <null>

Example Masking Schema JSON property

    "maskingSchema": {
        "DEFAULT": [
            {
                "column": "last_name",
                "keyColumn": "phone1",
                "maskerName": "USLastNameMasker"
            },
            {
                "column": "phone1",
                "maskerName": "US555TelephoneMasker"
            }
        ],
        "Contact": [
            {
                "column": "full_name",
                "maskerName": "USFullNameMasker"
            },
            {
                "column": "phone",
                "maskerName": "US555TelephoneMasker"
            }
            {
                "column": "email",
                "maskerName": "EmailMasker"
            }
        ]
    }

Example Obfusware Configuration JSON

An example of a configuration JSON with all 5 property groups populated.

{
    "name": "Configuration Name",
    "description": "Description of the configuration name",
    "license": "s3://obfusware-obfusware-381492123456-us-east-1/3.0/obfusware-license.lic",
    "statistics": {
        "sample": 1,
        "abortFailureRate": 100,
        "logReport": true
    },
    "maskingObjects": [
        {
            "name": "US555TelephoneMasker",
			"algorithm": "USTelephone",
			"description": "Generates a new telephone number, replacing the exchange with '555' and the final digits with a new sequence of digits",
			"maskExchange": "DISCRETE",
			"exchangeDiscrete": "555",
			"maskExtension": "NONE"
        },
        {
            "name": "USLastNameMasker",
			"algorithm": "HashList",
			"description": "Replaces original string data with a realistic, culturally USA, last name",
			"trimWhiteSpace": true,
			"csvFile": "obfusware/maskingdata/us-addresses.csv",
			"index": 1
        }
    ],
    "maskingSchema": {
        "DEFAULT": [
            {
                "column": "last_name",
                "keyColumn": "phone1",
                "maskerName": "USLastNameMasker"
            },
            {
                "column": "phone1",
                "maskerName": "US555TelephoneMasker"
            }
        ]
        "Contact": [
            {
                "column": "full_name",
                "maskerName": "USFullNameMasker"
            },
            {
                "column": "phone",
                "maskerName": "US555TelephoneMasker"
            }
            {
                "column": "email",
                "maskerName": "EmailMasker"
            }
        ]
    }
}