Content Security Policy
Mango supports Content Security Policies (CSP) for improved security. CSP is an added layer of security that helps detect and mitigate certain types of attacks, including cross-site scripting (XSS) and data injection attacks. These attacks are used for everything from data theft to site defacement and malware distribution. CSP works by instructing the browser which sources of content it should trust and load.
Overview
CSP is configured through the mango.properties file and applies as HTTP response headers that the browser enforces. When CSP is enabled, the browser rejects content from sources not explicitly permitted by the policy.
There are two CSP contexts in Mango:
- Modern UI (HTML5): The AngularJS-based user interface.
- Legacy UI: The older Dojo-based user interface.
Both are disabled by default and can be configured independently.
Configuration Properties
CSP settings are defined in mango.properties under the web.security.contentSecurityPolicy prefix:
# Enable CSP (disabled by default)
web.security.contentSecurityPolicy.enabled=false
# Report-only mode (logs violations without blocking)
web.security.contentSecurityPolicy.reportOnly=false
# Default source for all content types
web.security.contentSecurityPolicy.defaultSrc='self'
# JavaScript source restrictions
web.security.contentSecurityPolicy.scriptSrc='self' 'unsafe-eval' https://maps.google.com https://maps.googleapis.com https://www.google-analytics.com
# CSS source restrictions
web.security.contentSecurityPolicy.styleSrc='self' 'unsafe-inline' https://fonts.googleapis.com
# Fetch/AJAX/WebSocket source restrictions
web.security.contentSecurityPolicy.connectSrc='self' ws: wss:
# Image source restrictions
web.security.contentSecurityPolicy.imgSrc='self' data: https://maps.google.com https://maps.gstatic.com https://www.google-analytics.com
# Font source restrictions
web.security.contentSecurityPolicy.fontSrc='self' https://fonts.gstatic.com
# Media source restrictions
web.security.contentSecurityPolicy.mediaSrc=
# Plugin source restrictions (Flash, Java applets, etc.)
web.security.contentSecurityPolicy.objectSrc=
# iframe source restrictions
web.security.contentSecurityPolicy.frameSrc=
# Web worker source restrictions
web.security.contentSecurityPolicy.workerSrc=
# Manifest source restrictions
web.security.contentSecurityPolicy.manifestSrc=
# Additional directives not covered above
web.security.contentSecurityPolicy.other=
Understanding the Default Policy
The default CSP configuration includes several directives that are required for Mango's UI to function properly:
Modern UI Requirements
| Directive | Value | Reason |
|---|---|---|
style-src 'unsafe-inline' | Required | AngularJS Material uses inline styles for dynamic theming. |
script-src 'unsafe-eval' | Required | Fabric.js (used by amCharts for chart annotations) requires eval(). Also provides AngularJS a 30% performance improvement. |
connect-src ws: wss: | Required | The 'self' directive does not permit WebSocket connections on the same origin. For production, restrict this to your server's actual hostname. |
img-src data: | Required | Allows small base64-encoded images to be embedded inline in HTML. |
Optional Third-Party Integrations
| Directive | Value | Integration |
|---|---|---|
script-src https://cdnjs.cloudflare.com | Optional | Allows AngularJS to load locale files from the internet. |
img-src/script-src https://www.google-analytics.com | Optional | Enables Google Analytics tracking. |
img-src/script-src https://maps.google.com https://maps.googleapis.com https://maps.gstatic.com | Optional | Enables the Google Maps component in dashboards. |
style-src/font-src https://fonts.googleapis.com https://fonts.gstatic.com | Optional | Enables Google Fonts in dashboards. |
Legacy UI Requirements
The legacy UI has its own set of requirements:
| Directive | Value | Reason |
|---|---|---|
script-src 'unsafe-inline' | Required | Inline scripts are used extensively in the legacy UI. |
script-src 'unsafe-eval' | Required | The Dojo JavaScript library uses eval(). |
style-src 'unsafe-inline' | Required | Inline styles are used throughout the legacy UI. |
connect-src ws: wss: | Required | WebSocket connections for real-time updates. |
img-src data: | Required | Base64-encoded inline images. |
Enabling CSP
Step 1: Enable in Report-Only Mode
Start by enabling CSP in report-only mode to identify any violations without breaking functionality:
web.security.contentSecurityPolicy.enabled=true
web.security.contentSecurityPolicy.reportOnly=true
In report-only mode, the browser logs CSP violations to the developer console but does not block the content. This allows you to identify and fix any issues before enforcing the policy.
Step 2: Review Violations
Open the browser developer console (F12) and monitor for CSP violation reports. Common violations include:
- Custom dashboard pages loading external resources.
- Third-party modules injecting inline scripts.
- Custom pages using Google Maps or other external services without the corresponding CSP directive.
Step 3: Adjust the Policy
Add any additional sources needed by your specific deployment. For example, if you use a custom mapping service:
web.security.contentSecurityPolicy.imgSrc='self' data: https://your-map-service.com
web.security.contentSecurityPolicy.scriptSrc='self' 'unsafe-eval' https://your-map-service.com
Step 4: Enforce the Policy
Once you are confident the policy is correct, switch from report-only to enforcement mode:
web.security.contentSecurityPolicy.reportOnly=false
Restart Mango for the changes to take effect.
X-Frame-Options
In addition to CSP, Mango supports the X-Frame-Options header to control whether the application can be embedded in iframes:
# Options: SAMEORIGIN, DENY, ANY, or a specific domain
web.security.iFrameAccess=SAMEORIGIN
| Value | Behavior |
|---|---|
SAMEORIGIN | Only allow embedding in iframes when the parent page is from the same domain. |
DENY | Do not allow embedding in iframes at all. |
ANY | Do not send the X-Frame-Options header (allows embedding from any domain). |
| A domain name | Sends ALLOW-FROM http://domain.com to allow embedding from a specific domain. |
Best Practices
- Start with report-only mode: Always test your CSP in report-only mode before enforcing it to avoid breaking functionality.
- Restrict WebSocket sources: Replace
ws: wss:with your specific server hostname (e.g.,wss://mango.example.com) for tighter security. - Avoid
'unsafe-inline'for scripts when possible: The modern UI requires'unsafe-eval'but not'unsafe-inline'for scripts, which is a better security posture than the legacy UI. - Keep policies as restrictive as possible: Only add sources that are actually needed by your deployment.
- Review policies after module changes: Installing new Mango modules may introduce additional resource requirements that need to be reflected in the CSP.
Troubleshooting
| Problem | Cause | Solution |
|---|---|---|
| External images or scripts are blocked | The domain serving the resource is not listed in the appropriate CSP directive | Add the domain to the relevant directive in mango.properties. For images, add to imgSrc; for scripts, add to scriptSrc. For example: web.security.contentSecurityPolicy.imgSrc='self' data: https://your-image-host.com. Restart Mango after the change. |
| Dashboard components not loading after enabling CSP | The components require resources from domains not covered by the current policy | Open the browser developer console (F12) and look for CSP violation messages. Each message identifies the blocked resource and the directive that blocked it. Add the required domain to the corresponding directive. Use reportOnly=true first to find all violations without breaking functionality. |
| iFrame embedding blocked -- Mango cannot be embedded in another site | The X-Frame-Options header is set to SAMEORIGIN or DENY | Change the web.security.iFrameAccess property in mango.properties to the domain that needs to embed Mango (e.g., web.security.iFrameAccess=https://portal.example.com) or set it to ANY to allow embedding from all domains. Setting it to ANY removes the header entirely, which may reduce security. |
| Google Maps component not displaying in dashboards | The Maps API domains are not in the CSP script and image directives | Add https://maps.google.com, https://maps.googleapis.com, and https://maps.gstatic.com to both scriptSrc and imgSrc directives. See the default configuration in the "Optional Third-Party Integrations" section above. |
| CSP enabled but no violations are reported | CSP is in enforcement mode but reportOnly is not set, so violations are blocked silently | Switch to reportOnly=true temporarily and open the browser console to see violation reports. Once you have identified and fixed all violations, switch back to enforcement mode. |
Related Pages
- Mango Properties Reference — All CSP properties are configured under
web.security.contentSecurityPolicy.* - Linux Security — Additional server-level security measures for production deployments
- Rate Limiting — Protect the REST API against denial-of-service attacks
- Reverse Proxy Configuration — CSP considerations when running behind a reverse proxy