> For the complete documentation index, see [llms.txt](https://burp-ai-agent.six2dez.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://burp-ai-agent.six2dez.com/getting-started/installation.md). # Installation ## Prerequisites 1. **Burp Suite 2026.2 or newer**, Community or Professional. The current source compiles against Montoya API `2026.2` and uses its scan-check interfaces. 2. **Java 21** for building from source. > Recent Burp versions include bundled Java runtime for extension execution. Separate Java is mainly needed for local builds. {% hint style="info" %} MCP TLS certificate generation launches the `keytool` binary from the active Java runtime. Use the documented Java 21 toolchain (or the runtime bundled with a compatible Burp build) and ensure `keytool` is present; the current project does not establish a blanket Java 8–25 compatibility guarantee. {% endhint %} ## Install Path There are two builds: the **BApp Store build** and the **GitHub full build**. [Which Build?](/getting-started/which-build.md) explains what each contains and what it needs from Burp. {% tabs %} {% tab title="BApp Store (not yet listed)" %} {% hint style="warning" %} Custom AI Agent is not listed in the BApp Store yet: the BApp Store build is going through PortSwigger's review in [extension-portal#231](https://github.com/PortSwigger/extension-portal/issues/231). {% endhint %} The BApp Store build (`./gradlew bappJar`) holds the 8 extension-native MCP tools and 7 AI backends (Burp AI and six HTTP backends), and sends AI requests only while Burp's "Use AI" setting is enabled for the extension. Until it is listed, download it from GitHub Releases (next tab) or build it yourself (last tab). See [Which Build?](/getting-started/which-build.md). {% endtab %} {% tab title="Download from Releases" %} 1. Open [GitHub Releases](https://github.com/six2dez/burp-ai-agent/releases). 2. Download one build. From v1.1.0, every release attaches both: * `Custom-AI-Agent-full-.jar`, the GitHub full build, with `Custom-AI-Agent-full-.jar.sha256`; * `Custom-AI-Agent-bapp-.jar`, the BApp Store build, with `Custom-AI-Agent-bapp-.jar.sha256`; * one `bom.json` (CycloneDX SBOM) for the release. [Which Build?](/getting-started/which-build.md) explains which one to pick. 3. Verify the JAR integrity (see [Verify JAR Integrity](#verify-jar-integrity-sha-256)) before loading. {% hint style="info" %} This documentation tracks the current source tree. A tagged release can lag changes on `main`; build from source when you need behavior documented as current-main hardening, and read the release notes before assuming it is present in an older JAR. {% endhint %} {% endtab %} {% tab title="Build from Source" %} 1. Clone repository: ```bash git clone https://github.com/six2dez/burp-ai-agent.git cd burp-ai-agent ``` 2. Build a fat JAR with JDK 21. Each build has its own task: ```bash # BApp Store build (8 extension-native MCP tools, 7 AI backends) ./gradlew clean bappJar # GitHub full build (all 59 MCP tools, 12 AI backends) ./gradlew clean fullJar ``` 3. Output paths: ``` build/libs/custom-ai-agent-bapp.jar # BApp Store build build/libs/Custom-AI-Agent-full-.jar # GitHub full build ``` 4. (Optional) Generate an SBOM alongside the JAR: ```bash ./gradlew cyclonedxBom --no-configuration-cache # Output: build/reports/sbom/bom.json ``` {% endtab %} {% endtabs %} ## Verify JAR Integrity (SHA-256) The GitHub release workflow publishes a `.sha256` checksum file (in `sha256sum` format) next to each JAR and one CycloneDX `bom.json` software bill of materials. Verify the JAR before loading it. The examples use the full build; for the BApp Store build, use `Custom-AI-Agent-bapp-.jar` and its `.sha256`: {% tabs %} {% tab title="macOS / Linux" %} ```bash # Run in the folder that holds the JAR and its .sha256 file sha256sum -c Custom-AI-Agent-full-.jar.sha256 # Linux shasum -a 256 -c Custom-AI-Agent-full-.jar.sha256 # macOS ``` {% endtab %} {% tab title="Windows (PowerShell)" %} ```powershell Get-FileHash -Algorithm SHA256 Custom-AI-Agent-full-.jar ``` {% endtab %} {% endtabs %} If the two values differ, **do not load the JAR** — re-download from the official release page. ## Load into Burp Suite Load only one build. Both builds register as **Custom AI Agent**; unload any other copy before you add a JAR (see [Which Build?](/getting-started/which-build.md#load-only-one-build)). 1. Open **Extensions -> Installed -> Add**. 2. Select extension type `Java`. 3. Choose the JAR file. 4. Complete load wizard. ![Screenshot: Burp extensions add](https://741304880-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FaQ3pR328GUzNEoYZ2fgc%2Fuploads%2Fgit-blob-8a1ddc304c64d9a9830b0583d0269a4c78a384df%2Fburp-extensions-add.png?alt=media) ## Verify Installation Expected indicators: * extension loads without startup errors, * the extension appears as **Custom AI Agent** in **Extensions -> Installed**, and its **Custom AI Agent** tab appears in Burp main navigation. > The extension registers its display name as **Custom AI Agent** to distinguish it from Burp's built-in **Burp AI** provider; that is the name shown in Burp's Extensions list and Suite tab, and the name intended for the still-pending BApp Store listing.
Burp with the Custom AI Agent suite tab visible after extension load
## Runtime Directory On first start, `~/.burp-ai-agent/` is created: ``` ~/.burp-ai-agent/ ├── audit.jsonl ├── bundles/ ├── contexts/ ├── backends/ # GitHub full build only: drop-in backend JARs ├── cache/ # created on demand by PersistentPromptCache (per project) ├── certs/ │ └── mcp-keystore.p12 ├── logs/ # created on demand by the opt-in rolling AI Request Logger └── AGENTS/ ├── default # plain text file whose content names the active profile (no extension) ├── pentester.md ├── bughunter.md └── auditor.md ``` The directory keeps the legacy `burp-ai-agent` name on disk to preserve upgrades for existing users; the product itself is now called **Custom AI Agent**. See [Configuration Directory](/reference/configuration-directory.md) for a per-entry reference. Custom additions: * profiles: `~/.burp-ai-agent/AGENTS/*.md` ([Agent Profiles](/user-guide/agent-profiles.md)) * backend plugins (GitHub full build only; the BApp Store build never creates or loads this directory): `~/.burp-ai-agent/backends/` ([Adding a Backend](/developer/adding-backend.md)) ## Troubleshooting * Extension load failure: inspect Burp Errors/Output tabs and Java version. * Tab missing: ensure extension is enabled. * Permission errors: ensure write access to `~/.burp-ai-agent/`. ## Next Steps Continue with [Quick Start](/getting-started/quick-start.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://burp-ai-agent.six2dez.com/getting-started/installation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.