> 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/reference/configuration-directory.md). # Configuration Directory The extension stores all runtime state under a single directory in the user's home folder. The directory keeps the legacy `burp-ai-agent` name for upgrade compatibility — see [Legacy Identifier Reference](#legacy-identifier-reference) below for why the product name and the on-disk name diverge. ## Location | Platform | Path | | -------- | ------------------------------------------------------------------------ | | macOS | `~/.burp-ai-agent/` | | Linux | `~/.burp-ai-agent/` | | Windows | `%USERPROFILE%\.burp-ai-agent\` (e.g., `C:\Users\\.burp-ai-agent\`) | The directory is created on first start. `AGENTS/` is populated with bundled profiles at the same time. ## Layout ``` ~/.burp-ai-agent/ ├── audit.jsonl ├── bundles/ ├── contexts/ ├── cache/ │ └── / │ └── .json ├── backends/ │ └── my-backend.jar # optional drop-in ├── AGENTS/ │ ├── default # plain-text marker with the active profile name │ ├── pentester.md │ ├── bughunter.md │ ├── auditor.md │ └── .md # your profiles ├── certs/ │ └── mcp-keystore.p12 └── logs/ # created on demand ├── ai-request-log.jsonl └── ai-request-log.1.jsonl ``` ## Entry Reference | Entry | Created by | Purpose | Contains secrets? | | --------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `audit.jsonl` | `AuditLogger` when **Audit Logging** is enabled | Append-oriented JSONL of prompt, scanner, and MCP events with per-event SHA-256 payload hashes. | Yes. It reflects the mode and carrier coverage active when each event was created. | | `bundles/` | `AuditLogger.writePromptBundle` | `PromptBundle` JSON snapshots of dispatched prompt text and embedded context for reproducibility. A ZIP-export helper exists in code but has no production UI/caller in the current release. | Yes. Treat as engagement evidence, not sanitized public output. | | `contexts/` | `AuditLogger` initialization | Reserved directory. The runtime creates it, but no production caller currently invokes `writeContextFile`; bundle JSON embeds `contextJson` directly. | Empty in normal current operation; treat future contents as sensitive. | | `cache//` | `PersistentPromptCache` | Per-project on-disk cache of parsed scanner AI results. The directory name is the first eight characters of `api.project().id()` (or `default` on lookup failure); JSON files are keyed by prompt SHA-256. TTL and max size come from **Passive Scanner** settings. | Potentially. Model output can repeat source values, and cached entries are not retroactively rewritten when privacy mode changes. | | `backends/*.jar` | User | Drop-in backend JARs loaded via `ServiceLoader` at startup; see [Adding a Backend](/developer/adding-backend.md). | Depends on the JAR. | | `AGENTS/*.md` | Extension at first launch + user | Agent profiles. Editable; changes are picked up on the next action without restart. | No. | | `AGENTS/default` | `AgentProfileLoader` | Plain-text marker file with the active profile name (matches a sibling `*.md`). | No. | | `certs/mcp-keystore.p12` | `McpTls` auto-generation | PKCS12 keystore for the MCP TLS listener (RSA 2048 / SHA256withRSA / 365 d / `CN=burp-mcp`). | Yes — keystore password is stored in Burp preferences. | | `logs/*.jsonl` | `AiRequestLogger` when rolling persistence is enabled via JVM properties | Rolling JSONL copies of the in-memory activity log. | Yes. | The privacy mode is a processing control, not a classification label for these files. `OFF`, stored scanner findings, model-echoed content, and [known carrier limits](/privacy-and-logging/limitations.md#redaction-coverage-and-known-boundaries) can all leave sensitive values at rest. ## Chat Sessions Are Not Here Chat sessions do **not** live in this directory. They are stored in Burp's `extensionData()` keyed to the active `.burp` project file, so switching projects switches sessions. See [Chat & Sessions → Project-Scoped Storage](/user-guide/chat-sessions.md#project-scoped-storage). ## Backup and Portability * **Portable between machines**: `AGENTS/*.md` and intentionally selected `backends/*.jar`. Treat backend JARs as executable code and re-verify their source/checksum on the destination. * **Portable but sensitive**: `audit.jsonl` and `bundles/` can be archived or moved, but may contain engagement traffic, prompts, and model output. Treat any future `contexts/` contents the same way. Transfer them only through an approved encrypted channel. * **Do not copy between machines**: `cache//`. The namespace is derived from the local Burp project ID and entries are keyed by prompt hash; moving it to another host can produce irrelevant hits. * **Secrets**: the MCP keystore at `certs/mcp-keystore.p12` and its password (stored in Burp preferences, not here) together authenticate the local MCP listener. Rotate both when a host is retired. ## Cleanup | Goal | Action | | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Forget one project's cached analyses | With the passive scanner disabled, delete only `cache//`; reload the extension as well if you need to clear its in-memory caches. | | Reset MCP TLS | Delete `certs/mcp-keystore.p12`; the next MCP start will regenerate it. | | Start fresh for a new client engagement | Move the directory aside (`mv ~/.burp-ai-agent ~/.burp-ai-agent.bak`) before launching Burp. | | Disable rolling logs | Unset the `-Dburp.ai.logger.rolling.enabled=true` JVM flag at Burp startup (the `logs/` directory remains but no new entries are appended). | ## Legacy Identifier Reference The product is called **Custom AI Agent** but several internal identifiers still use the legacy name `burp-ai-agent`. This table lists exactly where each form appears. | Context | Value | Notes | | -------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Product and Burp extension name | `Custom AI Agent` | Visible in Burp's Extensions list and in the main tab. | | Release artifact (full build) | `Custom-AI-Agent-full-.jar` | Published on GitHub Releases; registers all 59 MCP tools. Built with `./gradlew shadowJar`. | | BApp Store-targeted artifact | `Custom-AI-Agent-.jar` | Not currently published while submission #231 remains open; build locally with `./gradlew shadowJar -PstoreBuild=true`. Registers only the 8 extension-native AI MCP tools. | | Checksum / SBOM | `Custom-AI-Agent-full-.jar.sha256`, `bom.json` | The current release workflow attaches both beside the full JAR. | | Burp tab title | `Custom AI Agent` | Registered by `App` and shown in Burp's main tab navigation. | | GitHub repository | `github.com/six2dez/burp-ai-agent` | Repo URL kept to avoid breaking external links, issues, and forks. | | Runtime directory | `~/.burp-ai-agent/` (Windows: `%USERPROFILE%\.burp-ai-agent\`) | Documented above. | | Java package | `com.six2dez.burp.aiagent` | Kept to preserve backend SPI compatibility for drop-in JARs. | | Gradle project name | `burp-ai-agent` (in `settings.gradle.kts`) | Internal only. | | MCP implementation string | `burp-ai-agent` | Shows up in MCP `initialize` responses; clients may rename. | | MCP server name in client configs (examples) | `burp-ai-agent` | Suggested key in `claude_desktop_config.json` and similar; you can call it anything you like. | | Audit log path | `~/.burp-ai-agent/audit.jsonl` | Inside the runtime directory above. | ### Why the Two Names Coexist The product is called **Custom AI Agent** because PortSwigger naming guidance asks third-party extensions to avoid using "Burp" as the leading word in a product name. User-facing strings and the JAR artifact carry the new name; internal identifiers still use the legacy `burp-ai-agent` form on purpose, for three reasons: 1. **Migrations**: existing users already have `~/.burp-ai-agent/` populated with audit logs, prompt caches, agent profiles, and drop-in backend JARs. Renaming the directory would invalidate all of that silently. 2. **SPI compatibility**: external drop-in backends ship JARs that register under `com.six2dez.burp.aiagent.backends.AiBackendFactory` via `META-INF/services`. Renaming the package would break every published third-party backend. 3. **GitHub identifiers**: repo URL, issue IDs, and pull requests are stable references that appear in pinned dependencies, automation, and user bookmarks. ### What to Expect in Each Surface * **UI, chat labels, audit payloads, documentation titles** → `Custom AI Agent`. * **Filesystem paths, repo URL, Java imports, Gradle tasks** → `burp-ai-agent`. * **MCP client configs** → either is fine; the identifier is advisory. Prefer `burp-ai-agent` if you want copy-paste examples from the docs to keep working. ### Ops and CI Naming Notes When wiring scripts, automation, or dashboards against this extension: * Scripts that download or pin the GitHub release JAR should target `Custom-AI-Agent-full-*.jar` and its matching `.jar.sha256` file. * Dashboards or Slack messages that reference the Burp tab should use **`Custom AI Agent`**, matching the user-visible tab name. Scripts that reference `~/.burp-ai-agent/`, the GitHub repo URL, the Java package, or the MCP implementation string follow the legacy identifier form — those do **not** need to match the product name. ## Related Pages * [Settings Reference](/reference/settings-reference.md) * [Audit Logging](/privacy-and-logging/audit-logging.md) * [AI Request Logger](/privacy-and-logging/ai-request-logger.md) * [Agent Profiles](/user-guide/agent-profiles.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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://burp-ai-agent.six2dez.com/reference/configuration-directory.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.