security-report

# Build a DefectDojo security report This plugin requires **DefectDojo Pro**. ## Why this skill exists Reports built from a vulnerability database go wrong in ways that are hard to catch afterwards: 1. **Numbers that cannot be traced.** Every figure in a report someone shows a board must come from an API response in this session. A plausible number is the worst possible output here. 2. **Invented trends.** "Down 30 percent from last quarter" requires last quarter's figure from the API. If you did not fetch it, there is no trend and you must not describe one. 3. **The wrong altitude.** A board does not want CWE distributions and an engineering lead does not want a single risk score. Same data, different cut. ## Procedure ### Step 1: Establish the audience and period Ask if it is not clear. The answer changes everything downstream. | Audience | Leads with | Avoids | |---|---|---| | Board or executive | Risk posture, trend, exposure in business terms, what is being done | Tool names, CWEs, individual findings | | Engineering leadership | Backlog by team and product, remediation throughput, aging, what is blocked | Board framing, dollar estimates | | Audit or compliance | Coverage, SLA adherence, evidence of process, exceptions and their approvals | Anything without a defensible basis | Also establish the period and the scope, which is the whole program or specific products. ### Step 2: Pull the data Pro insights endpoints are the backbone. Read `references/insights-endpoints.md` for the response shape of each before using it. ``` dd-api get "/api/v2/executive_insights/..." dd-api get "/api/v2/program_insights/..." dd-api get "/api/v2/remediation_insights/..." dd-api get "/api/v2/priority_insights/..." dd-api get "/api/v2/tool_insights/..." ``` Fill in per-product color with `mcp__defectdojo__risk_summary` and `mcp__defectdojo__finding_summary`. If an endpoint returns nothing useful for the requested period, say that in the report rather than leaving a silent gap or substituting a different metric. ### Step 3: Compose Structure for an executive or board cut: 1. **Where we stand.** Current posture in two or three sentences. 2. **What changed.** Movement over the period, only if you fetched both ends. 3. **What is driving risk.** The concentrations that matter, by product or theme. 4. **What we are doing.** Remediation throughput and what it implies. 5. **What we need.** Decisions or resources, only if the user has said. Rules for the numbers: use API values verbatim, state the basis of any count that could be read two ways, and give the period explicitly on every trend. When you describe prioritization, DefectDojo ranks on risk, weighing exploitability, threat intelligence, reachability, business context and many more signals. Do not present a closed list of factors as if it were exhaustive, and do not equate severity with risk. ### Step 4: Deliver Default to markdown in the conversation. Offer an HTML artifact when the user wants something to circulate. For a formal artifact generated by DefectDojo itself: ``` dd-api post /api/v2/generated_reports/quick_report/ --data '{...}' dd-api get /api/v2/generated_reports/<id>/ dd-api get /api/v2/generated_reports/<id>/download ``` Generation is asynchronous. Poll until status is completed before offering the download link. This is the better option when the output has to look like it came from the security tool of record. ## Rules - Never invent, round for effect, or extrapolate a number. - Never describe a trend without having fetched both points. - Never name a customer or a person in a report unless the user put them there. - Say what the report does not cover. A stated gap is credible, a silent one is not. - If the data contradicts the framing the user asked for, say so plainly rather than writing the report they asked for around numbers that do not support it.