The Umbrella Deployment Documentation Developer Hub

Welcome to the Umbrella Deployment Documentation developer hub. You'll find comprehensive guides and documentation to help you start working with Umbrella Deployment Documentation as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Frequently Asked Questions

Q: What happens if the Umbrella roaming client can’t connect to the server for IP Layer Enforcement?
A: If the VPN can't connect, it keeps trying to connect but it also backs off and should not interfere with other services. The VPN does not fail closed and block other traffic, it simply fails open if the VPN server is not available. On Windows - IP Blocks continue to apply as blocks without block page responses (block page loading requires the tunnel to be up). Possibly suspicious IPs are permitted when the VPN cannot connect.

Q: How does this affect my existing Umbrella service?
A: Other than improving a small gap in our ability to secure your computers both on and off the network, there should be no change. Direct requests to IP addresses that are not considered suspicious won't be affected. Only direct connections to IP addresses or ranges of IPs, listed in the routing table delivered on to the Umbrella roaming client will be affected and only attempts to contact these IPs will be intercepted by the technology.

Q: How is the VPN for IP Layer Enforcement secured?
A: The secure tunnel for the IP Layer Enforcement is based on IPSec, so the traffic between the computer that has the Umbrella roaming client installed and the Umbrella service is encrypted for integrity and confidentiality from end to end.

Q: How does IP Layer Enforcement work with another VPN installed?
A: When another VPN, such as AnyConnect or JunOS/Pulse Secure, is active and detected, the IP Layer Enforcement feature will 'back off’ automatically and become disabled. The IP Layer Enforcement will be enabled when the VPN is not connected. See Umbrella Roaming Client: VPNs and Software Compatibility for known specifics. Any issues you do see with other VPN software should be reported to support.

Q: Can I add my own list of IPs to allow or block?
A: On our early release of this feature, the IP Layer Enforcement will have a single list of malicious/suspicious IPs for everyone. Umbrella security researchers will maintain and update the list to protect you from the latest threats. However, customer specified IP addresses are something we'd love to add in and are part of the roadmap under a "Destination List". We do have the ability to allow particular IP or CIDR in limited availability right now and hopefully, that functionality will be released to a broader group of customers soon.

Q: How does this VPN approach fit into my existing policy application?
A: The policy application takes place at the same point in the cloud as any other policy, so whatever you’ve defined for the policy will still take place. For instance, if you have a custom block page and are attempting to reach a malicious IP on port 80 through a browser, you should see a block page displayed.

IP Layer Enforcement: Advanced Details

Q: How does IP Layer Enforcement determine which IP addresses to block?
A: The Umbrella roaming client retrieves a list of suspicious IP addresses from Umbrella and automatically checks again for any new IP addresses every five minutes from the Umbrella API. Updates in the backend are provided at a minimum every 45 minutes, but the roaming client checks every five minutes to stay as up to date as possible.

The information is downloaded to the local client and loaded into memory when the Umbrella roaming client is running. The information about which IP addresses are being routed is not kept on disk, only in memory.

Although the IP Layer Enforcement feature comes bundled with the Umbrella roaming client software but is, in fact, a separate process running alongside the Umbrella roaming client. The primary purpose of the client-side process is to create an IPSec VPN tunnel using the built-in VPN client for the OS. In OS X, the built-in VPN is Raccoon and in Windows, it’s RASClient (or RRAS Client).

Q: Once the Umbrella roaming client has the list of possibly suspicious IP addresses, what happens next?
A: If the feature is enabled in the policy for the Umbrella roaming client identity, the roaming client establishes an IPSec tunnel using the IP addresses listed in the prerequisites of the setup article. The IPSec tunnel is established in advance of any traffic being sent through it so we’re prepared for traffic to be routed through the tunnel; however, traffic flow isn’t established until required.

If a request from the client’s network stack (so, from any application or user-generated internet request on the computer) is made to one of those IPs, then (and only then) the Umbrella roaming client will intercept that traffic and proxy that traffic through the IPSec tunnel. There is some difference in how that operation takes place between the versions of the Umbrella roaming client for Windows and OS X.

On OS X, the IP Layer Enforcement process will add a route for each of the IPs in the list. Once the routes are in place, all traffic to any of these IP address will be sent through the VPN to our servers.

On Windows, the process is a little different. Instead of adding all IPs as routes (as on OS X), we utilize the Windows Filtering Platform (https://msdn.microsoft.com/en-us/library/windows/desktop/aa366510(v=vs.85).aspx) to watch for outbound packets to any of the blocked IP addresses in our list. When a request is made to one of these IPs, a route is dynamically created ‘on the fly’ and all subsequent packets destined to the IP will be sent through the tunnel to our servers. As a result, the first connection attempt may result in a failed connection; however, the TCP retry would succeed in being sent over the tunnel to Umbrella.

Q: When the suspicious traffic reaches the Umbrella servers, is it blocked right away?
When traffic through the VPN has reached the Umbrella IP Layer Enforcement servers, that doesn’t necessarily mean the requests are blocked right away. Instead, when the traffic reaches the Umbrella servers, the destination is then inspected. Depending on the amount of information Umbrella has about this IP address, Umbrella will either return the IP of the block page instead of the destination or traffic or send it through to the intelligent proxy which could block on specific content.

Basically, a decision process that determines whether or not we hand back a blocked page response. If we know the destination suspicious IP is known malicious, then we'll hand back the block page response. Otherwise, if the IP address is found on our greylist (list of domains/IPs that could be okay, could be not okay), we'll hand that traffic over to our intelligent proxy which will continue to proxy the traffic destined for that IP and block if there's only a single malicious URL on that IP while allowing access to all other resources hosted on that particular IP.

For instance, an IP might present perfectly normal web data but have a single compromised URL (for example, http://x.x.x.x/malware.exe) that we could block using the intelligent proxy.

Another example would be a file distribution website which hosts software for free download. There may be many files stored on the domain’s server y.y.y.y, where most are safe. A blacklist (block list) entry would block y.y.y.y and y.y.y.y/* connections whereas a greylist entry may block just http://y.y.y.y/software/windows/malware.exe with the intelligent proxy and allow the remaining good files through to the user.

Q: Where does the VPN for IP Layer Enforcement terminate?
The IPSec VPN tunnel terminates with the IP Layer Enforcement server infrastructure. At that point, the traffic can be sent through to the intelligent proxy for blocking of specific URLs. Interestingly, the IP Layer Enforcement servers contain a second, complete version of the intelligent proxy within the servers themselves and do not need to forward to a separate set of servers to parse URLs.

When the tunnel terminates at Umbrella servers, there's basically a decision process that is made in terms of whether or not we hand back a blocked page response. If we know the destination suspicious IP is known malicious, then we'll hand back the block page response. Otherwise, if the IP is found on our greylist (list of domains/IPs that could be okay, could be not okay), we'll hand that traffic over to our intelligent proxy which will continue to proxy the traffic destined for that IP and block if there's only a single malicious URL on that IP while allowing access to all other resources hosted on that particular IP.

Q: How does IP Layer Enforcement ensure the IPSec VPN tunnel isn’t used to bypass your other security checks?
It’s possible that a very savvy user, or specially crafted malware, could notice that the Roaming Client was tunneling traffic to IP addresses out of your network and assume that tunnel could be used to bypass perimeter protections, such as firewalls or IDS. If such traffic is detected by Umbrella, we will actually drop any traffic that doesn’t have a destination of one of the IP addresses that we’re routing. In the future, such requests will be logged so you can take note of them.

Q: How can I troubleshoot IP Layer Enforcement?
If you run into any issues, or if you were working with Support to rule this feature out as a problem, see:

  • Run this diagnostic test for logging details
  • Are you using any kind of VPN client (besides Umbrella roaming client features)
  • What other network devices upstream on the network might be capable of blocking traffic on the required ports?
    In regard to tests, a quick test to ensuring IP Layer Enforcement is functional is just going to http://ipblock.opendnstest.com/. If the tunnel is set up and enabled, success will be reported here.

If you’re seeing unreliable connectivity or troubles with other VPN software, first confirm the IP Layer Enforcement system is functional (using the test above) without the VPN established. If it is functional, confirm that the issue is the result of a VPN compatibility conflict by disabling the IP Layer Enforcement feature, then reconnecting to the VPN.

If the VPN works without issue when the IP Layer Enforcement feature is disabled, but not when the feature is enabled, please contact Support.

Q: Are there any incompatible programs?
Below is a list of known possible incompatible programs.

  • Peerblock—This software blocks IPs with a routing table entry. If the IP Layer Enforcement IP (in the 100.64.0.0/10 for use in carrier-grade NAT range) IP received is blocked by PeerBlock, the IP Layer Enforcement feature will not be able to function.

Add IP Layer Enforcement < Frequently Asked Questions > Identity Support for the Roaming Client

Frequently Asked Questions


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.