Use VS Code development and debugging Burp Suite extension

This translation from: https://parsiya.net/blog/2019-12-02-developing-and-debugging-java-burp-extensions-with-visual-studio-code/

00 Overview

A few days ago, I posted a Bug Diaries Burp extension, which is a Burp extension program aimed at the community (free) version Burp Issues mimic the function. For some reason, I decided to rewrite it in Java. This is the first I learned to switch to the Java series.

This section talking about how to set up the environment to use Visual Studio Code for development, such as code hints, and most importantly, Gradle build and debugging things.

You can clone your repositories to skip some of the steps in the blog, and if you are not familiar Gradle Burp development, I still suggest you direct clone of the following warehouse:

• https://github.com/parsiya/burp-sample-extension-java

01 Bug diary when using Python

The original extension is written in Python. Until today, all my Burp extensions are written in Python, in this process, I record what I learned:

• Swing in Python Burp Extensions - Part 1

• Swing in Python Burp Extensions - Part 2 - NetBeans and TableModels

• Swing in Python Burp Extensions - Part 3 - Tips and Tricks

I Burp's IMesageEditors encountered a lot of problems when you right-click on the feature is enabled. In short, I decided to switch to Java rewrite extension.

The following is my method deployed in the development environment of the virtual machine.

02 installed Visual Studio Code

1. Install VS Code .

2. Install Java Expansion Pack

https://aka.ms/vscode-java-installer-win on to the VS Code also has a program to install Java developers, but I did not use it.

03 OpenJDK installation

Because Oracle strict licensing requirements, so I use OpenJDK.

1. Download OpenJDK 11 (please refer to the following reasons). I used AdoptOpenJDK.net installer.

   • Red Hat in https://developers.redhat.com/products/openjdk/download also install the package, but you need a free developer account.

2. If you manually extract the OpenJDK, modify bad environment variables:

   • Set JAVA_HOMEto C:Program Files\path\to\jdk\. (Not including the bindirectory)

     (For my JDK it is C:\Program Files\AdoptOpenJDK\jdk-11.0.5.10-hotspot)

   • Add the JDK bindirectory to the PATHenvironment variable

Now execution java -versionshould return something like this (remember setting up the PATHre-opened after a new command line):

openjdk version "11.0.5" 2019-10-15
OpenJDK Runtime Environment AdoptOpenJDK (build 11.0.5+10)
OpenJDK 64-Bit Server VM AdoptOpenJDK (build 11.0.5+10,mixed mode

Note: If you install JDK version 13 or higher, you can not use Burp exe file to load your extension. As of December 2019, Burp the exefile has been built by a JDK 11 (version 55.0) bundled JRE. If you try to load the extension with a higher version of Java built, this error occurs:

java.lang.UnsupportedClassVersionError: burp/BurpExtender has been compiled by a more recent version of the Java Runtime (class file version 57.0), this version of the Java Runtime only recognizes class file versions up to 55.0

Solution:

1. Use an earlier version to build the extension (recommended)

2. Using the installed Java jar files to run directly Burp

   • Actually I do not know if it is valid, if you try to succeed, please tell me

04 Gradle

Gradle no installer, the following steps need to be installed manually.

1. From https://gradle.org/releases/ download the latest version

2. Unzip it to C:\Program Files( C盘say: "! But I prefer to file")

   • In my virtual machine, it will eventually located C:\Program Files\gradle-6.0.1

3. Will binbe added to the directoryPATH

   • C:\Program Files\gradle-6.0.1\bin

Now execution gradle -versionshould return something like this:

gradle -version
​
------------------------------------------------------------
Gradle 6.0.1
------------------------------------------------------------
​
Build time:   2019-11-18 20:25:01 UTC
Revision:     fad121066a68c4701acd362daf4287a7c309a0f5
​
Kotlin:       1.3.50
Groovy:       2.5.8
Ant:         Apache Ant(TM) version 1.10.7 compiled on September 1 2019
JVM:          11.0.5 (AdoptOpenJDK 11.0.5+10)
OS:           Windows 10 10.0 amd64

05 is set to Gradle

Create a directory for developing extensions, in this directory, run the following command:

• gradle init --type basic

• Press twice Enterto select the default value

• If you want to create a specific extension names, you can customize this step in the project name, followed by settings.gradlemodification

This step will complete the creation of a bunch of directories and files.

06 build.gradle

Open build.gradleand paste in the following.

// Apply the Java plugin
apply plugin: 'java'
​
// Use Maven (because Burp Extender is on Maven)
repositories {
     mavenCentral()
}
​
dependencies {
    // Add the Burp Extender interface
    compile 'net.portswigger.burp.extender:burp-extender-api:2.1'
}
​
sourceSets {
    main {
        java {
            // Set the source directory to "src"
            srcDir 'src'
       }
   }
}
​
// Create a task for bundling all dependencies into a jar file.
task bigJar(type: Jar) {
    baseName = project.name + '-all'
    from { configurations.compile.collect { it.isDirectory() ? it : zipTree(it) } }
    with jar
}

Read the comments in the file to see the function of each part, the most important part is to add Burp Maven repositor Extender interface , which provides support and build with IntelliCode for us (iT's Ai BaSeD !! 1!) It is also important code hints Features.

Other additional dependencies can be like Burp extender interface as been added. For example, it can be added Google's Gson Version 2.8.6 :

dependencies {
    // Add the Burp Extender interface
    compile 'net.portswigger.burp.extender:burp-extender-api:2.1'
    compile 'com.google.code.gson:gson:2.8.6'
}

07 Gradle Wrapper

Whether local Gradle version number, Gradle Wrapper is a way to get reliable construction. Please note that you need to install Gradle Wrapper.

If you just want to start Wrapper, you have to first install Gradle. Executed in the extensions directory gradle wrapper. In order to build the project using the Wrapper, please put your command gradleis replaced with gradlew(* nix) or gradlew.bat(Windows), for example gradlew.bat build.

08 Created the extension skeleton

1. Create a src\burpdirectory, the directory will contain burpthe package

   • So the package will be placed srcin the directory

2. In src/burpCreate a file named in BurpExtender.javafile

   • The file extension will be the entry point

   

3. Edit BurpExtender.javaand add the code:

package burp;
​
public class BurpExtender implements IBurpExtender
{
    //
    // implement IBurpExtender
    //
    @Override
    public void registerExtenderCallbacks(IBurpExtenderCallbacks callbacks)
   {
        // set our extension name
        callbacks.setExtensionName("Burp Sample Extension Java");
   }
}

Note: If your extension is only one package (or several files), you can put all your files directly into srcthe directory

09 VS Code configuration tasks

To make the code easier to knock you, we bigjarassign the task to a default Gradle VS Code of build tasks, it is important, if your extension using a non Burp dependencies (like the above gson). In this case, you need to publish this jar file.

1. Press Ctrl+Shift+Por F1opening command panel VS Code

2. Input taskand selectConfigure Default Build Task

3. select Create tasks.json file from template

4. select Others

   • VS Code will create the .vscode\tasks.jsonfile

5. Open .vscode\tasks.jsonand paste into the following:

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
       {
            "label": "gradle",
            "type": "shell",
            "command": "gradle bigjar",
            // "command": "gradlew.bat bigjar", // Wrapper on Windows
            // "command": "gradlew bigjar",     // Wrapper on *nix
            "group": {
                "kind": "build",
                "isDefault": true
           }
       }
   ]
}

Now we can build the project:

1. Press Ctrl+Shift+B. Recommendation, so more quickly and looks very 1337 (hacker slang).

2. Terminal (菜单) > Run Task (子菜单) > gradle

3. Open a command panel, input taskselectRun Build Task

That will be executed once and download Burp Extender interface to build the library, the output file will be stored in a jar build\libs\burp-sample-extension-java-all.jar

10 Set IntelliCode

Our building work as usual, but you may have noticed, VS Code does not recognize from burpthe interface imported package.

Each time you add a new dependent (otherwise we will encounter the same mistake again), we need to clean up the Java language server.

1. Use Ctrl+Shift+Por F1open command panel VS Code

2. Input java cleanand selectJava Clean the Java language server workspace

3. When asked we choose to restart VS Code

4. Now we have IntelliCode support

Note: This is the most vscode-javascalable solution of the problem.

11 start writing Burp extension

Let's add some code to the extension, to show how to test the extension after each compilation.

Modify BurpExtender.javahow we look IntelliCode is easier to write code.

package burp;
​
public class BurpExtender implements IBurpExtender
{
    //
    // implement IBurpExtender
    //
    @Override
    public void registerExtenderCallbacks(IBurpExtenderCallbacks callbacks)
   {
        // set our extension name
        callbacks.setExtensionName("Burp Sample Extension Java");
        String fileName = callbacks.getExtensionFilename();
        callbacks.printOutput(fileName);
   }
}

这段代码打印了扩展文件的名字到控制台。使用 Ctrl+Shift+B 编译扩展。

jar 文件会出现在 build\libs目录下。

安装扩展：

1. 在第二个监视器（屏幕）中启动 Burp

2. 通过 Window (菜单) > Detach Extender 打开 Extender 窗口

3. 按下 windows+左箭头 将其放置到屏幕的一边

4. Windows 会显示其它进程的列表，要我选择一个放到屏幕的另一遍

5. 选择 Burp，以便 Extender 和 Burp 并排出现在第二个屏幕中

6. 点住这两个窗口之间的边界以调整其大小

我的扩展开发周期是：

1. 在监视器1中编辑 VS Code 中的代码

2. 按下 Ctrl+Shift+B 进行编译

3. 通过 Ctrl+鼠标左键 选中 Extender 中扩展前面的复选框来重新加载它（在监视器2中）

4. 在 Burp 中使用扩展（监视器2）

12 使用 VS Code 调试扩展

这是本篇文章最重要的一部分，我将讨论如何在 VS Code 中调试扩展程序。环顾四周，我只能找到这些参考资料：

• Eric Gruber 在 https://blog.netspi.com/debugging-burp-extensions/ 上的扩展程序调试展示了如何使用 IntelliJ 来调试 Burp，它给了我使用 jdwp 的想法。

• Derek（@StackCrash）在其博客 https://www.itsecguy.com/my-first-burp-suite-extension/ 中提到，将 burp.StatBurp 添加到项目属性的 Run 部分即可。

  （这与 Dafydd Stuttard 在 Burp support ticket 中所说的一致，“将 Burp JAR文件作为库添加到项目中，然后通过在 burp.StartBurp.main() 中调用 main 方法来启动 Burp”）

VS Code 的 Java 扩展包中自带一个 Java 调试器，要使用它，我们需要使用以下命令行选项运行 Burp：

• -agentlib:jdwp=transport=dt_socket,address=localhost:8000,server=y,suspend=n

这将 localhost:80000 上运行调试服务器。请注意，互联网上的大多数示例都只是以端口来运行，这样服务器会默认监听 0.0.0.0，这样显然不好（除非你从远程主机来进行调试）。

接下来，我们必须使用以下参数运行 Burp 的 jar 文件。Burp 的 jar 文件默认安装在以下路径：

• C:\Program Files\BurpSuiteCommunity\burpsuite_community.jar

完整的命令：

java -agentlib:jdwp=transport=dt_socket,address=localhost:8000,server=y,suspend=n
    -jar "C:\Program Files\BurpSuiteCommunity\burpsuite_community.jar"

• 提示：使用这个作为快捷方式，以便你一直在你的开发环境虚拟机中调试 Burp

• 你可能会得到关于 JDK 未被 Burp 测试通过的错误，忽略它

13 使用 Burp 的捆绑 JRE

你可能已经在 Burp 的目录中看到了 BurpSuiteCommunity.vmoptions 文件，我们可以向里面添加运行时参数，向文件中添加下面一行来启用调试：

-agentlib:jdwp=transport=dt_socket,address=localhost:8000,server=y,suspend=n

现在我们可以运行 exe 然后调试我们的扩展程序。我已经在 Git 仓库中包含了一个 .vmoptions 样本文件 。

接下来，我们必须在 VS Code 中启动 Java 调试器并连接到调试端口。在 callbacks.printOutput(fileName); 这一行设置断点，然后选择 Debug (菜单) > Start Debugging 或 按下 F5。

这将创建并打开 .vscode\launch.json 文件 ，粘贴下面这段代码到里面并保存它：

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "java",
            "name": "BurpExtension",
            "request": "attach",
            "hostName": "localhost",
            "port": 8000 // Change this if you had set a different debug port.
        }
    ]
}

这个文件非常简单，唯一重要的参数就是 hostname 和 port ，它们应该指向上面的调试端口（localhost:8000）。

再次开始调试，Windows 防火墙可能会弹出来。如果可以，并且你不是在调试一台远程计算机，请按取消。如果防火墙对话框没关掉但调试器已经超时了，就按 F5 重新调试。

待调试器被附加后，通过在复选框上 Ctrl+鼠标右击 来重新加载扩展，然后能看到调试器成功断在断点处。

Save the path 14 to a different extension in

If you look in buildthe directory, you will see a lot of class files, we do not want these appear in the source code control, so to buildadd a directory to .gitignorethe file is wise, but this means our ultimate jar files will be ignored, we hopes to eventually appear jar file in the repository, so that people can download and use it.

We can modify the build.gradlefile libDirNameto change the storage path extension jar files.

libsDirName = "../@jar"

This configuration will copy the file to the final jar @jar\burp-sample-extension-java-all.jar

15 summary

Today we learned anything from this article?

1. Create a simple extension of the Java Burp

2. Compile and install Gradle extension

3. Open Java IntelliCode in the VS Code

4. Debugging Java Burp expansion in the VS Code

5. Change the file storage path of jar