diff --git a/docs/assets/images/pro_generate_report_dialog.png b/docs/assets/images/pro_generate_report_dialog.png new file mode 100644 index 00000000000..94374e7f9ca Binary files /dev/null and b/docs/assets/images/pro_generate_report_dialog.png differ diff --git a/docs/assets/images/pro_generated_reports_list.png b/docs/assets/images/pro_generated_reports_list.png new file mode 100644 index 00000000000..3a025031b7b Binary files /dev/null and b/docs/assets/images/pro_generated_reports_list.png differ diff --git a/docs/assets/images/pro_report_block_new_tabular.png b/docs/assets/images/pro_report_block_new_tabular.png new file mode 100644 index 00000000000..5d1fc0be987 Binary files /dev/null and b/docs/assets/images/pro_report_block_new_tabular.png differ diff --git a/docs/assets/images/pro_report_block_preview.png b/docs/assets/images/pro_report_block_preview.png new file mode 100644 index 00000000000..083a4eb0da0 Binary files /dev/null and b/docs/assets/images/pro_report_block_preview.png differ diff --git a/docs/assets/images/pro_report_blocks_list.png b/docs/assets/images/pro_report_blocks_list.png new file mode 100644 index 00000000000..f2bf84be20c Binary files /dev/null and b/docs/assets/images/pro_report_blocks_list.png differ diff --git a/docs/assets/images/pro_report_template_new.png b/docs/assets/images/pro_report_template_new.png new file mode 100644 index 00000000000..b841f9d4fad Binary files /dev/null and b/docs/assets/images/pro_report_template_new.png differ diff --git a/docs/assets/images/pro_report_templates_list.png b/docs/assets/images/pro_report_templates_list.png new file mode 100644 index 00000000000..60c38f66aea Binary files /dev/null and b/docs/assets/images/pro_report_templates_list.png differ diff --git a/docs/assets/images/pro_report_theme_new.png b/docs/assets/images/pro_report_theme_new.png new file mode 100644 index 00000000000..ac6be696459 Binary files /dev/null and b/docs/assets/images/pro_report_theme_new.png differ diff --git a/docs/assets/images/pro_report_themes_list.png b/docs/assets/images/pro_report_themes_list.png new file mode 100644 index 00000000000..a2cad4f71bf Binary files /dev/null and b/docs/assets/images/pro_report_themes_list.png differ diff --git a/docs/content/get_started/about/OS__new_user_checklist.md b/docs/content/get_started/about/OS__new_user_checklist.md index b3dd10e6328..cfe7cb1a86d 100644 --- a/docs/content/get_started/about/OS__new_user_checklist.md +++ b/docs/content/get_started/about/OS__new_user_checklist.md @@ -16,7 +16,7 @@ The essence of DefectDojo is to import security data, organize it, and present i 2. Now that you have data in DefectDojo, consider expanding your Product layout [Product Hierarchy Overview](/asset_modelling/os_hierarchy/product_hierarchy/). The Product Hierarchy creates a working inventory of your apps, which helps you divide your data up into logical categories. These categories can be used to apply access control rules, or to segment your reports to the correct team. -3. Use the [Report Builder](/metrics_reports/reports/using_the_report_builder/#opening-the-report-builder) to summarize the data you've imported. Reports can be used to quickly share Findings with stakeholders such as Product Owners. +3. Use the [Report Builder](/metrics_reports/reports/using-the-report-builder/#opening-the-report-builder) to summarize the data you've imported. Reports can be used to quickly share Findings with stakeholders such as Product Owners. This is the essence of DefectDojo - import security data, organize it, and present it to the folks who need to know. diff --git a/docs/content/get_started/about/faq.md b/docs/content/get_started/about/faq.md index d5855ae494d..de1a0e75f5b 100644 --- a/docs/content/get_started/about/faq.md +++ b/docs/content/get_started/about/faq.md @@ -23,7 +23,7 @@ DefectDojo is meant to be the central source of truth for your organization's se - Enforcing SLAs on vulnerabilities, ensuring that your organization handles each Finding within an appropriate timeframe. - [Sending tickets](/issue_tracking/intro/intro/) to Jira, ServiceNow or other Project Tracking software, allowing your development team to integrate issue remediation into their standard release process without requiring them to learn another project management tool. - Integrating into automated [CI/CD pipelines](/import_data/import_scan_files/api_pipeline_modelling/) to automatically ingest report data from repositories, even down to the branch level. -- Creating [reports](/metrics_reports/reports/using_the_report_builder/) on any set of vulnerabilities or software context, to quickly share scan results or status updates with stakeholders. +- Creating [reports](/metrics_reports/reports/) on any set of vulnerabilities or software context, to quickly share scan results or status updates with stakeholders. - Establishing acceptance and mitigation workflows, supporting formal risk-management tracking. @@ -123,7 +123,7 @@ Findings from DefectDojo can be deleted in a few ways: ### How can I generate a report in DefectDojo? -You can quickly create a customized report in DefectDojo using the [Report Builder](/metrics_reports/reports/using_the_report_builder/). +You can quickly create a customized report in DefectDojo using the [Report Builder](/metrics_reports/reports/). DefectDojo Pro users also have access to [executive-level Metrics dashboards](/get_started/about/ui_pro_vs_os/#new-dashboards) that can report on Product Types, Products or other data in real-time. diff --git a/docs/content/metrics_reports/ai/mcp_server_pro.md b/docs/content/metrics_reports/ai/mcp_server_pro.md index f8de8e9bee8..bb036f246f9 100644 --- a/docs/content/metrics_reports/ai/mcp_server_pro.md +++ b/docs/content/metrics_reports/ai/mcp_server_pro.md @@ -3,7 +3,7 @@ title: "MCP Server" description: "DefectDojo's MCP Server allows you to use LLMs with DefectDojo Pro" draft: false audience: pro -weight: 2 +weight: 23 aliases: - /en/ai/mcp_server_pro --- diff --git a/docs/content/metrics_reports/reports/OS__using_the_report_builder.md b/docs/content/metrics_reports/reports/OS__using_the_report_builder.md new file mode 100644 index 00000000000..01ffbf5f1af --- /dev/null +++ b/docs/content/metrics_reports/reports/OS__using_the_report_builder.md @@ -0,0 +1,161 @@ +--- +title: "Using the Report Builder" +description: "Build, run, and retrieve a custom report in open-source DefectDojo" +draft: false +audience: opensource +weight: 24 +slug: using-the-report-builder +aliases: + - /en/share_your_findings/pro_reports/working_with_generated_reports + - /metrics_reports/reports/working_with_generated_reports +--- +DefectDojo's report builder lets you assemble a custom report from a set of content widgets, run it, and export the result (for example, by printing it to PDF). Custom reports can summarize the Findings or Endpoints you want to share with an external audience, and can include branding and boilerplate text. + +> **Note:** In open-source DefectDojo, you build a report, run it, and retrieve its output as a one-time effort. Report layouts (templates) and the generated report output are **not saved** in open source. To reuse a layout, you rebuild it in the report builder. To save reusable Themes, Blocks, and Templates, and to keep a persistent history of generated reports, see DefectDojo Pro's [Report Builder](../report-builder/). + +## Opening the Report Builder + +The Report Builder can be opened from the **๐Ÿ“„ Reports** page on the sidebar. + +![image](images/Using_the_Report_Builder.png) + +The report builder page is organized in two columns. The left **Report Format** column is where you design your report, using widgets from the right **Available Widgets** column. + +![image](images/Using_the_Report_Builder_2.png) + +## Step 1: Set report options + +![image](images/Using_the_Report_Builder_3.png) + +From the Report Options section, you can take the following actions: + +* Set a **Report Name** for the report +* Include user-created **Finding Notes** in the report +* Include **Finding Images** in the report +* Upload a header **Image** to the report + +### Select a header image for your report + +To add an image to the top of your report, click the **Choose File** button and upload an image to DefectDojo. + +The image will automatically resize to fit the document, and will render directly above your **Report Name**. + +![image](images/Using_the_Report_Builder_4.png) + +## Step 2: Add content with widgets + +Once you have set your report options, you can begin to design your report using DefectDojo's widgets. + +Widgets are content elements of a report that you add by dragging and dropping them into the **Report Format** column. The final report will be generated based on the position of each widget, with the **Report Name** and **Header Image** rendered at the top. + +* The elements of your report can be reordered by dragging and dropping your widgets into a new order. +* To remove a widget from a report, click and drag it back to the right column. +* Widgets can also be collapsed by clicking on the grey header, for ease in navigating through the report builder. +* The Findings widget, WYSIWYG widget, and the Endpoints widget can each be used more than once. + +For more information about report widgets, see the [Report widget index](./#report-widget-index). + +## Step 3: Run and view the report + +Once you have finished building your report, you can generate it by clicking the green **Run** button at the bottom of the **Report Format** section. + +DefectDojo generates the report from the widgets you assembled. When generation is complete, you can view the resulting HTML report in your browser. + +![image](images/Using_the_Report_Builder_14.png) + +A generated report is a point-in-time snapshot: it reflects the data in DefectDojo at the moment you ran it and does not update automatically as your data changes. + +## Step 4: Export the report + +Reports are set up so that they can be exported or printed easily. + +The simplest method is to print to PDF. With the HTML report open, open a **Print** dialog in your browser and set **Save to PDF** as the **Print Destination**. + +![image](images/Using_the_Report_Builder_15.png) + +## Report formatting suggestions + +* WYSIWYG sections can be used to contextualize or summarize Finding lists. Consider using this widget throughout your report, in between Findings or Vulnerable Endpoints widgets. + +## Report widget index + +### Cover Page widget + +The Cover Page widget allows you to set a heading, sub-heading, and additional metadata for your report. You can only have a single Cover Page for a given report. + +![image](images/Using_the_Report_Builder_5.png) + +### Executive Summary widget + +The Executive Summary widget is intended to summarize your report at a glance. It contains a heading (defaults to Executive Summary), as well as a text box which can contain whatever information you feel is required to summarize the report. + +![image](images/Using_the_Report_Builder_6.png) + +You can also **Include SLAs** in your executive summary. To add images, markup formatting, or anything beyond pure text, consider adding a **WYSIWYG Content widget** immediately after the executive summary. + +* You can only have a single Executive Summary for a given report. +* If your report contains multiple SLA configurations (for example, you have Findings from separate Products which each have their own standards for SLA) each SLA configuration will be listed on the Executive Summary as a separate row. + +### Severities widget + +As each organization will have different definitions for each severity level, the Severities widget allows you to define the severity levels used in your report for ease of understanding. + +![image](images/Using_the_Report_Builder_7.png) + +### Table of Contents widget + +The Table of Contents widget creates a list of each Finding in your report, for quicker access to specific Findings. The table of contents creates a separate heading for each severity contained within the report. Each Finding listed in the table of contents has an anchor link attached to quickly jump to the Finding in the report. + +![image](images/Using_the_Report_Builder_8.png) + +* You can add a section of **Custom Content**, which will add text underneath the heading. +* You can upload an image to the Table of Contents by clicking the **Choose File** button next to the **Image** line. The uploaded image will render directly above the heading selected. Images will be resized to fit the document. + +### WYSIWYG Content widget + +The WYSIWYG (What You See Is What You Get) widget can be used to add a section containing text and images in your report. Multiple copies of this widget can be added to provide context to other sections of your report. + +![image](images/Using_the_Report_Builder_9.png) + +* WYSIWYG Content can include an optional heading. +* Images can be added to a WYSIWYG widget by dragging and dropping them directly into the **Content** box. Images inserted into the Content box will render at their full resolution. +* You can add multiple WYSIWYG widgets to a report. + +### Findings widget + +The Findings widget provides a list and summary of each Finding you want to include in your report. You can set the scope of the Findings you wish to include with filters. + +The Findings widget is divided into two sections. The upper section contains a list of filters which can be used to determine which Findings you want to include, and the lower section contains the resulting list of Findings after filters are applied. + +To apply filters to your Findings widget, set the filter parameters and click the **Apply Filter** button at the bottom. You can preview the results of your filter by checking the Findings list located underneath the Filters section. + +![image](images/Using_the_Report_Builder_10.png) + +* As with widgets, the Filters section can be expanded and collapsed by clicking the grey Filters header. +* You can add multiple separate Findings widgets to your report with different filter parameters if you want the report to contain more than one list of Findings. +* Only the Findings you are authorized to view are included in these listings, with respect to Role-Based Access Control. + +#### Example rendered Finding list + +![image](images/Using_the_Report_Builder_11.png) + +### Vulnerable Endpoints widget + +The Vulnerable Endpoints widget is similar to the Findings widget. You can use this widget to list all Findings for specific Endpoints, and sort the Finding list by Endpoint instead of by severity level. + +The **Vulnerable Endpoints** widget lists each active Finding for the Endpoints selected. Rather than creating a single list of unsorted Findings, this feature separates them into their Endpoint context. + +As with the Findings widget, the Vulnerable Endpoints widget is divided into a Filter section and a list of resulting Endpoints from the filter parameters. + +![image](images/Using_the_Report_Builder_12.png) + +Select the parameters for the Endpoints you wish to include here and click the **Apply Findings** button at the bottom. You can preview the results of your filter by checking the Endpoints list located underneath the Filters section. + +* You can add multiple separate Vulnerable Endpoints widgets to your report with different filter parameters if you want the report to contain more than one list. +* Only the Findings you are authorized to view are included in these listings, with respect to Role-Based Access Control. + +### ---- (separator) widget + +This widget renders a light grey horizontal line to divide between sections. + +![image](images/Using_the_Report_Builder_13.png) diff --git a/docs/content/metrics_reports/reports/PRO__report_builder.md b/docs/content/metrics_reports/reports/PRO__report_builder.md new file mode 100644 index 00000000000..6d409c18adb --- /dev/null +++ b/docs/content/metrics_reports/reports/PRO__report_builder.md @@ -0,0 +1,168 @@ +--- +title: "Report Builder" +description: "Build custom, reusable reports in DefectDojo Pro with Themes, Blocks, and Templates" +draft: false +audience: pro +weight: 20 +slug: report-builder +aliases: + - /en/share_your_findings/pro_reports/using_the_report_builder + - /metrics_reports/reports/using_the_report_builder +--- +Note: The reusable Report Builder (Themes, Blocks, Templates, and saved Generated Reports) is a DefectDojo Pro feature, currently in beta. + +The DefectDojo Pro Report Builder lets you compose polished reports out of reusable parts, so you can build the pieces once and reuse them everywhere instead of rebuilding a report from scratch each time. You reach it from the **๐Ÿ“„ Reporting** area in the sidebar (the live UI labels it "Reporting BETA"). + +## How it compares to open source + +Open source DefectDojo can build a report, run it, and let you retrieve the output, but it does **not** save report templates or persist the reports you generate. Each report is a one-time effort. + +DefectDojo Pro turns reporting into reusable building blocks. You save **Themes**, **Blocks**, and **Templates** that you can mix, match, and reuse, and every report you run is persisted as a **Generated Report** you can download or re-run later. Pro also exposes the entire workflow through a full REST API and supports LLM-assisted authoring, so reports can be built and run programmatically. + +> **๐Ÿ’ก Tip:** If you are using open source DefectDojo, see the [open source report builder](../using-the-report-builder/) instead. + +## Core concepts + +The Report Builder is made of four pieces, each available as a REST resource under `/api/v2/`: `report_themes`, `report_blocks`, `report_templates`, and `generated_reports`. Understanding how they fit together is the key to building reports efficiently. + +### Themes + +A **Theme** controls the visual style and branding of a report: the colors, the header and footer imagery, and the footer text. By defining a Theme once, you can apply consistent corporate branding to every report you produce. + +A Theme has the following settings: + +| Setting | Purpose | Default | +|---------|---------|---------| +| Name | A label for the Theme | โ€” | +| Primary color | Main brand color | `#1e3a5f` | +| Secondary color | Supporting brand color | `#4a90a4` | +| Accent color | Highlight color | `#e67e22` | +| Text color | Body text color | `#333333` | +| Background color | Page background color | `#ffffff` | +| Footer text | Text shown in the page footer | โ€” | +| Show page numbers | Whether to print page numbers | On | +| Header image | Image displayed in the header | โ€” | +| Footer image | Image displayed in the footer | โ€” | + +> **๐Ÿ’ก Tip:** All five colors are expressed as 7-character hex values (for example, `#1e3a5f`), so you can match your organization's exact brand palette. + +You can build this in the UI (below) or automate it with the [API](../report-builder-api/). + +### Blocks + +A **Block** is a reusable unit of content. You build a Block once, configure what it shows, and then drop it into as many Templates as you like. There are four block types: + +| Block type | What it produces | +|------------|------------------| +| **Stock** | Non-data content such as a cover page, a table of contents, a page break, an image, or a text block. | +| **Tabular** | A table of records drawn from a single entity. | +| **Detail** | A per-record layout, best for long-form fields that render as markdown (for example, description, impact, mitigation, and references). | +| **Chart** | Visual charts. *Coming soon* โ€” this block type is defined in the data model but is not yet available in the API or UI. | + +A **Stock** block is configured by choosing one of five stock types, along with a title, subtitle, text content, or image as appropriate: + +- **Cover page** +- **Table of contents** +- **Page break** +- **Image** +- **Text block** + +**Tabular** and **Detail** blocks both pull live records from one entity. You pick the entity with a model choice, then select which fields to include and how to order the records. The model choice is exactly one of these seven entities: + +- **Organization** +- **Asset** +- **Engagement** +- **Test** +- **Finding** +- **Test type** +- **Risk acceptance** + +> **๐Ÿ’ก Tip:** In DefectDojo Pro, **Assets** were formerly called **Products** and **Organizations** were formerly **Product Types**. You may still encounter the legacy wording in some underlying field and filter names. + +The difference is presentation: a **Tabular** block lays the records out as a table of columns, which is ideal for summaries and inventories, while a **Detail** block renders one record at a time in a long-form layout that is best suited to markdown-rich fields like description, impact, mitigation, and references. + +> **๐Ÿ’ก Tip:** Filters live on the Block, not on the Template. A Block carries its own filters with it, so reusing a Block reuses its filters identically everywhere it appears. If you need the same content but with a different filter, duplicate the Block and adjust the copy. + +You can build this in the UI (below) or automate it with the [API](../report-builder-api/). + +### Templates + +A **Template** is an ordered list of Blocks bound to a single Theme. The Template defines what appears in the report and in what order, while the Theme it is bound to controls how it looks. + +Because a Template references Blocks by inclusion, the same Block can appear in a Template more than once. A reusable page-break Block, for instance, can be inserted between several sections of the same report. + +You can build this in the UI (below) or automate it with the [API](../report-builder-api/). + +### Generated Reports + +Running a Template produces a **Generated Report**: a persisted PDF or HTML file that you can download and re-run on demand. Each Generated Report is **frozen in time** โ€” it captures your DefectDojo data at the moment it was generated and does **not** update automatically when the underlying data later changes. To get a fresh snapshot, re-run the Template. + +A Generated Report moves through these statuses as it is built: + +| Status | Meaning | +|--------|---------| +| Pending | The report has been requested and is queued. | +| Processing | The report is being assembled. | +| Completed | The report is ready to download. | +| Failed | The report could not be generated. | + +> **๐Ÿ”‘ Important:** Reporting must be enabled on your instance, and viewing respects DefectDojo's role-based access control (RBAC) โ€” users only ever see data they are authorized to view, even inside a report. + +You can build this in the UI (below) or automate it with the [API](../report-builder-api/). + +## Building a report in the UI + +The following steps walk through building a report end to end: create a Theme, create the Blocks that hold your content, assemble them into a Template, and generate the final report. + +### Step 1: Create a Theme + +Start in the Themes area. The Themes list shows every Theme you have defined and lets you create a new one. + +![Themes list](images/pro_report_themes_list.png) + +Open a new Theme to set its branding. The Theme form exposes the five colors, an optional header and footer image, the footer text, and the toggle for page numbers. Choose colors that match your organization's brand so every report you produce looks consistent. + +![Theme edit form](images/pro_report_theme_new.png) + +### Step 2: Create Blocks + +Next, build the content Blocks. The Blocks list shows all of your Blocks across every type. + +![Blocks list](images/pro_report_blocks_list.png) + +To create a data-driven Block, choose its type and configure it. The example below is a **Tabular** Block named for open findings: the Block Type is set to Tabular, a header is supplied, the Model is **Finding**, the selected fields are Severity, Title, Product, Age (Days), and SLA Days Remaining, and the records are ordered by Numerical Severity in descending order. Because filters live on the Block, the **Filter Entries** here scope exactly which records this Block will pull wherever it is used. + +![Tabular block configuration](images/pro_report_block_new_tabular.png) + +You can **Preview** a Block to see how it will render with a Theme applied before you commit it to a Template. The preview below shows a styled cover page ("DefectDojo Security Report") picking up the Theme's colors and branding. + +![Rendered block preview](images/pro_report_block_preview.png) + +> **๐Ÿ’ก Tip:** Use **Duplicate** to copy an existing Block when you need the same layout with a different filter. Since filters travel with the Block, duplicating is the right way to produce, say, a "Critical findings" table and a "High findings" table from the same column layout. + +### Step 3: Assemble a Template + +With your Blocks ready, build a Template. The Templates list shows your saved Templates. + +![Templates list](images/pro_report_templates_list.png) + +In the Template editor, you select a Theme and arrange the Blocks in the order they should appear. The example below sequences Cover Page โ†’ Executive Intro โ†’ Open Findings โ†’ KEV โ†’ Page Break โ†’ Asset Inventory. Use **Add Existing Block** to reuse a Block you already built, or **Add New Block** to create one on the spot, and use the drag handles to reorder. Remember that the same Block can appear more than once โ€” a single page-break Block can be inserted between several sections. + +![Template editor](images/pro_report_template_new.png) + +### Step 4: Generate and download + +When the Template is ready, generate the report. The generate dialog confirms the Template and lets you choose the output format โ€” **HTML** or **PDF**. + +![Generate report dialog](images/pro_generate_report_dialog.png) + +Generated reports are collected in the Generated Reports list, which shows each report's status, file format, the time it was requested and completed, and a download link. + +![Generated reports list](images/pro_generated_reports_list.png) + +You can re-run a Template at any time to produce a fresh report. Keep in mind that each Generated Report is frozen in time โ€” it reflects your data as of when it was generated and will not change as DefectDojo data changes, so re-run the Template whenever you need an up-to-date snapshot. + +## Next steps + +- **[Report Builder API](../report-builder-api/)** โ€” script the whole workflow (Themes, Blocks, Templates, and Generated Reports) for repeatable, automated reporting. +- **[Report Builder with an LLM](../report-builder-llm/)** โ€” use LLM-assisted authoring to design and build reports conversationally. diff --git a/docs/content/metrics_reports/reports/PRO__report_builder_api.md b/docs/content/metrics_reports/reports/PRO__report_builder_api.md new file mode 100644 index 00000000000..7505b10512b --- /dev/null +++ b/docs/content/metrics_reports/reports/PRO__report_builder_api.md @@ -0,0 +1,569 @@ +--- +title: "Automating Reports with the API" +description: "Create themes, blocks, and templates, then run reports and download results via the DefectDojo Pro REST API" +draft: false +audience: pro +weight: 21 +slug: report-builder-api +--- +Note: The Report Builder REST API (report themes, blocks, templates, and generated reports) is a DefectDojo Pro feature, currently in beta. + +The Report Builder REST API lets you automate the same Themes, Blocks, and Templates you assemble by hand in the [Report Builder UI](../report-builder/) โ€” and it goes one step further by letting you **run** a template and **download** the finished PDF or HTML. This guide walks the full lifecycle: authenticate, discover the field and filter vocabulary, create the building blocks, then generate and retrieve a report. + +## Authentication + +Every request authenticates with a personal API token sent in the `Authorization` header using the `Token` prefix (not `Bearer`). + +Get your token from the DefectDojo Pro UI under **User Settings โ†’ API v2 Key**. Store it in an environment variable so it never lands in your shell history or a committed script: + +```bash +export DD_IMPORTER_DOJO_API_TOKEN="YOUR_API_TOKEN" +``` + +The base URL for all calls is your instance plus `/api/v2`: + +``` +https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2 +``` + +Required headers: + +| Header | Value | When | +|--------|-------|------| +| `Authorization` | `Token YOUR_API_TOKEN` | Every request | +| `Accept` | `application/json` | Every request | +| `Content-Type` | `application/json` | `POST` / `PATCH` with a JSON body | + +A minimal authenticated request looks like this: + +```bash +curl -s \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/report_themes/" +``` + +List endpoints are paginated with `limit` and `offset` query parameters. + +> **โš ๏ธ Security Notice:** Your API token grants full access to your DefectDojo data. Never paste it into a chat, screenshot, ticket, or committed file. Read it from an environment variable, rotate it if it is ever exposed, and scope tokens to service accounts where possible. + +## The reporting API at a glance + +Four resources make up the Report Builder API. Each supports the standard list (`GET`), create (`POST`), retrieve (`GET {id}/`), update (`PATCH {id}/`), and delete (`DELETE {id}/`) operations, plus a handful of custom actions. + +| Resource | Path | What it is | Custom actions | +|----------|------|------------|----------------| +| Themes | `/report_themes/` | Colors, fonts, header/footer images, page numbers | โ€” | +| Blocks | `/report_blocks/` | A single piece of content: a cover page, a table, or a detail section | `field_options/`, `preview/`, `{id}/preview/`, `{id}/duplicate/` | +| Templates | `/report_templates/` | An ordered list of blocks plus a theme | `{id}/duplicate/` | +| Generated reports | `/generated_reports/` | A run of a template that produces a downloadable file | `{id}/download/` | + +Two more endpoints help you discover the vocabulary you need: + +| Endpoint | Purpose | +|----------|---------| +| `GET /report_blocks/field_options/` | Valid column field paths and ordering options for each model | +| `GET /oa3/schema/?format=json` | The full OpenAPI schema โ€” used to discover valid filter names | + +## Step 1: Discover the vocabulary + +Two things in a block are easy to get wrong if you guess: the **column fields** you list, and the **filters** you apply. The API gives you a source of truth for both. Fetch them first, then build against what the server actually accepts. + +### Column fields and ordering + +`field_options` returns the valid `fields` (column paths) and `ordering_fields` for every model you can put in a tabular or detail block: + +```bash +curl -s \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/report_blocks/field_options/" +``` + +The response is shaped like this (truncated): + +```json +{ + "fields": { + "finding": [ + {"path": "title", "label": "Title"}, + {"path": "severity", "label": "Severity"}, + {"path": "age_days", "label": "Age (days)"} + ], + "asset": [ ... ] + }, + "ordering_fields": { + "finding": [ ... ] + } +} +``` + +Use only the `path` values returned here for a block's `fields` list. Some paths are long-form or markdown and are intended for **detail** blocks rather than narrow tabular columns โ€” `field_options` is the authoritative list, so confirm against it rather than hardcoding an exhaustive set. + +### Filter names from the schema + +A block's filters live in `filter_entries`, where each entry is a `{field, value}` pair. The valid `field` names are the **GET query-parameter names** of the underlying entity's REST endpoint โ€” *not* the labels you see in the UI. Discover them by reading the OpenAPI schema: + +```bash +curl -s \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/oa3/schema/?format=json" \ + > schema.json +``` + +Then read the GET parameters for the entity you are filtering. For findings, look at `paths` โ†’ `/api/v2/findings/` โ†’ `get` โ†’ `parameters`. The analogous endpoints are `/api/v2/assets/` for **assets** (formerly Products), `/api/v2/organizations/` for **organizations** (formerly Product Types), `/api/v2/engagements/`, `/api/v2/tests/`, `/api/v2/test_types/`, and `/api/v2/risk_acceptance/`. Each parameter `name` is a valid filter `field`. + +> **๐Ÿ’ก Tip:** In DefectDojo Pro, **Assets** were formerly called **Products** and **Organizations** were formerly **Product Types**. The underlying filter field paths on findings still use the legacy `product` wording (for example, `test__engagement__product`), even though the entities are now Assets and Organizations. + +> **๐Ÿ”‘ Important:** The server **silently drops** any `filter_entry` whose `field` is not a real GET parameter for that model. No error is raised โ€” the filter simply does not exist on the saved block. Always GET the block back after creating it and compare the returned `filter_entries` to what you sent. + +### Common filter fields + +The tables below list verified, high-value filters. All values are sent as **single-value strings**; booleans are the literal strings `"true"` / `"false"`. + +**Finding filters** + +| Field | Example value | Notes | +|-------|---------------|-------| +| `active` | `"true"` | Boolean string | +| `verified` | `"true"` | Boolean string | +| `is_mitigated` | `"false"` | Boolean string | +| `risk_accepted` | `"false"` | Boolean string | +| `duplicate` | `"false"` | Boolean string | +| `false_p` | `"false"` | Boolean string | +| `out_of_scope` | `"false"` | Boolean string | +| `severity` | `"Critical"` | Single value only โ€” **not** comma-separated. Use one block per severity. | +| `known_exploited` | `"true"` | Boolean string | +| `ransomware_used` | `"true"` | Boolean string | +| `outside_of_sla` | `"1"` | **Numeric** string, not a boolean string | +| `priority_min` | `"800"` | Use `_min`/`_max`, not `_greater_than` | +| `priority_max` | `"1000"` | Use `_min`/`_max` | +| `tag` | `"DR"` | A single tag | +| `tags` | `"kev,pci"` | Any-of (matches any listed tag) | +| `tags__and` | `"kev,pci"` | All-of (must match every listed tag) | +| `test__engagement__product` | `"42"` | Asset ID (Assets were formerly Products) | +| `test__engagement__product__prod_type` | `"3"` | Organization ID (formerly Product Type) | +| `cve` | `"CVE-2024-12345"` | | +| `cwe` | `"79"` | | +| `date_after` | `"2025-12-31"` | | +| `date_before` | `"2025-12-31"` | | +| `planned_remediation_date_before` | `"2025-12-31"` | | + +**Asset filters** (Assets were formerly called Products; these are the parameters on `/api/v2/assets/`) + +| Field | Example value | Notes | +|-------|---------------|-------| +| `business_criticality` | `"very_high"` | | +| `internet_accessible` | `"true"` | Boolean string | +| `lifecycle` | `"production"` | | +| `platform` | `"web"` | | +| `tag` | `"pci"` | A single tag | + +**Risk acceptance filters** + +| Field | Example value | Notes | +|-------|---------------|-------| +| `decision` | `"Accept (Transfer)"` | | +| `owner` | `"7"` | User ID | +| `expiration_date_before` | `"2025-12-31"` | No `tag` filter exists on this model | + +For **engagement**, **test**, **test type**, and **organization** blocks, read the GET parameters straight from the schema as described above. High-value ones include `engagement__product` and `status` on tests, and `name` on test types โ€” but always confirm the exact name in `schema.json` before relying on it. + +> **โš ๏ธ** These legacy / UI-style names are **silently dropped** and must NOT be used: `status_any`, `priority_greater_than`, `severity__in`, `mitigated_within_sla`, and any **comma-separated `severity`** value (e.g. `"Critical,High"`). Use the real query-parameter names from the schema instead, and split multi-severity needs into separate blocks. + +> **๐Ÿ”‘ Important:** A `PATCH` that includes `filter_entries` **replaces the entire list** โ€” there is no merge. Always send the full desired set of filters on every update, or you will drop the ones you omit. + +## Step 2: Create theme, blocks, and templates + +Build the pieces in dependency order: a **theme**, then the **blocks**, then a **template** that references both. + +### Create a theme + +Colors are 7-character hex strings. Any field you omit falls back to its default (primary `#1e3a5f`, secondary `#4a90a4`, accent `#e67e22`, text `#333333`, background `#ffffff`). + +```bash +curl -s -X POST \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + -H "Content-Type: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/report_themes/" \ + -d '{ + "name": "Quarterly Review Theme", + "primary_color": "#1e3a5f", + "secondary_color": "#4a90a4", + "accent_color": "#e67e22", + "text_color": "#333333", + "background_color": "#ffffff", + "footer_text": "Confidential โ€” Internal Use Only", + "show_page_numbers": true + }' +``` + +The response includes the new theme `id`. Header and footer images are optional and are uploaded as multipart form fields (`header_image` / `footer_image`); the JSON example above skips them. + +### Create blocks + +A block has a `name`, a `block_type`, and a matching configuration object. The supported `block_type` values are `stock`, `tabular`, and `detail`. (A `chart` type exists in the data model but is not yet exposed through the API.) + +**A stock cover page.** Stock blocks hold fixed content. The `stock_type` is one of `cover_page`, `table_of_contents`, `page_break`, `image`, or `text_block`. + +```bash +curl -s -X POST \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + -H "Content-Type: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/report_blocks/" \ + -d '{ + "name": "Cover Page", + "block_type": "stock", + "header": "Cover", + "stock_configuration": { + "stock_type": "cover_page", + "title": "Quarterly Security Report", + "subtitle": "Q4 โ€” Active Critical Findings" + } + }' +``` + +**A tabular finding block with filters.** Tabular blocks render rows of a chosen model. `model_choice` is exactly one of `organization`, `asset`, `engagement`, `test`, `finding`, `test_type`, or `risk_acceptance`. The `fields` come from `field_options` (confirm each `path`), and `filter_entries` scope the rows. + +```bash +curl -s -X POST \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + -H "Content-Type: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/report_blocks/" \ + -d '{ + "name": "Active Critical Findings", + "block_type": "tabular", + "header": "Active Critical Findings", + "tabular_configuration": { + "model_choice": "finding", + "fields": ["severity", "title", "age_days", "sla_days_remaining"], + "ordering": "-age_days" + }, + "filter_entries": [ + {"field": "active", "value": "true"}, + {"field": "severity", "value": "Critical"} + ] + }' +``` + +**A detail finding block.** Detail blocks render one expanded section per record and can include long-form / markdown fields that are not suited to a narrow table column. Again, confirm `fields` against `field_options`. + +```bash +curl -s -X POST \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + -H "Content-Type: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/report_blocks/" \ + -d '{ + "name": "Critical Finding Detail", + "block_type": "detail", + "header": "Critical Findings โ€” Detail", + "detail_configuration": { + "model_choice": "finding", + "fields": ["title", "severity", "description", "mitigation"], + "ordering": "-severity" + }, + "filter_entries": [ + {"field": "active", "value": "true"}, + {"field": "severity", "value": "Critical"} + ] + }' +``` + +Each block response includes its `id`. Note that `filter_entries` echoes back what the server actually stored โ€” compare it to what you sent (see [Verify what you built](#verify-what-you-built)). + +### Create a template + +A template binds a theme to an ordered list of blocks. The read-only field is `template_blocks`; on create and update you **write** `template_blocks_write`. Each entry needs an `order` and a `block_id`, and the same `block_id` may appear more than once. + +```bash +curl -s -X POST \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + -H "Content-Type: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/report_templates/" \ + -d '{ + "name": "Quarterly Critical Report", + "description": "Cover page, critical findings table, then per-finding detail", + "theme_id": 1, + "template_blocks_write": [ + {"order": 0, "block_id": 10}, + {"order": 1, "block_id": 11}, + {"order": 2, "block_id": 12} + ] + }' +``` + +Replace `theme_id` and each `block_id` with the IDs returned in the previous steps. The response includes the template `id`. + +## Step 3: Run the report and download the result + +Generating a report is asynchronous: you create a run, poll its status, then download the file once it completes. + +**Start a run.** POST a `template_id` and a `file_format` of `pdf` or `html`: + +```bash +curl -s -X POST \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + -H "Content-Type: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/generated_reports/" \ + -d '{ + "template_id": 5, + "file_format": "pdf" + }' +``` + +The response returns the new report `id` with `status` set to `pending`. + +**Poll for status.** Retrieve the report until its `status` reaches a terminal state. The flow is `pending` โ†’ `processing` โ†’ `completed`. On `failed`, read `error_message` for the reason. + +```bash +curl -s \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/generated_reports/7/" +``` + +**Download the file.** Once `status` is `completed`, the download endpoint returns the file as an attachment. It responds with `404` until then. + +```bash +curl -s -L \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/generated_reports/7/download/" \ + -o report.pdf +``` + +## Putting it together: a full lifecycle script + +The script below runs the entire flow using only the Python 3 standard library โ€” no `requests`, no third-party packages. It reads the token from `DD_IMPORTER_DOJO_API_TOKEN`, creates a theme, three blocks, and a template, kicks off a report, polls with backoff until it completes or fails, downloads the result, and writes the created IDs to `created.json`. + +Set your instance URL and run it: + +```bash +export DD_IMPORTER_DOJO_API_TOKEN="YOUR_API_TOKEN" +export DD_BASE_URL="https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2" +python3 build_report.py +``` + +```python +#!/usr/bin/env python3 +"""Build and run a DefectDojo Pro report end-to-end using only the stdlib.""" + +import json +import os +import time +import urllib.error +import urllib.request + +# --- Configuration ------------------------------------------------------- +BASE_URL = os.environ.get( + "DD_BASE_URL", + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2", +).rstrip("/") +TOKEN = os.environ["DD_IMPORTER_DOJO_API_TOKEN"] # fail loudly if unset +FILE_FORMAT = "pdf" # "pdf" or "html" + + +def api_request(method, path, body=None, accept_json=True): + """Make an authenticated request. Returns parsed JSON (or raw bytes).""" + url = f"{BASE_URL}{path}" + data = json.dumps(body).encode("utf-8") if body is not None else None + + request = urllib.request.Request(url, data=data, method=method) + request.add_header("Authorization", f"Token {TOKEN}") + if accept_json: + request.add_header("Accept", "application/json") + if data is not None: + request.add_header("Content-Type", "application/json") + + try: + with urllib.request.urlopen(request) as response: + payload = response.read() + except urllib.error.HTTPError as error: + # Surface the server's error body to make debugging easy. + detail = error.read().decode("utf-8", errors="replace") + raise SystemExit(f"{method} {path} failed ({error.code}): {detail}") + + if accept_json: + return json.loads(payload) if payload else {} + return payload + + +def main(): + created = {} + + # 1. Create a theme. + theme = api_request("POST", "/report_themes/", { + "name": "Quarterly Review Theme", + "primary_color": "#1e3a5f", + "secondary_color": "#4a90a4", + "accent_color": "#e67e22", + "text_color": "#333333", + "background_color": "#ffffff", + "footer_text": "Confidential - Internal Use Only", + "show_page_numbers": True, + }) + created["theme_id"] = theme["id"] + print(f"Created theme id={theme['id']}") + + # 2. Create a stock cover page block. + cover = api_request("POST", "/report_blocks/", { + "name": "Cover Page", + "block_type": "stock", + "header": "Cover", + "stock_configuration": { + "stock_type": "cover_page", + "title": "Quarterly Security Report", + "subtitle": "Q4 - Active Critical Findings", + }, + }) + created["cover_block_id"] = cover["id"] + print(f"Created stock block id={cover['id']}") + + # 3. Create a tabular finding block scoped to active criticals. + # Confirm the chosen fields against /report_blocks/field_options/. + table = api_request("POST", "/report_blocks/", { + "name": "Active Critical Findings", + "block_type": "tabular", + "header": "Active Critical Findings", + "tabular_configuration": { + "model_choice": "finding", + "fields": ["severity", "title", "age_days", "sla_days_remaining"], + "ordering": "-age_days", + }, + "filter_entries": [ + {"field": "active", "value": "true"}, + {"field": "severity", "value": "Critical"}, + ], + }) + created["table_block_id"] = table["id"] + print(f"Created tabular block id={table['id']}") + + # 4. Create a detail finding block. + detail = api_request("POST", "/report_blocks/", { + "name": "Critical Finding Detail", + "block_type": "detail", + "header": "Critical Findings - Detail", + "detail_configuration": { + "model_choice": "finding", + "fields": ["title", "severity", "description", "mitigation"], + "ordering": "-severity", + }, + "filter_entries": [ + {"field": "active", "value": "true"}, + {"field": "severity", "value": "Critical"}, + ], + }) + created["detail_block_id"] = detail["id"] + print(f"Created detail block id={detail['id']}") + + # 5. Create a template binding the theme to the ordered blocks. + # Note: we WRITE template_blocks_write; template_blocks is read-only. + template = api_request("POST", "/report_templates/", { + "name": "Quarterly Critical Report", + "description": "Cover, critical findings table, then per-finding detail", + "theme_id": created["theme_id"], + "template_blocks_write": [ + {"order": 0, "block_id": created["cover_block_id"]}, + {"order": 1, "block_id": created["table_block_id"]}, + {"order": 2, "block_id": created["detail_block_id"]}, + ], + }) + created["template_id"] = template["id"] + print(f"Created template id={template['id']}") + + # 6. Kick off a report run. + report = api_request("POST", "/generated_reports/", { + "template_id": created["template_id"], + "file_format": FILE_FORMAT, + }) + report_id = report["id"] + created["report_id"] = report_id + print(f"Started report id={report_id} (status={report['status']})") + + # 7. Poll until completed or failed, backing off up to 10 seconds. + delay = 2 + while True: + time.sleep(delay) + report = api_request("GET", f"/generated_reports/{report_id}/") + status = report["status"] + print(f" status={status}") + if status == "completed": + break + if status == "failed": + raise SystemExit( + f"Report failed: {report.get('error_message', 'unknown error')}" + ) + delay = min(delay + 2, 10) # linear backoff, capped + + # 8. Download the finished file. + content = api_request( + "GET", + f"/generated_reports/{report_id}/download/", + accept_json=False, + ) + out_name = f"report.{FILE_FORMAT}" + with open(out_name, "wb") as handle: + handle.write(content) + print(f"Downloaded {out_name} ({len(content)} bytes)") + + # 9. Record the created IDs for later cleanup or reuse. + with open("created.json", "w") as handle: + json.dump(created, handle, indent=2) + print("Wrote created.json") + + +if __name__ == "__main__": + main() +``` + +## Verify what you built + +Because invalid filters are dropped silently, verification is part of the workflow โ€” not an afterthought. + +**Confirm a block's filters survived.** GET each block back and compare its `filter_entries` to what you POSTed: + +```bash +curl -s \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/report_blocks/11/" +``` + +If a filter you sent is missing from `filter_entries`, its `field` name was not a valid GET parameter for that model โ€” recheck the name in `schema.json`. + +**Confirm template order and theme.** GET the template and check that `template_blocks` lists the blocks in the expected `order` and that the bound theme matches: + +```bash +curl -s \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/report_templates/5/" +``` + +**Fix dropped filters with PATCH.** To correct a block's filters, PATCH the **full** desired set โ€” a PATCH replaces `filter_entries` wholesale: + +```bash +curl -s -X PATCH \ + -H "Authorization: Token ${DD_IMPORTER_DOJO_API_TOKEN}" \ + -H "Accept: application/json" \ + -H "Content-Type: application/json" \ + "https://[YOUR-INSTANCE].cloud.defectdojo.com/api/v2/report_blocks/11/" \ + -d '{ + "filter_entries": [ + {"field": "active", "value": "true"}, + {"field": "severity", "value": "Critical"}, + {"field": "outside_of_sla", "value": "1"} + ] + }' +``` + +## Next steps + +- Build and preview the same Themes, Blocks, and Templates interactively in the [Report Builder UI](../report-builder/). +- Let an LLM assemble report configurations for you with the [Report Builder LLM integration](../report-builder-llm/). diff --git a/docs/content/metrics_reports/reports/PRO__report_builder_llm.md b/docs/content/metrics_reports/reports/PRO__report_builder_llm.md new file mode 100644 index 00000000000..add2ccd14a4 --- /dev/null +++ b/docs/content/metrics_reports/reports/PRO__report_builder_llm.md @@ -0,0 +1,398 @@ +--- +title: "Building Reports with an LLM" +description: "Use Claude or another LLM to design, create, run, and download DefectDojo Pro reports via the API" +draft: false +audience: pro +weight: 22 +slug: report-builder-llm +--- +Note: Automating the Report Builder with the REST API and an LLM is a DefectDojo Pro feature, currently in beta. + +DefectDojo Pro's Report Builder (Themes, Blocks, and Templates) is fully driven by the REST API. That means you can hand the whole job to an LLM: paste one self-contained prompt into Claude, ChatGPT, or any other capable model, and it will interrogate your tenant's live OpenAPI schema and `field_options`, propose a theme plus a reusable block library and templates for the audiences you name, emit a runnable Python script, and then run the report and download the finished file. + +The pattern is simple. You provide your base URL, an API token, and a short description of who the reports are for. The LLM does the discovery, design, creation, verification, run, and download โ€” pausing for your approval before it builds anything against your tenant. + +This guide pairs with the [Report Builder API guide](../report-builder-api/), which documents the raw resources and request shapes the LLM is working with. If you want to understand or hand-tune what the LLM produced, that is the reference to keep open. + +## Before you start + +1. **Get an API token.** In the DefectDojo Pro UI, go to **User Settings โ†’ API v2 Key** and copy the token. Then set it as an environment variable so the generated script can read it without the token ever appearing in chat: + +```shell +export DD_IMPORTER_DOJO_API_TOKEN= +``` + +2. **Decide your audiences.** The LLM will ask who the reports are for. Common choices: + + - **Executive Summary** โ€” high-level posture; past-SLA, KEV, and asset inventory at a glance. + - **POA&M (Plan of Action & Milestones)** โ€” open findings with severity, due date, and recommended remediation, plus Critical detail and historical/closed findings. + - **Integrated Inventory Workbook** โ€” assets (formerly Products) in scope with criticality, platform, lifecycle, internet-accessibility, and finding counts. + - **Deviation Request (DRF) Package** โ€” active risk acceptances, DR-tagged findings, and past-SLA candidates for new deviation requests. + - **Engineering Findings Detail** โ€” full per-finding write-ups (description, impact, mitigation, references). + - **Compliance / Audit Snapshot** โ€” assets plus risk acceptances plus KEV. + +> **๐Ÿ’ก Tip:** You do not have to pick from this list. Tell the LLM your real audiences in plain language and it will map them onto the available entities and filters. + +## The prompt + +Copy the entire fenced block below and paste it into Claude, ChatGPT, or any other capable LLM. The prompt is self-contained โ€” the model will ask you for your tenant URL, token environment variable, and report audiences, then walk you through discovery โ†’ design โ†’ create โ†’ verify โ†’ run โ†’ download. + +``` +You are helping me build, run, and download custom reports in DefectDojo Pro +using its REST API and "Report Generator" (Themes / Blocks / Templates / +Generated Reports). + +================================================================================ +DATA MODEL +================================================================================ + +DefectDojo Pro custom reports use these related REST resources (all under +/api/v2/): + + report_themes visual style + report_blocks reusable content units (filters live here) + report_templates ordered blocks + a theme + generated_reports run a template and download the resulting PDF/HTML + +A Template references Blocks by ID and a Theme by ID. A Block carries its own +filters, so reusing a Block reuses its filters identically everywhere. A +Generated Report runs a Template and produces a downloadable file. + +================================================================================ +THEMES +================================================================================ + +A Theme controls the visual style applied to a template. Its fields are: + + name display name for the theme + primary_color 7-char hex (default #1e3a5f) + secondary_color 7-char hex (default #4a90a4) + accent_color 7-char hex (default #e67e22) + text_color 7-char hex (default #333333) + background_color 7-char hex (default #ffffff) + footer_text text shown in the page footer + show_page_numbers boolean -- whether to print page numbers + header_image optional image for the page header + footer_image optional image for the page footer + +All color values are 7-character hex strings (e.g. "#1e3a5f"). + +================================================================================ +BLOCK TYPES +================================================================================ + +A Block's `block_type` is one of: stock | tabular | detail + - stock : non-data content (cover_page, table_of_contents, page_break, + image, text_block). Config goes in `stock_configuration`. + - tabular : a table of records from a DefectDojo entity. Config in + `tabular_configuration`. Required: model_choice, fields[], ordering. + - detail : a per-record detail layout (good for long-text fields like + description, impact, mitigation). Config in + `detail_configuration`. Same required keys as tabular. + +(A `chart` block type is reserved but not yet exposed via the API.) + +`model_choice` is locked to one of EXACTLY these seven entities (this is an +enum in the OpenAPI schema -- do not invent others): + + organization | asset | engagement | test | finding | test_type | risk_acceptance + +NOTE: Even if the tenant has REST endpoints like /api/v2/location/, +/api/v2/location_findings/, or /api/v2/location_products/, those are NOT +selectable as `model_choice`. Any "location" scoping must flow through asset +(formerly Product), tag, or organization (formerly Product Type) filters on +the supported entities. + +================================================================================ +FIELDS (columns) -- discover, never invent +================================================================================ + +For each entity above, the list of valid `fields` (column paths) plus which +paths are allowed for `tabular` vs `detail` blocks is exposed at: + + GET /api/v2/report_blocks/field_options/ + +You MUST fetch this before designing any block. Use only the `path` values it +returns. Some fields are `detail`-only (description, mitigation, impact, +references, etc.) because they hold long-form / markdown content. + +================================================================================ +FILTERS -- this is the most error-prone area; READ CAREFULLY +================================================================================ + +Each tabular/detail block accepts: + + "filter_entries": [ + {"field": "", "value": ""}, + ... + ] + +The OpenAPI schema does NOT enumerate valid filter names. The valid vocabulary +is the GET query-parameter vocabulary of the underlying REST endpoint for that +entity. To discover the real filter names for an entity: + + finding -> GET /api/v2/findings/ (look at `parameters`) + asset -> GET /api/v2/assets/ (formerly Products) + engagement -> GET /api/v2/engagements/ + test -> GET /api/v2/tests/ + test_type -> GET /api/v2/test_types/ + organization -> GET /api/v2/organizations/ (formerly Product Types) + risk_acceptance -> GET /api/v2/risk_acceptance/ + +The fastest way is to load the full OpenAPI schema once: + + GET /api/v2/oa3/schema/?format=json + +then, for each entity, read + schema['paths'][]['get']['parameters'] +and use those `name` values as your filter `field` keys. + +DO NOT invent UI-style filter names (older docs sometimes mention +`status_any`, `priority_greater_than`, or comma-separated multi-value strings +like "Critical,High"). The DD Pro server SILENTLY DROPS or rewrites any +filter_entry whose `field` does not match a real GET-parameter name on the +underlying endpoint. Examples of names that DO work, from a live 2.58.x +tenant, on findings: + + {"field": "active", "value": "true"} boolean + {"field": "verified", "value": "true"} boolean + {"field": "is_mitigated", "value": "true"} boolean + {"field": "risk_accepted", "value": "true"} boolean + {"field": "duplicate", "value": "false"} boolean + {"field": "false_p", "value": "false"} boolean + {"field": "out_of_scope", "value": "false"} boolean + {"field": "severity", "value": "Critical"} single value (NOT comma-separated) + {"field": "known_exploited", "value": "true"} boolean + {"field": "ransomware_used", "value": "true"} boolean + {"field": "outside_of_sla", "value": "1"} NUMERIC (not boolean string) + {"field": "priority_min", "value": "800"} use _min / _max, not _greater_than + {"field": "priority_max", "value": "1000"} + {"field": "tag", "value": "DR"} single tag + {"field": "tags", "value": "kev,pci"} multiple tags (any-of) + {"field": "tags__and", "value": "kev,pci"} multiple tags (all-of) + {"field": "test__engagement__product", "value": ""} + {"field": "test__engagement__product__prod_type","value": ""} + {"field": "cve", "value": "CVE-2024-12345"} + {"field": "cwe", "value": "79"} + {"field": "planned_remediation_date_before", "value": "2025-12-31"} + {"field": "date_before", "value": "2025-12-31"} + {"field": "date_after", "value": "2025-01-01"} + +Asset filters (examples confirmed on live tenant): + + {"field": "business_criticality", "value": "very_high"} + {"field": "internet_accessible", "value": "true"} + {"field": "lifecycle", "value": "production"} + {"field": "platform", "value": "web"} + {"field": "tag", "value": "pci"} + +Risk-acceptance filters (note: no `tag` filter exists here -- filter by +`decision`, `owner`, or `expiration_date` instead, or push the DR-marking +tag onto the underlying findings): + + {"field": "decision", "value": "Accept (Transfer)"} + {"field": "owner", "value": ""} + {"field": "expiration_date_before", "value": "2025-12-31"} + +Operational rules for filter_entries: + + - Single-value strings only. "Critical,High" in one severity entry will NOT + keep both -- DefectDojo will store only "Critical". To cover multiple + severities, create separate blocks (one per severity) or compose multiple + filter rows where the underlying endpoint supports it (e.g. tags__and). + - Booleans go as the LITERAL string "true" or "false". + - PATCHing filter_entries REPLACES the whole list. Always send the full + desired set; never assume merge semantics. + - After POSTing a block, GET it back and compare the returned filter_entries + against what you sent. If any entry is missing, the field name was rejected + -- look it up in `parameters` on the corresponding REST endpoint. + +================================================================================ +TEMPLATES +================================================================================ + +A Template ties blocks together in order and binds them to a theme: + + POST /api/v2/report_templates/ + { + "name": "", + "description": "", + "theme_id": , + "template_blocks_write": [ + {"order": 0, "block_id": }, + {"order": 1, "block_id": }, + ... + ] + } + +The same `block_id` can appear multiple times (e.g. a "page break" block +reused several times in the same template). + +================================================================================ +GENERATED REPORTS -- run a template, then download the file +================================================================================ + +A Generated Report runs a Template and produces a downloadable file. + +1. Kick off a run: + + POST /api/v2/generated_reports/ + { + "template_id": , + "file_format": "pdf" // or "html" + } + + This returns a generated_reports record with an `id` and a `status`. + +2. Poll until it finishes: + + GET /api/v2/generated_reports/{id}/ + + `status` moves through: pending -> processing -> completed (or failed). + Poll on an interval until it reaches "completed". If it reaches "failed", + read `error_message` for the reason and stop. + +3. Download the file once completed: + + GET /api/v2/generated_reports/{id}/download/ + + This returns the binary PDF/HTML body. It returns 404 until status is + "completed", so only call it after polling confirms completion. Save the + response body to a file with the matching extension. + +================================================================================ +AUTH +================================================================================ + +Every request needs: + + Authorization: Token + Accept: application/json + Content-Type: application/json (on POST/PATCH) + +Get the token from User Settings -> API v2 Key in the DefectDojo Pro UI. + +================================================================================ +WHAT I WANT YOU TO DO +================================================================================ + +1. Ask me for: + - my DefectDojo Pro base URL (e.g. https://.cloud.defectdojo.com/api/v2) + - the env var name that holds my API token (default: DD_IMPORTER_DOJO_API_TOKEN) + - the audiences/reports I want (e.g. Executive Summary, POA&M, + Inventory Workbook, Deviation Request package, Engineering Detail, + Compliance/Audit Snapshot) + - any specific filters I care about (severity tiers, SLA cutoffs, KEV-only, + specific assets, tags, etc.) + - branding for the theme (primary/secondary/accent colors, footer text, + whether to show page numbers) + - which output format I want for the run: "pdf" or "html" + +2. Discover the live vocabulary BEFORE designing anything: + - GET /api/v2/oa3/schema/?format=json and save locally + - GET /api/v2/report_blocks/field_options/ and save locally + - For each entity I want to report on, extract the GET parameters from the + schema and show me the candidate filter names so we agree on vocabulary. + +3. Propose a design back to me consisting of: + - one shared theme (with the branding from step 1) + - a reusable Block library (cover page, page breaks, intro text blocks, + and the data tables/details I need) + - 1+ Templates that compose those blocks for the audiences I named + For every data block, show me: model_choice, fields[], ordering, and the + exact filter_entries list. Wait for my approval. + +4. Once I approve, generate a SINGLE Python script (stdlib only, urllib -- + no extra dependencies needed) that: + - reads the token from the env var I named + - POSTs the theme, then the blocks, then the templates (in that order, + because templates reference block IDs and a theme ID) + - prints each returned ID as it goes + - dumps everything to a created.json file for verification + - THEN runs and downloads the report (see steps 6-8 below) as part of the + same script + Show me the full script before running it. + +5. After creating, VERIFY: + - GET each created block back and confirm filter_entries persisted + EXACTLY as POSTed. If any entry is missing, that field name was rejected + by DD -- look it up in `parameters` on the relevant REST endpoint and + PATCH the block with the corrected vocabulary. + - GET each template back and confirm the block_id list and order, plus + theme_id binding, are correct. + +6. RUN the report: + - POST /api/v2/generated_reports/ with + { "template_id": , "file_format": "pdf" } (or "html") + - capture the returned generated report `id`. + +7. POLL until done: + - GET /api/v2/generated_reports/{id}/ on a short interval. + - statuses progress: pending -> processing -> completed/failed. + - stop polling when status is "completed". + - if status is "failed", read and print `error_message`, then stop. + +8. DOWNLOAD the file: + - once status is "completed", GET /api/v2/generated_reports/{id}/download/ + (it 404s until completed) and save the response body to a file with the + correct extension (.pdf or .html). + - print the saved file path. + +9. If I later want to tune a filter, swap a block, or change colors: + - PATCH the existing resource (do not recreate). + - When PATCHing filter_entries, send the FULL desired list -- it replaces, + not merges. + - Re-run steps 6-8 to regenerate the file. + +================================================================================ +HARD CONSTRAINTS +================================================================================ + +- Do NOT invent field paths or filter names. If unsure, GET field_options + (for column paths) or the entity's GET parameters (for filter names) and + use only what's there. +- Do NOT use "Critical,High" or other comma-separated values inside a single + severity/status filter_entry value -- DD will keep only the first match. + Use one block per value, or use multi-value filters that DD's underlying + endpoint explicitly supports (e.g. `tags`, `tags__and`). +- Do NOT use the older UI-style filter names like `status_any`, + `priority_greater_than`, `mitigated_within_sla`, or `severity__in`. They + are silently dropped. +- Do NOT call the download endpoint before status is "completed" -- it 404s. +- Show me each batch of commands or the full script before running it. +- Stop and ask if anything in the schema is ambiguous rather than guessing. + +Start by asking me for the base URL, the env var name holding the token, my +audience goals, theme branding, and my preferred output format. +``` + +## How to use it + +1. **Paste the prompt** above into Claude, ChatGPT, or another capable LLM. +2. **Answer its discovery questions.** It will ask for your base URL, the environment variable holding your token, your audiences, any specific filters you care about (severity tiers, SLA cutoffs, KEV-only, particular assets or tags), your branding, and the output format you want. +3. **Review the proposed design and approve before it builds.** The model should come back with one shared theme, a reusable block library, and one or more templates โ€” showing, for every data block, the `model_choice`, `fields`, ordering, and exact filter entries. Do not let it create anything against your tenant until you have signed off. +4. **Let it generate and run the script.** The single Python script (standard library only) creates the theme, blocks, and templates, then runs the report and downloads the finished file. +5. **It should verify before and after the run.** Expect it to GET each block and template back to confirm filters and ordering persisted, then POST to `generated_reports`, poll until status is `completed`, and download the file. + +> **๐Ÿ’ก Tip:** If the LLM jumps straight to designing blocks without first fetching your tenant's live schema (`/api/v2/oa3/schema/?format=json`) and `field_options`, push back. Filter and field names vary by version, and designing from memory is exactly how blocks end up silently missing filters. + +## Troubleshooting + +**A created block comes back missing filters you sent.** The filter `field` name did not match a real GET parameter on the underlying entity, so DefectDojo dropped it. Have the LLM fetch `/api/v2/oa3/schema/?format=json`, read the `parameters` list for that entity's GET endpoint (for example the findings endpoint), and use a real parameter name. + +**Boolean filters are not taking effect.** Boolean values must be sent as the strings `"true"` or `"false"`, not actual JSON booleans. + +**`outside_of_sla` is not filtering.** That filter takes a numeric value as a string โ€” use `"1"`, not `"true"`. + +**Multiple severities in one block do not work.** A single block keeps only the first severity. Split into one block per severity instead. + +**Template blocks come back in the wrong order or missing.** Make sure the LLM POSTed `template_blocks_write` (the write-only field), not `template_blocks` (which is read-only). The `order` field is required on every entry. + +**The report run is stuck or failed.** Keep polling `GET /api/v2/generated_reports/{id}/` โ€” status moves from `pending` to `processing` to `completed`. If status becomes `failed`, read the `error_message` field for the cause before retrying. + +> **โš ๏ธ** The download endpoint (`/api/v2/generated_reports/{id}/download/`) returns 404 until the run reaches `completed`. Always poll to completion before downloading. + +## Next steps + +- [Report Builder (UI)](../report-builder/) โ€” design and run reports interactively in the DefectDojo Pro interface. +- [Report Builder API](../report-builder-api/) โ€” the raw REST resources and request shapes the LLM is working with, for hand-tuning or deeper automation. diff --git a/docs/content/metrics_reports/reports/_index.md b/docs/content/metrics_reports/reports/_index.md index 2ab02bc3710..8ec7b3923a4 100644 --- a/docs/content/metrics_reports/reports/_index.md +++ b/docs/content/metrics_reports/reports/_index.md @@ -13,4 +13,31 @@ seo: canonical: "" robots: "" exclude_search: true ---- \ No newline at end of file +--- +The Report Builder lets you turn DefectDojo data into polished, shareable reports โ€” executive summaries, compliance snapshots, POA&M packages, engineering detail, and more โ€” for audiences inside and outside your security team. + +## Open source vs. DefectDojo Pro + +How you build reports depends on which edition you run: + +| | Open Source | DefectDojo Pro | +|---|---|---| +| **Build a report** | Yes โ€” assemble from widgets | Yes โ€” compose from reusable Blocks | +| **Run and retrieve output** | Yes (HTML, print-to-PDF) | Yes (saved PDF or HTML) | +| **Save reusable Themes / Blocks / Templates** | No โ€” rebuild each time | Yes | +| **Persisted history of generated reports** | No | Yes โ€” list, download, re-run | +| **REST API + LLM automation** | โ€” | Yes โ€” full create โ†’ run โ†’ download | + +In short: **open source** lets you build a report, run it, and export the result, but does not save templates or keep a report history. **DefectDojo Pro** turns reporting into reusable, brandable building blocks that you can drive from the UI, the REST API, or an LLM. + +## Where to go next + +**DefectDojo Pro** + +- **[Report Builder](report-builder/)** โ€” concepts (Themes, Blocks, Templates, Generated Reports) and a full UI walkthrough. +- **[Automating Reports with the API](report-builder-api/)** โ€” create, run, poll, and download reports over the REST API, with a complete script. +- **[Building Reports with an LLM](report-builder-llm/)** โ€” let an LLM design, create, run, and download reports for you. + +**Open Source** + +- **[Using the Report Builder](using-the-report-builder/)** โ€” build, run, and export a report with the widget-based builder. \ No newline at end of file diff --git a/docs/content/metrics_reports/reports/using_the_report_builder.md b/docs/content/metrics_reports/reports/using_the_report_builder.md deleted file mode 100644 index b1e85ddbc9f..00000000000 --- a/docs/content/metrics_reports/reports/using_the_report_builder.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: "Using the Report Builder" -description: "Build and publish custom reports for external audiences, or your own records" -weight: 1 -aliases: - - /en/share_your_findings/pro_reports/using_the_report_builder ---- -DefectDojo allows you to create Custom Reports for external audiences, which summarize the Findings or Endpoints that you wish to report on. Custom Reports can include branding and boilerplate text, and can also be used as **[Templates](https://docs.defectdojo.com/metrics_reports/reports/working_with_generated_reports/)** for future reports. - -## Opening the Report Builder - -The Report Builder can be opened from the **๐Ÿ“„Reports** page on the sidebar. - -![image](images/Using_the_Report_Builder.png) - -The report builder page is organized in two columns. The left **Report Format** column is where you can design your report, using widgets from the right **Available Widgets** column. - -![image](images/Using_the_Report_Builder_2.png) - -## Step 1: Set Report Options - -![image](images/Using_the_Report_Builder_3.png) - -From the Report Options section, you can take the following actions: - -* Set a **Report Name** for the Report or Template -* Include user\-created **Finding Notes** in the report -* Include **Finding Images** in the report -* Upload a header **Image** to the report - -### Select a header image for your report - -To add an image to the top of your report, click the **Choose File** button and upload an image to DefectDojo. - -The image will automatically resize to fit the document, and will render directly above your **Report Name**. - -![image](images/Using_the_Report_Builder_4.png) - -## Step 2: Add content to your report with Widgets - -Once you have set your Report Options, you can begin to design your report using DefectDojoโ€™s widgets. - -Widgets are content elements of a report which can be added by dragging and dropping them into the Report Format column. The final Report will be generated based on the position of each Widget, with the **Report Name** and **Header Image** rendered at the top. - -* The elements of your report can be reordered by dragging and dropping your widgets into a new order. -* To remove a widget from a report, click and drag it back to the right column. -* Widgets can also be collapsed by clicking on the grey header, for ease in navigation through a report builder. -* The Findings Widget, WYSIWYG Widget and the Endpoints widget can be used more than once. - -For more information about Report Widgets, see our [Report Widget index](./#report-widget-index). - -## Step 3: Publish and view your Report - -Once you have finished building your report, you can generate it by clicking the green โ€˜**Runโ€™** button at the bottom of the **Report Format** section. - -This will automatically take you to the Generated Reports page, and your report will begin to generate in the background. You can check on the Status of your report by reading the Status column next to it, and refreshing the page periodically. - -Once your report has generated, you can view it by either clicking on the **Status** (which will be set to โ€˜Complete: View Reportโ€™), or by opening the **โ‹ฎ** menu next to your report and selecting **View Report**. - -![image](images/Using_the_Report_Builder_14.png) - -## Step 4: Exporting a Report - -Only DefectDojo users will have access to Reports stored in the software, but Reports are set up in a way where they can be exported or printed easily. - -The easiest method to use is to Print To PDF \- with an HTML Report open, open a **Print** dialog in your browser and set **Save To PDF** as the **Print Destination**. - -![image](images/Using_the_Report_Builder_15.png) - -## Report formatting suggestions - -* WYSIWYG sections can be used to contextualize or summarize Finding lists. We recommend using this widget throughout your report in between Findings or Vulnerable Endpoints widgets. - -## Report Widget Index - -### Cover Page Widget - -The Cover Page Widget allows you to set a Heading, Sub heading and additional metadata for your report. You can only have a single Cover Page for a given Report. - -![image](images/Using_the_Report_Builder_5.png) - -### Executive Summary Widget - -The Executive Summary widget is intended to summarize your report at a glance. It contains a Heading (defaults to Executive Summary), as well as a text box which can contain whatever information you feel is required to summarize the report. - -![image](images/Using_the_Report_Builder_6.png) - -You can also **Include SLAs** in your executive summary. To add images, markup formatting or anything beyond pure text, consider adding a **WYSIWYG Content Widget** immediately after the executive summary. - -* You can only have a single Executive Summary for a given Report. -* If your Report contains multiple SLA configurations (I.E. you have Findings from separate Products which each have their own standards for SLA) each SLA configuration will be listed on the Executive Summary as a separate row. - -### Severities Widget - -As each organization will have different definitions for each severity level, the Severities Widget allows you to define the Severity Levels used in your report for ease of understanding. - -![image](images/Using_the_Report_Builder_7.png) - -### Table Of Contents Widget - -The Table Of Contents Widget creates a list of each Finding in your report, for quicker access to specific Findings. The table of contents will create a separate heading for each Severity contained within the report. Each Finding listed in the table of contents will have an anchor link attached to quickly jump to the Finding in the report. - -![image](images/Using_the_Report_Builder_8.png) - -* You can add a section of **Custom Content**, which will add text underneath the Heading. -* You can upload an image to the Table Of Contents by clicking the **Choose File** button next to the **Image** line. The uploaded image will render directly above the **Heading** selected. Images will be resized to fit the document. - -### WYSIWYG Content Widget - -The WYSIWYG (What You See Is What You Get) widget can be used to add a section containing text and images in your report. Multiple copies of this Widget can be added to add context to other sections of your report. - -![image](images/Using_the_Report_Builder_9.png) - -* WYSIWYG Content can include an optional Heading. -* Images can be added to a WYSIWYG widget by dragging and dropping them directly into the **Content** box. Images inserted into the Content box will render at their full resolution. -* You can add multiple WYSIWYG widgets to a report. - -### Findings Widget - -The Findings Widget provides a list and summary of each Finding you want to include in your report. You can set the scope of the Findings you wish to include with Filters. - -The Findings Widget is divided into two sections. The upper section contains a list of filters which can be used to determine which Findings you want to include, and the lower section contains the resulting list of Findings after filters are applied. - -To apply filters to your Findings widget, set the filter parameters and click the **Apply Filter** button at the bottom. You can preview the results of your filter by checking the Findings list located underneath the Filters section. - -![image](images/Using_the_Report_Builder_10.png) - -* As with Widgets, the Filters section can be expanded and collapsed by clicking the gret Filters header. -* You can add multiple separate Findings Widgets to your report with different filter parameters if you want the report to contain more than one list of Findings. -* Only the Findings you are authorized to view are included in these listings, with respect to Role\-Based Access Control. - -#### Example Rendered Finding List - -![image](images/Using_the_Report_Builder_11.png) - -### Vulnerable Endpoints Widget - -The Vulnerable Endpoints widget is similar to the Findings widget. You can use this widget to list all Findings for specific Endpoints, and sort the Finding list by Endpoint instead of by Severity level. - -The **Vulnerable Endpoints** widget will list each active Finding for the Endpoints selected. Rather than creating a single list of unsorted Findings this feature will separate them into their Endpoint context. - -As with the Findings Widget, the Vulnerable Endpoints Widget is divided into a Filter section and a list of resulting Endpoints from the filter parameters. - -![image](images/Using_the_Report_Builder_12.png) - -Select the parameters for the Endpoints you wish to include here and click the **Apply Findings** button at the bottom. You can preview the results of your filter by checking the Endpoints list located underneath the Filters section. - -* You can add multiple separate Vulnerable Widgets to your report with different filter parameters if you want the report to contain more than one list. -* Only the Findings you are authorized to view are included in these listings, with respect to Role\-Based Access Control. - -### ---- (separator) Widget - -This Widget will render a light grey horizontal line to divide between sections. - -![image](images/Using_the_Report_Builder_13.png) \ No newline at end of file diff --git a/docs/content/metrics_reports/reports/working_with_generated_reports.md b/docs/content/metrics_reports/reports/working_with_generated_reports.md deleted file mode 100644 index 74f211f41a8..00000000000 --- a/docs/content/metrics_reports/reports/working_with_generated_reports.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "Templates and Historical Reports" -description: "Use a report as a template, or re-run an existing report with updated data" -weight: 2 -aliases: - - /en/share_your_findings/pro_reports/working_with_generated_reports ---- -Once you have created one or more **Reports** in DefectDojo you can take further actions, including: - -* Using a report as a template for subsequent reports - -* Re-running a report with updated data - -* Deleting an old or unused report - -![image](images/Working_with_Generated_Reports.png) - -## Use a report as a Template - -DefectDojo allows you to easily create Report templates with your team logo, boilerplate text and a standardized content order. - -If you want to change the way a report is set up, or create a new one with a similar layout, you can re\-open the Report Builder by selecting **View Template** from the **โ‹ฎ** menu next to the report you wish to use as a template. - -There are two places where you can find a Report Template to use: - -1. From the **Generated Reports** page, where you can see a list of completed reports -2. From the **Report Templates** page, where you can see a list of previously run reports, including reports which were deleted from the **Generated Reports** page. - -Both of these pages can be found in the ๐Ÿ“„ **Reports** tab on the sidebar. - -![image](images/Working_with_Generated_Reports_2.png) - -To access the **Report Templates** page, open ๐Ÿ“„**Reports \> Report Templates** from the sidebar. From that table, you can open the report builder by clicking the **โ‹ฎ** menu next to the report you wish to use as a template. - -Every time you make changes to a template or previous report, the result will be saved as a **new** report under Generated Reports so that you don't lose the older version. If you like, the older version can be deleted. - -## Re\-Running a Report - -DefectDojo Reports are โ€˜frozen in timeโ€™ \- to keep your records consistent, they do not update automatically when DefectDojo experiences data changes. - -However, if you want to create an updated version of a previously created report, you can do so by selecting **Re\-run Report** from the **โ‹ฎ** menu next to the report you wish to generate. - -Selecting this option will create a new report in the **Generated Reports** list, with a different **Created** timestamp to indicate that the report was run at a separate time. - -![image](images/Working_with_Generated_Reports_3.png) - -## Deleting a Report - -If you no longer need a report, you can delete it by selecting **Delete Report** from the **โ‹ฎ** menu next to the report you wish to delete. Note that this will only remove the report from the **Generated Reports** list \- a record of the report will still exist under **Report Templates** if you want to re\-run it. diff --git a/docs/content/triage_findings/findings_workflows/intro_to_findings.md b/docs/content/triage_findings/findings_workflows/intro_to_findings.md index 70fd854ec15..5f60358fed3 100644 --- a/docs/content/triage_findings/findings_workflows/intro_to_findings.md +++ b/docs/content/triage_findings/findings_workflows/intro_to_findings.md @@ -75,7 +75,7 @@ If youโ€™re in charge of security reporting for many different contexts, softwar * Each Product in DefectDojo can have a different SLA configuration, so that you can instantly flag Findings that are discovered in Production or other highly sensitive environments. * You can create a report directly from a **Product Type, Product, Engagement or Test** to โ€˜zoom in and outโ€™ of your security context. **Tests** contain results from a single tool, **Engagements** can combine multiple Tests, **Products** can contain multiple Engagements, **Product Types** can contain multiple Products. -For more information on creating a Report, see our guides to **[Custom Reporting](/metrics_reports/reports/using_the_report_builder)**. +For more information on creating a Report, see our guides to **[Custom Reporting](/metrics_reports/reports/)**. ### Triage Vulnerabilities using Finding Status