docs(sensei): Sensei documentation chapter (GitHub and GitLab) (#15308)

* docs(sensei): add Sensei chapter as its own top-level tab

Document DefectDojo Pro's Sensei (AI scan-and-fix) feature as a new
top-level docs tab with a multi-page chapter:

- content/sensei/: About, Set Up, Fixing Findings, Reference (audience: pro)
  plus an Open Source "Pro-only feature" explainer (OS__sensei.md).
- menus.en.toml: Sensei top-level tab + sidebar_sensei section menu.
- params.toml: add "sensei" to doks.sectionNav so the chapter renders a
  left sidebar.
- custom.js: generalize the edition-aware top-nav so the Sensei tab swaps
  between the OS explainer and the Pro guide (mirrors "Model Your Assets").
- pro_features.md: add a Sensei entry linking to the guide.
- Screenshots captured from a DefectDojo-org demo repo (no internal repos).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(sensei): document GitLab connectivity and clean prose

Add the GitLab portion of the Sensei docs alongside the existing GitHub content:
a "Connect GitLab" section (access-token scopes/role, base URL, webhook setup),
a provider note in About, and a "GitLab specifics" reference section
(merge requests, commit-status gate, self-managed). Also remove em dashes and
tidy phrasing across the Sensei chapter for a consistent, plain style.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Maffooch

docs/assets/js/custom.js

@@ -22,24 +22,34 @@ window.ddOffcanvas = Offcanvas;
 (() => {
     "use strict";
 
-    // Asset-modelling landing pages per edition. The top nav is otherwise
-    // static, so a single URL can't be correct for both editions: we keep the
-    // "Model Your Assets" nav link in sync with the selected version, and —
-    // when the user is already viewing one of these pages — navigate to the
-    // matching edition's page so the main content follows the toggle.
-    const assetNavUrls = {
-        opensource: "/asset_modelling/engagements_tests/os__assets/",
-        pro: "/asset_modelling/pro_hierarchy/asset_hierarchy/",
+    // Edition-specific landing pages per top-nav tab. The top nav is otherwise
+    // static, so a single URL can't be correct for both editions: we keep these
+    // nav links in sync with the selected version, and — when the user is
+    // already viewing one of these pages — navigate to the matching edition's
+    // page so the main content follows the toggle. Keyed by nav-link label.
+    const editionNavUrls = {
+        "Model Your Assets": {
+            opensource: "/asset_modelling/engagements_tests/os__assets/",
+            pro: "/asset_modelling/pro_hierarchy/asset_hierarchy/",
+        },
+        // Sensei is Pro-only: Open Source shows a short "Pro feature" page,
+        // Pro shows the full guide.
+        "Sensei": {
+            opensource: "/sensei/os__sensei/",
+            pro: "/sensei/about_sensei/",
+        },
     };
 
-    const switchAssetPageForVersion = (version) => {
-        const target = assetNavUrls[version];
-        const other = assetNavUrls[version === "pro" ? "opensource" : "pro"];
-        // Only redirect when currently on the *other* edition's asset page,
-        // so this never fires on unrelated pages or loops on the target page.
-        if (target && location.pathname === other) {
-            location.assign(target);
-        }
+    const switchPageForVersion = (version) => {
+        Object.values(editionNavUrls).forEach((urls) => {
+            const target = urls[version];
+            const other = urls[version === "pro" ? "opensource" : "pro"];
+            // Only redirect when currently on the *other* edition's page, so
+            // this never fires on unrelated pages or loops on the target page.
+            if (target && location.pathname === other) {
+                location.assign(target);
+            }
+        });
     };
 
     const setVersion = (version) => {
@@ -58,11 +68,12 @@ window.ddOffcanvas = Offcanvas;
             btn.setAttribute("aria-checked", btn.dataset.versionValue === version ? "true" : "false");
         });
 
-        // Edition-aware top nav: route "Model Your Assets" to the page that
-        // matches the selected version (see assetNavUrls above).
+        // Edition-aware top nav: route these tabs to the page that matches the
+        // selected version (see editionNavUrls above).
         document.querySelectorAll("a.nav-link").forEach(link => {
-            if (link.textContent.trim() === "Model Your Assets") {
-                link.setAttribute("href", assetNavUrls[version] || assetNavUrls.opensource);
+            const urls = editionNavUrls[link.textContent.trim()];
+            if (urls) {
+                link.setAttribute("href", urls[version] || urls.opensource);
             }
         });
     };
@@ -80,8 +91,8 @@ window.ddOffcanvas = Offcanvas;
         if (btn) {
             setVersion(btn.dataset.versionValue);
             // Only on an explicit user toggle (not on load) follow the page to
-            // the matching edition when viewing an asset-modelling page.
-            switchAssetPageForVersion(btn.dataset.versionValue);
+            // the matching edition when viewing one of the edition-specific pages.
+            switchPageForVersion(btn.dataset.versionValue);
         }
     });
 

docs/config/_default/menus/menus.en.toml

@@ -23,6 +23,42 @@
   url = "/metrics_reports/dashboards/introduction_dashboard/"
   weight = 14
 
+[[main]]
+  name = "Sensei"
+  # Sensei is Pro-only. Default to the Open Source "Pro feature" page; custom.js
+  # swaps this tab to the full guide (/sensei/about_sensei/) when Pro is selected.
+  url = "/sensei/os__sensei/"
+  weight = 14
+
+# Left-hand section sidebar for the Sensei chapter (the chapter is flat, so the
+# Doks subsection-based sidebar has nothing to render without this menu).
+# Entries are audience-filtered by the version toggle: the opensource page shows
+# in the OS view, the pro pages show in the Pro view.
+[[sidebar_sensei]]
+  name = "Sensei"
+  pageRef = "/sensei/OS__sensei"
+  weight = 0
+
+[[sidebar_sensei]]
+  name = "About Sensei"
+  pageRef = "/sensei/about_sensei"
+  weight = 1
+
+[[sidebar_sensei]]
+  name = "Set Up Sensei"
+  pageRef = "/sensei/setup_sensei"
+  weight = 2
+
+[[sidebar_sensei]]
+  name = "Fixing Findings with Sensei"
+  pageRef = "/sensei/fixing_findings"
+  weight = 3
+
+[[sidebar_sensei]]
+  name = "Sensei Reference"
+  pageRef = "/sensei/sensei_reference"
+  weight = 4
+
 [[main]]
   name = "Admin"
   url = "/admin/admin_intro/intro/"

docs/config/_default/params.toml

@@ -56,7 +56,8 @@ mainSections = ["docs"]
     "admin",
     "automation",
     "asset_modelling",
-    "issue_tracking"] # ["docs"] (default) or list of sections (e.g. ["docs", "guides"])
+    "issue_tracking",
+    "sensei"] # ["docs"] (default) or list of sections (e.g. ["docs", "guides"])
 
   toTopButton = true # scroll-to-top button
   breadcrumbTrail = true # breadcrumb navigation on doc pages

docs/content/get_started/pro/pro_features.md

@@ -39,6 +39,12 @@ See our [Rules Engine Guide](/automation/rules_engine/about) for more info.
 
 ![image](images/rules_engine_4.png)
 
+### Sensei
+
+DefectDojo Pro's **Sensei** (BETA) is an AI-powered scan-and-fix capability: connect a repository through a GitHub App and Sensei scans it, imports the findings, and opens pull requests that remediate them — with a preview-first workflow, so nothing runs (and no LLM cost is incurred) until you approve.
+
+See our [Sensei Guide](/sensei/about_sensei/) for more info.
+
 ### Pro Dashboards and Reporting
 
 Generate [instant reports and metrics](/get_started/about/ui_pro_vs_os/#new-dashboards) to share the security posture of your apps and repos, evaluate your security tools and analyze your team's performance in addressing security issues.

docs/content/sensei/OS__sensei.md

@@ -0,0 +1,27 @@
+---
+title: "Sensei"
+description: "Sensei is a DefectDojo Pro feature"
+draft: false
+audience: opensource
+weight: 1
+---
+<span style="background-color:rgba(242, 86, 29, 0.3)">Note: Sensei is a DefectDojo Pro-only feature.</span>
+
+**Sensei**, DefectDojo's AI-powered **scan-and-fix** for source code repositories, is available only in **DefectDojo Pro**. It is not part of the open-source edition.
+
+With Sensei, DefectDojo Pro can:
+
+- Scan your GitHub repositories and import the results as findings.
+- Open pull requests that **remediate** those findings with a large language model, using a preview-first approval workflow (nothing runs until you approve).
+- Start a fix from the findings table, from staged auto-fix candidates, or with a `/fix` comment on a pull request.
+
+## See the full Sensei documentation
+
+The complete Sensei guide is part of the **Pro** documentation. Switch the documentation version toggle (top of the left navigation) to **Pro** to read it:
+
+- **About Sensei:** what it is and how hosted scan-and-fix works
+- **Set Up Sensei:** connect a GitHub App and onboard a repository
+- **Fixing Findings with Sensei:** scan, triage candidates, and open fix PRs
+- **Sensei Reference:** statuses, quotas, and troubleshooting
+
+To learn more about DefectDojo Pro, visit [defectdojo.com](https://www.defectdojo.com/) or contact your DefectDojo account team.

docs/content/sensei/_index.md

@@ -0,0 +1,19 @@
+---
+title: "Sensei"
+description: "AI-powered scan-and-fix for your source code repositories"
+summary: ""
+date: 2023-09-07T16:06:50+02:00
+lastmod: 2023-09-07T16:06:50+02:00
+draft: false
+weight: 5
+chapter: true
+sidebar:
+  collapsed: true
+seo:
+  title: "" # custom title (optional)
+  description: "" # custom description (recommended)
+  canonical: "" # custom canonical URL (optional)
+  robots: "" # custom robot tags (optional)
+audience: pro
+exclude_search: true
+---

docs/content/sensei/about_sensei.md

@@ -0,0 +1,58 @@
+---
+title: "About Sensei"
+description: "What Sensei is and how DefectDojo-hosted scan-and-fix works"
+draft: false
+audience: pro
+weight: 1
+---
+<span style="background-color:rgba(242, 86, 29, 0.3)">Note: Sensei is a DefectDojo Pro-only feature and is currently in BETA.</span>
+
+**Sensei** is DefectDojo's AI-powered **scan-and-fix** capability for source code repositories. Connect a repository (through a **GitHub App** or a **GitLab** access token) and Sensei scans it, imports the results as DefectDojo findings, and then uses a large language model to **remediate those findings by opening pull/merge requests**, all without leaving DefectDojo.
+
+> **🔀 GitHub and GitLab:** Sensei supports both providers with the same scan-and-fix flow. On GitLab (gitlab.com or self-managed), a *pull request* is a **merge request** and the PR *status check* is a **commit status**. Connection differs by provider (see [Set up Sensei](/sensei/setup_sensei/)); everything after onboarding is identical.
+
+- **Scan-and-fix in one place:** repositories are scanned and remediated from the Sensei page and from your findings, using the same normalized, deduplicated finding data as the rest of DefectDojo.
+- **Preview-first:** Sensei stages fix *candidates* for review. Nothing is sent to an LLM and no pull request is opened until you approve, so there is no surprise cost or unexpected PR.
+- **Short-lived credentials:** Sensei runs entirely through a GitHub App and uses short-lived installation tokens. There is nothing to paste and nothing to rotate.
+- **Metered and license-gated:** Sensei is a Pro feature with per-instance quotas for fixes and onboarded repositories.
+
+> **🔎 BETA:** Sensei is under active development and is labeled **BETA** throughout the UI. Behavior and screens may change between releases.
+
+> **📍 Where to find it:** open **Sensei** from the left-hand navigation.
+
+![Sensei hub](images/hub_overview.png)
+
+## How DefectDojo-hosted scanning works
+
+DefectDojo-hosted scanning is the recommended way to run Sensei. Scans run **inside DefectDojo**, and nothing is added to your repository:
+
+1. **Connect a GitHub App** and install it on the organization (or account) that owns your repositories.
+2. **Onboard a repository** for hosted scanning and choose how findings are reported and (optionally) auto-fixed.
+3. **Sensei scans the repository** (on demand, or automatically when a pull request is opened) and imports the results into an engagement named after the branch.
+4. **Sensei remediates findings** by generating a fix and opening a pull request against the repository's default branch.
+
+Each onboarded repository is linked to a DefectDojo **asset** (product), so its findings, engagements, and fixes live alongside the rest of your data.
+
+## The three ways a fix gets started
+
+Sensei can remediate a finding in three ways:
+
+- **The Fix button on a finding:** trigger a one-off fix directly from the findings table or a finding's detail page. See [Fixing findings with Sensei](/sensei/fixing_findings/).
+- **Auto-fix candidates:** after each scan, Sensei stages the findings that match your criteria as candidates. You review them and approve the ones to fix (or let Sensei remediate them automatically). See [Auto-fix candidates](/sensei/fixing_findings/#auto-fix-candidate-triage).
+- **A `/fix` comment on a pull request:** comment `/fix` on a pull request and Sensei pushes a remediation to that PR.
+
+## Requirements
+
+- A **DefectDojo Pro** license that includes the **Sensei** feature.
+- A connected source-control provider (see [Set up Sensei](/sensei/setup_sensei/)): either a **GitHub App** installed on the organization/account that owns the repositories, or a **GitLab** project/group access token (gitlab.com or self-managed).
+- To **configure** Sensei (connect apps, onboard repositories): a global **Maintainer** or **Owner** role.
+- To **trigger a fix** on a finding: at least **Writer** access to that finding's product.
+
+## Quotas
+
+Sensei is metered against your license. The Sensei hub shows two usage meters at the top of the page:
+
+- **Fixes:** the number of remediations applied against your prepaid limit. Approving a candidate or triggering a fix consumes from this quota.
+- **Onboarded Repositories:** the number of repositories onboarded against your repository limit.
+
+When a quota is reached, Sensei blocks further fixes (or onboarding) until it is raised. See [Reference](/sensei/sensei_reference/#quotas-and-metering) for details.

docs/content/sensei/fixing_findings.md

@@ -0,0 +1,70 @@
+---
+title: "Fixing Findings with Sensei"
+description: "Scan, triage auto-fix candidates, and open fix pull requests"
+draft: false
+audience: pro
+weight: 3
+---
+<span style="background-color:rgba(242, 86, 29, 0.3)">Note: Sensei is a DefectDojo Pro-only feature and is currently in BETA.</span>
+
+Once a repository is onboarded, Sensei surfaces directly on your findings and on the Sensei hub. This page covers scanning a repository, triaging auto-fix candidates, and remediating individual findings. You need at least **Writer** access to a finding's product to trigger a fix.
+
+## Scan a repository
+
+Scans import findings into an engagement named after the branch. You can trigger a scan on demand from the Sensei hub: open a repository's row actions and choose **Scan now**.
+
+![Scan with Sensei dialog](images/scan_dialog.png)
+
+Pick the branch to scan (it defaults to the repository's default branch) and choose **Start scan**. In DefectDojo-hosted mode, scans also run automatically when a pull request is opened.
+
+## The Sensei column on findings
+
+Onboarded repositories add a **Sensei** column to the findings table. Each finding shows a **Fix** button (or its current fix status), so you can remediate without leaving your triage view.
+
+![Sensei column on the findings table](images/findings_sensei_column.png)
+
+The button has two states:
+
+- **Fix:** the finding's product is onboarded to Sensei. Clicking it starts a remediation.
+- **Configure Product:** the finding's product is **not** onboarded yet. Clicking it takes you to Sensei to onboard a repository for that product; once onboarded, the button becomes **Fix**.
+
+## Fix a single finding
+
+Clicking **Fix** (on the findings table or in a finding's detail header) opens the **Fix with Sensei** dialog. Choose the base branch the fix pull request should target, then click **Fix**.
+
+![Fix with Sensei dialog](images/fix_with_sensei_dialog.png)
+
+Sensei generates a remediation and opens a pull request. The finding's fix status is shown as a badge that moves through *in progress* → *PR open* (or *failed*). Once the pull request is open, the badge links straight to it.
+
+![Finding detail with fix status badge](images/finding_detail_fix.png)
+
+> **💡 One fix, one PR:** each approved fix consumes one fix from your quota and opens one pull request. Review and merge the PR in GitHub as you would any other.
+
+## Auto-fix candidate triage
+
+When a repository has automated fixes enabled, each scan stages matching findings as **candidates** on the **Auto-fix Candidates** tab of the Sensei hub. This is Sensei's preview-first model: findings are staged, but **nothing runs (no LLM cost) until you approve**. Approving opens fix pull requests and consumes fixes.
+
+![Auto-fix candidate triage](images/auto_fix_candidates.png)
+
+Each candidate shows the finding, its status, severity, risk, priority, target repository, and PR branch. To remediate:
+
+- **Approve one:** click **Approve** on a row to open the branch picker and start that fix.
+- **Approve several:** select multiple rows and use the bulk approve action.
+
+Approved findings stay listed as **In Progress** (or **Failed**) until their pull request is attached, so an in-flight or failed fix never disappears before it produces a PR.
+
+> **🔎 Hands-off remediation:** if you enabled *Automatically remediate candidates* on the repository, a background check opens fix PRs for staged candidates automatically, up to your fix quota, without manual approval.
+
+## Track scans and impact
+
+Two places on the Sensei hub help you follow what Sensei has done:
+
+- **Scan Activity:** a ledger of every scan and fix run, with its mode (Branch Scan, PR Scan, Fix (Finding)), trigger (Manual, Webhook, Auto Remediated), status, execution time, and links to the engagement or the pull request it produced.
+
+  ![Scan Activity ledger](images/scan_activity.png)
+
+- **Fix Impact:** a summary of fixes applied, with the assets fixed most often, at the top of the hub.
+
+  ![Fix Impact panel](images/fix_impact.png)
+
+Use the **Scan now**, **Scan history**, **Configure**, and **Re-stage candidates** row actions to manage each onboarded repository over time (see [Reference](/sensei/sensei_reference/#repository-row-actions)).