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
```