# Findings and reports

> Record security findings with severity, CVSS, CWE and redacted evidence, keep them in Git, and export a PDF, HTML or Markdown report, JSON, SARIF or Burp XML.

Source: https://docs.subcloak.com/cloak-proxy/security/findings/

Added in Cloak Proxy 0.5.1.

When a test turns something up, record it where you found it. **Add to Findings** on a request in the traffic list, an Authorization Matrix cell, an Insights or API Scan issue, a fuzzer result or an AI Security finding saves a finding with its severity, CVSS score, CWE and OWASP references, and the requests that prove it, with tokens, cookies and keys redacted. The findings belong to an **engagement**: one test of one system, with its scope. An engagement is a folder of small files you can keep in Git, and it exports a report with a cover, a summary, the scope, a findings table, each finding with its evidence, and an appendix, as PDF, HTML or Markdown, or as JSON, SARIF and Burp XML for other tools.

*[Screenshot: The Findings window for the engagement ShopApp API, October 2026, with counts by severity, New Finding and Export Report. The list on the left, worst first: F-002 Gift card balance without signing in (Critical, 8.2), F-001 Orders readable by other users (High, 6.5), F-003 Missing rate limiting, F-004 CORS allows any origin with credentials (Fixed), F-006 Coupon applied twice in parallel checkouts (Draft) and F-005 Server version disclosure (Info), each with its status and endpoint. The right side edits F-002: Severity Critical, Status Open, a CVSS 3.1 vector scored 8.2 High, the affected endpoint, references CWE-306 and OWASP API2:2023, Description, Impact, Steps to reproduce, Remediation and Evidence.. An engagement's findings, worst first, and the selected one's details. Each change is saved to the engagement folder as you type.]*

## Start an engagement

1. Open **Tools › Findings…**.

2. Click **New Engagement**. Give it a name, and optionally the client, the assessors and the dates. The **Scope** tab takes the hosts and paths the test covers, one per line, written as in [Tools › Scope](https://docs.subcloak.com/cloak-proxy/security/scope/): `api.example.com`, `.example.com` for a domain and its subdomains, `https://api.example.com/v2/*` or `203.0.113.0/24`. A new engagement starts from the active target scope, and **Use Target Scope** copies it again later. The **Report** tab sets the title, the classification (`Confidential` by default) and what the report includes.

3. By default the folder goes in `~/Library/Application Support/CloakProxy/Engagements/`. Click **Choose…** to put it somewhere else, such as a folder in a Git repository.

The **Engagement** menu next to the engagement's name has **New Engagement…**, **Open Engagement Folder…**, **Import JSON Report…**, your recent engagements, **Engagement Details…**, **Show in Finder** and **Reload from Disk**. Cloak Proxy remembers the open engagement between launches.

*[Screenshot: The Engagement details sheet with Details, Scope and Report tabs: Name ShopApp API, October 2026, Client ShopApp, Assessors Ada Park, testing dates, an empty Summary with the placeholder Left empty, one is written from the findings, and Cancel and Save buttons.. Engagement details: who the test is for, when, the scope and how the report is made.]*

## Add a finding

| Where | What it adds |
|---|---|
| Right-click requests in the traffic list → **Add to Findings…** | The requests as evidence, with their endpoints |
| The inspector's <kbd>…</kbd> menu → **Add to Findings…** | The request you're looking at |
| An [Authorization Matrix](https://docs.subcloak.com/cloak-proxy/testing/authorization-matrix/) cell with **Same data** → **Add to Findings** | A broken object-level authorization finding (CWE-639, OWASP API1:2023), the original and the replayed exchange as evidence, the leaked identifiers highlighted |
| **Insights › Security** → an issue → **Add to Findings…** | The check's finding (CORS, HSTS, cookie flags, version disclosure…) with the responses that failed it |
| **Insights › Secrets** → a secret → **Add to Findings…** | An exposed-secret finding with the request that carried it |
| **[Insights › API Scan](https://docs.subcloak.com/cloak-proxy/insights/api-scan/)** → an issue → **Add to Findings…** | The scanner's finding (BOLA, mass assignment, missing rate limits, desync risk…) with its OWASP API and CWE references and the requests it saw |
| **[Request Fuzzer](https://docs.subcloak.com/cloak-proxy/security/request-fuzzer/)** → a result → **Add to Findings…** | The fuzzed request and its response, with the payload highlighted when it was reflected |
| **[AI Security](https://docs.subcloak.com/cloak-proxy/security/ai-security/)** → a prompt injection, a changed MCP server or an AI Guard event → **Add to Findings…** | The finding with its OWASP LLM reference and the model or MCP requests that show it |
| **New Finding** in the Findings window | A blank finding, or one from a template |

Each of these opens the **Add to Findings** sheet. Check the title and severity, then choose **A new finding**, or **Evidence for F-002** to add the requests to a finding you already have. If the same matrix cell, scanner issue or fuzzer result was added before, the sheet offers that finding first.

*[Screenshot: The Add to Findings sheet: a note that Claude Code suggested this finding, an Add as menu set to A new finding, Title Profile endpoint returns password reset tokens, Severity High, Status Open, references CWE-200 and OWASP API3:2023, two requests as evidence, a checked Redact credentials and secrets option, and Cancel and Add Finding buttons.. Every Add to Findings opens this sheet: nothing is saved until you click Add Finding.]*

Requests outside the engagement's scope are named in the sheet, so you notice before you add them. When the engagement has no scope of its own, the sheet checks the active target scope in **Tools › Scope** instead.

*[Screenshot: The Add to Findings sheet opened from Insights, API Scan: From API scanner, an Add as menu set to A new finding, Title Object addressed by id behind a login, Severity Medium, Status Open, references OWASP API1:2023 and CWE-639, four requests as evidence, and Redact credentials and secrets checked.. A scanner issue, ready to add with the requests it saw.]*

### Templates

**New Finding** and the sheet's template button fill in a description, impact, remediation, references and a CVSS vector for common issues: broken object-level and function-level authorization, mass assignment, excessive data exposure, missing rate limiting, a permissive CORS policy, missing HSTS, cookie flags, credentials in the URL, sensitive data over plain HTTP, exposed secrets, version disclosure, verbose errors and prompt injection. Edit the text to fit what you found.

## The finding

| Field | |
|---|---|
| ID | `F-001`, `F-002`… (the prefix is set in the engagement's Report tab). Numbers aren't reused |
| Severity | Critical, High, Medium, Low or Informational |
| Status | **Draft**, **Open**, **Fixed**, **Accepted risk** or **False positive**. Drafts and false positives stay out of reports unless you include them |
| CVSS | Optional. Paste a CVSS 3.1 or 4.0 vector and the score is worked out (3.1 with the specification's equations, 4.0 with FIRST's MacroVector tables). A new vector sets the severity to its rating; you can still change it. The arrow opens the vector in FIRST's calculator |
| Affected endpoints | One per line, for example `GET api.example.com/v2/orders/{id}` |
| References | Search the built-in list of common CWEs, the OWASP Top 10, the API Security Top 10 and the LLM Top 10, or type `CWE-918`, `API1:2023` or a URL |
| Description, Impact, Steps to reproduce, Remediation | Markdown |
| Evidence | The captured requests and responses, each with a note |

Right-click a finding in the list to change its status, duplicate it or delete it.

## Evidence and redaction

Evidence is a copy of the exchange taken when you add it, so it survives clearing the session. Before it's saved, Cloak Proxy replaces credentials and secrets with `REDACTED`: `Authorization` and API-key headers (keeping the scheme, as in `Bearer REDACTED`), cookie values, tokens and keys in URLs, and passwords, keys and card numbers in JSON and form bodies. Bodies are decoded and JSON is pretty-printed. Binary bodies are left out, and bodies over 64 KB are cut.

Turn off **Redact credentials and secrets** in the sheet only when the report needs the real values; that evidence is marked **Not redacted** in the window, and the report says so.

Click an evidence's arrow to see the request and response, with the highlighted values (such as another user's email) marked. Its <kbd>…</kbd> menu has **Show in Traffic List** while the request is still in the session, **Copy Request**, **Copy Response** and **Remove Evidence**.

## Export the report

Click **Export Report** and choose a format:

| Format | What you get |
|---|---|
| **PDF** | A report ready to send: cover with the client, assessors, dates, classification and counts by severity; executive summary; scope; a findings table; each finding on its own page with its evidence; the appendix with the methodology and the severity ratings. Page numbers and the classification are in every footer |
| **HTML** | The same report as one self-contained page (no scripts or external files) that prints well, with full evidence bodies |
| **Markdown** | The same content, for a wiki, a pull request or SysReptor |
| **JSON for Tooling** | Every reported finding in a flat shape (ID, severity, status, CVSS score, CWE numbers, OWASP ids, endpoints, text), plus the whole engagement with its evidence. **Import JSON Report…** opens it again |
| **SARIF** | SARIF 2.1.0: a rule and a result per finding, with the endpoint as a logical location and the first evidence as the web request and response, for GitHub code scanning and other SARIF tools |
| **Burp XML** | Burp Suite's issue XML, which SysReptor, Dradis and DefectDojo import: an issue per piece of evidence, with the request and response. Burp has no Critical rating, so critical findings are High there; the finding's ID and CVSS score are in each issue's detail |

**Copy as Markdown** puts the report on the clipboard. Leave the engagement's summary empty and the report writes one from the findings, such as "Ada Park tested ShopApp (11–20 October 2026) and found 5 issues: 1 critical, 1 high, 2 medium and 1 informational."

> **About the PDF:**
> The PDF uses the standard PDF fonts, so characters outside Western European languages show as `?`; arrows become `->`. Evidence in the PDF is cut after 60 lines per request or response; the HTML and JSON keep it whole.

## Keep it in Git

An engagement folder looks like this:

```
ShopApp API, October 2026/
  engagement.json                         name, client, dates, scope, summary, report settings
  findings/F-001-orders-readable-by-other-users.json
  findings/F-002-gift-card-balance-without-signing-in.json
  evidence/<finding id>/E1.json           one file per request, redacted when it was added
```

Files are pretty-printed with sorted keys and only rewritten when they change, so diffs stay small and two people's findings merge cleanly. If a merge brings two findings with the same number, the newer one is renumbered when the folder opens, and the window says which. Edit files by hand if you like: missing fields get their defaults. Cloak Proxy picks up changes made outside it (a `git pull`, a teammate's edit) when you open the Findings window, or with **Reload from Disk**.

## AI assistants

Three MCP tools work with the open engagement:

| Tool | What it does |
|---|---|
| `list_findings` | The findings, worst first, filtered by severity, status or text; `id` returns one in full, and `include_evidence` adds the redacted exchanges. `format: "markdown"` returns the report |
| `add_finding` | Proposes a finding with a title, severity, CVSS vector, endpoints, text, references and captured request ids as evidence, or adds evidence to an existing finding with `finding: "F-002"`. It never saves on its own: Cloak Proxy opens the Add to Findings sheet filled in, and the assistant is told it's waiting for you |
| `export_findings_report` | Writes the PDF, HTML, Markdown, JSON, SARIF or Burp XML report and returns its path |

`list_findings` and `export_findings_report` take `engagement: "/path/to/folder"` to read another engagement without opening it. On Linux, where the engine has no Findings window yet, `add_finding` saves the finding as a **Draft**, which stays out of reports until someone reviews it.

The [assistant scope](https://docs.subcloak.com/cloak-proxy/automation/assistant-scope/) applies to findings too: evidence from a request outside it is withheld from `list_findings` and from reports an assistant exports, and where the scope shares metadata only, the evidence comes without bodies. `add_finding` only takes requests the assistant may read in full. The findings themselves, which you wrote, stay visible.

## Command line

`cloakctl findings` works on an engagement folder without the app, which makes it useful in CI:

```sh
cloakctl findings list ./pentest                       # the findings, worst first
cloakctl findings show F-001 ./pentest                 # one finding as Markdown (--json for JSON)
cloakctl findings export ./pentest --format pdf --out report.pdf
cloakctl export --engagement ./pentest --format sarif --out findings.sarif
cloakctl findings export ./pentest --format burp --out findings.xml   # for SysReptor, Dradis or DefectDojo
cloakctl findings new "ShopApp API" --dir ./pentest --client ShopApp --scope api.example.com
cloakctl findings import report.json --dir ./restored
cloakctl findings check ./pentest --fail-on high       # exit code 2 if an open finding is high or critical
```

Without a folder, `cloakctl findings` uses the current folder when it's an engagement, otherwise the one open in Cloak Proxy.

## Limits

- There's no Findings window in the Linux app yet. Use `cloakctl findings` and the findings MCP tools; there, `add_finding` saves a **Draft**.
- Evidence keeps up to 64 KB of each body, and the PDF up to 60 lines of each message.
- Redaction finds common credential formats. Read the evidence before you share a report outside your team.

## Related

  - [Scope](https://docs.subcloak.com/cloak-proxy/security/scope/): The hosts and paths an engagement covers.
  - [API scan](https://docs.subcloak.com/cloak-proxy/insights/api-scan/): Passive checks whose issues go straight into a report.
  - [Authorization Matrix](https://docs.subcloak.com/cloak-proxy/testing/authorization-matrix/): Confirm broken object-level authorization, then add the cell.
  - [cloakctl](https://docs.subcloak.com/cloak-proxy/automation/cloakctl/): Export reports and gate CI on open findings.