FileUploadAndDownloadSecuritySettings in SFDX

Architectural Overview#

FileUploadAndDownloadSecuritySettings is a critical security governance metadata type that regulates how Salesforce handles uploaded files, document attachments, and browser downloads. In enterprise Salesforce deployments, users, automated integrations, and external Experience Cloud community members upload millions of files annually. Unrestricted file handling introduces severe threat vectors—including Cross-Site Scripting (XSS), ransomware distribution, and malware execution.

This metadata type allows enterprise security architects to enforce defense-in-depth file security policies. Administrators can mandate explicit dispositions for specific file extensions: blocking high-risk executable binaries entirely (BLOCKED), forcing safe local downloads without in-browser rendering (DOWNLOAD), or permitting controlled browser execution (EXECUTE_IN_BROWSER) only for trusted formats.

Managing this configuration in version control guarantees that all scratch orgs, sandboxes, and production orgs strictly comply with corporate cybersecurity standards and SOC2/ISO-27001 compliance frameworks.

Directory and File Conventions#

FileUploadAndDownloadSecuritySettings follows standard Salesforce DX settings conventions in the settings directory:

Key Metadata Fields#

The FileUploadAndDownloadSecuritySettings XML schema defines file disposition rules and upload safeguards:

Each entry in dispositions contains:

• fileExtension: The target file extension (e.g., html, pdf, exe).
• behavior: Security disposition (DOWNLOAD, EXECUTE_IN_BROWSER, or HYBRID).

Declarative XML and Package Manifest Examples#

Below is a declarative XML definition of FileUploadAndDownloadSecurity.settings-meta.xml configured according to enterprise security best practices:

<?xml version="1.0" encoding="UTF-8"?>
<FileUploadAndDownloadSecuritySettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <dispositions>
        <behavior>DOWNLOAD</behavior>
        <fileExtension>html</fileExtension>
    </dispositions>
    <dispositions>
        <behavior>DOWNLOAD</behavior>
        <fileExtension>htm</fileExtension>
    </dispositions>
    <dispositions>
        <behavior>DOWNLOAD</behavior>
        <fileExtension>svg</fileExtension>
    </dispositions>
    <dispositions>
        <behavior>EXECUTE_IN_BROWSER</behavior>
        <fileExtension>pdf</fileExtension>
    </dispositions>
    <noHtmlUploadAsAttachment>true</noHtmlUploadAsAttachment>
</FileUploadAndDownloadSecuritySettings>

Scratch Org Configuration (project-scratch-def.json)#

{
  "orgName": "Security Hardened Dev Org",
  "edition": "Enterprise",
  "settings": {
    "fileUploadAndDownloadSecuritySettings": {
      "noHtmlUploadAsAttachment": true
    }
  }
}

Package Manifest (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>FileUploadAndDownloadSecurity</members>
        <name>Settings</name>
    </types>
    <version>68.0</version>
</Package>

CLI Retrieval and Deployment Commands#

Manage file security settings with the Salesforce CLI:

# Retrieve file security settings from the target org
sf project retrieve start --metadata Settings:FileUploadAndDownloadSecurity

# Deploy file security settings to production
sf project deploy start --metadata Settings:FileUploadAndDownloadSecurity

# Preview file security settings deployment
sf project deploy preview --metadata Settings:FileUploadAndDownloadSecurity

Architect Best Practices and Gotchas#

• Preventing Stored XSS via HTML/SVG: Files with extensions like .html, .htm, and .svg can contain executable JavaScript. Always configure these extensions to DOWNLOAD rather than EXECUTE_IN_BROWSER to prevent malicious scripts from accessing session tokens or DOM objects.
• Email Attachment Hardening: Always set noHtmlUploadAsAttachment to true. This prevents social engineering attacks where malicious actors upload weaponized HTML attachments to outbound customer service emails.
• Third-Party Antivirus Pairing: While FileUploadAndDownloadSecuritySettings enforces browser execution boundaries, it does not scan file payloads for binary viruses. Combine this setting with a certified Salesforce AppExchange antivirus integration or AWS Lambda ICAP scanner.

Frequently asked questions

What security policies are governed by FileUploadAndDownloadSecuritySettings?

It governs file extension upload restrictions, forced download vs browser execution behaviors, and HTML file handling to prevent XSS attacks.

Why should HTML files be set to Download instead of Execute in Browser?

Forcing download prevents malicious scripts inside uploaded HTML files from executing in the context of the user authenticated Salesforce session.

How does FileUploadAndDownloadSecuritySettings prevent ransomware propagation?

Administrators can block high-risk executable extensions such as exe, bat, and vbs from ever being uploaded to Salesforce record attachments.

Where is FileUploadAndDownloadSecuritySettings located in an SFDX repo?

It is located in force-app/main/default/settings/FileUploadAndDownloadSecurity.settings-meta.xml.