Managing Content Security Policy

Content Security Policy (CSP) is an essential layer of protection that helps safeguard your Hudu environment from unauthorized or potentially harmful external content. By controlling which sources of content are allowed to load within your instance, CSP plays a major role in defense against cross-site scripting (XSS), code injection, and other web-based security threats.

Hudu includes default CSP settings that balance security with compatibility. These defaults ensure that the majority of common content types will function safely without additional configuration. However, administrators may occasionally need to allow custom sources, for example, to embed external media, integrate third-party tools, or support unique workflows.

What CSP Controls in Hudu

Hudu’s CSP configuration governs which external content types can be loaded or embedded within your instance. Administrators can adjust allowed sources for different categories.

Customizing Allowed Content Sources

Administrators can enhance Hudu’s default security policy by adding trusted sources to specific content types. This allows you to expand functionality while keeping strong security in place.

• Embed training videos from external platforms

• Use self-hosted assets such as fonts, scripts, or internal tools

To customize allowed content sources, navigate to Admin > Security, where you can enable or disable CSPs for the following categories:

• Frame

• Media

• Style

• Script

For each category, you can add additional trusted sources that you want to permit within your Hudu environment.

Important Note About Disabling CSP

While customization is recommended when needed, disabling a CSP entirely is strongly discouraged. When a CSP is disabled:

• There are no restrictions on the content sources that can be loaded within Hudu.

• Any script, iFrame, or external media—trusted or not—may be embedded or executed.

• Your exposure to XSS attacks, malicious scripts, and unsafe third-party content significantly increases.

In short, disabling CSP removes a major security safeguard. It should only be considered in exceptional situations and with full understanding of the associated risks.

For Self-Hosted Instances: How .env Settings Interact With the Content Policy UI

If your self-hosted instance previously used environment variables such as WHITELISTED_FRAME_SRC, WHITELIST_MEDIA_SRC, or DISABLE_FRAME_CSP to manage CSP behavior, those variables still work. The Content Policy UI does not replace them, it layers on top of them.

A few things to keep in mind

The Content Policy page is only seeded from .env on first creation or first visit. Editing .env afterward does not rewrite what's shown in the UI, but your .env defaults still apply at runtime.

If your instance already relies on .env for iframe or CSP sources, you can keep using it. There's no need to migrate.

For one-off or occasional additions, we recommend using Admin Security Content Policy directly. Reserve .env for sources you intend to keep long-term or manage as part of your deployment configuration.

Best Practices for Admins

To keep your Hudu instance secure while maintaining functionality:

• Rely on Defaults Whenever Possible
  • Hudu’s default CSP configuration is designed to be secure and broadly compatible.
• Add, Don’t Remove
  • If additional content is needed, add that specific source rather than weakening or disabling the entire policy.
• Validate Trusted Sources
  • Only allow URLs or domains from vendors and services you trust completely.
• Test Changes Before Wide Use
  • After modifying CSP settings, verify that the affected content loads correctly without exposing the system to unnecessary risk.
• Avoid Disabling CSP
  • Consider disabling policies only as a last resort. If disabling is necessary, ensure it is temporary and that compensating security measures are in place.