How to enable loopback and troubleshoot network isolation (Windows Runtime apps)

  • Article

This topic explains the how to enable loopback for network access and how to troubleshoot network isolation issues in Windows 8 for a Windows Store app.

What you need to know

Technologies

Prerequisites

  • The following information applies to any connected or network-aware Windows Runtime app that needs to make network connections. This affects apps written in JavaScript. This also affects apps written using the .NET Framework 4.5 in C#, VB.NET, and C++.

Diagnostic tool for network isolation

A built in diagnostic tool, CheckNetIsolation.exe, is provided to help developers test, diagnose and troubleshoot an app that requires network capabilities. CheckNetIsolation.exe is a command line tool that takes input parameters from the command line. It has two main options:

  • LoopbackExempt
    View a list of installed apps that are exempt from IP loopback restrictions and allowed access to loopback addresses. This option also allows adding access to IP loopback addresses for a specific app when testing.

  • Debug
    Determines the enabled capabilities that are used by an app and any enabled capabilities that are unused. Any enabled capabilities that are not used make the app less secure. This option can also provides information on network traffic that was dropped, which may have been unintentional.

CheckNetIsolation.exe can display a help message with usage information. To display help, use the example command below.

CheckNetIsolation -?

Some CheckNetIsolation.exe options require the app name or the app ID be provided. Once an app is deployed on a target computer, the app name can be found under the c:\Program Files\Applications folder. This is the name used to start the app. This is the package family name displayed when using Microsoft Visual Studio 2013 and represents the App Container. The app ID can be found in the registry under the following key:

HKEY_CURRENT_USER\Software\Classes\Local Settings\Software\Microsoft\Windows\CurrentVersion\AppContainer

Enable loopback for network access

Network communications using an IP loopback address cannot be used for interprocess communication (between two different apps) in a Windows Runtime app since this is restricted by network isolation. Network communication using an IP loopback address is allowed within an app within the same process for communication purposes.

A developer may want to use loopback for testing or debugging purposes, even though that capability will not be available for customers. For example, an app may want to download data from a web service from a Windows Runtime app. For development purposes, the developer wants to test the app on a single computer that is configured with the web service locally on 127.0.0.1.

Note  Loopback is permitted only for development purposes. Usage by a Windows Runtime app installed outside of Visual Studio is not permitted. Further, a Windows Runtime app can use an IP loopback only as the target address for a client network request. So a Windows Runtime app that uses a DatagramSocket or StreamSocketListener to listen on an IP loopback address is prevented from receiving any incoming packets.

 

To enable access to loopback addresses, a developer must configure network isolation to exempt the app from loopback restrictions. For packets to be received by a network service, the listener on a TCP or UDP port also needs to be allowed by firewall rules.

Apps installed and run in Visual Studio will automatically be registered as being exempt from the loopback restrictions. A developer can view the list of exempt apps by running the following command:

CheckNetIsolation.exe LoopbackExempt -s

A developer can also use the CheckNetIsolation.exe tool to manually add loopback exemptions for an app.

To exempt an app from loopback restrictions, the app ID for the package must be provided. The example command below exempts an app from loopback restrictions.

CheckNetIsolation.exe LoopbackExempt –a –p=S-1-15-2-4125766819-3228448775-2449327860-2490758337-1264241865-3581724871-2122349299

The exemption from loopback restrictions can also be removed for a specific app. The example command below removes the loopback exemption for the same app.

CheckNetIsolation.exe LoopbackExempt –d –p=S-1-15-2-4125766819-3228448775-2449327860-2490758337-1264241865-3581724871-2122349299

The CheckNetIsolation.exe tool also allows a developer to exempt an app from these loopback restrictions based on the name of the App Container. The example command below exempts an app from loopback restrictions by App Container name:

CheckNetIsolation.exe LoopbackExempt –a –n=stocks_mw26f2swbd5nr

The exemption from loopback restrictions can also be removed for an app written using the .NET Framework from these loopback restrictions based on the name of the app container. The example command below removes the loopback exemption for the same app.

CheckNetIsolation.exe LoopbackExempt –d –n=stocks_mw26f2swbd5nr

The exemption from loopback restrictions can also be removed for all apps installed. The example command below removes the loopback exemption for all apps installed on the local computer.

CheckNetIsolation.exe LoopbackExempt –c

Debug network isolation issues

The debug option is used to generate a report of network capabilities that are used by an app.

The debug option provides a way to identify if an app is using all the capabilities that are declared in the app manifest. When the debug option is used, the system is instructed to track which of the declared capabilities the app is using and which declared capabilities are not used.

To use the debug option, first deploy the app to the target computer and determine the app ID and app name. A CMD window must then be opened with elevated privileges (run as Administrator). The example command below sets debug option for a specific app ID.

CheckNetIsolation.exe Debug –p=S-1-15-2-4125766819-3228448775-2449327860-2490758337-1264241865-3581724871-2122349299

The example command below sets debug option for an app based on the name of the App Container.

CheckNetIsolation.exe Debug –n=stocks_mw26f2swbd5nr

Once the Debug option is set, launch the app from an elevated CMD window. You should execute, and test the app for operations that the app will perform. Hit Ctrl-C when the testing is done and while the app is still running. A summary report is displayed in the CMD window that lists network capabilities status with an entry for each capability indicating if the capability was declared and whether the capability was used. When unneeded capabilities were declared, the summary report will indicate that a capability was unused (the summary report calls this Not Used and Insecure). A detailed traffic report also lists the source and destination IP address used for network access.

The following text displays the output for an app that enables the excessive capabilities.

Network Isolation Debug Session started.
Reproduce your scenario, then hit Ctrl-C when done.

Summary Report

Network Capabilities Status
----------------------------------------------------------------------
    InternetClient                Not Used and Insecure
    InternetClientServer          Not Used and Insecure
    PrivateNetworkClientServer    Used and Declared


Detailed Traffic Report
----------------------------------------------------------------------

    InternetClient                Not Used and Insecure

----------------------------------------------------------------------

    InternetClientServer          Not Used and Insecure

----------------------------------------------------------------------

    PrivateNetworkClientServer    Used and Declared

------------------------------------------------------------------
       10.195.58.77    10.195.58.78

The following text displays the output for an app that enables the appropriate capabilities.

Network Isolation Debug Session started.
Reproduce your scenario, then hit Ctrl-C when done.

Summary Report

Network Capabilities Status
----------------------------------------------------------------------
    PrivateNetworkClientServer    Used and Declared


Detailed Traffic Report
----------------------------------------------------------------------

    PrivateNetworkClientServer    Used and Declared

------------------------------------------------------------------
       10.195.58.77    10.195.58.78

Adding support for networking

How to configure network isolation capabilities

Troubleshooting and debugging network connections