How to Read the Source Code of Chrome and Firefox Extensions

I am writing a Chrome extension (more on that next week !) and so far the experience has been excellent. Google has a decent set of API and has a good tutorial to get you started on developing extensions. But other than that I did not find many good resources in net for developing Chrome extensions. So I used the old way of reading the code of other good Chrome extensions to learn the ropes. Since the extension I write emulates a Firefox extension, I had to read some code of Firefox extensions too !

So in this post, I will talk about how to go about reading the code of Chrome/Firefox extensions and experimenting with them. I intend to write a more detailed post of developing/debugging Chrome extensions once I finish my extension.

A Word Of Caution

1) It is quite easy to mess with the extension’s application logic or its internal data structures. So be a little cautious when you are playing with the extension internals.
2) Also when you read the code, you might be tempted to reuse some of them. Just cross check with the extension’s license. Most of them have fairly liberal licenses. But it does not hurt to verify.

I will talk about Chrome extensions first and later will discuss the Firefox extensions.

Getting the Chrome Extension Id

One of the first things to know before playing with the extension is the extension id. There are two ways to know the id of an extension.

If the extension is installed in your computer, then you can get the id from the Extensions menu. Click on the wrench icon and select Extensions. In the Extensions page, each extension will be listed with some details like its name, description, version and most importantly an id. The id is a strange looking string with around 32 characters. For eg hoildcfdkjkefngkheffkiepkdcfdiok .

If you have not installed the extension, you can get the extension id by going to the extension’s page in the official Chrome extensions page . The extension id corresponds to the xxxx in the sample url – https://chrome.google.com/extensions/detail/xxxx.

Reading the Chrome Extension Source Code

I have two OSes in my system (Ubuntu and Windows 7). So I will explain the process for these two OS. But I am sure the process for other OS will be very similar.

In my Ubuntu system, for an extension with id say xxxx, the source code is located at ~/.config/google-chrome/Default/Extensions/xxxx . In this case Default is the name of my profile. If you have a different profile, substitute it. This is the root folder and it has child folder with the name of the version. Once you go in, you can see the extension code . Have fun !

In Windows 7, you can see the extension source folder at "C:\Users\<username>\AppData\Local\Google\Chrome\User Data\Default\Extensions\xxxx" . Again replace username with your login name, Default with your profile name if you use alternate profile.

Some times, you do not want to install an extension to read the source code. In this case, all you need to do is to download the crx file. At Google’s office Chrome extension page, to download the crx file , go to the extension’s details page (which is of the format https://chrome.google.com/extensions/detail/extensionid ) . Right click on the "Install" button and select "Save Link As". You will get a crx file. Now all you need to do is to use unzip command to extract the contents. If you are in Windows , any extraction software that can extract zip files will do. It might whine about some missing headers. Ignore it. You will get the extension code in the extracted folder.

Playing with Chrome Extension’s Local Storage

One of the coolest feature in HTML 5 is Local Storage which allows to store application info in a hash like data structure (which is usually internally a SQLite database). Most of the extensions use it extensively. So you can learn a lot about their internals by exploring what they store in the local storage. Note that Local Storage usually contains information that are critical to the proper execution of the extension and tampering it is not a good idea !

In Ubuntu, you can take a look at the extension’s local storage file at "~/.config/google-chrome/Default/Local Storage". In Windows 7, you can look at the file at "C:\Users\<username>\AppData\Local\Google\Chrome\User Data\Default\Local Storage". The local storage is nothing but a SQLite file and will have a name like "chrome-extension_xxxx_num.localstorage" where xxxx is the extension id and num is a number (usually 0).

The contents are stored in a table called "ItemTable". You will need a SQLite program to view its contents. I think, if you are in Lucid Lynx (Ubuntu 10.04) , you will already have it in the system (sqlite3) . Else you can install it via update manager. I am not sure what is the best program to view SQLite databases in Windows.

If you do not want to dirty your hand with command line tools , then check out instructions later at the section "Playing with Live Chrome Extensions" .

Playing with Chrome Extension’s Web Databases

HTML 5 also allows an extension to have arbitrarily structured databases. Currently I see only SQLite databases. For my extension, I really wanted to use databases instead of the local storage but I did not find enough good references on using Web databases. Also the problem of migrating one database version structure to another was a nightmare. So I did not invest much time in exploring databases. Again, I think very few extensions use Web Databases (None of the ones I sampled used it !).

In Ubuntu, you can see the database file at ~/.config/google-chrome/Default/databases . In Windows 7, you can see it at C:\Users\<username>\AppData\Local\Google\Chrome\User Data\Default\databases. As above, this is a SQLite file and you can explore it using a SQLite database browser.

Other Stuff

As you have noticed, the folder ~/.config/google-chrome/Default (In Ubuntu) and C:\Users\<username>\AppData\Local\Google\Chrome\User Data\Default\ (in Windows 7) have lot of good stuff. Play around the files. But be cautious as fooling around can cause the extension to malfunction and at worst, crash of Google Chrome.

Playing with Live Chrome Extensions

Chrome’s Developer Tools is a delight. It packs lot of very nifty functions. I will talk more about it in future. If you want to know all about a Chrome extension (especially Js files and local storage) without much pain, Developer tools is the way to go.

Go to the extensions menu (Wrench icon -> Extensions). Lets say you want to dig into extension xxxx. Go to the xxxx’s section in that page. You can see that there is a line "Inspect active views:" . And it usually lists "background.html" (or something similar like bg.html) . If you are viewing some other html file of the extension (say options.html, help.html etc) , then you will see them here too. But you should be able to see background.html (or some background file) always. Click on the link "background.html".

It should open Chrome’s Developer Tools which has many tabs. "Elements" tab has the page’s html content. "Scripts" tab displays all the js file included by the background file. You can read/view all the js file by clicking on the drop down or by using the left/right button. It also has a decent javascript debugger.

My favorite tab is however "Storage". It shows all the extension’s internal stuff like its local storage, web databases (if available), sessions and cookies. So if you want to view the local storage contents without using SQLite program, this is your (GUI) way. It will show all the keys and values. It even allows you to edit/delete the storage !

The last tab is "Console". Most of the extensions typically put lot of log info. So you can take a look at the console and get valuable information about the execution trace. Another thing that you can do is call the internal (JS) functions of the extension. The commands you type run in the context of the extension/page. Its a great way to tinker with the extension. I refrain from giving any direct example but it is trivial to experiment if you had some basic stuff with Firebug or something similar.

The other tabs are very useful but needs a lot more space to explain. But if your aim is to know the internals , then the tabs I mentioned are more than enough.

Reading Firefox Extensions

I did not dig much into Firefox extensions so this section will be brief. In the case of Firefox , getting the extension id is a bit tricky. So I primarily depended on grep to find the information. Most of the extension code will be at "~/.mozilla/firefox/<profile>/extensions/" (In Ubuntu). Most extensions have strange names although some popular ones have their named folder (eg ubiquity is under ‘ubiquity@labs.mozilla.com’. Ditto for foxmarks, listit, moonlight etc). Firefox extensions are also written primarily in Javascript although for UI you need to use XUL.

Misc Stuff – Dealing with Obfuscation

Some times you can see that the code is obfuscated. Some time the intent is to minify the file, some times it is not ! It may even be encoded using some simple scheme like base64. If you find that the code you want to read is unreadble, go to some JS beautifier site. My favorite is JS Beautifier . It is excellent, very flexible with lot of options and can even handle various packers.

Resources

There are lot of good resources available in net.

1. Google Chrome Extensions Tutorial
This page has a pretty good tutorial and a good API documentation . Their page on debugging had lot of useful information .

2. SQLite
If you are a command line person like me, you will want to read about SQLite to browse local storage or databases content. SQLite allows most basic SQL commands although the other commands are non standard (eg .tables, .schema etc) . Check out their docs.

3. Local Storage and Web Databases These are HTML 5 features and resources can be found in many places in the internet.