0
# Deanonymization
1

2
The DeanonymizeEngine reverses anonymization operations when using reversible operators like encryption. It takes anonymized text and the original anonymization metadata to restore the original content.
3

4
## Capabilities
5

6
### Text Deanonymization
7

8
Main deanonymization method that reverses anonymization operations using operator metadata.
9

10
```python { .api }
11
def deanonymize(
12
    self,
13
    text: str,
14
    entities: List[OperatorResult],
15
    operators: Dict[str, OperatorConfig]
16
) -> EngineResult:
17
    """
18
    Deanonymize text that was previously anonymized.
19

20
    Parameters:
21
    - text (str): The anonymized text to restore
22
    - entities (List[OperatorResult]): Metadata from original anonymization
23
    - operators (Dict[str, OperatorConfig]): Configuration for deanonymization operators
24

25
    Returns:
26
    EngineResult: Contains restored text and metadata about transformations
27
    """
28
```
29

30
**Usage Example:**
31

32
```python
33
from presidio_anonymizer import AnonymizerEngine, DeanonymizeEngine
34
from presidio_anonymizer.entities import RecognizerResult, OperatorConfig
35

36
# First, anonymize with reversible operators
37
anonymizer = AnonymizerEngine()
38
original_text = "My credit card is 4111-1111-1111-1111"
39
analyzer_results = [RecognizerResult("CREDIT_CARD", 18, 37, 0.9)]
40

41
# Use encryption for reversible anonymization
42
encrypt_config = OperatorConfig("encrypt", {"key": "my-secret-key-32-characters-long12"})
43
anonymize_result = anonymizer.anonymize(
44
    text=original_text,
45
    analyzer_results=analyzer_results,
46
    operators={"CREDIT_CARD": encrypt_config}
47
)
48

49
print(f"Anonymized: {anonymize_result.text}")
50

51
# Now deanonymize
52
deanonymizer = DeanonymizeEngine()
53
decrypt_config = OperatorConfig("decrypt", {"key": "my-secret-key-32-characters-long12"})
54

55
deanonymize_result = deanonymizer.deanonymize(
56
    text=anonymize_result.text,
57
    entities=anonymize_result.items,  # Use original anonymization metadata
58
    operators={"CREDIT_CARD": decrypt_config}
59
)
60

61
print(f"Restored: {deanonymize_result.text}")  # Original text restored
62
```
63

64
### Deanonymizer Management
65

66
Add or remove custom deanonymization operators at runtime.
67

68
```python { .api }
69
def add_deanonymizer(self, deanonymizer_cls: Type[Operator]) -> None:
70
    """
71
    Add a new deanonymizer to the engine.
72

73
    Parameters:
74
    - deanonymizer_cls (Type[Operator]): The deanonymizer class to add
75
    """
76

77
def remove_deanonymizer(self, deanonymizer_cls: Type[Operator]) -> None:
78
    """
79
    Remove a deanonymizer from the engine.
80

81
    Parameters:
82
    - deanonymizer_cls (Type[Operator]): The deanonymizer class to remove
83
    """
84
```
85

86
**Usage Example:**
87

88
```python
89
from presidio_anonymizer.operators import Operator
90

91
class CustomDecrypter(Operator):
92
    def operate(self, text, params):
93
        # Custom decryption logic
94
        return decrypt_with_custom_algorithm(text, params.get("key"))
95

96
deanonymizer = DeanonymizeEngine()
97
deanonymizer.add_deanonymizer(CustomDecrypter)
98
```
99

100
### Available Deanonymizers
101

102
Get list of all available deanonymization operators.
103

104
```python { .api }
105
def get_deanonymizers(self) -> List[str]:
106
    """
107
    Return a list of supported deanonymizers.
108

109
    Returns:
110
    List[str]: Names of available deanonymizer operators
111
    """
112
```
113

114
**Usage Example:**
115

116
```python
117
deanonymizer = DeanonymizeEngine()
118
available = deanonymizer.get_deanonymizers()
119
print(available)  # ['decrypt', 'deanonymize_keep']
120
```
121

122
## Reversible Operators
123

124
Only certain operators support deanonymization:
125

126
### Encrypt/Decrypt
127

128
Uses AES encryption with a secret key to enable full restoration.
129

130
```python
131
# Anonymization
132
encrypt_config = OperatorConfig("encrypt", {
133
    "key": "my-secret-key-32-characters-long12"
134
})
135

136
# Deanonymization  
137
decrypt_config = OperatorConfig("decrypt", {
138
    "key": "my-secret-key-32-characters-long12"  # Must match
139
})
140
```
141

142
### Keep/DeanonymizeKeep
143

144
Keeps text unchanged during both anonymization and deanonymization.
145

146
```python
147
# Both operations use keep
148
keep_config = OperatorConfig("keep")
149
deanonymize_keep_config = OperatorConfig("deanonymize_keep")
150
```
151

152
## Workflow Pattern
153

154
1. **Anonymize** with reversible operators, save the `EngineResult.items`
155
2. **Store** the anonymization metadata (`items`) for later use
156
3. **Deanonymize** using the anonymized text, metadata, and matching operators
157

158
```python
159
# Step 1: Anonymize and save metadata
160
anonymize_result = anonymizer.anonymize(text, analyzer_results, operators)
161
anonymized_text = anonymize_result.text
162
anonymization_metadata = anonymize_result.items  # Save this!
163

164
# Step 2: Later, restore original text
165
deanonymize_result = deanonymizer.deanonymize(
166
    text=anonymized_text,
167
    entities=anonymization_metadata,  # Use saved metadata
168
    operators=deanonymize_operators
169
)
170
original_text = deanonymize_result.text
171
```
172

173
## Limitations
174

175
- **Irreversible Operators**: Replace, mask, redact, and hash cannot be deanonymized
176
- **Key Management**: Encryption keys must be securely stored and matched exactly
177
- **Metadata Required**: Original anonymization metadata (OperatorResult list) is required
178
- **Operator Consistency**: Deanonymization operators must match anonymization operators