diff --git a/docs/content/sensei/fixing_findings.md b/docs/content/sensei/fixing_findings.md index c19c53cdf0c..2525f557ddb 100644 --- a/docs/content/sensei/fixing_findings.md +++ b/docs/content/sensei/fixing_findings.md @@ -7,7 +7,7 @@ weight: 3 --- Note: Sensei is a DefectDojo Pro-only feature and is currently in BETA. -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 Asset to trigger a fix. +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 Asset to trigger a fix. Linking a new repository to an Asset (below) needs the global **Maintainer** or **Owner** role, the same as onboarding. ## Finding your way around the Sensei hub @@ -29,18 +29,46 @@ Pick the branch to scan (it defaults to the repository's default branch) and cho ## 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 adds 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 Asset is onboarded to Sensei. Clicking it starts a remediation. -- **Configure Asset:** the finding's Asset is **not** onboarded yet. Clicking it takes you to Sensei to onboard a repository for that Asset; once onboarded, the button becomes **Fix**. +Clicking **Fix** walks you through whatever Sensei still needs to open a pull request, so you no longer have to set up onboarding first. If the finding's Asset already has a linked repository, you go straight to the fix; if it does not, Sensei asks for one on the spot. The [next section](#fix-a-single-finding) covers the whole flow. On the findings table an Asset that is not linked yet may instead show **Configure {Asset}**; clicking it starts the same flow. ## 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**. +Clicking **Fix** (on the findings table or in a finding's detail header) starts a short, guided flow. Sensei only asks for what it is missing, then opens the fix. + +### Link a repository, if the Asset does not have one + +Sensei fixes a finding by opening a pull request, so it needs to know which repository the finding's code lives in. If the finding's Asset is not linked to a repository yet, Sensei asks for one right there, rather than sending you off to set up onboarding first. + +![Linking a repository at fix time](images/link_repository_dialog.png) + +There are two ways to supply it: + +- **From a connection:** pick a repository from a source-control connection you already have. +- **Enter manually:** paste the repository's URL and an access token. Sensei reads the provider and repository name from the link, so this is how you fix a repository Sensei has no connection for. + +The link is remembered, so the next fix on the same Asset goes straight to the pull request. A repository you link this way is **fix-only**: it is available for fixes but does not start scanning until you enable it (see [Repositories linked at fix time](#repositories-linked-at-fix-time)). + +### Choose the repository, if the Asset has several + +An Asset can be linked to more than one repository. When it is, Sensei asks which one the finding belongs to before it opens the pull request. + +![Choosing which repository a finding belongs to](images/repo_fix_picker.png) + +### Point Sensei at the file, if the finding has no location + +Sensei patches a file, so a finding needs a file path. Findings imported from some scanners arrive without one, or with a path that does not line up with your repository layout. When that happens, Sensei asks where the code lives. + +![Telling Sensei where the code lives](images/locate_file_dialog.png) + +Paste a link to the file (a GitHub, GitLab, Bitbucket, or Azure DevOps permalink, which fills in the path and line for you) or type the repository-relative path. Sensei records it on the finding and continues. + +### Open the pull request + +Once Sensei has a repository and a file, the **Fix with Sensei** dialog confirms the base branch the pull request should target. Choose the branch, then click **Fix**. ![Fix with Sensei dialog](images/fix_with_sensei_dialog.png) @@ -61,6 +89,26 @@ What closes the finding is the next scan that sees the fix in place. For code sc While a fix is outstanding, the same finding may keep being reported by each new scan. Sensei recognises those as the same underlying issue and will not stage another candidate or open a second pull request for it, so a slow review or deploy does not consume extra fixes. +## Repositories linked at fix time + +A repository you link from a finding (the [Link a repository](#link-a-repository-if-the-asset-does-not-have-one) step above) is added for fixes only. It does not scan, and inbound webhooks do not trigger anything for it, until you turn scanning on. This keeps an ad-hoc fix from quietly enrolling a repository in scanning you did not ask for. + +On the **Repositories** view of the Sensei hub, a fix-only repository is marked **Fix-only**. + +![A fix-only repository on the Repositories view](images/targets_fix_only.png) + +To start scanning it, open its row actions and choose **Enable scanning**. From then on it behaves like any onboarded repository. + +![Enabling scanning on a fix-only repository](images/enable_scanning_menu.png) + +## Cloud findings: link the repository inline + +A cloud posture finding (from a connected cloud account) is usually fixed by changing the infrastructure-as-code that provisions the resource, so Sensei opens a pull request against that repository rather than patching the finding's own file. Clicking **Fix** on such a finding follows the same gap-closing flow as a code finding. + +If the finding's cloud account is not yet linked to an infrastructure-as-code repository, Sensei asks for one inline, in the same **Link a Repository** dialog used for code findings. The cloud account is detected from the finding automatically (its provider and account are already on the finding), so you only supply the repository, from a connection or by pasting its URL and a token. Sensei records the account, links the repository, and continues into the fix. + +Once linked, the repository fixes that account's findings from then on, and if more than one repository is linked to the account Sensei asks which one a given finding belongs to before opening the pull request. Linking an infrastructure-as-code repository this way does not enable direct cloud remediation, which stays a separate, explicitly configured action. + ## 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. diff --git a/docs/content/sensei/images/enable_scanning_menu.png b/docs/content/sensei/images/enable_scanning_menu.png new file mode 100644 index 00000000000..6de5a82714a Binary files /dev/null and b/docs/content/sensei/images/enable_scanning_menu.png differ diff --git a/docs/content/sensei/images/link_repository_dialog.png b/docs/content/sensei/images/link_repository_dialog.png new file mode 100644 index 00000000000..5b80b0711f7 Binary files /dev/null and b/docs/content/sensei/images/link_repository_dialog.png differ diff --git a/docs/content/sensei/images/locate_file_dialog.png b/docs/content/sensei/images/locate_file_dialog.png new file mode 100644 index 00000000000..3810e20b396 Binary files /dev/null and b/docs/content/sensei/images/locate_file_dialog.png differ diff --git a/docs/content/sensei/images/repo_fix_picker.png b/docs/content/sensei/images/repo_fix_picker.png new file mode 100644 index 00000000000..1cc09c7a389 Binary files /dev/null and b/docs/content/sensei/images/repo_fix_picker.png differ diff --git a/docs/content/sensei/images/targets_fix_only.png b/docs/content/sensei/images/targets_fix_only.png new file mode 100644 index 00000000000..86c9d10f0cd Binary files /dev/null and b/docs/content/sensei/images/targets_fix_only.png differ