DOCSEARCHbyAlgolia
Submit Docs

burp-rest-api

repository·master·Indexed 20 days ago

https://github.com/vmware-archive/burp-rest-api

A REST/JSON interface for Burp Suite that enables automation of web scanning, spidering, and orchestration of security tools. It includes a Java client (BurpClient.java) and provides a Swagger-documented API for interacting with Burp Suite Professional.

Tokens
1.4K
Snippets
5
Records
9
Agent score
69%

What's inside burp-rest-api

  2. Install and run burp-rest-api

    master

    To use burp-rest-api, follow these steps:

    1. Download the JAR: Get the latest burp-rest-api JAR (e.g., burp-rest-api-2.3.2.jar) from the releases page.
    2. Prepare Burp Suite: Place the burp-rest-api JAR in the same directory as the original standalone Burp Suite Professional JAR (e.g., burpsuite_pro_v2025.6.3.jar).
      • Warning: Do NOT use the burpsuite_pro.jar from a local Burp Suite installation; use the standalone JAR from PortSwigger.
      • Architecture Note: Running on ARM64 may cause issues with the Burp Browser, affecting spidering and scanning. x86 is recommended.
    3. Run with Java 21: Execute the following command, ensuring you update the filenames to match your specific JAR versions.

    Linux/macOS:

    java --add-opens=java.desktop/javax.swing=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED -cp "burpsuite_pro.jar:burp-rest-api-2.3.2.jar" org.springframework.boot.loader.launch.JarLauncher

    Windows:

    java --add-opens=java.desktop/javax.swing=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED -cp "burpsuite_pro.jar;burp-rest-api-2.3.2.jar" org.springframework.boot.loader.launch.JarLauncher
    java --add-opens=java.desktop/javax.swing=ALL-UNNAMED --add-opens=java.base/java.lang=ALL-UNNAMED -cp "burpsuite_pro.jar:burp-rest-api-2.3.2.jar" org.springframework.boot.loader.launch.JarLauncher

  3. Customize the Burp Proxy Listener address and port

    master

    The Burp Proxy Listener is a Burp Suite configuration rather than a burp-rest-api setting. To customize the binding address and port, use a custom Burp project option file containing a request_listeners configuration block.

    "request_listeners":[
    {
        "certificate_mode":"per_host",
        "listen_mode":"192.168.1.1",
        "listener_port":8080,
        "running":true
    }
]

  5. Access the HTTP API documentation

    master

    The REST API is documented using Swagger. Once the application is running (default port 8090), you can access the documentation and interactive UI at the following endpoints:

    • API Docs (JSON): http://localhost:8090/v3/api-docs
    • Swagger UI: http://localhost:8090/swagger-ui/index.html#

  6. Configure burp-rest-api runtime settings

    master

    Use the following command-line arguments to configure the extension's behavior:

    ArgumentDescription
    --headless.mode=<true/false>Set to false to run Burp Suite in UI mode. Default is based on the system property java.awt.headless.
    --server.port=<port_number>Sets the REST API endpoint port. Shorthand: --port=<port_number>.
    --server.address=<network address>Sets the network address to which the REST API binds. Shorthand: --address=<address_ip>.
    --apikey=<customApiKey>Enables API key authentication for all paths under /burp/. When enabled, every HTTP request must include the header: API-KEY: <customApiKey>
    --burp.ext=<filename.{jar,rb,py}>Loads specific Burp extensions during startup. This flag can be repeated.
    --burp.jar=<filename.jar>Note: Only works on Java <= 1.8. For newer Java versions, use the provided launcher scripts.
    --headless.mode=false
--server.port=8081
--server.address=192.168.1.2
--apikey=mySecretKey

  7. Ensure correct Java environment for Burp Suite and burp-rest-api

    master

    Both Burp Suite and burp-rest-api require Java x64 to run. If you encounter activation issues or runtime errors, verify your JAVA_HOME environment variable and ensure the active Java Runtime version matches JAVA_HOME.

    Verifying Java version

    • Linux (Debian/Ubuntu): Use sudo update-alternatives --config java.
    • Linux (Archlinux): Use archlinux-java.
    • Windows: Check via Control Panel -> Java -> (General)(Update)Java -> View.

    Backing up activation preferences

    Before changing JVMs or upgrading JDKs, back up your Burp activation preferences:

    • Windows: Back up the registry key Computer\HKEY_CURRENT_USER\Software\JavaSoft\Prefs\burp.
    • Linux: Back up the folder ~/.java/.userPrefs/burp/.

  8. Pass arguments to Burp Suite

    master

    Arguments passed to the burp-rest-api JAR are forwarded directly to the Burp Suite JAR. You can use these to manage Burp projects:

    • --project-file=<filename>: Opens a specific Data Project File. Creates a new project if it doesn't exist.
    • --config-file=<filename>: Opens the project using a specific Project Configuration File. Can be used multiple times.
    • --user-config-file=<filename>: Opens the project using a specific User Configuration File. Can be used multiple times.
    --project-file=my_project.burp

  9. Customize the burp-rest-api server address and port

    master

    You can customize the IP address and port used by the burp-rest-api RPC mechanism at runtime using the following command line arguments:

    • --server.address: The IP address to bind to.
    • --server.port: The port to bind to.
    --server.address <address> --server.port <port>