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