> For the complete documentation index, see [llms.txt](https://docs.gomboc.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gomboc.ai/gomboc-playbook.md). # Gomboc Playbook ### 1. The Daily Triage: Dashboard & High-Level Metrics *As an Engineer starting my day, I need a quick overview of our infrastructure health to see if any critical vulnerabilities were recently introduced, and to track our overall remediation progress.* The [Dashboard](https://app.gomboc.ai/) is your command center. It provides immediate visibility into your security posture through high-level stats and visualizations: * **Fixes**: The count of unique fixes found over the lifetime of your account. A growing number indicates a growing backlog. * **Time Saved**: An estimated ROI metric calculating the engineering hours saved by Gomboc’s automated code remediation. * **Repositories**: The total number of code repositories scanned during the latest indexing update. #### Key Charts to Monitor: * **Fixes by Top Severity**: Don't look at everything at once. Use this chart to identify if there are any new "Critical" issues: these are your priority targets for the day. * **Fixes by Top Targets**: This chart tells you *where* the bleeding is. It identifies the specific resources, code syntax trees, or policies that are generating the most hits. * **Number of Fixes**: A visual timeline showing the volume of fixes delivered over time, perfect for tracking weekly progress.
*** ### 2. The Weekly Review: Managing Reports *As a Lead preparing for a weekly sync, I need to filter out the noise, identify the most pressing issues from the last sprint, and export a report for the Engineering /* *Leadership team* The [Reports](https://app.gomboc.ai/reports) view is where you drill down into specific findings; to avoid alert fatigue, you must aggressively filter this list. #### Strategic Filtering Navigate to the Reports tab on the left-hand menu and open the advanced filtering sidebar: * **Time Range**: Set this to the "Last 7 days" to focus exclusively on recent drifts and new code changes. * *This is crucial for weekly syncs so you only look at recent drifts and new code changes, rather than historical tech debt.* * **Severity vs. Risk**: * Severity refers to the vulnerability threat level (High, Critical). * Risk Level refers to *operational* risk—such as the potential for data loss, downtime, or complex change control required to apply the fix. * *Note: You can also specify several other filters, such as Origin (e.g. Gomboc default scheduled runs, the* [*IDE Plugin*](https://docs.gomboc.ai/integrations/vscode-plugin)*, specific* [*Policies*](https://docs.gomboc.ai/policy-management) *and more)* * **Exporting Data**: Use the CSV export function to share prioritized findings with stakeholders who do not use the Gomboc platform.
*** ### 3. Continuous Remediation: Reviewing and Delivering Fixes *As an Engineer, I need to review a security finding, validate the proposed Infrastructure-as-Code (IaC) fix, and merge it safely into our repository.* This is where Gomboc moves from "alerting" to "**fixing**." When you find a priority issue in your Reports list, follow this Remediation workflow: 1. **Open the Finding**: Click on a specific fix in the report from your filtered list. 2. **Analyze the Code Diff**: Gomboc will display a remediation report, including all details from the specific finding as well as the code diff to address it (verify that the logic aligns with your architecture) 1. ```
``` 3. **Deliver the Fix**: If the code looks good, click on the workspace name for that fix (at the top, next to the "Remediation report for:"); it will bring you to the workspace where you'll see all the most recent runs and the "Deliver Fixes" button. Gomboc will automatically create a Pull Request (PR) directly in your SCM tool (GitHub, GitLab, etc.). 1. ```
``` 4. **Merge in SCM**: Your team reviews and merges the PR in GitHub/GitLab as usual. Once merged, Gomboc detects the change and marks the issue as resolved. **How to Handle Exceptions**: If an issue is already mitigated by an external tool (like a WAF), you shouldn't apply a code fix. 1. Click Create Exception on the finding (expanding the bottom section "Applied rules"). 2. Select the relevant Policy Set. 3. Provide a clear Reasoning Note for compliance tracking. 1. ```
``` > ⚠️ Pro-Tip : Use caution here. Applying an exception might suppress all instances of that detection globally across that policy set, not just for this specific line of code. *** ### 4. Platform Administration: Workspaces & Governance *As an Engineer, I need to onboard a new microservice repository and ensure it strictly adheres to our production compliance standards (e.g., OWASP Top 10).* #### Managing Workspaces [Workspaces](https://docs.gomboc.ai/workspaces) are the primary scan units in Gomboc, defined by a combination of: Repository + Branch + Path + Language. * **Automatic Detection**: Gomboc's remediation language engine automatically detects the languages and relevant files within a repository (via `pom.xml`, `.tf` files, etc.) to map out workspaces. * **Tags**: You can add custom tags to workspaces for internal grouping, or configure Gomboc to automatically reflect existing tags inherited from GitHub/GitLab.
#### Policies and Policy Sets Gomboc allows for granular, segmented control over code governance through [Policy Mgmt](https://docs.gomboc.ai/policy-management): * [**Policy Library**](https://app.gomboc.ai/policies): Contains the hierarchy of rules anchored to specific security frameworks. * **Custom Classifications**: You can create your own custom policy hierarchies to align with internal company compliance initiatives, while still mapping them to external standards like OWASP. * [**Policy Sets**](https://app.gomboc.ai/policy-sets): Group policies together and apply them to specific workspaces. For example, you can enforce a "Strict Default" set for Production workspaces, and a more lenient "Development" set for lower environments. *** ### 5. Troubleshooting & Operational Status Checks If your automated PRs fail to generate or scans seem delayed, follow this troubleshooting checklist: * [**Run History**](https://app.gomboc.ai/runs): View the execution details of every scan. You can check the status (In Progress, Success, Failed), duration, and access the raw scan logs for deep-dive troubleshooting. * [**Status Page**](https://status.gomboc.ai/): Check `status.gomboc.ai` to verify the operational health of Gomboc's infrastructure and the API connections to your SCM platforms. * **Check Token Permissions** *(reachable through your Profile icon on the top right > Settings)*: * **API Tokens**: Created by admins and accessible at the account level for system-to-system integrations. * **Personal Tokens**: Individual user tokens that carry the same permissions as API tokens but are restricted in scope to the specific user's actions.