Add detailed explanations for integration with GitHub, GitLab, Jira, and external entity providers #93
+428
−15
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,8 +1,84 @@ | ||||||
| import Image from 'next/image'; | ||||||
| import { Callout, Steps } from 'nextra/components'; | ||||||
| import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/ui/tooltip"; | ||||||
|
|
||||||
| # External Entity Providers | ||||||
|
|
||||||
| External Entity Providers allow DevGuard to synchronize organizational structure and permissions from external platforms like GitLab. Instead of manually creating organizations, projects, and assets in DevGuard, you can import them directly from your existing infrastructure. | ||||||
|
|
||||||
| ## Overview | ||||||
|
|
||||||
| External Entity Providers enable: | ||||||
|
|
||||||
| - **Automatic Organization Creation**: GitLab instances become DevGuard organizations | ||||||
| - **Project Synchronization**: GitLab groups map to DevGuard projects | ||||||
| - **Asset Discovery**: GitLab projects map to DevGuard assets | ||||||
| - **Permission Inheritance**: External access levels translate to DevGuard roles | ||||||
| - **Real-time Sync**: Permissions update when users authenticate | ||||||
| - **Issue Management**: Vulnerabilities can be tracked in the same platform | ||||||
|
|
||||||
|
|
||||||
|
|
||||||
| ## Entity Mapping | ||||||
|
|
||||||
| | External Entity | DevGuard Entity | | ||||||
| |-----------------|-----------------| | ||||||
| | GitLab Instance | Organization | | ||||||
| | GitLab Group | Project | | ||||||
| | GitLab Project | Asset | | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
|
|
||||||
| ## Synchronization Process | ||||||
|
|
||||||
| When a user authenticates via an external provider: | ||||||
|
|
||||||
| 1. **Token Retrieval**: DevGuard retrieves OAuth2 tokens from the identity provider | ||||||
| 2. **Organization Sync**: Organizations are created/updated based on the provider | ||||||
| 3. **Project Sync**: GitLab groups are synchronized as DevGuard projects | ||||||
| 4. **Asset Sync**: GitLab projects within groups are synchronized as DevGuard assets | ||||||
| 5. **Permission Sync**: User roles are updated based on external permissions | ||||||
|
|
||||||
| ## Permission Synchronization | ||||||
|
|
||||||
| | GitLab Access Level | DevGuard Role | | ||||||
| |---------------------|---------------| | ||||||
| | Owner / Maintainer | Admin | | ||||||
| | Developer / Reporter / Guest | Member | | ||||||
|
|
||||||
| When external permissions change, DevGuard: | ||||||
|
|
||||||
| - **Revokes Old Roles**: Removes access to projects/assets the user no longer has access to | ||||||
| - **Grants New Roles**: Adds access based on current external permissions | ||||||
| - **Updates Existing Roles**: Adjusts role levels if permissions changed | ||||||
|
|
||||||
| ## Triggering Sync | ||||||
|
|
||||||
| ### Automatic Sync | ||||||
|
|
||||||
| Synchronization occurs automatically when: | ||||||
| - Users authenticate via the external provider | ||||||
| - Users access an organization linked to an external entity | ||||||
|
Member
There was a problem hiding this comment. We are doing this only after a fixed interval. So not all requests to an organization will issue a whole sync. |
||||||
|
|
||||||
| ### Manual Sync | ||||||
|
|
||||||
| Users can trigger a manual sync via the DevGuard UI or API endpoints. | ||||||
|
|
||||||
|
|
||||||
| ## Benefits | ||||||
|
|
||||||
| - **Single Source of Truth**: Permissions are managed in your existing platform | ||||||
| - **Reduced Administration**: No need to manually create DevGuard entities | ||||||
| - **Automatic Updates**: Changes in external systems reflect in DevGuard | ||||||
| - **Consistent Access**: Users have the same access levels across platforms | ||||||
|
|
||||||
| ## Limitations | ||||||
|
|
||||||
| - **Provider Support**: Currently limited to GitLab | ||||||
| - **Token Validity**: Requires valid OAuth2 tokens for sync | ||||||
|
Member
There was a problem hiding this comment. There is another limitation: devguard can never decide if a user just lost access to an repository on Gitlab or if it got deleted. Thus devguard will be never delete any external entity projects and instead just revokes permissions |
||||||
|
|
||||||
|
|
||||||
| ## Related Documentation | ||||||
|
|
||||||
| - [GitLab Integration](/explanations/integrations/gitlab-integration) — GitLab-specific integration details | ||||||
| - [GitLab Permission Sync](/how-to-guides/integrations/gitlab/permission-sync) — Configure permission synchronization | ||||||
| - [Integration Architecture](/explanations/integrations/integration-architecture) — Overall integration design | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,8 +1,75 @@ | ||
| import Image from 'next/image'; | ||
| import { Callout, Steps, Tabs } from 'nextra/components'; | ||
| import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/ui/tooltip"; | ||
|
|
||
| # GitHub Integration | ||
|
|
||
| DevGuard integrates with GitHub through a **GitHub App**, providing secure access to your repositories for issue management. | ||
|
|
||
| ## Overview | ||
|
|
||
| The GitHub integration provides: | ||
|
|
||
| - **Repository Access**: List and import repositories from GitHub organizations | ||
| - **Issue Management**: Create and update GitHub Issues for discovered vulnerabilities | ||
| - **Webhook Processing**: React to issue changes and comments in real-time | ||
| - **CI/CD Integration**: Automated scanning via GitHub Actions | ||
|
|
||
| <Callout type="info"> | ||
| The GitHub App enables secure repository access and manages webhooks for issue tracking. Vulnerability scanning is authenticated separately using a DevGuard Token (Personal Access Token, PAT). | ||
| </Callout> | ||
|
|
||
|
|
||
|
|
||
| ## How It Works | ||
|
|
||
| 1. **Configure Integration**: Add the DevGuard GitHub App to your GitHub organization | ||
| 2. **Link Asset**: Connect a DevGuard asset to a GitHub repository | ||
| 3. **Create Issues**: Vulnerabilities can be pushed to GitHub Issues for tracking (automatically or manually) | ||
| 4. **Sync Status**: Changes in either system are synchronized via webhooks | ||
|
|
||
|
|
||
| ## Issue Creation | ||
|
|
||
| When a vulnerability is flagged for remediation, DevGuard creates a GitHub issue containing detailed information about the vulnerability, including severity, affected components, and labels for categorization. | ||
|
|
||
| ## Comment Commands | ||
|
|
||
| Users can control vulnerability status through issue comments: | ||
|
|
||
| | Command | Effect | | ||
| |---------|--------| | ||
| | `/accept <reason>` | Accept the vulnerability risk | | ||
| | `/false-positive <reason>` | Mark as false positive | | ||
|
Member
There was a problem hiding this comment. Please double check. Isn't the user forced to provide the mechanical justification instead like vulnerable code not present? |
||
| | `/reopen` | Reopen a closed vulnerability | | ||
|
|
||
| <Callout type="info"> | ||
| Only repository collaborators can use these commands. DevGuard verifies permissions before processing. | ||
| </Callout> | ||
|
|
||
|
|
||
|
|
||
| ### Processed Events | ||
|
|
||
| | Event | Action | | ||
| |-------|--------| | ||
| | Issue Closed | Vulnerability marked as accepted | | ||
| | Issue Reopened | Vulnerability reopened | | ||
| | Issue Deleted | Vulnerability marked as false positive | | ||
| | Comment Added | Process slash commands | | ||
|
|
||
| ## Issue State Synchronization | ||
|
|
||
| | GitHub Action | DevGuard Interpretation | | ||
| |---------------|-------------------------| | ||
| | Close issue | Vulnerability accepted | | ||
| | Reopen issue | Vulnerability reopened | | ||
| | Delete issue | Vulnerability false positive | | ||
|
|
||
|
|
||
| ## Related Documentation | ||
|
|
||
| - [Setup GitHub Integration](/how-to-guides/integrations/github/setup-github-integration) — Step-by-step setup guide | ||
| - [GitHub Webhooks](/how-to-guides/integrations/github/webhooks) — Configure webhooks | ||
| - [GitHub Auto-Setup](/how-to-guides/integrations/github/auto-setup) — Automated repository configuration | ||
| - [Scan with GitHub Actions](/how-to-guides/scanning/scan-with-github-actions) — CI/CD integration guide | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,8 +1,92 @@ | ||
| import Image from 'next/image'; | ||
| import { Callout, Steps, Tabs } from 'nextra/components'; | ||
| import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/ui/tooltip"; | ||
|
|
||
| # GitLab Integration | ||
|
|
||
| DevGuard integrates with GitLab through two authentication methods: **Personal Access Token (PAT)** or **OAuth2**. Both methods support gitlab.com and self-hosted GitLab instances. | ||
|
|
||
| | Method | Use Case | | ||
| |--------|----------| | ||
| | **Personal Access Token** | Repository access, issue management | | ||
| | **OAuth2** | Permission sync, External Entity Provider | | ||
|
|
||
| <Callout type="info"> | ||
| This page covers the **Personal Access Token** integration. For OAuth2-based integration, see [External Entity Providers](./external-entity-providers). | ||
| </Callout> | ||
|
|
||
| ## Overview | ||
|
|
||
| The GitLab PAT integration provides: | ||
|
|
||
| - **Repository Access**: List and import GitLab projects | ||
| - **Issue Management**: Create and update GitLab Issues for vulnerabilities | ||
| - **Webhook Processing**: React to issue and note events in real-time | ||
| - **CI/CD Integration**: Automated scanning via GitLab CI/CD pipelines | ||
|
|
||
| <Callout type="info"> | ||
| The GitLab PAT enables secure repository access and manages webhooks for issue tracking. Vulnerability scanning is authenticated separately using a DevGuard Token (Personal Access Token, PAT). | ||
| </Callout> | ||
|
|
||
| ## How It Works | ||
|
|
||
| 1. **Configure Integration**: Add your GitLab instance URL and Personal Access Token in DevGuard | ||
| 2. **Link Asset**: Connect a DevGuard asset to a GitLab project | ||
| 3. **Create Issues**: Vulnerabilities can be pushed to GitLab Issues for tracking (automatically or manually) | ||
| 4. **Sync Status**: Changes in either system are synchronized via webhooks | ||
|
|
||
|
|
||
| ## Issue Creation | ||
|
|
||
| When a vulnerability is flagged for remediation, DevGuard creates a GitLab issue containing detailed information about the vulnerability, including severity, affected components, and labels for categorization. | ||
|
|
||
| ## Comment Commands | ||
|
|
||
| Users can control vulnerability status through issue comments: | ||
|
|
||
| | Command | Effect | | ||
| |---------|--------| | ||
| | `/accept <reason>` | Accept the vulnerability risk | | ||
| | `/false-positive <reason>` | Mark as false positive | | ||
| | `/reopen` | Reopen a closed vulnerability | | ||
|
|
||
| ## Webhook Processing | ||
|
|
||
| DevGuard processes GitLab webhooks to synchronize issue state changes. | ||
|
|
||
| <Callout type="warning"> | ||
| Configure the webhook secret in your GitLab settings to ensure only authenticated requests are processed. DevGuard only accepts webhooks with a valid secret. | ||
| </Callout> | ||
|
|
||
| ### Processed Events | ||
|
|
||
| | Event | Action | | ||
| |-------|--------| | ||
| | Issue Closed | Vulnerability marked as accepted | | ||
| | Issue Reopened | Vulnerability reopened | | ||
| | Comment Added | Process slash commands | | ||
|
|
||
| ## Issue State Synchronization | ||
|
|
||
| | GitLab Status | DevGuard Interpretation | | ||
| |---------------|-------------------------| | ||
| | Open | Open vulnerability | | ||
| | Closed | Closed vulnerability | | ||
|
|
||
| ## Self-Hosted Instances | ||
|
|
||
| GitLab integration fully supports self-hosted GitLab instances: | ||
|
|
||
| - Configure your GitLab instance URL in the OAuth2 or Access Token settings | ||
| - Multiple GitLab instances can be connected simultaneously | ||
| - Each instance is treated as a separate External Entity Provider | ||
|
|
||
| ## Testing the Integration | ||
| When saving a new GitLab integration, DevGuard performs a test connection to validate the provided credentials and permissions. If the test fails, an error message will indicate the issue. | ||
|
|
||
| ## Related Documentation | ||
|
|
||
| - [Setup GitLab Integration](/how-to-guides/integrations/gitlab/setup-gitlab-integration) — Step-by-step setup guide | ||
| - [GitLab Permission Sync](/how-to-guides/integrations/gitlab/permission-sync) — Configure permission synchronization | ||
| - [GitLab Webhooks](/how-to-guides/integrations/gitlab/webhooks) — Configure webhooks | ||
| - [External Entity Providers](/explanations/integrations/external-entity-providers) — Understanding external entities |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,8 +1,98 @@ | ||
| import Image from 'next/image'; | ||
| import { Callout, Cards, Card } from 'nextra/components'; | ||
| import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/ui/tooltip"; | ||
|
|
||
| # Integration Architecture | ||
|
|
||
| DevGuard is designed as a flexible and extensible platform that integrates with a wide variety of security tools, code hosting platforms, and issue tracking systems. The architecture is built around a core API that allows for seamless integration with third-party services. | ||
|
|
||
| ## Overview | ||
|
|
||
| DevGuard's integration architecture serves two primary purposes: | ||
|
|
||
| 1. [**Finding Vulnerabilities**](#finding-vulnerabilities): Integrate with your code repositories and CI/CD pipelines to automatically scan code for vulnerabilities | ||
| 2. [**Managing Vulnerabilities**](#managing-vulnerabilities): Track and manage discovered vulnerabilities in your preferred issue tracking system | ||
|
|
||
| ```mermaid | ||
| graph TB | ||
| subgraph "Code Hosting Platforms" | ||
| GH[GitHub] | ||
| GL[GitLab] | ||
| end | ||
|
|
||
| subgraph "DevGuard" | ||
|
|
||
| end | ||
|
|
||
| subgraph "Issue Tracking" | ||
| GHI[GitHub Issues] | ||
| GLI[GitLab Issues] | ||
| JIRA[Jira] | ||
| end | ||
|
|
||
| GH --> DevGuard | ||
| GL --> DevGuard | ||
| DevGuard --> GHI | ||
| DevGuard --> GLI | ||
| DevGuard --> JIRA | ||
|
|
||
| ``` | ||
|
|
||
| ## Finding Vulnerabilities | ||
|
|
||
| You can integrate DevGuard with your code repository and CI/CD pipeline so that every time you push code or create a pull request, DevGuard automatically scans your code for vulnerabilities and reports the results. | ||
|
|
||
| ### Authentication Method | ||
| Scan results are sent to DevGuard using a **Personal Access Token (PAT)** also called DevGuard Token. This token authenticates the scanner and to your asset in DevGuard. | ||
|
|
||
|
|
||
|
|
||
| ## Managing Vulnerabilities | ||
|
|
||
| Once DevGuard has identified vulnerabilities in your code, you can manage them in your preferred issue tracking platform. This could be: | ||
|
|
||
| - **Same Platform**: GitHub Issues or GitLab Issues where your code is hosted | ||
| - **Different Platform**: A separate project on GitHub/GitLab or a specialized system like Jira | ||
|
|
||
| <Callout type="info"> | ||
| The issue tracking platform doesn't need to be the same as your code hosting platform. For example, you can host your code on GitHub but track vulnerabilities in Jira. | ||
| </Callout> | ||
|
|
||
| ### Authentication Methods | ||
|
|
||
| Each platform uses a different authentication method for issue management: | ||
|
|
||
| | Platform | Authentication Method | Description | | ||
| |----------|----------------------|-------------| | ||
| | [**GitHub**](./github-integration) | GitHub App | Install the DevGuard GitHub App in your organization | | ||
| | [**GitLab**](./gitlab-integration) | [OAuth2](./external-entity-providers) or Access Token | Use OAuth2 for gitlab.com/self-hosted instances, or configure an Access Token | | ||
| | [**Jira**](./jira-integration) | API Token | Configure an API token with your Jira user email | | ||
|
|
||
| ### Bidirectional Synchronization | ||
|
|
||
| DevGuard maintains bidirectional synchronization with integrated platforms: | ||
|
|
||
| 1. **DevGuard → External System**: | ||
| - Creating tickets when vulnerabilities are discovered | ||
| - Updating ticket status when vulnerabilities are resolved | ||
| - Adding comments with remediation information | ||
|
|
||
| 2. **External System → DevGuard**: | ||
| - Closing tickets marks vulnerabilities as accepted | ||
| - Reopening tickets reopens the vulnerability | ||
| - Comments with special commands (e.g., `/accept`, `/false-positive`) update vulnerability status | ||
|
|
||
| ## Webhook System | ||
|
|
||
| DevGuard uses webhooks to receive real-time updates from integrated platforms. The webhook handler: | ||
|
|
||
| 1. Validates the incoming webhook payload | ||
| 2. Routes the webhook to the appropriate integration | ||
| 3. Processes events (issue updates, comments, etc.) | ||
| 4. Updates vulnerability states accordingly | ||
|
|
||
| <Callout type="warning"> | ||
| Webhook secrets should be configured to ensure only authenticated requests are processed. | ||
| </Callout> | ||
|
|
||
|
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We are calling it now Group in the frontend.