README.rdoc in emonti-buby-1.0.0 vs README.rdoc in emonti-buby-1.0.1
- old
+ new
@@ -27,70 +27,83 @@
The java BurpExtender included with Buby is an implementation of IBurpExtender which is the interface API supplied by PortSwigger for writing extensions to Burp Suite. It mostly acts as a method proxy between Ruby and Java, doing very little except event handler proxying between the java and ruby runtimes with run-time type conversion as needed.
== REQUIREMENTS:
-Buby requires a copy of Burp Suite. Not sure if this will work with the unlicensed trial version. Point is, you'll need to get this separately since it's a trade-marked commercial product of PortSwigger Ltd.
+* JRuby - http://jruby.org
+ Burp is Java based and the extension is developed specifically around JRuby.
+ The C version of ruby will not work.
-See http://portswigger.net/
+* Burp (pro or free version): Buby is useless without a copy of Burp.
+ Buby has been tested successfully with both Burp Suite free and pro versions
+ 1.2, 1.2.01, and 1.2.05. See http://portswigger.net/
-== BUILD/INSTALLATION:
+== BUILD/INSTALL:
=== Gem
You should be able to get up and running with just the gem and a copy of Burp.
I've packaged up a pre-built buby.jar file containing the required classes
minus ofcourse, Burp itself.
gem install emonti-buby
-See manual step #5 below. For best results, you'll still want to make your
-burp.jar available in the ruby runtime library path.
+* IMPORTANT: The buby gem doesn't include a copy of Burp! See manual step #5
+below. For best results, you'll still want to make your burp.jar available
+in the ruby runtime library path.
=== Manual
Here are manual instructions if you want or need to build things yourself:
-1. Download buby from github
+Step 1. Download buby from github
git clone git://github.com/emonti/buby.git
-2. Compile BurpExtender.java. Include jruby.jar in the classpath:
+Step 2. Compile BurpExtender.java. Include jruby.jar in the classpath:
cd buby/java/src
javac -classpath (.../jruby/root)/lib/jruby.jar:. BurpExtender.java
-3. Create a new lib/buby.jar
+Step 3. Create a new lib/buby.jar
- jar cvf ../../lib/buby.jar .
+ jar cvf ../buby.jar .
-4. Copy the buby library to your JRuby library path. Your location may vary:
+Note: At this point you can also just do a rake gem:install from the
+top-level, which will install a local 'buby' gem instead of 'emonti-buby'. If
+you do this, just skip the next step and move onto step #5.
- cp buby.jar buby.rb (.../jruby)/lib/site_ruby/1.8/
+Step 4. Copy buby.rb and jar to your JRuby lib-path. Locations may vary:
-5. The last part is a bit tricky. Burp Suite itself is obviously not packaged
- with buby. You'll need to somehow put your 'burp.jar' in a place where
- it is visible in the JRuby RUBY-LIB paths. While there are a few other
- methods added for pulling in 'burp.jar' during run-time, this one is by far
- the least amount of hassle in the long run.
+ cd ../../
+ cp lib/buby.rb (.../jruby)/lib/site_ruby/1.8/
+ cp -p java/buby.jar (.../jruby)/lib/site_ruby/1.8/java/buby.jar
-Here's a quick way to see jruby's runtime lib-path:
+Step 5.
+
+The last part is a bit tricky. Burp Suite itself is obviously not included
+with buby. You'll want to somehow put your 'burp.jar' in a place where it
+is visible in the JRuby RUBY-LIB paths. There are a few other ways of pulling
+in Burp during runtime, but this method probably involves the least amount of
+hassle in the long run.
+
+JRuby gives you a 'java' site_ruby directory for this kind of thing. Here's a
+quick way to see jruby's runtime lib-path:
jruby -e 'puts $:'
There is usually a '.../jruby/lib/1.8/java' directory reference in there,
-though the directory may not exist in your set-up yet and you may need to
-create it.
+though the actual directory may need to be created.
-Note: I keep my jruby installation under my home directory. Also, I think
-my jruby version is out of date at the time of writing. But your configuration
-should still be relatively close to this.
+Here's how I do it. I have jruby installation under my home directory.
+Your configuration details can be substituted below.
-Here's how I have mine set up.
-
mkdir ~/jruby-1.1.5/lib/ruby/1.8/java
ln -s ~/tools/burp.jar ~/jruby-1.1.5/lib/ruby/1.8/java/burp.jar
-Once this is done, everything should be ready to go.
+Now everything should be ready to go. Try at least the first few parts of the
+test below to confirm everything is set up. Or if you installed the gem, just
+run 'buby' from the command-line.
+
== TEST AND USAGE EXAMPLE:
The gem includes a command-line tool called 'buby' but it doesn't do much right
now. You can, however use this as a minimal test to confirm whether Burp can be