WIXLIB

YouTube API v3Rule Set DocumentationTable Of ContentsYouTube API v3 .1Scope .1Disclaimer .2Overview .2Prerequisites .2Installation .2Import Error Templates .2Import the Rule Set .2Configuration .3Extract Meta Data .3Get Title/Description .3Get Uploader/Channel .4Get Thumbnails .4Filters Based on Meta Data .4Filter By Category .4Filter By Keywords.4Filter By Uploader/Channel .4Filter By Video ID.5Filter By DLP Acceptable Use .5Fail-Open Error Handler .5Troubleshooting .5ScopeThis document is a short whitepaper which comes along with a rule set for McAfee Web Gateway.The document describes how to import the associated rule set into a default McAfee Web Gatewaypolicy.

DisclaimerThis rule set along with all of its associated files and documents is provided on an as-is basis. McAfeewill not take any responsibilities for problems, outages or any other issues resulting from using thisrule set, or any of the files associated.Please be careful when importing the rule set into your existing policy. Make sure you understoodwhat the rule set is supposed to do and verified it does not interfere with any other rules thatcurrently exist within your configuration.Many values used within the rules are example values and will most likely not fit your environment.Always make sure that you have changed examples to real-life values.OverviewYouTube offers a publically accessible API which allows access to a YouTube videos Meta informationsuch as uploader, category or similar. Recently Version 3 of the API has been released which mightsupersede previous implementations using the older API.This rule set utilizes Version 3 to lookup Categories and Uploader/Channel names in order to providesome additional filter capabilities to MWG. It uses external list calls to poll the API servers and writesthe results into custom HTTP headers which are usable from within the rule engine.PrerequisitesCompared to the previous API the API v3 requires a user to obtain an API key which is used toidentify who is querying the API. Every API has a specific quota which defined how many requestsagainst the API can be done.More details can be found at tarted.Please note that McAfee and/or the product McAfee Web Gateway don’t have any control about theAPI itself (in regards to availability) and/or the quota. In case you exceed the quota for your API key itmay be required to talk to YouTube/Google to increase the available quota for your key.Additionally the API now heavily utilizes JSON, so a version of McAfee Web that has JSON SupportGateway is required.InstallationImport Error TemplatesBefore you import the rule set itself it is required to import the error templates.1.)2.)3.)4.)5.)Find the “Template Editor”, for example by editing any of the existing Block ActionsClick the “Import” buttonPoint to the ZIP file which came with the rule set and contains the templatesResolve any conflictClose the template editorImport the Rule Set1.) Access the McAfee Web Gateway Web Interface (UI)2

2.)3.)4.)5.)6.)7.)8.)Open the “Policy” tabFind an appropriate location for the rule set, for example between URL Filter and AV rule setsSelect “Add - Top Level Rule Set - Import Rule Set from Library”Click the “Import from file” button in the lower left corner of the new windowSelect the rule set from the file you have downloadSolve all conflicts by “refer to existing” objectsDone!ConfigurationBecause the YouTube API requires a personalized API key now the rule set will not work butimmediately exit unless you provide MWG with your API key:In the parent rule set “Youtube API v3” you will have to put your API key into a user-definedproperty. If the key is not provided, the server will deny all API requests. This will result intoproblems when looking up the videos Meta data.Extract Meta DataThere are several Meta objects MWG will extract. The rules responsible for the extraction are locatedin the parent rule set “Get Meta Information Via Youtube API”. They will be described below.Get CategoryMcAfee Web Gateway will try to extract the category ID from the API response. In API version 3 thecategory is no longer provided as a string but as a numerical identifier (which optionally can betranslated into a string, see below).Translate Category IDIn order to translate the category ID (numerical value) into a readable value (for example “Autos &Vehicles”) McAfee Web Gateway can initiate another call to the API. This setting has a cache settingof 24 hours as categories usually do not change on a regular interval.If you do not want to utilize categorization in your policy you can disable both rule sets. If you arehappy with category IDs only you can disable the “Translate Category ID” rule set. This will save someof your available quota, however it will make category handling more inconvenient.Get Title/DescriptionThis rule set is responsible for grabbing the videos title and description. Both can be used to searchfor specific keywords you would like to filter or to mark up the block template with the videos titleand/or description, which can be helpful for users.If you do not want to filter based on title or description you can disable this rule set.3

Get Uploader/ChannelIn case you want to restrict access to specific uploaders/channels you can add the allowed and/orblocked uploaders to a list. McAfee Web Gateway will fetch a videos uploader via the API call andmake it available for filtering.If you do not want to filter based on Uploader/Channel you can disable this rule set.Get ThumbnailsThis rule set can most likely be disabled. The default block templates contain a thumbnail of thevideo, which is grabbed here.Filters Based on Meta DataThe rule set comes with several examples which use the extracted Meta data in order to enforce aspecific policy.Filter By CategoryThis will allow you to set up a “Allow only these categories” or a “Allow all but these categories”policy. You will have to fill the category ID or category name (if translation is enabled, see above) intothe associated lists.If you watch a video in the browser you can find the category name in the video description:You can find the correct category ID by accessing the list of ID - category name mappings bymaking a browser call to the egories?part snippet®ionCode usIf you are unable to see the result because there is no quote left please add your API key to the URLby adding “&key your API key ” to the end of the URL.Filter By KeywordsThis rule set will allow you to add a very simple keyword filter based on wildcard found in a videostitle or description. Please note that the list requires wildcard expressions, so in case you want tosearch for the word “naked” in the title or description, please type “*naked*” into the list. You canalso apply regular expressions.Filter By Uploader/ChannelThis rule set will allow you to set up a “Allow only these channels” or a “Allow all but these channels”policy, which will allow you to (for example) only allow your users to see the companies YouTubevideos or to block specific YouTube channels which are time consuming or contain inappropriatematerials.You can find a videos uploader/channel name below a video if you watch it in the browser:4

Filter By Video IDThis is a very specific filter that will allow you to only allow or block specific videos. You can grab thevideo ID from the browsers address bar:Filter By DLP Acceptable UseThis filter will apply DLP rules to title/description of a video and can search for inappropriate words.More information about the DLP rules can be found in the official product documentation.Fail-Open Error HandlerCalling an external list may cause problems, for example when the remote server is not available ornot responding fast enough. In such a case McAfee Web Gateway usually presents a block page anddenies access for the user.Therefore the rule set contains an additional Error Handler which is set as default while McAfee WebGateway polls the API servers for a response and is set back to the Default error handler once thisoperation succeeds.This error handler is configured to write a log line and fail-open, so that access to YouTube is grantedrather than blocked when an API lookup does not work. In case this behaviour is not desired pleaseturn off the “Get Meta Information Via Youtube API - Set Fail-Open Error Handler” rule.In case you are using a non-default error handler you may need to look more closely at the errorhandler configuration to make sure your policies uses the correct error handler. If unsure simply turnoff the “Get Meta Information Via Youtube API - Set Fail-Open Error Handler” and “Get MetaInformation Via Youtube API - Set Default Error Handler” rules.TroubleshootingPlease note this rule set is not officially supported. For any help, further comments or featurerequests please use the McAfee Community /email web/webgateway5

McAfee Web Gateway will fetch a videos uploader via the API call and make it available for filtering. If you do not want to filter based on Uploader/Channel you can disable this rule set. Get Thumbnails This rule set can most likely be disabled. The default block templates contain a thumbnail of the