Microsoft's best practices for building custom visuals in PowerBI
Power BI enables developers to build their own custom visuals, and to visualize their business metrics the way they want them to be.
As a developer of custom visuals, you need to be aware of the security implications and take steps to make sure your visuals are as secure as possible.
Here are a few of the common web-based threats you should be aware of:
- Data leakage
- XSS attack
- Session hijack
- Malicious infected files
Power BI infrastructure and iframe sandboxing, along with today's browsers security, blocks most malicious attacks, but there are several precautions you can take to increase security even more.
Before building a custom visual, you should consider the quality and popularity of packages and libraries you want to utilize.
Although there’s no strict policy about importing 3rd party vendor's libraries, we still review all packages before approving them.
There could be many security issues for an unknown package, so it’s worthwhile to use Microsoft's recommended packages, such as D3, for creating graphics and charts, or Bootstrap if you want a modern CSS look and feel.
To install external libraries onto a custom visual, please visit the following link for more information:
Before publishing a custom visual, we recommend reviewing the resources it includes.
Following the guidance in the following sections will help keep your visual as safe as possible:
- Do not use local resources that might disclose private information about you, your organization, or anything that's not specifically related to the Power BI visual.
- Try not to keep TODO tasks as comments inside the code, these can be viewed when debugging the visual at any point from the browser.
- Do not accept user input as a resource. For example, if you provide a set of colors to choose from, make sure to provide an element with hardcoded values, or values that came from your resource file. Do not let the user type the name of the color as a free text. Although programmatically this is possible, it requires a more robust input validation so it won't be bypassed, possibly causing a Code Injection or an XSS
When running a custom visual, inspect the network requests it sends and gets.
We recommend that developers keep control of their visuals’ network traffic and any external resources they consume.
PowerBI contains each custom visual in a secure sandbox of its own,
This structure provides the necessary data isolation on the client side from one visual to another.
Read more about sandbox attribute.
Linting helps developers align with the best developing practices, security practices and syntax standards.
Microsoft's recommended linting rule sets are the following:
The following commands install the necessary packages to properly lint your code”
npm install tslint --save-dev
npm install typings --save-dev
npm install tslint-microsoft-contrib --save-dev
tslint --init ( if tslint.json does not exist already )
TypeScript is a programming language developed by Microsoft.
Even though it restricts the base code to types and classes, using TypeScript does not mean the code is safe from vulnerabilities.
XSS attacks are possible if using a string that is not parsed correctly.
Here are some rules you should keep in mind:
- Never trust user input or data
- Encode everything
- Keep data and markup separated
- Use DOM properties manipulation like setAttribute(), getAttribute() , .attr(), .append(element), etc'.
Read more about element properties.
More about TypeScript.
Parsing user input
If you want to add content to an element inside a visual please use the proper DOM API for it, for example: .append, .setAttribute, element.TextContext, element.text, etc....
We recommend using the D3 library, since D3 was tested and is very popular, it is safer to set and get user input with.
When you use the D3 and the DOM API correctly, there is no need to perform vast input escaping - the browser API makes sure user input resides between the text apostrophes, rendered as text and not as HTML Markup, eliminating the risk of code injection and XSS attacks.
Examples how to use D3 in a custom visual are found in the following location:
In addition, you may want to check the latest OWASP recommendations.
XSS Prevention Rules Summary
The following HTML snippets demonstrate how to safely render untrusted data in a variety of different contexts.
Data Type Context Code Sample Defense
|String||HTML Body||<span>UNTRUSTED DATA</span>|
|String||Safe HTML Attributes||<input type="text" name="fname" value="UNTRUSTED DATA">|
- Aggressive HTML Entity Encoding
- Only place untrusted data into a whitelist of safe attributes (listed below).
- Strictly validate unsafe attributes such as background, id and name.
|String||GET Parameter||<a href="/site/search?value=UNTRUSTED DATA">clickme</a>|
|String||Untrusted URL in a SRC or HREF attribute||<a href="UNTRUSTED URL">clickme</a>|
<iframe src="UNTRUSTED URL" />
|String||CSS Value||<div style="width: UNTRUSTED DATA;">Selection</div>|
- Avoid backslash encoding (\" or \' or \\)
|HTML||HTML Body||<div>UNTRUSTED HTML</div>|
|String||DOM XSS||<script>document.write("UNTRUSTED INPUT: " + document.location.hash);<script/>|
OWASP XSS CHEATSHEET
When developing a visual on your local workstation, developers sometimes test it with our own files, which usually contains some data, which you may not always want to expose or publish.
In custom visuals there are several sections to check, in terms of ensuring security, before releasing a custom visual.
- Do not include private files or folders such as node_modules, dist, all temp folders
- Check files signature - verify no private information is contained in your files (images, text files)
- Do not keep private configuration files on the git repository. (use .gitignore)
- Do not push temporary or redundant files to the git repository - only the files that the visual is using ( what pbiviz new creates for you + optional sample data for project )
- Make sure sample data is free of private company data.
Packages, Resources, HTTP Requests, Sandboxing, Linting, TypeScript, Parsing user input, and Privacy
Custom visuals provide a perfect platform to share your data visualization within, or out of your company, but make sure you keep the data & information safe on your side.
It is highly recommended to go through all the sections described in this document so you can harden your visuals before releasing them.
Power BI Custom visuals