diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-03-17 15:09:52 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-03-17 15:09:52 +0300 |
commit | 8ae26d705abe341b03bc15d4373d6cd0c77c0baf (patch) | |
tree | 655ee03a968e340c975b8ab7d77cfd5ceaf3c969 /doc/development | |
parent | fc1df8c8307fc5022f9e8aae04164c089d8fdf2e (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/development')
-rw-r--r-- | doc/development/README.md | 1 | ||||
-rw-r--r-- | doc/development/integrations/secure_partner_integration.md | 103 |
2 files changed, 104 insertions, 0 deletions
diff --git a/doc/development/README.md b/doc/development/README.md index 75dc54050d8..bc5f50b0499 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -163,6 +163,7 @@ Complementary reads: - [Jira Connect app](integrations/jira_connect.md) - [Security Scanners](integrations/secure.md) +- [Secure Partner Integration](integrations/secure_partner_integration.md) ## Testing guides diff --git a/doc/development/integrations/secure_partner_integration.md b/doc/development/integrations/secure_partner_integration.md new file mode 100644 index 00000000000..9991ee57257 --- /dev/null +++ b/doc/development/integrations/secure_partner_integration.md @@ -0,0 +1,103 @@ +# Secure Partner Integration - Onboarding Process + +If you want to integrate your product with the [Secure Stage](https://about.gitlab.com/direction/secure), +this page will help you understand the developer workflow GitLab intends for +our users to follow with regards to security results. These should be used as +guidelines so you can build an integration that fits with the workflow GitLab +users are already familiar with. + +This page also provides resources for the technical work associated +with [onboarding as a partner](https://about.gitlab.com/partners/integrate/). +The steps below are a high-level view of what needs to be done to complete an +integration as well as linking to more detailed resources for how to do so. + +## What is the GitLab Developer Workflow? + +This workflow is how GitLab users interact with our product and expect it to +function. Understanding how users use GitLab today will help you choose the +best place to integrate your own product and its results into GitLab. + +- Developers want to write code without using a new tool to consume results + or address feedback about the item they are working on. Staying inside a + single tool, GitLab, helps them to stay focused on finishing the code and + projects they are working on. +- Developers commit code to a Git branch. The developer creates a merge request (MR) + inside GitLab where these changes can be reviewed. The MR triggers a GitLab + pipeline to run associated jobs, including security checks, on the code. +- Pipeline jobs serve a variety of purposes. Jobs can do scanning for and have + implications for app security, corporate policy, or compliance. When complete, + the job reports back on its status and creates a + [job artifact](../../user/project/pipelines/job_artifacts.md) as a result. +- The [Merge Request Security Widget](../../user/project/merge_requests/index.md#security-reports-ultimate) + displays the results of the pipeline's security checks and the developer can + review them. The developer can review both a summary and a detailed version + of the results. +- If certain policies (such as [merge request approvals](../../user/project/merge_requests/merge_request_approvals.md)) + are in place for a project, developers must resolve specific findings or get + an approval from a specific list of people. +- The [security dashboard](../../user/application_security/security_dashboard/index.md#gitlab-security-dashboard-ultimate) + also shows results which can developers can use to quickly see all the + vulnerabilities that need to be addressed in the code. +- When the developer reads the details about a vulnerability, they are + presented with additional information and choices on next steps: + 1. Create Issue (Confirm finding): Creates a new issue to be prioritized. + 1. Add Comment and Dismiss Vulnerability: When dismissing a finding, users + can comment to note items that they + have mitigated, that they accept the vulnerability, or that the + vulnerability is a false positive. + 1. Auto-Remediation / Create Merge Request: A fix for the vulnerability can + be offered, allowing an easy solution that does not require extra effort + from users. This should be offered whenever possible. + 1. Links: Vulnerabilities can link out external sites or sources for users + to get more data around the vulnerability. + +## How to onboard + +This section describes the steps you need to complete to onboard as a partner +and complete an intgration with the Secure stage. + +1. Read about our [partnerships](https://about.gitlab.com/partners/integrate/index.md). +1. [Create an issue](https://gitlab.com/gitlab-com/alliances/alliances/issues/new?issuable_template=new_partner) + using our new partner issue template to begin the discussion. +1. Get a test account to begin developing your integration. You can + request a [GitLab.com Gold Subscription Sandbox](https://about.gitlab.com/partners/integrate/index.md#gitlabcom-gold-subscription-sandbox-request) + or an [EE Developer License](https://about.gitlab.com/partners/integrate/index.md#requesting-ee-dev-license-for-rd). +1. Provide a [pipeline job](../../development/pipelines.md) + template that users could integrate into their own GitLab pipelines. +1. Create a report artifact with your pipeline jobs. +1. Ensure your pipeline jobs create a report artifact that GitLab can process + to successfully display your own product's results with the rest of GitLab. + - See detailed [technical directions](secure.md) for this step. + - Read more about [job report artifacts](../../ci/yaml/README.md#artifactsreports). + - Read about [job artifacts](../../user/project/pipelines/job_artifacts.md). + - Your report artifact must be in one of our currently supported formats. + For more information, see the [documentation on reports](secure.md#report). + - Documentation for [SAST reports](../../user/application_security/sast/index.md#reports-json-format). + - Documentation for [Dependency Scanning reports](../../user/application_security/dependency_scanning/index.md#reports-json-format). + - Documentation for [Container Scanning reports](../../user/application_security/container_scanning/index.md#reports-json-format). + - See this [example secure job definition that also defines the artifact created](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml). + - If you need a new kind of scan or report, [create an issue](https://gitlab.com/gitlab-org/gitlab/issues/new#) + and add the label `devops::secure`. + - Once the job is completed, the data can be seen: + - In the [Merge Request Security Report](../../user/project/merge_requests/index.md#security-reports-ultimate) ([MR Security Report data flow](https://gitlab.com/snippets/1910005#merge-request-view)). + - While [browsing a Job Artifact](../../user/project/pipelines/job_artifacts.md). + - In the [Security Dashboard](../../user/application_security/security_dashboard/index.md) ([Dashboard data flow](https://gitlab.com/snippets/1910005#project-and-group-dashboards)). +1. Optional: Provide a way to interact with results as Vulnerabilities: + - Users can interact with the findings from your artifact within their workflow. They can dismiss the findings or accept them and create a backlog issue. + - To automatically create issues without user interaction, use the [issue API](../../api/issues.md). This will be replaced by [Standalone Vulnerabilities](https://gitlab.com/groups/gitlab-org/-/epics/634) in the future. +1. Optional: Provide auto-remediation steps: + - If you specified `remediations` in your artifact, it is proposed through our [auto-remediation](../../user/application_security/index.md#solutions-for-vulnerabilities-auto-remediation) + interface. +1. Demo the integration to GitLab: + - After you have tested and are ready to demo your integration please + [reach out](https://about.gitlab.com/partners/integrate/index.md) to us. If you + skip this step you won’t be able to do supported marketing. +1. Begin doing supported marketing of your GitLab integration. + - Work with our [partner team](https://about.gitlab.com/partners/integrate/index.md) + to support your go-to-market as appropriate. + - Examples of supported marketing could include being listed on our [Security Partner page](https://about.gitlab.com/partners/index.md#security), + doing an [Unfiltered blog post](https://about.gitlab.com/handbook/marketing/blog/unfiltered/index.md), + doing a co-branded webinar, or producing a co-branded whitepaper. + +If you have any issues while working through your integration or the steps +above, please create an issue to discuss with us further. |