Best practices

This guide provides comprehensive best practices for using the Blocklist XStream adapter securely and effectively.

1. Prefer allowlist mode for new applications

1
2
// ✅ Good: Start with allowlist mode for new projects
XStream xstream = new BlocklistRestrictedXStream();
xstream.allowTypes(new Class<?>[] { 
    UserProfile.class,
    UserPreferences.class,
    Address.class 
});

Why: Provides maximum security from the start with no legacy constraints.

2. Minimize allowed types

1
2
// ✅ Good: Specific type allowlisting
XStream xstream = new BlocklistRestrictedXStream();
xstream.allowTypes(new Class<?>[] { 
    UserProfile.class,
    UserPreferences.class,
    Address.class 
});

// ❌ Bad: Overly broad allowlisting
xstream.allowTypeHierarchy(Object.class);

Why: Reduces attack surface and makes security reviews easier.

3. Avoid broad hierarchies when possible

1
2
// ✅ Good: Specific collection types
xstream.allowTypes(new Class<?>[] {
    ArrayList.class,
    HashMap.class,
    HashSet.class
});

// ⚠️ Acceptable but broader: Allow collection hierarchies
xstream.allowTypeHierarchy(Collection.class);
xstream.allowTypeHierarchy(Map.class);

// ❌ Bad: Too broad
xstream.allowTypeHierarchy(Object.class);

4. Document allowed types and rationale

1
2
public class XStreamSecurityConfig {
    
    // Document why each type is allowed
    private static final Class<?>[] CORE_BUSINESS_TYPES = {
        UserProfile.class,     // Core user data structure
        SessionData.class,     // Required for session persistence
        AuditLog.class        // Compliance requirement
    };
    
    public static void configureAllowlist(XStream xstream) {
        xstream.allowTypes(CORE_BUSINESS_TYPES);
        
        // Document business justification for hierarchies
        xstream.allowTypeHierarchy(Collection.class); // For user preference lists
        xstream.allowTypeHierarchy(Map.class);         // For configuration data
    }
}