Security Classes

BlocklistConverter

Package: com.atlassian.security.serialblocklist.xstream

Description: A high-priority converter that blocks serialization/deserialization of dangerous classes.

Implements: Converter

Constructor

1
2
public BlocklistConverter(Predicate<Class<?>> blocklist)

Creates a new blocklist converter.

Parameters:

• blocklist - Predicate returning true for allowed classes, false for blocked classes

Methods

1
2
public void marshal(Object o, HierarchicalStreamWriter writer, MarshallingContext context)

Always throws ForbiddenClassException - marshalling is forbidden for blocklisted types.

Parameters:

• o - The object to marshal
• writer - The hierarchical stream writer
• context - The marshalling context

Throws:

• ForbiddenClassException - Always, indicating the class is blocked

1
2
public Object unmarshal(HierarchicalStreamReader reader, UnmarshallingContext context)

Always throws ForbiddenClassException - unmarshalling is forbidden for blocklisted types.

Parameters:

• reader - The hierarchical stream reader
• context - The unmarshalling context

Returns: Never returns normally

Throws:

• ForbiddenClassException - Always, indicating the class is blocked

1
2
public boolean canConvert(Class<?> type)

Returns true if the type is blocklisted (and thus this converter should handle it).

Parameters:

• type - The class to check

Returns: true if the class is blocklisted and should be blocked

Protected Methods

1
2
protected boolean isBlocked(Class<?> clazz)

Checks if a class is blocklisted.

Parameters:

• clazz - The class to check

Returns: true if the class is blocked

1
2
protected Class<?> checkClass(Class<?> clazz)

Validates a class against the blocklist.

Parameters:

• clazz - The class to validate

Returns: The class if allowed

Throws:

• ForbiddenClassException - If the class is blocked

BlocklistConverterWrapper

Package: com.atlassian.security.serialblocklist.xstream

Description: Wraps another converter to add blocklist checking before delegation.

Extends: BlocklistConverter

Constructor

1
2
public BlocklistConverterWrapper(Predicate<Class<?>> blocklist, Converter wrapped)

Creates a wrapper around another converter.

Parameters:

• blocklist - Predicate for blocklist checking
• wrapped - The converter to wrap and delegate to

Methods

1
2
public void marshal(Object o, HierarchicalStreamWriter writer, MarshallingContext context)

Checks the object's class against the blocklist, then delegates to the wrapped converter.

Parameters:

• o - The object to marshal
• writer - The hierarchical stream writer
• context - The marshalling context

Throws:

• ForbiddenClassException - If the class is blocklisted

Behavior: If the class passes blocklist validation, delegates to the wrapped converter's marshal method.

1
2
public Object unmarshal(HierarchicalStreamReader reader, UnmarshallingContext context)

Checks the required type against the blocklist, then delegates to the wrapped converter.

Parameters:

• reader - The hierarchical stream reader
• context - The unmarshalling context

Returns: The unmarshalled object from the wrapped converter

Throws:

• ForbiddenClassException - If the required type is blocklisted

Behavior: If the type passes blocklist validation, delegates to the wrapped converter's unmarshal method.

1
2
public boolean canConvert(Class<?> type)

Determines whether the wrapped converter can handle the given class.

Parameters:

• type - The class to check

Returns: true if the wrapped converter can handle the class

Note: This method does not perform a blocklist check; it simply delegates to the wrapped converter.

Constants and Configuration

Priority Constants

The priority level used for the blocklist converter. User converters cannot use this priority or higher.

Value: 100,000 (10 times XStream's PRIORITY_VERY_HIGH)

Purpose: Ensures the blocklist converter always runs before any user-registered converter.

Exception Types

ForbiddenClassException

Package: com.thoughtworks.xstream.security

Description: Thrown when attempting to process a blocklisted class

Inheritance: Extends XStreamException

When thrown:

• During marshalling of a blocklisted object
• During unmarshalling of a blocklisted type
• When explicitly attempting to allow a blocklisted class

IllegalArgumentException

Scenarios:

• Attempting to register converter with priority >= blocklist priority
• Attempting to explicitly allow a blocklisted class
• Invalid configuration parameters

Example:

1
2
// This will throw IllegalArgumentException
xstream.registerConverter(myConverter, BLOCKLIST_CONVERTER_PRIORITY);

// This will also throw IllegalArgumentException
xstream.allowTypes(new Class<?>[] { ProcessBuilder.class });

UnsupportedOperationException

Scenarios:

• Calling blocked methods like allowTypesByWildcard()
• Attempting to use regex-based type allowlisting

Example:

1
2
// This will throw UnsupportedOperationException
xstream.allowTypesByWildcard(new String[] { "com.dangerous.**" });

Implementation Details

Security Architecture

The security classes work together to provide layered protection:

1. BlocklistConverter: High-priority converter that intercepts and blocks dangerous classes
2. BlocklistConverterWrapper: Wraps existing converters to add blocklist checking
3. Priority System: Ensures security converters always run first

Usage in BlocklistRestrictedXStream

These security classes are automatically configured when using BlocklistRestrictedXStream:

1
2
// Automatic setup - no manual configuration needed
XStream xstream = new BlocklistRestrictedXStream();

// BlocklistConverter is automatically registered at high priority
// Local converters are automatically wrapped with BlocklistConverterWrapper
xstream.registerLocalConverter(MyClass.class, "field", new MyConverter());

Advanced Usage

Custom Security Predicates

1
2
// Create custom blocklist predicate
Predicate<Class<?>> customBlocklist = clazz -> {
    // Custom logic to determine if class is allowed
    return !clazz.getName().startsWith("com.dangerous.");
};

// Use with custom converter
BlocklistConverter customConverter = new BlocklistConverter(customBlocklist);
xstream.registerConverter(customConverter, XStream.PRIORITY_VERY_HIGH);

Wrapping Existing Converters

1
2
// Wrap an existing converter with blocklist checking
Converter existingConverter = new MyExistingConverter();
Predicate<Class<?>> blocklist = BlocklistConfigurator.getBlocklistPredicate();
BlocklistConverterWrapper secureConverter = 
    new BlocklistConverterWrapper(blocklist, existingConverter);

xstream.registerConverter(secureConverter, XStream.PRIORITY_NORMAL);