A useful vulnerability finding lets a developer locate and repair one harmful behavior, lets a security reviewer judge the evidence, and lets a decision maker understand the business consequence. It should state the actor, entry point, failed control, affected asset, observed or source-supported effect, scope, uncertainty, fix direction and check for closure. Keep the plain-language answer first and technical evidence underneath. If a key part of the path is unknown, label the item an investigation rather than writing a confident finding. If the issue was independently verified, say how and at which revision; a scanner's label or a code citation alone does not provide that verdict.
The OWASP Web Security Testing Guide's reporting chapter separates the executive view from technical detail and recommends reporting scope, limitations, affected function, impact and remediation. For an internal developer ticket, use the same information in a shorter, decision-ready form.
The minimum useful packet
Use this checklist before sending a finding to engineering. The fields form a chain: each one should support the next. A generic “critical access control issue” is not a substitute for any link.
| Field | Answer to write | Common failure |
|---|---|---|
| Stable ID and status | Which finding version is this, and is it a candidate, unresolved investigation or verified issue? | A title silently changes as reviews progress. |
| Scope | Which repository, immutable revision, component, deployment and assessment boundary were examined? | A line from one commit is presented as current production behavior. |
| Harmful action and asset | What could the actor read, change, impersonate or stop, and whose asset is it? | “Improper authorization” appears without a consequence. |
| Actor and prerequisite | What identity, role, account, network position, secret or user action is required? | The report assumes an anonymous internet attacker when only an internal operator can call the path. |
| Entry and control path | Where does input enter, what controls run, which expected check fails, and where is the result delivered? | A source line is treated as proof that the route can be reached. |
| Evidence and method | Which bounded source references, policy/configuration records or authorized observations support each claim? What was not done? | A screenshot, scanner score or hypothetical request is presented as an executed exploit. |
| Business effect and practical difficulty | Why does this matter here, and what makes exploitation easy, hard or unknown? | Severity, impact and attack effort collapse into one unexplained label. |
| Fix direction and acceptance check | What property must the change enforce, and what evidence at a new revision would show it works? | “Add validation” leaves the developer guessing and the reviewer unable to close the issue. |
| Owner, timing and limits | Who acts next, by when, and which assumptions or unreviewed paths remain? | A report quietly implies complete coverage. |
An organization may require additional fields such as a CVE, policy mapping or score vector. Add them only when they answer a reader's question. FIRST's CVSS v4.0 specification separates intrinsic Base characteristics from changing Threat and environment-specific metrics. If you show a number, identify the version and metric set; the number does not replace the path or the business decision.
A filled example: read-only role reaches a billing export
Entirely illustrative. Imagine a fictional company, Pine Harbor, with an application where finance editors may export billing data. A read-only finance user can open the billing screen but should not export the full CSV. A security reviewer has traced a deployed export handler at revision DEF456. The handler checks that the caller belongs to the finance area but does not check the export permission before generating the CSV. The filled record assumes independent approval as part of the constructed scenario; it does not report an actual review, executed request or customer assessment.
Here is a compact report that an engineer and a business owner could each use:
PH-017 · Verified for revision DEF456 · Open
- Title: A read-only finance user can export the full billing CSV.
- Problem: The export route checks finance-area membership, then calls the CSV generator. It does not enforce the separate export capability required by Pine Harbor's role policy. The generator performs no later authorization check.
- Business impact: A user granted read-only access to billing screens could obtain a bulk copy of customer billing records. The exact exposed fields and record count depend on the export configuration; those values were not inferred from the code alone.
- Practical difficulty: The actor needs an active read-only finance account and knowledge of the normal export action. No special infrastructure access is shown. The path was established from source and approved configuration, not by running an exploit.
- Evidence: Revision DEF456, export route lines 40–61; capability policy lines 18–25; export service lines 92–118; production route map version 7. Source references and line numbers are illustrative.
- Fix condition: Enforce the export capability on the request against the current caller and the requested billing scope before any CSV content is prepared or delivered. Check alternate exports and background jobs separately.
- Closure check: At a new pinned revision, an authorized export still works; the read-only role is denied at the same and alternate delivery paths in an approved test setting. A source review confirms the enforcement point.
- Limits: The original review did not examine older deployment versions or all administrator roles. Those are separate scope questions.
The title names an action and an asset. The first three sentences tell a non-specialist what is wrong and why it matters. The evidence then lets a technical reviewer challenge the conclusion. This is stronger than embedding a raw CSV, a user's data or a copy of sensitive source in a broad ticket. OWASP's reporting advice also calls for masking sensitive data that appears in a finding.
Keep evidence, inference and recommendation visually separate
Write a sentence as observed only when the method actually observed it. “The route calls the export service without checking the export capability” may be supported by source at a pinned revision. “A read-only user downloaded 6,000 rows in production” requires authorized runtime evidence; it cannot be inferred from that source line. “An attacker could obtain customer billing data” is an impact inference that depends on the role, route, data and downstream controls. State those conditions.
A simple evidence ledger helps:
| Claim | Supporting artifact | What would change the conclusion? |
|---|---|---|
| Read-only users can call the route | Role policy and route authorization at DEF456 | A gateway or handler check that independently blocks that role |
| Export service returns billing rows | Service implementation and selected export schema | A downstream entitlement filter or an empty export for that role |
| The route is part of the assessed deployment | Artifact digest and route map | A different deployed artifact or disabled feature flag |
If the decisive artifact is missing, revise the status to “investigation.” Do not fill the gap with a more emphatic adjective. If a reviewer finds a real downstream check, record the counterevidence and reject or narrow the claim. If an approved test reveals a broader path, create a new version with the new evidence instead of silently editing history.
Give each reader the right depth
The business reader needs the affected action, consequence, confidence, scope and decision. The developer needs the exact control failure, source location, expected property, constraints and closure check. A security reviewer needs the method, counterevidence and uncertainty. Put those layers in one well-structured record, with access appropriate to the sensitivity of each section. Avoid distributing exploit instructions, raw secrets or customer records to a broad audience just to make a report feel “complete.”
Use plain words before category names. “A read-only finance user can download the billing CSV” is more useful than “CWE-862 in ExportController.” A standard ID can follow as a search and reporting aid, but should not stand in for evidence. Similarly, “the role has access to this screen” does not prove it may perform every action behind it: OWASP's Authorization Cheat Sheet distinguishes authentication from permission for the requested action.
Repair a report without inflating the claim
Try editing this deliberately bad version against Pine Harbor's evidence:
Critical: anonymous attackers can dump all 6,000 billing records. Missing authorization in ExportController. Add validation immediately.
Almost every confident word does work the evidence cannot support. The route requires a signed-in finance user, so remove “anonymous.” The source establishes a CSV-generating path, not a production download, so remove the claim of observed dumping. Neither the export's row count nor the full data population has been established. “Validation” fails to say which permission the server must enforce.
The repaired opening is:
A signed-in finance user with read-only access can reach the billing-export operation without the export capability required by the product policy. The reviewed handler and export service generate the CSV after checking finance membership only. This source-and-configuration finding concerns DEF456 and route map 7; no production download was performed. Enforce the export capability before generation and delivery.
That paragraph can support two different views without changing the facts:
| Recipient | Useful next sentence |
|---|---|
| Engineering owner | “Preserve read-only screen access; deny CSV creation and retrieval for this role while retaining finance-editor exports.” |
| Engineering manager | “Assign the billing owner to restore the intended separation between viewing the screen and obtaining an export; verify the deployed change before closing.” |
| Security reviewer | “Challenge the policy interpretation and look for a mandatory downstream entitlement check; either could change the finding.” |
Now remove one artifact: suppose capability policy lines 18–25 were never supplied. The author can no longer establish that read-only users should be denied export. The action becomes a policy investigation: product owner confirms the intended role/action matrix, then security compares implementation with it. A beautifully formatted report with an unsupported security rule is still not ready to become a verified vulnerability.
Check whether the packet survives a real handoff
A report can contain every field and still leave the recipient unable to act. In Pine Harbor, imagine the billing developer receives PH-017 after the reviewer has left for a week. The developer should be able to answer three practical questions without that person's memory: which permission is missing, which operation must enforce it, and which ordinary use must continue working. If any answer requires a meeting simply to recover the original reasoning, repair the packet before assigning it.
The access-controlled evidence links also need usable labels. “Source evidence” is less helpful than “DEF456 export handler and generator; shows membership check and no export-capability decision.” The recipient can recognize an inaccessible artifact and ask for the right access instead of assuming a broken link means the finding is unsupported. Do not solve an access problem by pasting private billing rows into a widely visible ticket.
Add a short change history when the conclusion evolves. For example, the first version might describe an unresolved policy question; the second can record the supplied role matrix and the resulting finding. Keep both dates and the reason for the change. The latest summary should say which version is actionable so that an engineer does not implement an obsolete recommendation from an older comment.
Finally, check the closure wording against the proposed repair. If the implementation denies generation but still permits retrieval of an existing export, a requirement to protect both operations has not been met. If the intended change also affects finance editors, retain an allowed editor case in the acceptance notes. These checks turn a report from an accusation into a shared description of the behavior the patch must establish.
Before sending your next report, underline every claim about actor, quantity, environment and observed effect. Each needs evidence or an explicit limit. Use the triage guide to choose the work state and the attack-path guide to make the technical chain inspectable.