/reporting-security-findings

name: reporting-security-findings
description: Write security findings and assessment reports — severity scoring with CVSS and business impact, reproducible proof of concept, remediation guidance, executive summaries, and coordinated disclosure. Use when writing up a vulnerability, producing a pentest or audit report, triaging a bug bounty submission, or preparing a disclosure timeline.
verified: 2026-07-28

Reporting Security Findings

The report is the product. Findings that are not understood are not fixed, and findings that cannot be reproduced are disputed. Most of the value an assessment creates is destroyed or preserved in the write-up.

When to Use

• Writing up a single vulnerability
• Producing a penetration test, code audit, or red team report
• Submitting to a bug bounty program or triaging inbound submissions
• Scoring severity and arguing priority with an engineering team
• Planning coordinated disclosure for an unpatched issue

When NOT to Use

• **Finding the bug** — use the relevant testing or audit skill first
• **Assembling the raw record a report is built from** (provenance, artifact

register, evidence, dead ends) — use `maintaining-engagement-state`; this skill consumes that record

• **Incident narratives and postmortems** — use `responding-to-incidents`
• **Compliance-framework mapping as the primary goal** — different document,

different audience

Anatomy of a Finding

Every finding answers five questions, in this order:

### F-03  Tenant isolation bypass in report export     [High]

**Summary**
An authenticated user of any tenant can export reports belonging to other
tenants by supplying an arbitrary report ID to `GET /api/v2/reports/{id}/export`.

**Impact**
Full read access to other customers' report data, including the financial
figures and contact records those reports contain. Any customer account —
including a self-service trial — is sufficient. This is a cross-tenant
confidentiality breach with likely contractual and regulatory consequences.

**Affected**
`api/handlers/reports.go:214` (`handleExport`), deployed in production as of
commit `a1b2c3d`. Reproduced on staging 2026-07-24 14:02 UTC.

**Reproduction**
1. Authenticate as `trial-user@tenant-a` and obtain a session token.
2. Note your own report ID from `GET /api/v2/reports` (e.g. `1041`).
3. Request a neighbouring ID:
   curl -H "Authorization: Bearer $TOKEN" \
        https://staging.example.com/api/v2/reports/1042/export -o out.csv
4. `out.csv` contains tenant B's data. Confirmed with IDs 1042, 1043, 1055.

**Root cause**
The handler looks the report up by primary key and checks only that the
session is valid. The tenant scope present on the list endpoint
(`WHERE tenant_id = ?`) is absent from the export query.

**Remediation**
Add the tenant predicate to the export lookup, and enforce it at the data
access layer rather than per handler so new endpoints inherit it:
    SELECT ... FROM reports WHERE id = ? AND tenant_id = ?
Then audit the remaining 14 handlers that call `findByID` without a scope —
listed in Appendix B.

**References**
CWE-639, OWASP API1:2023 Broken Object Level Authorization

Rules that make findings act-on-able:

• **One finding per issue.** Bundling ten IDORs into "authorization issues"

guarantees partial fixes.

• **Exact locations.** File, line, endpoint, commit, and the environment where

you reproduced it.

• **Reproduction someone else can run** without asking you a question. Include

the setup, the request, and the observed result — not just the payload.

• **Root cause, not just symptom.** The fix for a symptom leaves the class.
• **Remediation that names the change.** "Validate input" is not remediation.
• **Variants listed.** If you found one instance and suspect more, say what you

checked and what you did not.

• **Revalidated against what ships.** Before a finding goes in the report,

confirm the vulnerable code is not already fixed on a branch you haven't pulled (`git log --oneline <checkout>..origin/main -- <file>`). One already-patched finding teaches the reader to distrust the rest.

Invariants to check before a finding leaves draft

Four of the rules above are mechanical enough to check rather than judge. Run them over every finding; each maps to a way reports have actually gone wrong.

1. **Every finding cites at least one piece of evidence** — a command and its output, a request and response, a crash, a screenshot. A finding whose only support is a code reading is a *candidate*, not a finding. Label it so. 2. **Confirmed status and low confidence cannot coexist.** If you would not bet on it, it is still a candidate. Downgrade the status or say plainly what would settle it. This pair is the single most common way a speculative finding acquires unearned authority on its way into a report. 3. **Every reproduction runs without asking you a question**, or names the environment it cannot leave — an offline sample, a lab-only target, a credential the reader must supply. An unreproducible finding is not a finding you can defend in a remediation meeting. 4. **A claim of obtained access or data has evidence of that specific claim.** "Full database read" needs a row you actually read, not an injectable parameter plus an inference about what lies behind it. Reachability is not impact.

When a finding fails one of these, it does not get quietly dropped: it moves to the candidate worklist with the reason attached, so a later pass knows what would promote it. See `orchestrating-vulnerability-research` for how candidates are graded when a separate critic does the promoting.

Severity

CVSS is the common currency, but it scores a vulnerability in the abstract. Score with CVSS, then state business impact separately — engineering prioritizes on the second.

CVSS 4.0 base vector example:
CVSS:4.0/AV:N/AC:L/AT:N/PR:L/UI:N/VC:H/VI:N/VA:N/SC:N/SI:N/SA:N   → 6.9 Medium

Then adjust for reali