Skip to content

Commit a6c7709

Browse files
refoo0refoo0
committed
Add detailed explanations for integration with GitHub, GitLab, Jira, and external entity providers
Signed-off-by: rafi <refaei.shikho@hotmail.com>
1 parent 8c9485c commit a6c7709

5 files changed

Lines changed: 428 additions & 15 deletions

File tree

‎src/pages/explanations/integrations/external-entity-providers.mdx‎

Lines changed: 79 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,84 @@
11
import Image from 'next/image';
2-
import { Callout } from 'nextra/components';
2+
import { Callout, Steps } from 'nextra/components';
33
import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/ui/tooltip";
4-
import PageContentComingSoon from '@/components/PageContentComingSoon'
54

65
# External Entity Providers
76

8-
<PageContentComingSoon />
7+
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.
8+
9+
## Overview
10+
11+
External Entity Providers enable:
12+
13+
- **Automatic Organization Creation**: GitLab instances become DevGuard organizations
14+
- **Project Synchronization**: GitLab groups map to DevGuard projects
15+
- **Asset Discovery**: GitLab projects map to DevGuard assets
16+
- **Permission Inheritance**: External access levels translate to DevGuard roles
17+
- **Real-time Sync**: Permissions update when users authenticate
18+
- **Issue Management**: Vulnerabilities can be tracked in the same platform
19+
20+
21+
22+
## Entity Mapping
23+
24+
| External Entity | DevGuard Entity |
25+
|-----------------|-----------------|
26+
| GitLab Instance | Organization |
27+
| GitLab Group | Project |
28+
| GitLab Project | Asset |
29+
30+
31+
## Synchronization Process
32+
33+
When a user authenticates via an external provider:
34+
35+
1. **Token Retrieval**: DevGuard retrieves OAuth2 tokens from the identity provider
36+
2. **Organization Sync**: Organizations are created/updated based on the provider
37+
3. **Project Sync**: GitLab groups are synchronized as DevGuard projects
38+
4. **Asset Sync**: GitLab projects within groups are synchronized as DevGuard assets
39+
5. **Permission Sync**: User roles are updated based on external permissions
40+
41+
## Permission Synchronization
42+
43+
| GitLab Access Level | DevGuard Role |
44+
|---------------------|---------------|
45+
| Owner / Maintainer | Admin |
46+
| Developer / Reporter / Guest | Member |
47+
48+
When external permissions change, DevGuard:
49+
50+
- **Revokes Old Roles**: Removes access to projects/assets the user no longer has access to
51+
- **Grants New Roles**: Adds access based on current external permissions
52+
- **Updates Existing Roles**: Adjusts role levels if permissions changed
53+
54+
## Triggering Sync
55+
56+
### Automatic Sync
57+
58+
Synchronization occurs automatically when:
59+
- Users authenticate via the external provider
60+
- Users access an organization linked to an external entity
61+
62+
### Manual Sync
63+
64+
Users can trigger a manual sync via the DevGuard UI or API endpoints.
65+
66+
67+
## Benefits
68+
69+
- **Single Source of Truth**: Permissions are managed in your existing platform
70+
- **Reduced Administration**: No need to manually create DevGuard entities
71+
- **Automatic Updates**: Changes in external systems reflect in DevGuard
72+
- **Consistent Access**: Users have the same access levels across platforms
73+
74+
## Limitations
75+
76+
- **Provider Support**: Currently limited to GitLab
77+
- **Token Validity**: Requires valid OAuth2 tokens for sync
78+
79+
80+
## Related Documentation
81+
82+
- [GitLab Integration](/explanations/integrations/gitlab-integration) — GitLab-specific integration details
83+
- [GitLab Permission Sync](/how-to-guides/integrations/gitlab/permission-sync) — Configure permission synchronization
84+
- [Integration Architecture](/explanations/integrations/integration-architecture) — Overall integration design

‎src/pages/explanations/integrations/github-integration.mdx‎

Lines changed: 70 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,75 @@
11
import Image from 'next/image';
2-
import { Callout } from 'nextra/components';
2+
import { Callout, Steps, Tabs } from 'nextra/components';
33
import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/ui/tooltip";
4-
import PageContentComingSoon from '@/components/PageContentComingSoon'
54

65
# GitHub Integration
76

8-
<PageContentComingSoon />
7+
DevGuard integrates with GitHub through a **GitHub App**, providing secure access to your repositories for issue management.
8+
9+
## Overview
10+
11+
The GitHub integration provides:
12+
13+
- **Repository Access**: List and import repositories from GitHub organizations
14+
- **Issue Management**: Create and update GitHub Issues for discovered vulnerabilities
15+
- **Webhook Processing**: React to issue changes and comments in real-time
16+
- **CI/CD Integration**: Automated scanning via GitHub Actions
17+
18+
<Callout type="info">
19+
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).
20+
</Callout>
21+
22+
23+
24+
## How It Works
25+
26+
1. **Configure Integration**: Add the DevGuard GitHub App to your GitHub organization
27+
2. **Link Asset**: Connect a DevGuard asset to a GitHub repository
28+
3. **Create Issues**: Vulnerabilities can be pushed to GitHub Issues for tracking (automatically or manually)
29+
4. **Sync Status**: Changes in either system are synchronized via webhooks
30+
31+
32+
## Issue Creation
33+
34+
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.
35+
36+
## Comment Commands
37+
38+
Users can control vulnerability status through issue comments:
39+
40+
| Command | Effect |
41+
|---------|--------|
42+
| `/accept <reason>` | Accept the vulnerability risk |
43+
| `/false-positive <reason>` | Mark as false positive |
44+
| `/reopen` | Reopen a closed vulnerability |
45+
46+
<Callout type="info">
47+
Only repository collaborators can use these commands. DevGuard verifies permissions before processing.
48+
</Callout>
49+
50+
51+
52+
### Processed Events
53+
54+
| Event | Action |
55+
|-------|--------|
56+
| Issue Closed | Vulnerability marked as accepted |
57+
| Issue Reopened | Vulnerability reopened |
58+
| Issue Deleted | Vulnerability marked as false positive |
59+
| Comment Added | Process slash commands |
60+
61+
## Issue State Synchronization
62+
63+
| GitHub Action | DevGuard Interpretation |
64+
|---------------|-------------------------|
65+
| Close issue | Vulnerability accepted |
66+
| Reopen issue | Vulnerability reopened |
67+
| Delete issue | Vulnerability false positive |
68+
69+
70+
## Related Documentation
71+
72+
- [Setup GitHub Integration](/how-to-guides/integrations/github/setup-github-integration) — Step-by-step setup guide
73+
- [GitHub Webhooks](/how-to-guides/integrations/github/webhooks) — Configure webhooks
74+
- [GitHub Auto-Setup](/how-to-guides/integrations/github/auto-setup) — Automated repository configuration
75+
- [Scan with GitHub Actions](/how-to-guides/scanning/scan-with-github-actions) — CI/CD integration guide

‎src/pages/explanations/integrations/gitlab-integration.mdx‎

Lines changed: 87 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,92 @@
11
import Image from 'next/image';
2-
import { Callout } from 'nextra/components';
2+
import { Callout, Steps, Tabs } from 'nextra/components';
33
import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/ui/tooltip";
4-
import PageContentComingSoon from '@/components/PageContentComingSoon'
54

65
# GitLab Integration
76

8-
<PageContentComingSoon />
7+
DevGuard integrates with GitLab through two authentication methods: **Personal Access Token (PAT)** or **OAuth2**. Both methods support gitlab.com and self-hosted GitLab instances.
8+
9+
| Method | Use Case |
10+
|--------|----------|
11+
| **Personal Access Token** | Repository access, issue management |
12+
| **OAuth2** | Permission sync, External Entity Provider |
13+
14+
<Callout type="info">
15+
This page covers the **Personal Access Token** integration. For OAuth2-based integration, see [External Entity Providers](./external-entity-providers).
16+
</Callout>
17+
18+
## Overview
19+
20+
The GitLab PAT integration provides:
21+
22+
- **Repository Access**: List and import GitLab projects
23+
- **Issue Management**: Create and update GitLab Issues for vulnerabilities
24+
- **Webhook Processing**: React to issue and note events in real-time
25+
- **CI/CD Integration**: Automated scanning via GitLab CI/CD pipelines
26+
27+
<Callout type="info">
28+
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).
29+
</Callout>
30+
31+
## How It Works
32+
33+
1. **Configure Integration**: Add your GitLab instance URL and Personal Access Token in DevGuard
34+
2. **Link Asset**: Connect a DevGuard asset to a GitLab project
35+
3. **Create Issues**: Vulnerabilities can be pushed to GitLab Issues for tracking (automatically or manually)
36+
4. **Sync Status**: Changes in either system are synchronized via webhooks
37+
38+
39+
## Issue Creation
40+
41+
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.
42+
43+
## Comment Commands
44+
45+
Users can control vulnerability status through issue comments:
46+
47+
| Command | Effect |
48+
|---------|--------|
49+
| `/accept <reason>` | Accept the vulnerability risk |
50+
| `/false-positive <reason>` | Mark as false positive |
51+
| `/reopen` | Reopen a closed vulnerability |
52+
53+
## Webhook Processing
54+
55+
DevGuard processes GitLab webhooks to synchronize issue state changes.
56+
57+
<Callout type="warning">
58+
Configure the webhook secret in your GitLab settings to ensure only authenticated requests are processed. DevGuard only accepts webhooks with a valid secret.
59+
</Callout>
60+
61+
### Processed Events
62+
63+
| Event | Action |
64+
|-------|--------|
65+
| Issue Closed | Vulnerability marked as accepted |
66+
| Issue Reopened | Vulnerability reopened |
67+
| Comment Added | Process slash commands |
68+
69+
## Issue State Synchronization
70+
71+
| GitLab Status | DevGuard Interpretation |
72+
|---------------|-------------------------|
73+
| Open | Open vulnerability |
74+
| Closed | Closed vulnerability |
75+
76+
## Self-Hosted Instances
77+
78+
GitLab integration fully supports self-hosted GitLab instances:
79+
80+
- Configure your GitLab instance URL in the OAuth2 or Access Token settings
81+
- Multiple GitLab instances can be connected simultaneously
82+
- Each instance is treated as a separate External Entity Provider
83+
84+
## Testing the Integration
85+
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.
86+
87+
## Related Documentation
88+
89+
- [Setup GitLab Integration](/how-to-guides/integrations/gitlab/setup-gitlab-integration) — Step-by-step setup guide
90+
- [GitLab Permission Sync](/how-to-guides/integrations/gitlab/permission-sync) — Configure permission synchronization
91+
- [GitLab Webhooks](/how-to-guides/integrations/gitlab/webhooks) — Configure webhooks
92+
- [External Entity Providers](/explanations/integrations/external-entity-providers) — Understanding external entities

‎src/pages/explanations/integrations/integration-architecture.mdx‎

Lines changed: 93 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,98 @@
11
import Image from 'next/image';
2-
import { Callout } from 'nextra/components';
2+
import { Callout, Cards, Card } from 'nextra/components';
33
import { Tooltip, TooltipTrigger, TooltipContent } from "@/components/ui/tooltip";
4-
import PageContentComingSoon from '@/components/PageContentComingSoon'
54

65
# Integration Architecture
76

8-
<PageContentComingSoon />
7+
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.
8+
9+
## Overview
10+
11+
DevGuard's integration architecture serves two primary purposes:
12+
13+
1. [**Finding Vulnerabilities**](#finding-vulnerabilities): Integrate with your code repositories and CI/CD pipelines to automatically scan code for vulnerabilities
14+
2. [**Managing Vulnerabilities**](#managing-vulnerabilities): Track and manage discovered vulnerabilities in your preferred issue tracking system
15+
16+
```mermaid
17+
graph TB
18+
subgraph "Code Hosting Platforms"
19+
GH[GitHub]
20+
GL[GitLab]
21+
end
22+
23+
subgraph "DevGuard"
24+
25+
end
26+
27+
subgraph "Issue Tracking"
28+
GHI[GitHub Issues]
29+
GLI[GitLab Issues]
30+
JIRA[Jira]
31+
end
32+
33+
GH --> DevGuard
34+
GL --> DevGuard
35+
DevGuard --> GHI
36+
DevGuard --> GLI
37+
DevGuard --> JIRA
38+
39+
```
40+
41+
## Finding Vulnerabilities
42+
43+
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.
44+
45+
### Authentication Method
46+
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.
47+
48+
49+
50+
## Managing Vulnerabilities
51+
52+
Once DevGuard has identified vulnerabilities in your code, you can manage them in your preferred issue tracking platform. This could be:
53+
54+
- **Same Platform**: GitHub Issues or GitLab Issues where your code is hosted
55+
- **Different Platform**: A separate project on GitHub/GitLab or a specialized system like Jira
56+
57+
<Callout type="info">
58+
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.
59+
</Callout>
60+
61+
### Authentication Methods
62+
63+
Each platform uses a different authentication method for issue management:
64+
65+
| Platform | Authentication Method | Description |
66+
|----------|----------------------|-------------|
67+
| [**GitHub**](./github-integration) | GitHub App | Install the DevGuard GitHub App in your organization |
68+
| [**GitLab**](./gitlab-integration) | [OAuth2](./external-entity-providers) or Access Token | Use OAuth2 for gitlab.com/self-hosted instances, or configure an Access Token |
69+
| [**Jira**](./jira-integration) | API Token | Configure an API token with your Jira user email |
70+
71+
### Bidirectional Synchronization
72+
73+
DevGuard maintains bidirectional synchronization with integrated platforms:
74+
75+
1. **DevGuard → External System**:
76+
- Creating tickets when vulnerabilities are discovered
77+
- Updating ticket status when vulnerabilities are resolved
78+
- Adding comments with remediation information
79+
80+
2. **External System → DevGuard**:
81+
- Closing tickets marks vulnerabilities as accepted
82+
- Reopening tickets reopens the vulnerability
83+
- Comments with special commands (e.g., `/accept`, `/false-positive`) update vulnerability status
84+
85+
## Webhook System
86+
87+
DevGuard uses webhooks to receive real-time updates from integrated platforms. The webhook handler:
88+
89+
1. Validates the incoming webhook payload
90+
2. Routes the webhook to the appropriate integration
91+
3. Processes events (issue updates, comments, etc.)
92+
4. Updates vulnerability states accordingly
93+
94+
<Callout type="warning">
95+
Webhook secrets should be configured to ensure only authenticated requests are processed.
96+
</Callout>
97+
98+

0 commit comments

Comments
 (0)