0
# DefusedXML
1

2
A comprehensive Python library that provides XML bomb protection for Python's standard library XML processing modules. DefusedXML offers secure alternatives to xml.etree.ElementTree, xml.sax, xml.dom.minidom, xml.dom.pulldom, and xml.parsers.expat by disabling dangerous features like external entity processing, DTD processing, and entity expansion that can be exploited for billion laughs attacks, quadratic blowup attacks, and external entity attacks.
3

4
## Package Information
5

6
- **Package Name**: defusedxml
7
- **Language**: Python
8
- **Installation**: `pip install defusedxml`
9

10
## Core Imports
11

12
```python
13
import defusedxml
14
from defusedxml import DefusedXmlException, DTDForbidden, EntitiesForbidden, ExternalReferenceForbidden, NotSupportedError
15
```
16

17
Drop-in replacements for stdlib modules:
18

19
```python
20
import defusedxml.ElementTree as ET  # instead of xml.etree.ElementTree
21
import defusedxml.sax as sax         # instead of xml.sax
22
import defusedxml.minidom as minidom # instead of xml.dom.minidom
23
import defusedxml.pulldom as pulldom # instead of xml.dom.pulldom
24
```
25

26
**Deprecated modules** (avoid in new code):
27
```python
28
import defusedxml.cElementTree as cET  # DEPRECATED: use defusedxml.ElementTree instead
29
import defusedxml.lxml as lxml_defused # DEPRECATED: no longer supported, will be removed
30
```
31

32
## Basic Usage
33

34
```python
35
import defusedxml.ElementTree as ET
36

37
# Parse XML safely with default security restrictions
38
try:
39
    # Parse from file
40
    tree = ET.parse('document.xml')
41
    root = tree.getroot()
42
    
43
    # Parse from string
44
    xml_string = '<root><item>value</item></root>'
45
    root = ET.fromstring(xml_string)
46
    
47
    # Access elements normally
48
    for item in root.findall('item'):
49
        print(item.text)
50
        
51
except ET.ParseError as e:
52
    print(f"XML parsing error: {e}")
53
except defusedxml.DTDForbidden as e:
54
    print(f"DTD processing forbidden: {e}")
55
except defusedxml.EntitiesForbidden as e:
56
    print(f"Entity processing forbidden: {e}")
57
```
58

59
## Architecture
60

61
DefusedXML provides secure wrappers around Python's standard XML processing modules:
62

63
- **Core Security**: Common exception hierarchy and security parameter handling
64
- **Parser Wrappers**: Secure parsers that inherit from stdlib parsers but add security checks
65
- **Drop-in Replacements**: API-compatible modules that can replace stdlib imports
66
- **Configurable Security**: Three main security parameters control different attack vectors
67

68
The security model prevents XML-based attacks by:
69
- Blocking DTD processing (prevents external entity attacks and DTD processing attacks)
70
- Restricting entity expansion (prevents billion laughs and quadratic blowup attacks)
71
- Forbidding external references (prevents SSRF and local file access)
72

73
## Capabilities
74

75
### Exception Handling
76

77
Core exception classes for handling XML security violations and library-specific errors.
78

79
```python { .api }
80
class DefusedXmlException(ValueError):
81
    """Base exception for all defusedxml security violations"""
82

83
class DTDForbidden(DefusedXmlException):
84
    """Raised when DTD processing is attempted but forbidden"""
85

86
class EntitiesForbidden(DefusedXmlException):
87
    """Raised when entity processing is attempted but forbidden"""
88

89
class ExternalReferenceForbidden(DefusedXmlException):
90
    """Raised when external reference processing is attempted but forbidden"""
91

92
class NotSupportedError(DefusedXmlException):
93
    """Raised when an operation is not supported by the defused implementation"""
94
```
95

96
[Exception Handling](./exceptions.md)
97

98
### ElementTree Processing
99

100
Secure ElementTree-based XML parsing with configurable security restrictions, providing drop-in replacement for xml.etree.ElementTree with comprehensive protection against XML attacks.
101

102
```python { .api }
103
def parse(source, parser=None, forbid_dtd=False, forbid_entities=True, forbid_external=True): ...
104
def iterparse(source, events=None, parser=None, forbid_dtd=False, forbid_entities=True, forbid_external=True): ...
105
def fromstring(text, forbid_dtd=False, forbid_entities=True, forbid_external=True): ...
106
def XML(text, forbid_dtd=False, forbid_entities=True, forbid_external=True): ...
107

108
class DefusedXMLParser: ...
109
```
110

111
[ElementTree Processing](./elementtree.md)
112

113
### SAX Processing
114

115
Secure SAX-based XML parsing with event-driven processing and configurable security restrictions, providing drop-in replacement for xml.sax with protection against XML attacks.
116

117
```python { .api }
118
def parse(source, handler, errorHandler=None, forbid_dtd=False, forbid_entities=True, forbid_external=True): ...
119
def parseString(string, handler, errorHandler=None, forbid_dtd=False, forbid_entities=True, forbid_external=True): ...
120
def make_parser(parser_list=[]): ...
121

122
class DefusedExpatParser: ...
123
```
124

125
[SAX Processing](./sax.md)
126

127
### DOM Processing
128

129
Secure DOM-based XML parsing that builds complete document object models with configurable security restrictions, providing drop-in replacements for xml.dom.minidom and xml.dom.pulldom.
130

131
```python { .api }
132
# minidom functions
133
def parse(file, parser=None, bufsize=None, forbid_dtd=False, forbid_entities=True, forbid_external=True): ...
134
def parseString(string, parser=None, forbid_dtd=False, forbid_entities=True, forbid_external=True): ...
135

136
# pulldom functions  
137
def parse(stream_or_string, parser=None, bufsize=None, forbid_dtd=False, forbid_entities=True, forbid_external=True): ...
138
def parseString(string, parser=None, forbid_dtd=False, forbid_entities=True, forbid_external=True): ...
139
```
140

141
[DOM Processing](./dom.md)
142

143
### XML-RPC Protection
144

145
Secure XML-RPC client and server protection with gzip bomb prevention, providing defused parsers and decompression limits for XML-RPC communications.
146

147
```python { .api }
148
def monkey_patch(): ...
149
def unmonkey_patch(): ...
150
def defused_gzip_decode(data, limit=None): ...
151

152
class DefusedExpatParser: ...
153
class DefusedGzipDecodedResponse: ...
154
```
155

156
[XML-RPC Protection](./xmlrpc.md)
157

158
### System-wide Protection
159

160
Experimental system-wide XML protection by monkey-patching all standard library XML modules with defused alternatives.
161

162
```python { .api }
163
def defuse_stdlib(): ...
164
```
165

166
[System-wide Protection](./stdlib-patching.md)
167

168
## Security Parameters
169

170
All parsing functions accept these security configuration parameters:
171

172
- `forbid_dtd` (bool, default: False): Forbid DTD processing to prevent DTD-based attacks
173
- `forbid_entities` (bool, default: True): Forbid entity expansion to prevent billion laughs attacks  
174
- `forbid_external` (bool, default: True): Forbid external references to prevent SSRF and local file access
175

176
## Common Patterns
177

178
### Basic Secure Parsing
179
Use default security settings for maximum protection:
180

181
```python
182
import defusedxml.ElementTree as ET
183
root = ET.fromstring(xml_string)  # Uses secure defaults
184
```
185

186
### Custom Security Configuration
187
Adjust security parameters based on trust level:
188

189
```python
190
# Allow DTDs but keep other protections
191
root = ET.fromstring(xml_string, forbid_dtd=False)
192

193
# Allow entities for trusted content
194
root = ET.fromstring(trusted_xml, forbid_entities=False)
195
```
196

197
### Exception Handling
198
Handle security violations gracefully:
199

200
```python
201
try:
202
    root = ET.fromstring(untrusted_xml)
203
except defusedxml.DTDForbidden:
204
    # Handle DTD processing attempt
205
except defusedxml.EntitiesForbidden:
206
    # Handle entity expansion attempt
207
except defusedxml.ExternalReferenceForbidden:
208
    # Handle external reference attempt
209
```