PithHelmet

Links and Downloads

Documentation

Download

Pith Helmet Logo
Purchase your copy today for only $10 USD.

0.0 Latest Announcements

I recently added the PithHelmet Rule Exchange so users can request and share custom scripts for particular sites. There isn't much there right now, but hopefully more to come soon.

1.1 What It Does

PithHelmet is an extended site preferences and ad blocking plugin for Apple's Safari browser. The basic purpose of the plugin is to empower you the user to view the web as you like. You can block ad images, Flash, Shockwave or horrible midi loops - the world is your oyster.

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.

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.

For additional installation information and trouble shooting, check PithHelmet Installation Notes. These notes are updated more frequently than the main site.

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 - (more info)
/Library/Application Support/SIMBL/Plugins/PithHelmet.bundle - this is the actual code section of PithHelmet - this is what gets upgraded
/Library/Frameworks/DuctTape.framework - a framework I wrote for my plug-ins and applications
~/Library/Application Support/PithHelmet/PithHelmet.log - logs all blocked urls if logging is enabled
~/Library/Application Support/PithHelmet/com.apple.Safari/PHRuleSet.ka - 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

Open the rule editor (PithHelmet Menu -> Show Rule Editor)
Click the New button
The pattern value is a Perl-compatible regular expression - any matches will be blocked. For an explanation of Perl-compatible regular expressions, open the Terminal and type "man perlre".
Under the "Filter" tab, select which types of content you would like to block.

You can test the rules on a particular URL by clicking the "Show Rule Tester" 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 rules editor or click the Apply 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 and under the filter tab select "Allow" instead of "Block". 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 has a test panel (accessibly via the rule editor) 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.

4.0 Quick Explanation of the Preferences Pane

5.0 Quick Explanation of the Rule Editor

6.0 Quick Explanation of Menu Items and Keyboard Shortcuts

7.0 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 enjoy PithHelmet, please take a moment to register your copy.

8.0 Revision History

v2.6.7 - released 2006-06-28

compatible with Safari 2.0.4 (from the 10.4.7 update)

v2.6.6 - released 2006-05-18

fixed support for NetNewsWire 2.1
fixed a few rare but unpleasant code bugs (asserts)
fixed a few translations

v2.6.5 - released 2006-03-04

Universal Binary (support for Intel Macs)
new rules for new and annoying ad techniques
added Russian translation

v2.6.4 - released 2005-01-14

added compatibility with Safari 2.0.3

v2.6.3 - released 2005-12-31

made the initial registration alert significantly less annoying for new users
added Russian translation
fixed: removed spurious logging to the console
fixed: bugs in the feed:// urls - especially with feedburner.

v2.6.2 - released 2005-11-01

changed installer and version check for Safari 2.0.2

v2.4.2 - released 2005-11-01

changed installer and version check for Safari 1.3.1

v2.6.1 - released 2005-08-07

added a command to quickly toogle blocking all plugins (Flash, QuickTime and others)
added a keyboard shortcut for purging all of the session cookie
added a menu item to completely disable PithHelmet's blocking code (it's in the Advanced submenu)
changed name of "Javascript Console" to "Javascript Editor" to combat confusion
fixed: spurious registration warnings in NetNewsWire/Shiira
fixed: bugs in the cookie code that could occasionally crash
fixed: rule wizard could crash in certain circumstances

v2.6 - released 2005-08-01

added new interactive rule wizard
added new wildcard style rules (similar to AdBlock)
added support for NetNewsWire Lite 2.0.1
added a menu item to Show PithHelmet Preferences
updated rule set
fixed: file descriptor leak in Machete
fixed: preferences would occasionally not show up

v2.5.2 - released 2005-06-01

added support for NetNewsWire Lite 2.0
added support for Shiira 1.0
updated rule set
fixed: version checking code
fixed: installer package

v2.5.1/v2.4.2/v2.3.3 - released 2005-05-05

fixed: occasional hang when accessing certain sites, this is the same fix applied to different versions

v2.5 - released 2005-04-29

compatibility release for Safari 2.0 on Mac OS X 10.4 (Tiger)

v2.4.1 - released 2005-04-27

removed support for Shiira
fixed: crash bug in the url tracker
fixed: cookie expiring (discard-on-quit now works properly)

v2.4 - released 2005-04-18

properly updated internal structure to match Safari 1.3 (compatible only with Safari 1.3)
content collapsing is now turned off by default due to bugs in WebCore/JavascriptCore
updated French and Italian translation
fixed: cookie blocking
fixed: GIF animation blocking

v2.3.2 - released 2005-04-27

compatible only with Safari 1.2.x
removed support for Shiira
fixed: crash bug in the url tracker

v2.3.1 - released 2005-04-17

fixed version checking
updated localizations

v2.3 - released 2005-03-21

added new check for host spoofing (homograph/IDN attacks)
added new options to aggressively attack popunder ads (off by default)
added pref to turn off the version check window unless there is an update
added Javascript console for interactive sessions (in the PithHelmet Debug menu)
added faster vs. safer mode for blocking (faster may crash some Java-enabled sites)
changed contextual menu to be on by default
fixed: bug in regex domain rules that prevented proper operation
fixed: rare crash on startup
fixed: rule set upgrading
fixed: intermittent crash with Java-enabled pages in tabs

Show Complete History

v2.2 - released 2005-01-07

matching engine 35% faster
content collapsing 2-40x faster (that is not a typo)
animated image preferences no longer add any overhead - fixes high CPU usage on sites using GIFs
automatic version checking
search filter in the cookie editor
proper sorting for cookies (groups by domain)
rule list supports find-as-you-type
allow custom "onLoad" javascript per site
menubar icon indicates enabled/disabled status
better validation in the Rule Editor prevents bad settings
custom css/javascript can be used to "theme" a web site with attached images
automatically resolves file urls with ~ (useful for theme images)
machete scripts now alert on incorrect file permissions
localized for French, German and Italian
new, optimized rule set (should be much better for users in Europe)
fixed: focus/rename issues in the rule list
fixed: rules were not saved properly on quit
fixed: custom css was not applied 100% of the time
fixed: Java/Javascript preferences were not saved reliably
fixed: rule tester crashed on malformed url
fixed: block referer did not work in certain cases
fixed: occasional appearances of the "spinning pinwheel of death"

v2.1.1 - released 2004-10-07

fixed default site rule to no longer delete cookies on exit
fixed bug with Machete popup

v2.1 - released 2004-09-26

overlapping Safari and PithHelmet preferences are properly synchronized
faster performance (starting up, quitting and general use)
smaller rules files
fixed potential crash bug when quitting Safari
fixed content collapsing to respect the block rules properly
fixed the "None Selected" option in the custom css and Machete file popups

v2.0.1 - released 2004-08-26

added preferences to move the PithHelmet menu or bury it under the Safari menu

v2.0 - released 2004-08-12

entirely new and improved blocking engine
simplied preferences for ad blocking and cookie privacy
Site Preferences - change Safari and PithHelmet settings per site
cookie filtering adds new privacy settings
Machete allows you to clean up or remix web sites with small scripts
drag-n-drop rule sharing - create rule files that are easy to share with friends via email
transmogrifier editor
enable/disable particular rules
works in other WebKit applications like Shiira
block sending the referrer header
cookie editor allows you to view cookies as they are sent
menu items for clearing site or session cookies

v0.7.3 - released 2004-07-02

redistributed with a new version of SIMBL to prevent it from b reaking with new releases of Safari
included new fix tool to correct occasional problems with the preferences pane not appearing
added Swedish localization

v0.7.2b - re-released 2004-06-06

added localizations for Italian, Japanese and Korean

v0.7.2a - re-released 2004-02-03

labeled as compatible with Safari 1.1 (v100) and Safari 1.2 (v125)

v0.7.2 - released 2003-11-16

compatible with Mac OS X 10.3 (Panther) Safari 1.1 (v100) only
fixed French and German localization

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.