Skip to main content
Help us improve Python packaging – donate today!

XML bomb protection with modified expat parser

Project Description

============
defusedexpat
============


.. contents:: Table of Contents
:depth: 2

defusedexpat protects the XML packages of Python's standard library from
several denial of service vulnerabilities and external entity exploits. It
contains

* a modified and enhanced version of expat parser library

* replacements for pyexpat and cElementTree's _elementtree extension modules

* loader code that replaces built-in extensions with the modified extensions

* monkey patches for xml.sax and xml.dom to prevent external entity expansions

In order to protect your application you have to import the ``defusedxml``
module **before** any of the stdlib's XML modules.


Countermeasures
===============

* limited entity expansion level to antagonize billion laugh attacks

* limited total length of expansions to prevent quadratic blowups

* monkey patch to prevent retrieval of external entities and DTDs


Modifications
=============

Modifications in pyexpat
------------------------

Parser object
..............

New parser attributes (r/w)

* max_entity_indirections
* max_entity_expansions
* reset_dtd


Module constants
................

* XML_DEFAULT_MAX_ENTITY_INDIRECTIONS
* XML_DEFAULT_MAX_ENTITY_EXPANSIONS
* XML_BOMB_PROTECTION


Modules functions
..................

* get_reset_dtd(), set_reset_dtd(bool)
* get_max_entity_expansions(), set_max_entity_expansions(int)
* get_max_entity_indirections(), et_max_entity_indirections(int)


New CAPI members
................

* capi.GetFeature
* capi.SetFeature
* capi.GetFeatureDefault
* capi.SetFeatureDefault


Modifications in _elementtree
-----------------------------

_elementtree.XMLParser
.......................

New arguments and r/o attributes

* max_entity_indirections
* max_entity_expansions
* ignore_dtd


Modifications in expat
----------------------

new definitions::

XML_BOMB_PROTECTION
XML_DEFAULT_MAX_ENTITY_INDIRECTIONS
XML_DEFAULT_MAX_ENTITY_EXPANSIONS
XML_DEFAULT_RESET_DTD

new XML_FeatureEnum members::

XML_FEATURE_MAX_ENTITY_INDIRECTIONS
XML_FEATURE_MAX_ENTITY_EXPANSIONS
XML_FEATURE_IGNORE_DTD

new XML_Error members::

XML_ERROR_ENTITY_INDIRECTIONS
XML_ERROR_ENTITY_EXPANSION

new API functions::

int XML_GetFeature(XML_Parser parser,
enum XML_FeatureEnum feature,
long *value);
int XML_SetFeature(XML_Parser parser,
enum XML_FeatureEnum feature,
long value);
int XML_GetFeatureDefault(enum XML_FeatureEnum feature,
long *value);
int XML_SetFeatureDefault(enum XML_FeatureEnum feature,
long value);

XML_FEATURE_MAX_ENTITY_INDIRECTIONS
Limit the amount of indirections that are allowed to occur during the
expansion of a nested entity. A counter starts when an entity reference
is encountered. It resets after the entity is fully expanded. The limit
protects the parser against exponential entity expansion attacks (aka
billion laughs attack). When the limit is exceeded the parser stops and
fails with `XML_ERROR_ENTITY_INDIRECTIONS`.
A value of 0 disables the protection.

Supported range
0 .. UINT_MAX
Default
40

XML_FEATURE_MAX_ENTITY_EXPANSIONS
Limit the total length of all entity expansions throughout the entire
document. The lengths of all entities are accumulated in a parser variable.
The setting protects against quadratic blowup attacks (lots of expansions
of a large entity declaration). When the sum of all entities exceeds
the limit, the parser stops and fails with `XML_ERROR_ENTITY_EXPANSION`.
A value of 0 disables the protection.

Supported range
0 .. UINT_MAX
Default
8 MiB

XML_FEATURE_RESET_DTD
Reset all DTD information after the <!DOCTYPE> block has been parsed. When
the flag is set (default: false) all DTD information after the
endDoctypeDeclHandler has been called. The flag can be set inside the
endDoctypeDeclHandler. Without DTD information any entity reference in
the document body leads to `XML_ERROR_UNDEFINED_ENTITY`.

Supported range
0, 1
Default
0


Requirements
============

* Python 2.6.6 or newer (2.6.8 or newer for randomized hashing)
* Python 2.7 (2.7.3 or newer for randomized hashing and Windows binaries)
* Python 3.1 (3.1.5 or newer for randomized hashing and Windows binaries)
* Python 3.2 (3.2.3 or newer for randomized hashing and Windows binaries)
* Python 3.3.0 or newer

Windows binaries are compatible to 2.6.6, 2.7.3, 3.1.5, 3.2.3 or 3.3.0 or
newer micro releases. They don't work on older versions.


License
=======

Copyright (c) 2013 by Christian Heimes <christian@python.org>

Licensed to PSF under a Contributor Agreement.

See http://www.python.org/psf/license for licensing details.


Contributors
============

Antoine Pitrou
code review

Brett Cannon
code review

Changelog
=========

defusedexpat 0.4
----------------

*Release date: 25-Feb-2013*

- Make code source compatible to Python versions without hash randomization.
- Include latest version of expat patch


defusedexpat 0.3
----------------

*Release date: 19-Feb-2013*

- Disable some tests on Windows because proxy trick doesn't work
- Remove 'bomb protection' suffix from CAPI MAGIC
- Don't support additional kwargs in _elementtree when XML_BOMB_PROTECTION
is not available.
- Implement better and more flexibel get/set feature API in expat
- Add module functions to set global settings


defusedexpat 0.2
----------------

*Release date: 15-Feb-2013*

- Python 3.1 support
- Misc fixes and improvements


defusedexpat 0.1
----------------

*Release date: 11-Feb-2013*

- Initial and internal release for PSRT review

Release history Release notifications

This version
History Node

0.4

History Node

0.3

History Node

0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
defusedexpat-0.4.tar.gz (259.3 kB) Copy SHA256 hash SHA256 Source None Feb 25, 2013
defusedexpat-0.4.win32-py2.6.exe (281.6 kB) Copy SHA256 hash SHA256 Windows Installer 2.6 Feb 25, 2013
defusedexpat-0.4.win32-py2.7.exe (282.5 kB) Copy SHA256 hash SHA256 Windows Installer 2.7 Feb 25, 2013
defusedexpat-0.4.win32-py3.2.exe (284.0 kB) Copy SHA256 hash SHA256 Windows Installer 3.2 Feb 25, 2013
defusedexpat-0.4.win32-py3.3.exe (284.2 kB) Copy SHA256 hash SHA256 Windows Installer 3.3 Feb 25, 2013
defusedexpat-0.4.win-amd64-py2.6.exe (320.7 kB) Copy SHA256 hash SHA256 Windows Installer 2.6 Feb 25, 2013
defusedexpat-0.4.win-amd64-py2.7.exe (322.1 kB) Copy SHA256 hash SHA256 Windows Installer 2.7 Feb 25, 2013
defusedexpat-0.4.win-amd64-py3.2.exe (324.1 kB) Copy SHA256 hash SHA256 Windows Installer 3.2 Feb 25, 2013
defusedexpat-0.4.win-amd64-py3.3.exe (324.4 kB) Copy SHA256 hash SHA256 Windows Installer 3.3 Feb 25, 2013
defusedexpat-0.4.zip (275.9 kB) Copy SHA256 hash SHA256 Source None Feb 25, 2013

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page