Core Classes

BlocklistRestrictedXStream

Package: com.atlassian.security.serialblocklist.xstream

Description: A hardened XStream implementation that enforces Atlassian's serialization blocklist to prevent deserialization attacks.

Inheritance: BlocklistRestrictedXStream extends XStream

Constructors

1
2
public BlocklistRestrictedXStream()

Creates a new BlocklistRestrictedXStream instance in allowlist mode (default). Only explicitly allowed types can be processed.

1
2
public BlocklistRestrictedXStream(ReflectionProvider reflectionProvider)

Creates a new instance with a custom reflection provider.

Parameters:

• reflectionProvider - Custom reflection provider for object instantiation

1
2
public BlocklistRestrictedXStream(HierarchicalStreamDriver hierarchicalStreamDriver)

Creates a new instance with a custom stream driver.

Parameters:

• hierarchicalStreamDriver - Custom driver for reading/writing hierarchical streams

1
2
public BlocklistRestrictedXStream(ReflectionProvider reflectionProvider, 
                                  HierarchicalStreamDriver hierarchicalStreamDriver)

Creates a new instance with custom reflection provider and stream driver.

1
2
public BlocklistRestrictedXStream(ReflectionProvider reflectionProvider,
                                  Mapper mapper,
                                  HierarchicalStreamDriver hierarchicalStreamDriver)

Creates a new instance with custom reflection provider, mapper, and stream driver.

1
2
public BlocklistRestrictedXStream(ReflectionProvider reflectionProvider,
                                  HierarchicalStreamDriver hierarchicalStreamDriver,
                                  ClassLoaderReference classLoaderReference)

Creates a new instance with custom reflection provider, stream driver, and class loader reference.

Security Mode Configuration

1
2
public void addPermission(TypePermission permission)

Adds a type permission. Use AnyTypePermission.ANY to enable blocklist mode.

Parameters:

• permission - The permission to add

Example:

1
2
// Enable blocklist mode
xstream.addPermission(AnyTypePermission.ANY);

Type Allowlisting Methods

1
2
public void allowTypes(Class<?>[] types)

Explicitly allows the specified types for serialization/deserialization.

Parameters:

• types - Array of classes to allow

Throws:

• IllegalArgumentException - If any type is on the security blocklist

Example:

1
2
xstream.allowTypes(new Class<?>[] { UserProfile.class, Config.class });

1
2
public void allowTypes(String[] typeNames)

Allows types by their class names. Unknown classes are ignored, but blocklisted classes will cause an exception.

Parameters:

• typeNames - Array of fully qualified class names

Throws:

• IllegalArgumentException - If any resolvable type is on the security blocklist

1
2
public void allowTypeHierarchy(Class<?> type)

Allows a type and all its subtypes/implementations.

Parameters:

• type - The base type to allow (including subtypes)

Throws:

• IllegalArgumentException - If the type is on the security blocklist

Example:

1
2
xstream.allowTypeHierarchy(Collection.class); // Allows List, Set, etc.

Blocked Methods

The following XStream methods are intentionally blocked for security:

1
2
public void allowTypesByWildcard(String[] patterns)

Status: ❌ BLOCKED - Throws UnsupportedOperationException

1
2
public void allowTypesByRegExp(String[] regexps)

Status: ❌ BLOCKED - Throws UnsupportedOperationException

1
2
public void allowTypesByRegExp(Pattern[] regexps)

Status: ❌ BLOCKED - Throws UnsupportedOperationException

Converter Registration

1
2
public void registerConverter(Converter converter, int priority)

Registers a converter with the specified priority.

Parameters:

• converter - The converter to register
• priority - Priority level (must be < blocklist converter priority)

Throws:

• IllegalArgumentException - If priority >= blocklist converter priority

1
2
public void registerLocalConverter(Class<?> definedIn, String fieldName, Converter converter)

Registers a field-specific converter. The converter is automatically wrapped with blocklist checking.

Parameters:

• definedIn - The class containing the field
• fieldName - The field name
• converter - The converter for the field

Usage Examples

Basic Configuration

1
2
// Allowlist mode (recommended)
XStream xstream = new BlocklistRestrictedXStream();
xstream.allowTypes(new Class<?>[] { MyClass.class });

// Blocklist mode (migration)
XStream xstream = new BlocklistRestrictedXStream();
xstream.addPermission(AnyTypePermission.ANY);

Advanced Configuration

1
2
// Custom driver with security
XStream xstream = new BlocklistRestrictedXStream(new DomDriver());
xstream.allowTypeHierarchy(Collection.class);

// Custom converter registration
xstream.registerConverter(new MyConverter(), XStream.PRIORITY_NORMAL);

// Local field converter (automatically wrapped)
xstream.registerLocalConverter(MyClass.class, "field", new MyFieldConverter());

Error Handling

1
2
try {
    /// setting up xstream and xml input
    Object result = xstream.fromXML(xml);
} catch (ForbiddenClassException e) {
    // Blocklisted class encountered
    logger.warn("Security violation: {}", e.getMessage());
} catch (IllegalArgumentException e) {
    // Configuration error
    logger.error("Configuration error: {}", e.getMessage());
}