PithHelmet

Problem:

I hate ads.

Solution:

Kill my television.

Better Solution:

Content filter my web pages...

1.1 What It Does

PithHelmet adds some some basic but powerful content filtering to Apple's Safari browser. The basic purpose is to block ad images, but there are other potential uses as well (blocking Flash, Shockwave or horrible midi loops).

This is just a series of hacks on top of Apple's WebKit framework, but it seems to work rather effectively.

Due to the manner in which PithHelmet blocks ad content, most types of advertising content can be caught in the filter - this includes images, javascript, css, text, iframes, popups and popunders.

1.2 More Detailed Information

Progress reports are regularly written to the PithHelmet Development section of my development log. One of these days I will get around to hosting the source somewhere, but for now, inquiring minds can send me a quick email and get the latest branch.

2.1 Installing and Upgrading

PithHelmet is a plugin for SIMBL. This keeps PithHelmet from unintentionally interfering with other applications, such as the screen saver.

As of v0.6.3, PithHelmet is distributed as a metapackage and installed by Apple's Installer.app. The PithHelmet.mpkg file will automatically update or install the lastest version of SIMBL and the PithHelmet plugin. The installed components are listed below.

The actual PithHelmet.bundle will now be installed in the /Library/Application Supports/SIMBL/Plugins folder.

If you have added you own rules, they will get saved in a backup file in ~/Library/Application Support/PithHelmet before they are automatically upgraded.

Note: Some older versions (pre-v0.5) of PithHelmet will prevent the package from installing properly. There are a few useful error messages that will inform you of files that are in the way. If you remove these files, either by moving them or trashing them, the install should proceed. There are several potential directories to remove, but eventually, things should install correctly.

2.2 Uninstalling PithHelmet

Removing (trashing) the PithHelment.bundle from /Library/Application Support/SIMBL/Plugins folder will effectively remove PithHelmet from Safari.

2.3 Installed Files and Folders

• /Library/InputManagers/SIMBL - SIMBL is required for PithHelmet to load properly. (more info)
• /Library/Application Support/SIMBL/Plugins/PithHelmet.bundle - this is the actual code section of PithHelmet - this is what gets upgraded
• ~/Library/Application Support/PithHelmet/PithHelmet.log - logs all blocked urls if logging is enabled
• ~/Library/Application Support/PithHelmet/PithHelmet.plist - stores all the rules

3.1 How To Block A URL

Once you've installed the files, start Safari (restart it if it's been running during the install process). Try browsing a few sites and you should see markedly less advertisements. (I like cnn.com or msn.com for a good demo site)

If some undesirable content isn't blocked, you can add it to the "block list" in one of the following ways:

• Right click (Control-Click) an image and select Block Images from this Server
• Use the rules editor in the PithHelmet Preferences pane
1. open Safari's preferences and select the aptly chosen PithHelmet icon
2. select the Block group row and click the "+" icon to add a new rule
3. the string value is a Perl-compatible regular expression - any matches will be blocked
4. for an explanation of Perl-compatible regular expressions, open the Terminal and type "man perlre"

You can test the rules on a particular URL by clicking the "Test Rules" button. That will give you some information about whether or not the url was blocked or allowed, and for what reason. Once you close the preferences pane or click the Save button, the new rules will be active.

3.2 How To Allow A URL

If some desirable content is accidentally getting caught by the Block rules (a false positive), you can specifically allow content via an Allow rule. The method is similar to adding an Block rule, simply add the rule to the Allow group instead. Allow rules are applied only after an Block rule has been matched.

You can use the same testing method described in the previous section.

3.3 How To Build Better Blocking Rules

PithHelmet now has a test panel (accessibly via the PithHelmet preferences pane in Safari) which will give you an explanation of what exactly PithHelmet thinks about a specified URL.

In addition, the curious user can enable the PithHelmet.log file (from the preferences pane) and all urls matching a rule will be logged to this file. A side benefit of logging is that potentially, people can submit their logs to me for analysis, so I can prioritize the rules and make them both faster and more effective.

Additionally, a useful thing would be for people to mark items in the log which were matched unintentionally, so I can reduce accidental blocking. The best way to send the log files is via email attachment.

Also, feel free to send your custom Block/Allow rules back to me - I will make them available in any subsequent releases if they are widely applicable. If you do submit a rule, you might want to include a hint about which sites this rule is for - that way I can clean up the rule if necessary and also take some time to validate it myself.

3.4 Quick Explanation of the Preferences Pane

Bug Icon

Report a bug to me via email - this automatically fills out version info for Safari and PithHelmet

Plane Icon

Takes you to a PayPal page where you can send a donation to reward my development efforts

Enable Transmogrifier - (advanced users)

Enables you to transmogrify one url to another, similar, but different url.
Currently, the demo rule makes all New York Times Magazine pages go to the printer-friendly equivalent. You have to edit the PithHelmet.plist manually to make this work.

Hide Blocked Content

Executes a Javascript function once a page finishes loading to remove content matching the Block rules. It also checks the location of links, and links to matching the Block rules are also expunged.

Hide Ad-Sized Images

Causes images (and iframes too) matching common advertisement sizes to be blocked. This is only valid if Hide Blocked Content is enabled as well.

Hide Links To Blocked Content

Causes content linked to URLs matching the Block rules to be hidden. This is surprisingly time consuming and usually accounts for any slowness related to PithHelmet. This is only valid if Hide Blocked Content is enabled as well.

Enable Logging

Writes all PithHelmet actions to a log file ~/Library/Application Support/PithHelmet/PithHelmet.log It can be useful to tell you which URL's PithHelmet is blocking - useful to me because I can generate prioritized rules based on how often a rule causes a block/allow action.

Enable Contextual Menu

Adds a contextual menu item to allow images to be blocked with a single click.

Enable Debug Menu

Somebody wrote an application that basically just turned on the built-in Safari menu and then demanded cash for it, something around $10. Needless to say, that is dumb. It rubbed me the wrong way, so I included this option to turn the Debug menu on/off. This requires you to restart Safari for the option to take effect.

Block All Cross-site Content

If this is turned on, all images, movies, etc. on a page that do not come from the same domain that appears in the location bar will be blocked. This is pretty drastic, but a few people requested it. I leave it off personally.

GIF Animations

This can alter the number of times GIF animations play - Alway (default), Once (the entire animation will play only once) or Never (the first frame of the animation will be shown, but there will be no animation).

Plus Icon

Adds a new rule. You must have a group, or an existing rule already selected before you click.

Minus Icon

Removes the currently selected rule.

Rules Editor

Rules Types:

• Invalid Rule
• Domain Match - suffix match the domain with the text
• Regex Domain Match - regex match limited to the domain
• Regex URL Match - regex match against the whole URL

Rule Groups:

Block

Content matching these patterns are blocked.

Allow

An Allow rule will override a block rule. It also overrides images size blocking.

Exempt Sites

Disables all PithHelmet features for any sites matching these patterns. This is helpful for trusted sites.

Test Rules

Brings up a panel where you can type a URL and see the results of having PithHelmet run over it. It will tell you if it is allowed, blocked and why (which rule matches, etc.)

Reload

Reloads all rules from the PithHelmet.plist file - one might really call this revert. You will lose unsaved changes.

Save

Saves current rules to the PithHelmet.plist file.

3.5 Quick Explanation of Menu Items and Keyboard Shortcuts

Block Filtered Content (Safari menu)

Command-Shift-K
turns PithHelmet on/off

Reload Page Unfiltered (View menu)

Command-Shift-R
reloads the current url with PithHelmet disabled temporarily

Block Images from this Server (contextual menu)

Right-Click (Control-Click) on Image
adds a new Block rule for the server hosting the current image

Never Block Content from this Server (contextual menu)

Right-Click (Control-Click) on Page background (not an Image or a Link)
adds a new Exempt Site rule for the domain name of the current site

Preferences Pane Contextual Menu

Add New Rule...

allows you to add a new rule of a particular type

Set Rule Type

allows you to change the type of a rule (see above)

Remove Rule

see above

Truncate Log...

Deletes the PithHelmet log file if you feel it is getting too large

Revert To Factory Rules...

Deletes all user-added rules and restores them to the latest version of the factory rules

Report Bug...

see above

Send Donation...

see above

Help

Links to a few helpful sites and PithHelmet ReadMe

About PithHelmet...

Loads this document in a new browser window

I told you it was quick.

4.1 Caveats

1. This entire thing is based on private non-final APIs inside Safari. v0.6 works with Safari 1.0 v73 (Beta2) and is tested on Mac OS X 10.2.5 - I doubt it works on versions earlier than 10.2 and could very well break on the next release of Safari.

4.2 Possible Features for v0.8

1. Cookie filtering/mangling - I swear I'll work on it!
2. Collapse Flash content

5. Questions | Comments | Feedback

Please feel free to contact me via email - I'm interested to here your criticisms and thoughts.

You can always read about the latest PithHelmet status in my development journal. There are also a number of pages on the PithHelmet section of my collaborative web site, Wikir.

If you are feeling especially appreciative, consider sending me a donation via PayPal.

6. Thanks

Nora G - for letting me test the early versions on her laptop.

Numerous folks have expressed their thanks for PithHelmet and provided substantial encouragement.

7. Revision History

v0.7.1 - released 2003-10-20

• fixed the transmogrifier (broken in v0.7)
• updated rules to prevent them catching a few false positives
• added French localization
• added example transmogrification for emulating Mozilla keywords - http://rebug.org/archives/000483/custom_keywords_in_safari.html
• this version does NOT work with Panther

v0.7 - released 2003-08-26

• enabling PithHelmet is now saved as a preference (the "Block Filtered Content" menu item) between Safari sessions
• added a separate preference for hiding content that is linked to advertising content
• blocked content checks for a substitute file (this prevents annoying question mark/missing image graphics from loading even with content hiding disabled)
• content from localhost and file:/// is never filtered
• "Block Images from server" contextual menu item now includes the name of the server that will be blocked
• added a new rule set "Exempt Sites" which disables all PithHelmet blocking/hiding for any page matching this group of rules
• new contextual menu item "Never block content from " - adds a site to the "Exempt Sites" group
• content and error messages are now fully localizable (for info on becoming a translation volunteer see PithHelmetLocalization)
• sites that are in the location bar do not get blocked (this prevents accidental blocking when you type in a url that matches a block rule)
• added some new Help menu items to the preference pane contextual menu - mostly on the subject of regular expressions
• added "Revert to Factory Rules..." contextual menu item - this will remove all custom rules and restore the default set of rules that PithHelmet shipped with (it makes a backup copy of your customized rules first, just in case)
• completely new blocking mechanism based on new WebKit documentation from Apple
• Hide Blocked Content has been rewritten to limit the number of links it examines on a page - this fixes the very slow performance reading message digests which could contain ~1000 or more links on a single page
• merged url and domain-specific rules - this is only a UI change and should simplify the rule editor
• added GIF-wrangler functionality to control whether GIF animations play Always, Once or Never

v0.6.3 - released 2003-06-26

• compatible with Safari 1.0 (v85) only
• fixed metapackage distribution problems
• fixed crash bug related to malformed urls (caused half-loading pages)

v0.6.2 - released 2003-06-23

• compatible with Safari 1.0 (v85) only
• distributed as a metapackage
• release recalled 2003-06-25

v0.6.1 - released 2003-05-16

• fixes the transmogrifier
• fixes the way Block Images by Server works to be a bit more logical

v0.6 - released 2003-05-01

• compatible with Safari Beta2 (v73) only
• content collapsing handles IFRAME tags now
• collapse images matching common ad sizes
• Flash and other plugin content now blocked as well
• added Block/Allow Domains (more efficient than generic block)
• added new rule types (regex url, regex domain, match domain)
• contextual menu to block images from a server (much like Phoenix)
• fixed a bug preventing Reload Unfiltered from working properly
• preferences pane contextual menu adds new functionality
• rules editor rewritten to alert user of syntax errors
• rules editor shows invalid rules
• default rule set tweaked again
• future rule updates can be merged with user rules automatically
• errors appear as alerts rather than silent failures to the Console

v0.5 - released 2003-03-24

• compatible across Safari v6x releases, tested with v60, v64 and v67
• content collapsing (images blocked by PithHelmet are removed from the document completely)
• cross-site content blocking (loads content only from the domain in the location bar)
• Command+Shift+K turns off all of PithHelmet
• Command+Shift+R reloads the current page with all of PithHelmet's rules temporarily disabled
• preferences pane
• test panel to help you build/test your own rules
• new rules
• bug report button (tells me version of PithHelmet and Safari
• added timestamp to the log file entries
• PithHelmet.plist is now versioned
• transmogrifier fully functional
• added timestamp to the log file entries

v0.4.3 - released 2003-03-08

• New version to address Safari v64 more thoroughly.
• In my rush to fix up v0.4.3, I released a really crappy build.
• This changes the filtering mechanism again for v64, however this one has been tested more thoroughly by myself, based on problematic url suggested by users.

v0.4.2 - released 2003-03-06

• Due to public outcry vis-a-vis a hypothetical release of Safari (v64), the entire mechanism had to be redesigned for this new, hypothetical, release. This is 100% backward compatible with older versions.

v0.4.1 - released 2003-02-10

• Fixed bug creating the PithHelmet folder causing Safari to crash

v0.4 - released 2003-02-09

• Added log files to audit matched urls.
• Added menu item to turn off ad blocking.
• Added menu item to reload rules without restarting.
• Expanded the blocking rules.
• Distributed as a plugin for SIMBL.

v0.3 - released 2003-02-01

• Added include rules to prevent some false positives.
• Unreleased.

v0.2 - released 2003-01-28

• Minor fixes to make it distributable.

v0.1 - released 2003-01-15

• Internal use at my day job.