Rule evaluation order

Rule evaluation determines whether a web request should be allowed or denied by using the rules that you set in your policy. It considers the following attributes to make its decisions:

  • Priority of a rule: Lower integers indicate higher priorities.
  • SessionMatcher: Matches against the following session level attributes:
    • IP address of the source machine
    • Service account of the source machine
    • Secure Tag of the source machine
    • Hostname of the target machine
  • ApplicationMatcher: Matches against the following HTTP request attributes:
    • URL
    • Path
    • Request headers

For a list of all the SessionMatcher and ApplicationMatcher attributes, see Available attributes in SessionMatcher and ApplicationMatcher.

How rule evaluation works

The rules are evaluated in the following order:

  1. High-priority rules are evaluated first.
  2. The highest priority rule that matches the SessionMatcher and ApplicationMatcher attributes determines the action to be taken on the traffic.
  3. If the request does not match the SessionMatcher and ApplicationMatcher attributes of that rule, the next rule with the highest priority is evaluated.
  4. This process continues until a rule is found that matches the request, or all the rules have been evaluated. If no match is found, the request is denied.

Before you configure TLS inspection

You must understand the following rule-evaluation scenarios before you configure TLS inspection:

  • A client can send an HTTP request to the proxy server. The request is then evaluated by using all the available data, including the hostname, source identity, HTTP headers, and path.

    If the request is allowed, the HTTP traffic is sent to the destination. However, if the request is denied, the HTTP traffic is not allowed to pass.

  • A client can send the proxy an HTTP CONNECT request to establish a TCP tunnel to the destination. This is done when the client wants to send arbitrary TCP traffic or establish an end-to-end TLS connection with the destination through the proxy, as with HTTPS.

  • If a rule has a matching SessionMatcher attribute and does not contain an ApplicationMatcher attribute, and the rule evaluation results in allowing the traffic, then a tunnel to the destination is established and the traffic is TCP-proxied. This applies to HTTPS and TCP traffic.

  • If higher priority rules are unable to determine the action to be taken on a request, then the rule evaluation continues. If the evaluation proceeds to a rule with an ApplicationMatcher attribute, then the tunneled traffic is interpreted as HTTP or HTTPS.

    If the underlying data is not HTTP or HTTPS, then the connection fails.

    If the underlying data is HTTP, then the requests are evaluated, including the hostname, source identity, HTTP headers, and path. Based on the evaluation result, the traffic is either allowed or denied.

  • For HTTPS traffic, a rule is evaluated only if it has the TLS inspection flag enabled; otherwise, that rule is skipped.

  • For HTTPS traffic, a rule is inspected only if the following conditions are true:

    • The TLS inspection flag is enabled.
    • Traffic matches the SessionMatcher attributes.

Recommendations for configuring TLS inspection rules

  • If you want to allow TCP traffic, then the rule that allows TCP traffic must have a higher priority than the rules that allow HTTP traffic.
  • Rules with the ApplicationMatcher attribute should be tightly scoped by using the SessionMatcher attribute to minimize the interpretation of unrelated flows as HTTP.
  • Rules that allow TLS (including HTTPS) traffic but do not perform TLS inspection can be interpreted as TCP proxy rules.
  • To avoid unnecessary TLS inspection of traffic, TLS inspection rules should be lower in priority than non-TLS inspection rules. Alternatively, to fail fast for non-matching traffic, TLS inspection rules should be tightly scoped by using the SessionMatcher attribute.

Examples of TLS inspection rule configurations

Consider the two rules in the following examples.

Example 1

In this example, we assume the presence of other lower priority rules. Consider the following two rules:

  • Rule 1

    description: do not allow POST requests
priority: 10
basicProfile: DENY
sessionMatcher: true
tlsInspectionEnabled: true
applicationMatcher: request.method == 'POST'

  • Rule 2

    description: allow TCP proxying from tag 12345 to example.com
priority: 20
basicProfile: ALLOW
sessionMatcher: source.matchTag('tagValues/12345') && host() == 'example.com'

In this example, Secure Web Proxy interprets the two rules as follows:

  • Allowing TCP traffic but disallowing a specific type of HTTP request is mutually exclusive because the TCP traffic can contain a POST request.
  • Traffic in rule 2 is never allowed. It is denied because the traffic from tag 12345 to example.com is intercepted and interpreted as HTTP to evaluate the HTTP method.

  • For rule 2 to take effect, you can use either of the following solutions:

    • Recommended: Increase the priority of rule 2 to a higher level (priority: 5).

    • Scope rule 1 to avoid overlapping the allowed traffic with its SessionMatcher attribute:

      sessionMatcher: !(source.matchTag('tagValues/12345') && host() == 'example.com')

      We do not recommend this solution because it becomes difficult to maintain many overlapping rules.

Example 2

Consider the following two rules:

  • Rule 1

    description: allow to specific GitHub repository (TLS inspect to match specific path)
priority: 10
basicProfile: ALLOW
sessionMatcher: true
tlsInspectionEnabled: true
applicationMatcher: request.url().startsWith('github.com/grpc/grpc')

  • Rule 2

    description: allow TCP proxying from tag 12345 to example.com
priority: 20
basicProfile: ALLOW
sessionMatcher: host() == 'bankofamerica.com'

In this example, Secure Web Proxy interprets the two rules as follows:

  • All traffic, including that destined for bankofamerica.com, is inspected for TLS to match the request.url() of the high priority rule 1.

  • To avoid TLS inspection in rule 2, you can use either of the following solutions:

    • Increase the priority of rule 2 to a higher level (priority: 5). As a result, rule 2 is applied before evaluating rule 1, and traffic from bankofamerica.com is allowed without being TLS inspected.

    • Recommended: Narrow the scope of rule 1 to allow TLS inspection specifically for the github.com domain. To narrow the scope, add a targeted sessionMatcher attribute:

      sessionMatcher: host() == 'github.com'

Limitations

You must consider these limitations before configuring TLS inspection:

  • Servers are only verified by using public root certificates. The root certificate authority (CA) set is based on the Mozilla Root Program. The behavior of certificate verification is subject to change and corresponds to how web browsers verify certificates.

    Because backend verification is not possible at this time, traffic to servers with private or self-signed certificates cannot be intercepted.

  • Secure Web Proxy does not run certificate revocation list (CRL) checks.

  • For TLS inspection to work, clients must currently send Server Name Indication (SNI). SNI is a TLS specification extension that is optional, but most clients enable it by default.

  • TLS inspection does not work if the client requires Encrypted Client Hello (ECH) (formerly known as Encrypted SNI).

    ECH is a draft IETF standard that allows clients to encrypt the beginning of the TLS handshake by using a pre-established server key. Because TLS inspection is acting as an intercepting proxy, it does not have access to that pre-established server key. As a result, ECH does not function.

  • Clients must be configured to trust your private root certificate.

  • If you remove CAs from your private CA pool, you are served cached certificates signed by that CA for up to 28 hours. To prevent using the cached certificates, you can update your TLS inspection policy to point to a new CA pool. As a result, Secure Web Proxy is forced to generate new certificates.