Rule Tracing

Cycles in rule tracing

Processing starts when a request for web access has been received from a client of Web Gateway. It is performed in different cycles, beginning with the request cycle, in which rules are processed that are related to the elements of the request itself. For example, to a URL that was sent with a request.

If none of the rules in this cycle forbids a forwarding of the request to the web, for example, due to a negative categorization of a URL, the request is forwarded. Processing then waits for a response from the web.

When the response arrives, the rules of the response cycle are processed. For example, when a file that was requested for downloading is sent in response, it is scanned for virus and other malware infections according to a particular rule and eventually passed on or not to the client that requested the download.

Other processing cycles are performed for embedded objects sent with requests or responses. Processing activities can also be logged according to the configured logging rules.

All processing that is performed in the different cycles for an initial request from a client of Web Gateway can be viewed as an entity, which is termed a transaction.

To debug an issue with rule processing, you can analyze the complete rule trace of a transaction or focus on a particular cycle that seems interesting with regard to problem-solving.

Properties in rule tracing

Whether a rule applies and executes a particular action, for example, a Block action that blocks a request for web access, depends on the rule criteria, which contains properties that are set to particular values during the processing.

For example, the Antimalware.Infected property, which is contained in the rule criteria of a default anti-malware rule, is set to true when a scanned web object has been found to be infected by viruses or other malware. Then the criteria of this rule matches, and a Block action is executed.

When analyzing a rule trace, it can be useful to look at the properties that were involved in rule processing and the values they were set to. Therefore, properties and their values can also be viewed separately.

Delete and restore rule traces

Rule traces can be removed from the panes of the rule tracing page, but not deleted on that page.

To delete rule traces, you need to access the Rule tracing files section, which is provided for every individual appliance under the Troubleshooting top-level menu.

In this section, you can also restore traces to the rule tracing panes that you have previously removed.

Debug rule processing issues via rule tracing

Use the options of the rule tracing panes to create rule traces and review them to debug issues with rule processing.

1. Select Troubleshooting.
2. On the troubleshooting tree, select Rule Tracing Central.
   The rule tracing panes appear.
3. Work with the rule tracing panes to debug rule processing issues.

Use rule tracing to find out why a request was blocked

When a request for web access that a user sent from a client of Web Gateway has been blocked, you can use rule tracing to find the rule that blocked the request and the reason why it was done.

This is a sample procedure that describes one of several ways to use rule tracing for recording and analyzing rule processing on Web Gateway.

1. Select Troubleshooting and on the appliances tree, select Rule Tracing Central.
   The rule tracing panes appear.
2. Create rule traces.
   1. In the traces pane, leave the name of the current appliance, which appears in the appliances names field.
      In this sample procedure, you will perform rule tracing for requests that were processed on this appliance.
   2. In the client IP address field, enter the IP address of the client that sent the request you want to do rule tracing for.
   3. Click Go.
      Rule traces for the latest requests received from the client are created. When trace creation is completed, entries for the traces appear in the traces field.

3. Filter the rule traces.
   1. In the time and URL filtering field, enter the URL that was sent with the blocked request. 
      The rule traces are filtered to show only entries for traces that were performed for requests to access a web object with this URL.
      Let us assume that a request with this URL was only submitted once by the client in question. This would mean only one entry is shown as the filtering result.
   2. Select the entry.
      Detailed information from the trace that recorded rule processing for the request with this URL is shown in the rules and details panes.
4. Review a rule trace.
   1. Review the tracing information in the rules pane.
      The rules that were processed to deal with the request are shown with their rule sets.
      The rule that blocked the request is selected and marked by a red arrow. If the arrow points to the right, the rule blocked the request in the request cycle. If the arrow points to the left, it was in the response cycle.
   2. Review the tracing information in the details pane.
      • The cycle in which the rule blocked the request, the name of the rule, its criteria, action, and event are shown.
      • The criteria is marked with a grey hook, which means it has matched.
      • Under Evaluated in the field below the criteria with the hook, the criteria is repeated.
        Under Value in the same field, the value is shown that the property had at the time when the criteria matched and the rule blocked the request.

Let us assume that, for example, the details pane shows the following details for the rule that blocked the request.

• Cycle — Response
• Rule name — Block if virus was found
• Criteria — Antimalware.Infected<Gateway Anti.Malware> equals true
• Evaluated — Antimalware.Infected equals true, Value — true
• Action — Block<Virus found>
• Event — Statistics.Counter.Increment<Default>("BlockedByAntiMalware", 1>

This means that rule tracing showed the request was blocked because the requested object had been found to be infected by a virus or other malware.

The blocking action was performed by a virus and malware filtering rule, which was processed in the response cycle when the object was received from a particular web server in response to the request.

The criteria of this rule included the Antimalware.Infected property. To find out what this property must be set to, the Anti-Malware engine on Web Gateway was called. It scanned the requested web object and detected an infection, so the property could be set to true and the rule criteria matched.

Best practices - Find out why a web page displays no images

Use rule tracing to find out why a requested web page appears on a client system, but with text only and without displaying any images.

Imagine a sample issue, where a user requests access to the CNN channel homepage from a browser on a client of Web Gateway. The page appears but displays only text.

You can use rule tracing to see whether a CNN server that provides the images on the homepage might have been blocked and why this happened.

1. On the user interface of Web Gateway, select Troubleshooting.
   If you are using several Web Gateway appliances in a Central Management configuration, make sure you are logged on to the appliance that the client in question is connected to.
2. On the troubleshooting tree, select Rule Tracing Central.
3. Create a trace.
   1. In the input field on the top left, type the IP address of the client system that had a request blocked, then click Go on the toggle button next to the input field.
      Requests for web access sent from the client are now traced and entries for trace files are displayed in the output field on the lower left.
      The Go on the toggle button turns into a cross to let you stop the process when no more tracing is needed.
   2. On the client system, refresh the browser or click or enter ccn.com again to reproduce the issue.
      Trace file entries appear in the output field on Web Gateway. 
   3. When you have reproduced the issue and the trace file entries have appeared, click the toggle button again to stop the tracing.

4. Review the trace file entries.
   For every request that has been traced, a time stamp and the requested URL are shown.
   At the beginning of an entry, a symbol for the most impacting action that was executed when processing the request is also shown. The most impacting of all actions is the Block action.
   When reviewing the trace file entries, you will see several entries with the blocking symbol and a URL beginning with cdn.turner.com/ccn. These are probably trace files for requests to access the CCN server that provides the images.

5. Select a trace file entry with cdn.turner.com/ccn.
   Information on this trace appears in the rules and details panes on the right.
6. Review the rules pane.
   The pane shows the rules that were processed for the request that was traced. The view stops at the last rule that applied before rule processing stopped. The rule is highlighted.
   This way you can see that Block URLs whose category is in Category Block List is the last rule that is applied.
7. Review the details pane.
   On the two tabs of the details pane, more tracing information is shown.
   On the Top Properties tab, you will see, among other information, that the URL.Categories property had the value Business when the rule mentioned above was processed.

This completes your rule tracing activities for this issue. Images from the CNN server were not displayed because the URLs that were submitted for accessing this server have fallen into the Business category and this category is on a blocklist.

If you want to see the images displayed, you need to reconfigure the web security policy for your network and put, for example, cdn.turner.com/ccn/* on a URL allowlist.

Restore removed rule traces to the rule tracing panes

To restore rule traces that you have removed from the rule tracing panes, supply them from the rule traces directory of an appliance or import them in a source file.

How removed rule traces can be restored to the rule tracing panes depends on whether they were created on the appliance you are currently logged on to or were imported to this appliance.

Accordingly. you can supply them from the rule traces directory of the appliance or repeat the import of the source file.

• Restore removed rule traces from an appliance directory. When rule traces that you have removed from the rule tracing panes had been created on the current appliance, you can restore them from the directory of rule tracing files on that appliance.
• Restore removed rule traces by importing a source file. When rule traces that you have removed from the rule tracing panes had previously been imported, you can restore them by importing the source file once again.

Delete rule traces

To delete rule traces, access the directory of rule tracing files on an appliance and use the delete option that is provided.

1. Select Troubleshooting.
2. On the troubleshooting tree, select the appliance you want to delete rule traces on, then click Rule tracing files.
   The directory of rule tracing files appears on the right side of the troubleshooting page.
3. Under Trace files, select the rule tracing files you want to delete and click Delete.
4. In the window that opens, confirm the deletion.