diff --git a/developer-tools/cli-ide-and-ci-cd-integrations/snyk-cli/configure-the-snyk-cli/configure-snyk-cli-to-connect-to-snyk-api.md b/developer-tools/cli-ide-and-ci-cd-integrations/snyk-cli/configure-the-snyk-cli/configure-snyk-cli-to-connect-to-snyk-api.md index e44b0a0648fb..72ffa931de8e 100644 --- a/developer-tools/cli-ide-and-ci-cd-integrations/snyk-cli/configure-the-snyk-cli/configure-snyk-cli-to-connect-to-snyk-api.md +++ b/developer-tools/cli-ide-and-ci-cd-integrations/snyk-cli/configure-the-snyk-cli/configure-snyk-cli-to-connect-to-snyk-api.md @@ -6,7 +6,7 @@ By default, the Snyk CLI connects to `https://api.snyk.io/`. You can use the fol `SNYK_API` -Specifying this variable sets the API host that will be used for Snyk requests. This is useful for [regional hosting](https://app.gitbook.com/s/ELvljsaLKPkSpffOkmsQ/regional-hosting-and-data-residency#cli-and-ci-pipeline-urls), on-premise instances, or when you are using a proxy server. If this variable is set with the `http` protocol, the CLI upgrades the requests to `https` unless `SNYK_HTTP_PROTOCOL_UPGRADE` is set to `0`. +Specifying this variable sets the API host used for Snyk requests. This is useful for [regional hosting](https://app.gitbook.com/s/ELvljsaLKPkSpffOkmsQ/regional-hosting-and-data-residency#cli-and-ci-pipeline-urls), on-premise instances, or when you are using a proxy server. If this variable is set with the `http` protocol, the CLI upgrades the requests to `https` unless `SNYK_HTTP_PROTOCOL_UPGRADE` is set to `0`. `SNYK_HTTP_PROTOCOL_UPGRADE=0` @@ -24,7 +24,7 @@ Specifying this variable disables all Snyk CLI analytics. `SNYK_TOKEN` -Specifying this variable allows you to override the token that may be available in your Snyk configuration settings (`~/.config/configstore/snyk.json`). Use `SNYK_TOKEN` in a CI/CD environment. After setting `SNYK_TOKEN` you can [get started](../../../snyk-cli/getting-started-with-the-snyk-cli.md) using the CLI. +Specifying this variable lets you override the token available in your Snyk configuration settings (`~/.config/configstore/snyk.json`). Use `SNYK_TOKEN` in a CI/CD environment. After setting `SNYK_TOKEN` you can [get started](../../../snyk-cli/getting-started-with-the-snyk-cli.md) using the CLI. For information on how to get your account token see [Authenticate the CLI with your account](../../../snyk-cli/authenticate-to-use-the-cli.md). You can also use a service account to authenticate; for more information see [Service accounts](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/service-accounts/service-accounts). For additional information, see [Authentication for third-party tools](../../../implementation-and-setup/enterprise-setup/authentication-for-third-party-tools.md). diff --git a/developer-tools/implementation-and-setup/enterprise-setup/authentication-for-third-party-tools.md b/developer-tools/implementation-and-setup/enterprise-setup/authentication-for-third-party-tools.md index 726c843d9feb..6b025e427507 100644 --- a/developer-tools/implementation-and-setup/enterprise-setup/authentication-for-third-party-tools.md +++ b/developer-tools/implementation-and-setup/enterprise-setup/authentication-for-third-party-tools.md @@ -1,6 +1,6 @@ # Authentication for third-party tools -When you work with Snyk from within any third-party tool, Snyk requires authentication in order to initiate its processes. +When you work with Snyk from within any third-party tool, Snyk requires authentication to initiate its processes. Snyk offers API tokens to enable integrations with third-party developer tools. You can authenticate through your personal account using your personal token or through a [service account](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/service-accounts/service-accounts) using the token associated with that account. When you authenticate through a service account, you do not use any personal token. diff --git a/developer-tools/integrations/event-forwarding/README.md b/developer-tools/integrations/event-forwarding/README.md index 9fe1f29189b2..4e278976d68d 100644 --- a/developer-tools/integrations/event-forwarding/README.md +++ b/developer-tools/integrations/event-forwarding/README.md @@ -1,13 +1,13 @@ # Event forwarding -Snyk event forwarding integrations allow you to push Snyk platform events directly to certain products on other platforms, enabling you to set up custom alerting, build your own reporting, trigger automation, and more. +Snyk event forwarding integrations let you push Snyk platform events directly to certain products on other platforms, so you can set up custom alerting, build your own reporting, trigger automation, and more. ## Event types Snyk supports sending two different types of events: 1. **Snyk issue events** - these events are sent when new issues are discovered in a Snyk Project, or when an issue is updated. Each event contains information about the vulnerability or other problem found, including whether a remediation is available. -2. **Snyk platform audit events** - these events are sent every time a Snyk user performs an action within the Snyk platform. For more information, see [Audit logs](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/user-management/user-management-with-the-api/retrieve-audit-logs-of-user-initiated-activity-by-api-for-an-org-or-group). +2. **Snyk platform audit events** - these events are sent every time a Snyk user performs an action in the Snyk platform. For more information, see [Audit logs](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/user-management/user-management-with-the-api/retrieve-audit-logs-of-user-initiated-activity-by-api-for-an-org-or-group). {% hint style="info" %} The **Snyk issue** event type does not include Snyk Cloud issues. diff --git a/developer-tools/integrations/event-forwarding/amazon-eventbridge.md b/developer-tools/integrations/event-forwarding/amazon-eventbridge.md index 44d944c1d5bb..4a9b2153c3ac 100644 --- a/developer-tools/integrations/event-forwarding/amazon-eventbridge.md +++ b/developer-tools/integrations/event-forwarding/amazon-eventbridge.md @@ -1,13 +1,13 @@ # Amazon EventBridge -The [Amazon EventBridge](https://aws.amazon.com/eventbridge/) integration sends Snyk platform events to EventBridge, allowing you to integrate Snyk events into your existing AWS environments. The integration can be configured to send two different types of events: +The [Amazon EventBridge](https://aws.amazon.com/eventbridge/) integration sends Snyk platform events to EventBridge, so you can integrate Snyk events into your existing AWS environments. You can configure the integration to send two different types of events: * **Snyk issue events**: These events are sent when new issues are discovered in a Snyk Project, or when an issue is updated. Each event contains information about the vulnerability or other problem found, including whether a remediation is available. -* **Snyk platform audit events**: These events are sent every time a Snyk user performs an action within the Snyk platform. For more information, see [Retrieve audit logs of user-initiated activity by API for an Org or Group](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/user-management/user-management-with-the-api/retrieve-audit-logs-of-user-initiated-activity-by-api-for-an-org-or-group). This event type is available with Snyk Enterprise plans. For more information, see this page about [trials](https://app.gitbook.com/s/L7HyJj9FsK1W4pNt8Gzl/implementation-guides/enterprise-implementation-guide/trial-limitations) and [Plans and pricing](https://snyk.io/plans/). +* **Snyk platform audit events**: These events are sent every time a Snyk user performs an action in the Snyk platform. For more information, see [Retrieve audit logs of user-initiated activity by API for an Org or Group](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/user-management/user-management-with-the-api/retrieve-audit-logs-of-user-initiated-activity-by-api-for-an-org-or-group). This event type is available with Snyk Enterprise plans. For more information, see this page about [trials](https://app.gitbook.com/s/L7HyJj9FsK1W4pNt8Gzl/implementation-guides/enterprise-implementation-guide/trial-limitations) and [Plans and pricing](https://snyk.io/plans/). To set up the integration, there are two steps: -1. Configure an EventBridge integration in the Snyk dashboard. This will create a Snyk **Partner Event Source** in your AWS account, which you can see in the EventBridge dashboard. +1. Configure an EventBridge integration in the Snyk dashboard. This creates a Snyk **Partner Event Source** in your AWS account, which you can see in the EventBridge dashboard. 2. Configure the Snyk integration in Amazon EventBridge. This step involves associating the Snyk event source created in step one with an EventBridge **Event Bus**. After you complete these steps, Snyk immediately starts sending events to the configured event bus. @@ -26,19 +26,19 @@ When the form is completed, click **Add integration**. After this step is done, ## Snyk App authorization -If this is the first time you have set up an Amazon EventBridge integration for your Organization, you will be prompted to complete the Snyk App authorization flow. +If this is the first time you have set up an Amazon EventBridge integration for your Organization, Snyk prompts you to complete the Snyk App authorization flow.
-After completing the authorization flow, you will be redirected to the settings page for the integration. +After completing the authorization flow, Snyk redirects you to the settings page for the integration. ## Configure the integration in Amazon EventBridge -After configuring the EventBridge integration on the Snyk side, you should see a new **Partner Event Source** in the EventBridge console. Navigate to the EventBridge console and navigate to the **Partner event sources** page under the **Integration** section. +After configuring the EventBridge integration on the Snyk side, a new **Partner Event Source** appears in the EventBridge console. Navigate to the EventBridge console and navigate to the **Partner event sources** page under the **Integration** section.
Partner event sources

Partner event sources

-Snyk-generated event sources will have a naming pattern like this: +Snyk-generated event sources have a naming pattern like this: `aws.partner/snyk.io/org_/`\ \ @@ -53,14 +53,14 @@ Navigate to the [EventBridge integration settings page](https://app.snyk.io/mana Clicking on the name of the integration opens the integration settings page, which displays configuration information for the integration. {% hint style="info" %} -Because EventBridge integrations create an external resource that depends on the configured AWS Account ID, Region, and event type, it is not possible to edit these configuration fields. If you need to change one of these fields, delete the integration and create a new one. This deletes the existing **partner event source** in AWS and creates a new one, which you will need to associate with an **event bus** as described above. +Because EventBridge integrations create an external resource that depends on the configured AWS Account ID, Region, and event type, it is not possible to edit these configuration fields. If you need to change one of these fields, delete the integration and create a new one. This deletes the existing **partner event source** in AWS and creates a new one, which you must associate with an **event bus** as described in the preceding steps. {% endhint %} -To delete an integration, scroll to the bottom of the page and click the **Remove integration** button, then confirm the deletion. +To delete an integration, scroll to the bottom of the page and click **Remove integration**, then confirm the deletion.
Remove integration

Remove integration

-This deletes the integration configuration on the Snyk side and the **Partner Event Source** associated with this integration in AWS. You can verify that the event source has been deleted in the EventBridge console. +This deletes the integration configuration on the Snyk side and the **Partner Event Source** associated with this integration in AWS. You can verify that Snyk deleted the event source in the EventBridge console. ## Understanding event data diff --git a/developer-tools/integrations/event-forwarding/aws-cloudtrail-lake.md b/developer-tools/integrations/event-forwarding/aws-cloudtrail-lake.md index fdc94afe065f..227742da5055 100644 --- a/developer-tools/integrations/event-forwarding/aws-cloudtrail-lake.md +++ b/developer-tools/integrations/event-forwarding/aws-cloudtrail-lake.md @@ -5,7 +5,7 @@ The AWS CloudTrail Lake integration is available only with Snyk Enterprise plans. For more information, see [plans and pricing](https://snyk.io/plans/). {% endhint %} -The AWS CloudTrail Lake integration allows you to forward [Snyk audit logs](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/user-management/user-management-with-the-api/retrieve-audit-logs-of-user-initiated-activity-by-api-for-an-org-or-group) to AWS CloudTrail Lake, which lets you run SQL-based queries on your logs and retain them for up to seven (7) years. +The AWS CloudTrail Lake integration lets you forward [Snyk audit logs](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/user-management/user-management-with-the-api/retrieve-audit-logs-of-user-initiated-activity-by-api-for-an-org-or-group) to AWS CloudTrail Lake, which lets you run SQL-based queries on your logs and retain them for up to seven years. This integration can be configured to forward audit logs for a single Snyk Organization, or for a Snyk Group and all of its child Organizations. In either case, there are two steps required to set up the integration: @@ -20,18 +20,18 @@ This integration sends logs beginning when you enable it. Logs generated before Audit logs are captured when Snyk users perform actions on the Snyk platform, such as making changes to settings, adding other users, or accessing protected APIs. When you are setting up this integration, it is important to understand how audit logs are captured, based on how a customer's Snyk account is set up: -* For customers using Snyk with a single Snyk Organization (or with multiple disconnected Organizations), all audit logs are captured within the scope of the single Organization. +* For customers using Snyk with a single Snyk Organization (or with multiple disconnected Organizations), all audit logs are captured in the scope of the single Organization. * For customers who have a Snyk Group with child Organizations, actions such as adding new Organizations to the group or adding users to the group are audited at the Group level, and are not typically associated with an Organization. This integration supports both use cases: 1. Integrate CloudTrail Lake with a single Snyk Organization - 1. All audit logs associated directly with that Organization will be sent to CloudTrail Lake. + 1. All audit logs associated directly with that Organization are sent to CloudTrail Lake. 2. If the Organization has a parent Group, actions taken on that Group **a**re not sent to CloudTrail Lake. - 3. If the Organization has members who are also members of other Organizations and Groups, actions taken by those members will only be sent to CloudTrail Lake if they are directly associated with the Organization. + 3. If the Organization has members who are also members of other Organizations and Groups, actions taken by those members are sent to CloudTrail Lake only if they are directly associated with the Organization. 2. Integrate CloudTrail Lake with a Snyk Group and all of its child Organizations - 1. All audit logs associated with the Group or any of its child Organizations will be sent to CloudTrail Lake. - 2. When new Organizations are added to the Group, audit logs for those Organizations will be sent automatically to CloudTrail Lake. + 1. All audit logs associated with the Group or any of its child Organizations are sent to CloudTrail Lake. + 2. When new Organizations are added to the Group, audit logs for those Organizations are sent automatically to CloudTrail Lake. ## Add a Snyk integration in AWS CloudTrail Lake @@ -43,7 +43,7 @@ During the setup, you must supply an **External ID** for the integration. The va ### External ID for a Single Snyk Organization -If you are creating this integration for a single Snyk Organization, you will use your Snyk **Organization ID** as the **External ID.** You can find your Organization ID under Snyk **Organization Settings**. +If you are creating this integration for a single Snyk Organization, use your Snyk **Organization ID** as the **External ID.** You can find your Organization ID under Snyk **Organization Settings**.
Organization ID on Snyk Organization Settings page

Organization ID on Snyk Organization settings page

@@ -51,7 +51,7 @@ Copy the value in the **Organization ID** field to the **External ID** field in ### External ID for a Snyk group -If you are setting up this Organization for a Snyk Group, which will automatically include all child organizations, you will use your **Snyk Group ID** as the **External ID**. You can find your Group ID by clicking on the name of your Snyk group in the Snyk dashboard, and then navigating to the **Settings** page. +If you are setting up this Organization for a Snyk Group, which automatically includes all child Organizations, use your **Snyk Group ID** as the **External ID**. You can find your Group ID by clicking on the name of your Snyk group in the Snyk dashboard, and then navigating to the **Settings** page.
Group settings page

Group settings page

@@ -59,7 +59,7 @@ Copy the value in the **Group ID** field to the **External ID** field in the AWS ### CloudTrail Lake Channel ARN -When you are finished creating the Snyk integration in AWS CloudTrail Lake, copy the **Channel ARN** that is displayed on the integration page. You will need this for the next step. +When you are finished creating the Snyk integration in AWS CloudTrail Lake, copy the **Channel ARN** displayed on the integration page. You need this for the next step. ## Configure the integration in Snyk (single Organization) @@ -77,11 +77,11 @@ After this step is complete, Snyk immediately begins forwarding audit logs to AW ## Snyk App authorization -If this is the first time you have set up an AWS CloudTrail Lake integration for your Organization, you will be prompted to complete the Snyk App authorization flow. +If this is the first time you have set up an AWS CloudTrail Lake integration for your Organization, Snyk prompts you to complete the Snyk App authorization flow.
Snyk App authorization

Snyk App authorization

-After completing the authorization flow you will be redirected to the settings page for the integration. +After completing the authorization flow, Snyk redirects you to the settings page for the integration. ## Configure the integration in Snyk (Snyk Group and child Organizations) @@ -132,7 +132,7 @@ Select **Remove integration** and confirm that you want to remove the integratio
Remove integration button

Remove integration button

-This action removes Snyk’s configuration for this integration, which will prevent any further audit logs from being sent to AWS CloudTrail Lake. This does not remove the Snyk integration in AWS CloudTrail Lake. To do this, navigate to AWS CloudTrail Lake and delete the Snyk integration from the **Integration** list. +This action removes the Snyk configuration for this integration, which prevents any further audit logs from being sent to AWS CloudTrail Lake. This does not remove the Snyk integration in AWS CloudTrail Lake. To do this, navigate to AWS CloudTrail Lake and delete the Snyk integration from the **Integration** list. ## Remove an AWS CloudTrail Lake integration (Snyk Group and child Organizations) @@ -161,7 +161,7 @@ Replace `` with the ID of the event data store that is asso ## Understanding the log data -There are three (3) key fields to note when using the Snyk audit log data in AWS CloudTrail Lake. +There are three key fields to note when using the Snyk audit log data in AWS CloudTrail Lake. `eventdata.useridentity` @@ -173,4 +173,4 @@ This represents the type of audit event, for example, `api.access` or `org.cloud `eventdata.additionaleventdata` -This field contains a raw JSON payload with more detailed information about the audit event. The content of the payload depends on the type of the event. For example, an API access event will include the accessed URL, while a settings change event will include before and after values for the changed setting. +This field contains a raw JSON payload with more detailed information about the audit event. The content of the payload depends on the type of the event. For example, an API access event includes the accessed URL, while a settings change event includes before and after values for the changed setting. diff --git a/developer-tools/integrations/event-forwarding/aws-security-hub.md b/developer-tools/integrations/event-forwarding/aws-security-hub.md index e5e28ae17d88..92a0557a5987 100644 --- a/developer-tools/integrations/event-forwarding/aws-security-hub.md +++ b/developer-tools/integrations/event-forwarding/aws-security-hub.md @@ -1,6 +1,6 @@ # AWS Security Hub -The [AWS Security Hub](https://aws.amazon.com/security-hub/) integration sends Snyk issues to Security Hub, allowing you to centralize your security reporting, build custom alerting, and trigger automation. After it is configured, the integration automatically uploads Snyk issues to Security Hub as security findings. When issues are updated or new remediations become available, the corresponding Security Hub findings are automatically updated. +The [AWS Security Hub](https://aws.amazon.com/security-hub/) integration sends Snyk issues to Security Hub, so you can centralize your security reporting, build custom alerting, and trigger automation. After it is configured, the integration automatically uploads Snyk issues to Security Hub as security findings. When issues are updated or new remediations become available, the corresponding Security Hub findings are automatically updated. There are two steps required to configure the integration: @@ -28,16 +28,16 @@ Enter a **name** for the integration, along with the **AWS Account ID** and **AW After this step is complete, Snyk begins sending new issue events to Security Hub. {% hint style="info" %} -Issues on existing Projects will not be sent to Security Hub unless those issues are updated. To backfill issues from existing projects, you can delete and re-import them. +Issues on existing Projects are not sent to Security Hub unless those issues are updated. To backfill issues from existing Projects, you can delete and re-import them. {% endhint %} ## Snyk App authorization -If this is the first time you have set up an AWS Security Hub integration for your Organization, you will be prompted to complete the Snyk App authorization flow. +If this is the first time you have set up an AWS Security Hub integration for your Organization, Snyk prompts you to complete the Snyk App authorization flow.
Snyk App authorization

Snyk App authorization

-After completing the authorization flow you will be redirected to the settings page for the integration. +After completing the authorization flow, Snyk redirects you to the settings page for the integration. ## Managing and deleting a Security Hub integration @@ -47,8 +47,8 @@ Navigate to the [Security Hub integration settings page](https://app.snyk.io/man Clicking on the name of an integration opens the settings page for that integration, where you can view and update configuration information for the integration. -To delete an integration, scroll to the bottom of the integration settings page and click the **Remove integration** button. +To delete an integration, scroll to the bottom of the integration settings page and click **Remove integration**.
Remove integration

Remove integration

-After the integration is deleted, Snyk will no longer send issues to Security Hub. Issues that have already been sent to Security Hub will remain there until they are archived. +After the integration is deleted, Snyk no longer sends issues to Security Hub. Issues already sent to Security Hub remain there until they are archived. diff --git a/developer-tools/integrations/event-forwarding/crowdstrike-falcon-next-gen-siem.md b/developer-tools/integrations/event-forwarding/crowdstrike-falcon-next-gen-siem.md index 507b9eb4a0fe..7bec740b70dc 100644 --- a/developer-tools/integrations/event-forwarding/crowdstrike-falcon-next-gen-siem.md +++ b/developer-tools/integrations/event-forwarding/crowdstrike-falcon-next-gen-siem.md @@ -24,21 +24,21 @@ The process for setting up this integration consists of: To use the CrowdStrike NG-SIEM destination, you need to set up a Snyk Data Connector in your CrowdStrike NG-SIEM environment. To learn more, visit the [Snyk](https://falcon.us-2.crowdstrike.com/documentation/page/c7182a06/snyk) page in the CrowdStrike documentation. Select the **snyk-platform (Snyk Platform)** parser while configuring the data connector. -When setting up the data connector, you receive an API key and URL, which you will use later to configure the Snyk Issue Forwarder. +When setting up the data connector, you receive an API key and URL, which you use later to configure the Snyk Issue Forwarder. ## Configure Snyk Issue Forwarder -This section configures Snyk to send issue data to the CrowdStrike connector you just created. +This section configures Snyk to send issue data to the CrowdStrike connector you created. * Open the **Integrations** menu. -* Select the **Add integration** option. +* Select **Add integration**. * Select the **Issue Forwardin**g tag and search for CrowdStrike Issue Forwarding. -* Click the **Add** button. +* Click **Add**. * Add the profile name for this integration. * Add the **API URL** you copied earlier from your CrowdStrike Issue Forwarding account. * Add the **API key** you copied earlier from your CrowdStrike Issue Forwarding account. -* Click the **Done** button. -* When the connection is established, the status of the CrowdStrike Issue Forwarding integration is changed to **Connected**. +* Click **Done**. +* When the connection is established, the status of the CrowdStrike Issue Forwarding integration changes to **Connected**. ## Verify the integration connection diff --git a/developer-tools/integrations/event-forwarding/google-security-command-center.md b/developer-tools/integrations/event-forwarding/google-security-command-center.md index e9b6243e6e7e..f6c732c160c4 100644 --- a/developer-tools/integrations/event-forwarding/google-security-command-center.md +++ b/developer-tools/integrations/event-forwarding/google-security-command-center.md @@ -6,7 +6,7 @@ The Google Cloud Security Command Center integration is in [Early Access](https://app.gitbook.com/s/L7HyJj9FsK1W4pNt8Gzl/snyk-release-process#early-access-features), and is available only with Snyk Enterprise plans. For more information, see [Plans and pricing](https://snyk.io/plans/). {% endhint %} -The Google Cloud Security Command Center (SCC) integration sends Snyk issues to SCC, enabling you to view and manage Snyk issues alongside cloud security findings from Google Cloud in a single viewpoint. Snyk issues are represented in SCC as code security findings. When Snyk issues are updated, corresponding SCC findings are automatically updated as well. All details are available at the Organization level in the Google Cloud Security Command Center (SCC) integration. +The Google Cloud Security Command Center (SCC) integration sends Snyk issues to SCC, so you can view and manage Snyk issues alongside cloud security findings from Google Cloud in a single viewpoint. Snyk issues are represented in SCC as code security findings. When Snyk issues are updated, corresponding SCC findings are automatically updated as well. All details are available at the Organization level in the Google Cloud Security Command Center (SCC) integration. Use the following instructions to set up the integration: @@ -28,12 +28,12 @@ Service Accounts are not available at the Organization level in Google Cloud IAM ## Create the findings source using the Google Cloud SCC console * In the SCC console, navigate to **Marketplace** and search for Snyk. Alternatively, navigate directly to the [Snyk for SCC marketplace listing](https://console.cloud.google.com/marketplace/product/snyk-marketplace/snyk-google-scc). -* Click **SIGN UP WITH PARTNER** to install the Snyk for SCC integration. During this process, you will create a **Findings Source** for Snyk and a **Service Account** with [Security Center Findings Editor](https://cloud.google.com/security-command-center/docs/access-control-org#securitycenter.findingsEditor) permissions. +* Click **SIGN UP WITH PARTNER** to install the Snyk for SCC integration. During this process, you create a **Findings Source** for Snyk and a **Service Account** with [Security Center Findings Editor](https://cloud.google.com/security-command-center/docs/access-control-org#securitycenter.findingsEditor) permissions. {% hint style="warning" %} **Important Identity and Access Management (IAM) Configuration for Security Command Center** -The setup process will grant the Snyk Service Account the `Security Center Findings Editor` role on the Project you select. However, how you use Security Command Center determines if an additional step is needed. +The setup process grants the Snyk Service Account the `Security Center Findings Editor` role on the Project you select. However, how you use Security Command Center determines if an additional step is needed. * **If you use Google SCC at the Organization level** (most common for businesses): * You must also add an IAM policy binding at the Organization level. @@ -42,7 +42,7 @@ The setup process will grant the Snyk Service Account the `Security Center Findi {% endhint %} * Navigate to Google Cloud IAM and locate the **Service Accoun**t you created in the previous step, then [create a service account key](https://cloud.google.com/iam/docs/keys-create-delete#creating) in JSON format. -* Make a note of the **Source ID** (Findings Source name) and the **Service Account Key**, as you will need to provide them to the Snyk Web UI. +* Make a note of the **Source ID** (Findings Source name) and the **Service Account Key**, as you must provide them to the Snyk Web UI. You can then set up the integration in Snyk using the Snyk Web UI. @@ -60,7 +60,7 @@ You can then set up the integration in Snyk using the Snyk Web UI. 3. Enter the following information: * Profile name for the integration -* The **Org ID** for the for the Google Cloud project that holds the Kubernetes cluster +* The **Org ID** for the Google Cloud project that holds the Kubernetes cluster * The JSON Service Account Key File * The **Source ID** (Findings Source Name) diff --git a/developer-tools/integrations/integrate-with-snyk.md b/developer-tools/integrations/integrate-with-snyk.md index 9eec5f1d5b6c..4e104cefa8d5 100644 --- a/developer-tools/integrations/integrate-with-snyk.md +++ b/developer-tools/integrations/integrate-with-snyk.md @@ -4,7 +4,7 @@ Agentic workflows transform software development by using AI assistants to automate tasks and write code, boosting productivity. But this speed poses security risks, as AI-generated code may have vulnerabilities. -Snyk offers security guardrails through Snyk Studio, including its integration with the Model Context Protocol (MCP), an open standard enabling AI tools to communicate with the Snyk security platform. This allows AI assistants to run scans and check for vulnerabilities during code generation, embedding security early in AI-powered development for both human and AI-generated code. +Snyk offers security guardrails through Snyk Studio, including its integration with the Model Context Protocol (MCP), an open standard enabling AI tools to communicate with the Snyk security platform. This lets AI assistants run scans and check for vulnerabilities during code generation, embedding security early in AI-powered development for both human and AI-generated code. Snyk provides information about: @@ -23,7 +23,7 @@ The Snyk MCP Server is designed as a local MCP server, running on your system us ## Integrations for Snyk -Many integrations are available for using third-party functionality within Snyk and using Snyk with other tools. See [SCM, IDE, and CI/CD workflow and integrations](../scm-integrations/) for information on integrations and other methods of accomplishing that workflow. +Many integrations are available for using third-party functionality in Snyk and using Snyk with other tools. See [SCM, IDE, and CI/CD workflow and integrations](../scm-integrations/) for information on integrations and other methods of accomplishing that workflow. This page identifies additional Snyk integrations and where to find them. @@ -34,7 +34,7 @@ Snyk provides plugins for repository gatekeepers and integrations to connect wit There are integrations that support [Snyk Container](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/scan-with-snyk/snyk-container/container-registry-integrations). -Integrations for [event forwarding](event-forwarding/) allow you to push Snyk platform events directly to certain products on other platforms, enabling you to set up custom alerting, build your own reporting, trigger automation, and more. +Integrations for [event forwarding](event-forwarding/) let you push Snyk platform events directly to certain products on other platforms, so you can set up custom alerting, build your own reporting, trigger automation, and more. [Notification and ticketing systems integrations](jira-and-slack-integrations/) help you work with Snyk in Jira and Slack. @@ -48,7 +48,7 @@ The **Integrations** page shows all active integrations, including any data auto The following supported Snyk data are automatically synced: Snyk Open Source, Snyk Code, Snyk IaC, Snyk Container. -Each connected integration enables you to pause data syncing, modify integration profiles and configurations, delete the integration, or check when the integration was last synced and when the next sync is scheduled. +Each connected integration lets you pause data syncing, modify integration profiles and configurations, delete the integration, or check when the integration was last synced and when the next sync is scheduled. ### Integrations syncing time @@ -67,9 +67,9 @@ After you finish setting up an integration, you can see the following connection * Setup in progress * Connected * Connection failed -* x profile(s) connected -* x/y profile(s) connected -* x profile(s) failed +* x profiles connected +* x/y profiles connected +* x profiles failed If you encounter any of the failed statuses, check the Connection failure details list available on the integration card. @@ -115,7 +115,7 @@ You can add an integration by following these steps: See the [Group-level integrations](../scm-integrations/group-level-integrations/) page for step-by-step details about how to set up an integration. -After the integration is validated, a card is displayed on the Integrations page, allowing you to enable or disable the connection, edit the settings, or remove the connection from your configuration. +After the integration is validated, a card is displayed on the Integrations page, so you can enable or disable the connection, edit the settings, or remove the connection from your configuration. ### Using Snyk Broker diff --git a/developer-tools/integrations/jira-and-slack-integrations/jira-integration.md b/developer-tools/integrations/jira-and-slack-integrations/jira-integration.md index b4c9b05780ac..b9b92be86693 100644 --- a/developer-tools/integrations/jira-and-slack-integrations/jira-integration.md +++ b/developer-tools/integrations/jira-and-slack-integrations/jira-integration.md @@ -6,7 +6,7 @@ For Snyk Infrastructure as Code, see [Jira Integration for IaC](https://app.gitb ## Set up your Jira integration -Snyk Jira integration allows you to manually raise Jira issues in the Snyk UI for vulnerabilities or license issues. The Jira integration also includes the API endpoints [Create jira issue](../../snyk-api/reference/jira-v1.md#org-orgid-project-projectid-issue-issueid-jira-issue) and [List all jira issues](../../snyk-api/reference/jira-v1.md#org-orgid-project-projectid-jira-issues). +The Snyk Jira integration lets you manually raise Jira issues in the Snyk UI for vulnerabilities or license issues. The Jira integration also includes the API endpoints [Create jira issue](../../snyk-api/reference/jira-v1.md#org-orgid-project-projectid-issue-issueid-jira-issue) and [List all jira issues](../../snyk-api/reference/jira-v1.md#org-orgid-project-projectid-jira-issues). {% hint style="info" %} If your Jira instance is private, use [the Snyk Broker deployment method](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-broker/classic-broker/install-and-configure-snyk-broker/jira-prerequisites-and-steps-to-install-and-configure-broker/jira-install-and-configure-using-docker). @@ -15,7 +15,7 @@ If your Jira instance is private, use [the Snyk Broker deployment method](https: ## Prerequisites for Jira integration with Snyk * Snyk supports Jira from version 5 to version 10. -* The following [Jira permissions](https://confluence.atlassian.com/adminjiraserver073/managing-project-permissions-861253293.html) are required: **Browse Projects** and **Create Issues.** +* You need the following [Jira permissions](https://confluence.atlassian.com/adminjiraserver073/managing-project-permissions-861253293.html): **Browse Projects** and **Create Issues.** ## How to set up your Jira integration @@ -35,17 +35,17 @@ After entering the details into the integration, click **Save and continue**. If the connection is not successful, check that the Base URL starts with exactly `https://` It must not have capitals or be http. {% endhint %} -If the connection is successful, you will see the connection details in orange at the top of the page. +If the connection is successful, the connection details appear at the top of the page. Fill in the following fields: * Default Project (required) - Select a Jira Project from the list. * Default Issue Type (required) - Select an issue type from the list. The list is populated from available issue types in your Project. -* Ignored Fields (optional) - Specified fields will be excluded from the prompt users see when creating Jira issues in Snyk. For custom fields, use the [custom field id](https://confluence.atlassian.com/jirakb/find-my-custom-field-id-number-in-jira-744522503.html) in the format `customfield_XXXXXX`. +* Ignored Fields (optional) - Snyk excludes the specified fields from the prompt users see when creating Jira issues in Snyk. For custom fields, use the [custom field id](https://confluence.atlassian.com/jirakb/find-my-custom-field-id-number-in-jira-744522503.html) in the format `customfield_XXXXXX`. ## Create a Jira issue -After you set up the Jira integration connection, open one of your Snyk Projects in the Snyk Web UI. A new button, **Create an issue**, appears at the bottom of each vulnerability and license issue card. This button allows you to create a Jira issue. +After you set up the Jira integration connection, open one of your Snyk Projects in the Snyk Web UI. A new button, **Create an issue**, appears at the bottom of each vulnerability and license issue card. This button lets you create a Jira issue.
Create an issue button

Create an issue button

@@ -53,9 +53,9 @@ If the **Create an issue** button is not visible in the UI, ensure that **Group When you select **Create an issue**, a Jira issue creation form appears. This form includes the Snyk issue details, which are copied into the associated fields. You can review and edit this form before creating the issue. -Select the Jira project to which you want to send the issue. The fields in the example that follows are based on the fields that the specific Project has, so switching between Projects may show different options. +Select the Jira project to which you want to send the issue. The fields in the example that follows are based on the fields that the specific Project has, so switching between Projects might show different options. -
Crate a Jira issue

Create a Jira issue

+
Create a Jira issue

Create a Jira issue

After you create a Jira issue, the Jira key with a link is displayed on the issue card. If you are using the Jira API, you can generate multiple Jira issues for the same issue in Snyk. diff --git a/developer-tools/integrations/jira-and-slack-integrations/slack-app.md b/developer-tools/integrations/jira-and-slack-integrations/slack-app.md index a3568905f250..963406760d65 100644 --- a/developer-tools/integrations/jira-and-slack-integrations/slack-app.md +++ b/developer-tools/integrations/jira-and-slack-integrations/slack-app.md @@ -38,23 +38,23 @@ To enable the Snyk app for Slack, you must do the following: 1. Authorize the app with Snyk to get new issues data that can be forwarded to your Slack workspace. 2. Authorize the app with your Slack workspace to allow Snyk to send notifications to your channels in the workspace. -3. Configure the default notification settings in Snyk for all Projects in your Organization and add [Project-level notification overrides](slack-app.md#manage-project-level-notification-overrides) if you would like. +3. Configure the default notification settings in Snyk for all Projects in your Organization and add [Project-level notification overrides](slack-app.md#manage-project-level-notification-overrides) if you want. ## Configure the Snyk app for Slack Ensure the user performing this installation has the permission **Snyk Apps Management - Install Apps** before continuing. See [documentation for member roles](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/user-management/user-role-management). 1. Open the [Snyk integrations page](https://app.snyk.io/integrations), navigate to **Notifications**, and click the **Slack App** tile. -2. You must give authorization for Snyk to access data from Slack by selecting **Authorize with Snyk**. -3. Additional authorization is requested for Snyk to access the Snyk Slack workspace. This involves content and info about channels and conversations, as well as enabling Snyk to perform action in those channels and conversations. To proceed, select **Allow**. +2. Authorize Snyk to access data from Slack by selecting **Authorize with Snyk**. +3. Snyk requests additional authorization to access the Snyk Slack workspace. This involves content and info about channels and conversations, as well as enabling Snyk to perform actions in those channels and conversations. To proceed, select **Allow**. {% hint style="info" %} -If multiple Slack workspaces are available, a dropdown will be visible at the top right of the page. Select the desired Slack workspace. +If multiple Slack workspaces are available, a dropdown appears at the top right of the page. Select the desired Slack workspace. {% endhint %} You can configure the integration to provide a Slack channel ID for the channel where issue notifications for the Organization are sent, and also filter by severity level. -To find the channel ID of a Slack Channel, open Slack, right-click on the channel name, select **View channel details**, then scroll down to the bottom of the window where you will see the channel ID, for example, C2TB2222N. +To find the channel ID of a Slack Channel, open Slack, right-click on the channel name, select **View channel details**, then scroll down to the bottom of the window where the channel ID appears, for example, C2TB2222N. To add the Snyk for Slack app to a private channel, you must first add the app manually to the channel from within Slack and then select the channel within the Snyk integration. In the Private channel, select **Channel settings - Integrations**, and then **Add an app**. Search for **Snyk for Slack** and select **add**. After you have done this, the channel is displayed on the **Settings** page for the integration. @@ -62,8 +62,8 @@ If you are a Slack Admin, you can manually add the Snyk for Slack app to a priva ## Issue notifications -After the Slack app has been configured, new issue notifications are forwarded to the selected Slack channel according to the desired severity level threshold.\ -New issue notifications may take up to an hour to start propagating to your Slack workspace after it is configured. +After you configure the Slack app, new issue notifications are forwarded to the selected Slack channel according to the desired severity level threshold.\ +New issue notifications can take up to an hour to start propagating to your Slack workspace after it is configured.
Example of a new critical vulnerability notification received in Slack

Example of a new critical vulnerability notification received in Slack

@@ -114,7 +114,7 @@ To interact with the Project-level notification customization endpoints, you mus `GET /orgs/{org_id}/app_bots` {% hint style="info" %} -Ensure you apply the `expand=app` query string on your request. This enables you to find the Bot for the related Snyk App named **Slack App**. +Ensure you apply the `expand=app` query string on your request. This lets you find the Bot for the related Snyk App named **Slack App**. {% endhint %} #### Find your Project ID @@ -145,6 +145,6 @@ After retrieving the `org_id`, `bot_id`, and `project_id` values, you can use th ## Remove the Snyk app for Slack -To remove the Snyk app for Slack, navigate to the settings page, locate **Remove Slack Snyk app** at the bottom of the page, and click the **Disconnect Slack** button: +To remove the Snyk app for Slack, navigate to the settings page, locate **Remove Slack Snyk app** at the bottom of the page, and click **Disconnect Slack**:
Remove Slack App integration

Remove Slack App integration

diff --git a/developer-tools/integrations/jira-and-slack-integrations/slack-integration.md b/developer-tools/integrations/jira-and-slack-integrations/slack-integration.md index 73a4e4efe0db..f8cf22db4493 100644 --- a/developer-tools/integrations/jira-and-slack-integrations/slack-integration.md +++ b/developer-tools/integrations/jira-and-slack-integrations/slack-integration.md @@ -4,10 +4,10 @@ Snyk recommends that all customers use the [Slack App](slack-app.md), as the Slack integration is outdated. {% endhint %} -You can set up Slack to receive Snyk’s alerts about new vulnerabilities that affect your Projects and new upgrades or patches that have become available. +You can set up Slack to receive Snyk alerts about new vulnerabilities that affect your Projects and new upgrades or patches that have become available. {% hint style="info" %} -Vulnerabilities detected on initial import of projects are not sent to Slack immediately. +Vulnerabilities detected on initial import of Projects are not sent to Slack immediately. {% endhint %} ## Slack notification types @@ -22,9 +22,9 @@ A new upgrade or patch is available for a vulnerability that you previously igno ## Set up the Slack integration -To set up the integration, you must generate a Slack webhook. You can do this either via the [Incoming WebHooks app](https://slack.com/apps/A0F7XDUAZ-incoming-webhooks) or by [creating your own Slack app](https://api.slack.com/incoming-webhooks). +To set up the integration, you must generate a Slack webhook. You can do this either using the [Incoming WebHooks app](https://slack.com/apps/A0F7XDUAZ-incoming-webhooks) or by [creating your own Slack app](https://api.slack.com/incoming-webhooks). -Once you have generated your Slack Webhook URL, go to your **Manage Organization** settings and enter the URL. +After you generate your Slack Webhook URL, navigate to your **Manage Organization** settings and enter the URL.
Enter URL of the Slack webhook

Enter URL of the Slack webhook

diff --git a/developer-tools/integrations/jira-and-slack-integrations/snyk-security-in-jira-cloud-integration.md b/developer-tools/integrations/jira-and-slack-integrations/snyk-security-in-jira-cloud-integration.md index e592ca382bd7..89f512e97f85 100644 --- a/developer-tools/integrations/jira-and-slack-integrations/snyk-security-in-jira-cloud-integration.md +++ b/developer-tools/integrations/jira-and-slack-integrations/snyk-security-in-jira-cloud-integration.md @@ -22,7 +22,7 @@ To connect the Jira app to Snyk, you must be a [Snyk Organization administrator] To activate Security in Jira Cloud in Jira, navigate to **Project Settings > Features > Development > Security** and toggle **Security** **ON**. -Ensure you have the following permission scopes in Jira, which are required for the integration to operate. +Ensure you have the following permission scopes in Jira, which the integration needs to operate.
Required scope in JiraPurpose
Write data to the host applicationSynchronize vulnerabilities in Snyk with Jira so they appear in the Security tab in Jira.
Read data from the host applicationRead vulnerabilities from Jira to optimize the issues synchronization process.
Delete data from the host applicationRemove vulnerabilities from Jira when a Snyk Organization is removed from Jira.
@@ -59,8 +59,8 @@ Typically research and development engineering managers do this task because the {% endhint %} 1. In Jira, navigate to your **Project** and select the **Security** tab. -2. Click the **Connect security containers** button. -3. Click on the Snyk application and then select **Connect security containers**. +2. Click **Connect security containers**. +3. Click the Snyk application and then select **Connect security containers**.
Connect security containers in Jira via the Security tab and panels

Connect security containers in Jira via the Security tab and panels

4. Select your Snyk Organization from the list, and choose the Snyk Targets to connect to Jira. @@ -70,11 +70,11 @@ Typically research and development engineering managers do this task because the Developers can now use the security feature to view recent vulnerabilities found in the linked code repositories and start [creating Jira issues](snyk-security-in-jira-cloud-integration.md#create-a-jira-issue-from-a-vulnerability) from those vulnerabilities or [linking them to existing Jira issues](snyk-security-in-jira-cloud-integration.md#link-an-existing-jira-issue-to-a-vulnerability). {% hint style="info" %} -Issue syncing between Snyk and Jira happens asynchronously, meaning there may be a delay before issues appear in Jira. +Issue syncing between Snyk and Jira happens asynchronously, meaning there might be a delay before issues appear in Jira. {% endhint %} {% hint style="info" %} -Only **security vulnerabilities** will be shown on the Jira Security tab. +Only **security vulnerabilities** are shown on the Jira Security tab. {% endhint %} ### Deleting a target or repository @@ -82,15 +82,15 @@ Only **security vulnerabilities** will be shown on the Jira Security tab. To delete a target or repository from Snyk that you have connected to Jira, you must first delete the container code repository in Jira, through the **Security** panel in each Jira Project. Then you can remove the target or repository from Snyk: 1. In Jira, navigate to your **Project** and select the **Security** tab. -2. Click on the **Connect security containers** button. -3. Click on the Snyk application +2. Click **Connect security containers**. +3. Click the Snyk application 4. Select the security container you want to remove from the list using the **Remove connection** option
Remove connected security containers in the Jira Security panel

Remove connected security containers in the Jira Security panel

## Automate ticket creation in Jira -The following steps describe how to use Jira automation to automatically create tickets for Snyk Vulnerabilities: +The following steps describe how to use Jira automation to automatically create tickets for Snyk vulnerabilities: 1. In Jira, in your project, navigate to **Project Settings** and then **Automation**. 2. Click **Create Rule**. @@ -126,7 +126,7 @@ Select the title of a column in the table to sort all vulnerabilities by that at When triaging issues, you can add a Jira issue to the sprint or backlog to ensure the required work for resolving the vulnerability is planned and tracked. -Snyk provides vulnerability information to Jira, enabling users to have comprehensive data for resolving issues. +Snyk provides vulnerability information to Jira, giving users comprehensive data for resolving issues. To add a Jira issue, navigate to the Snyk Security tab, find a vulnerability, and click **Create issue**. @@ -141,7 +141,7 @@ If the vulnerability already has a Jira issue, you can link the vulnerability to These steps describe how to use Jira automation and JQL to automatically close or change the status of tickets for vulnerabilities that are now in a closed state. 1. In Jira on your Project, navigate to **Project Settings** and then **Automation.** -2. Click he **Create Rule** button. +2. Click **Create Rule**. 3. Click **Scheduled** and then **Scheduled**.
Add Scheduled trigger

Add Scheduled trigger

@@ -160,16 +160,16 @@ These steps describe how to use Jira automation and JQL to automatically close o 6. Now that the setup is complete, give it a name and click on **Turn on rule.** -Now, according to your schedule, Jira will search for any issues for which the vulnerability is closed, but the issues are not closed, and close each Jira issue. +Now, according to your schedule, Jira searches for any issues for which the vulnerability is closed but the issues are not closed, and closes each Jira issue. ## Uninstall Snyk Security in Jira Cloud {% hint style="warning" %} -Uninstalling Snyk Security in Jira Cloud will disconnect Snyk vulnerabilities from their associated Jira issues.\ +Uninstalling Snyk Security in Jira Cloud disconnects Snyk vulnerabilities from their associated Jira issues.\ \ To uninstall a Jira app, you must be an administrator in the site-admins, administrators, or jira-administrators groups. {% endhint %} 1. In Jira, navigate to **Apps** in the main menu and select **Manage your apps.** 2. Select **Snyk Security in Jira.** -3. Click the **Uninstall** button. +3. Click **Uninstall**. diff --git a/developer-tools/integrations/partner-integrations.md b/developer-tools/integrations/partner-integrations.md index da31fdb3464b..62e7766d884f 100644 --- a/developer-tools/integrations/partner-integrations.md +++ b/developer-tools/integrations/partner-integrations.md @@ -129,7 +129,7 @@ To see the documentation for each integration, click on the integration name in ## Identity correlation -Tracking SLDC workflows and vulnerabilities per developer/user. +Tracking SDLC workflows and vulnerabilities per developer/user. To see the documentation for each integration, click on the integration name in the table. @@ -206,7 +206,7 @@ To see the documentation for each integration, click on the integration name in | Integration | Description | | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [ServiceNow: Snyk Vulnerbility Intelligence for SBOM](https://store.servicenow.com/store/app/994d67e21b646a50a85b16db234bcb56) | Vulnerability Intelligence for ServiceNow SBOM allows you to efficiently prioritize and remediate vulnerabilities in the components identified in your SBOMs. | +| [ServiceNow: Snyk Vulnerability Intelligence for SBOM](https://store.servicenow.com/store/app/994d67e21b646a50a85b16db234bcb56) | Vulnerability Intelligence for ServiceNow SBOM allows you to efficiently prioritize and remediate vulnerabilities in the components identified in your SBOMs. | ## Ticketing and workflow diff --git a/developer-tools/scan-with-snyk/snyk-tools/README.md b/developer-tools/scan-with-snyk/snyk-tools/README.md index 3363ba1734d3..ef25f0555700 100644 --- a/developer-tools/scan-with-snyk/snyk-tools/README.md +++ b/developer-tools/scan-with-snyk/snyk-tools/README.md @@ -2,7 +2,7 @@ ## Scope of Snyk Tools -Snyk Tools help with specific pain points that may not be addressed by Snyk product functionality, regardless of whether you use Snyk through the Web UI, CLI, API, or an integration. Snyk Tools extend the functions of the Snyk API and the Snyk CLI. +Snyk Tools help with specific pain points that Snyk product functionality might not address, regardless of whether you use Snyk through the Web UI, CLI, API, or an integration. Snyk Tools extend the functions of the Snyk API and the Snyk CLI. {% hint style="info" %} You must have a [Snyk Account](https://snyk.io/login?cta=sign-up\&loc=nav\&page=support_docs_page) with populated Projects to use Snyk Tools. @@ -32,7 +32,7 @@ Refer to the repositories for instructions on how to use the following additiona * [snyk-user-sync-tool](https://github.com/snyk-tech-services/snyk-user-sync-tool): Add, remove, and sync user memberships. * [snyk-licenses-texts](https://github.com/snyk-tech-services/snyk-licenses-texts): Provides Organization-level licenses used, copyrights (until January 8, 2024), and dependencies data. * [snyk-request-manager](https://github.com/snyk-tech-services/snyk-request-manager): Rate-controlled and retry-enabled request manager to interact with Snyk APIs. -* [snyk-repo-issue-tracker](https://github.com/snyk-tech-services/snyk-repo-issue-tracker): A python script/module that allows for generating a changeset of issues between runs against the Snyk Project issues API. +* [snyk-repo-issue-tracker](https://github.com/snyk-tech-services/snyk-repo-issue-tracker): A python script/module that generates a changeset of issues between runs against the Snyk Project issues API. * [snyk-repo-diff:](https://github.com/snyk-tech-services/snyk-repo-diff) Helps determine which repositories are not monitored by Snyk. This works by retrieving a list of all Projects in a given Snyk Group, that is, all Projects in all Organizations belonging to the same Snyk Group, and associating them with a list of repositories found in a given GitHub Organization. diff --git a/developer-tools/scan-with-snyk/snyk-tools/python-code-to-extract-issues-from-snyk-api.md b/developer-tools/scan-with-snyk/snyk-tools/python-code-to-extract-issues-from-snyk-api.md index 0d80d8eb9e56..d34723e400ff 100644 --- a/developer-tools/scan-with-snyk/snyk-tools/python-code-to-extract-issues-from-snyk-api.md +++ b/developer-tools/scan-with-snyk/snyk-tools/python-code-to-extract-issues-from-snyk-api.md @@ -1,3 +1,3 @@ # Python code to extract issues from Snyk API -Snyk has an unsupported Python client that can be used to get issues using the V1 API: [https://github.com/snyk-labs/pysnyk](https://github.com/snyk-labs/pysnyk). +Snyk has an unsupported Python client you can use to get issues using the V1 API: [https://github.com/snyk-labs/pysnyk](https://github.com/snyk-labs/pysnyk). diff --git a/developer-tools/scan-with-snyk/snyk-tools/tool-jira-tickets-for-new-vulns.md b/developer-tools/scan-with-snyk/snyk-tools/tool-jira-tickets-for-new-vulns.md index f0115337eda1..2220d2479bdc 100644 --- a/developer-tools/scan-with-snyk/snyk-tools/tool-jira-tickets-for-new-vulns.md +++ b/developer-tools/scan-with-snyk/snyk-tools/tool-jira-tickets-for-new-vulns.md @@ -1,6 +1,6 @@ # Tool: jira-tickets-for-new-vulns -`jira-tickets-for-new-vulns` provides the means to sync your Snyk-monitored projects and automatically open Jira tickets for new issues and existing issue(s) without ticket(s) already created. +`jira-tickets-for-new-vulns` provides the means to sync your Snyk-monitored Projects and automatically open Jira tickets for new issues and existing issues without tickets already created. Cron it every X minutes/hours and fix the issues. This tool is aimed to be executed at regular intervals or with a trigger of your choice (webhooks). @@ -45,7 +45,7 @@ Use the binaries from [the release page](https://github.com/snyk-tech-services/j ## Restrictions -The tool does not support infrastructure as code projects. It opens an issue only for code and open source projects and ignores all other project types. +The tool does not support infrastructure as code Projects. It opens an issue only for code and open source Projects and ignores all other Project types. **Priority is severity** @@ -70,7 +70,7 @@ git clone the repo, build: > `go run main.go jira.go jira_utils.go vulns.go snyk.go snyk_utils.go` -Please report issues. +Report issues. ## Dependencies @@ -143,4 +143,4 @@ jira: * The token is not expected to be present in the config file. * Command line arguments override the config file. Example: Using the config file above, running `./snyk-jira-sync-macOs --Org=1234 --configFile=./path/to/folder --token=123` the org ID used by the tool will be 1234 and not a1b2c3de-99b1-4f3f-bfdb-6ee4b4990513. * See 'Extended options' for default values. -* Ensure you use the same issue type that is configured in your Jira. Default is Bug. Verify the type is use (or default) exists in your Jira configuration. +* Ensure you use the same issue type that is configured in your Jira. Default is Bug. Verify the type in use (or default) exists in your Jira configuration. diff --git a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/README.md b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/README.md index e41fb3a5192f..3cfb59f35ea9 100644 --- a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/README.md +++ b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/README.md @@ -8,10 +8,10 @@ The Snyk API Project importer, `snyk-api-import`, is a script intended to help i If you need to adjust concurrency, you can stop the script, change the concurrency variable, and start again. The tool skips previous repositories (Targets) that have been requested for import. -To use `snyk-api-import` you must do the following in advance: +To use `snyk-api-import` you must do the following first: * Set up your Snyk Organizations (Orgs) before running an import. -* Configure your Snyk Organizations with some connection to an SCM (GitHub, GitLab, Bitbucket, other) as you will need the `integrationId` to generate the import files. +* Configure your Snyk Organizations with some connection to an SCM (GitHub, GitLab, Bitbucket, other) as you need the `integrationId` to generate the import files. * Use the [Set notification settings](../../../snyk-api/reference/organizations-v1.md#org-orgid-notification-settings) API endpoint to disable notifications for emails and so on, to avoid receiving import notifications (recommended). * Use the [Update](../../../snyk-api/reference/integrations-v1.md#org-orgid-integrations-integrationid-settings) (integration settings) endpoint to disable the fix PRs and PR checks until import is complete to avoid sending extra requests to SCMs (GitHub, GitLab, Bitbucket, and so on). @@ -39,7 +39,7 @@ yarn global add snyk-api-import ## Usage -By default the `import` command will run if no command is specified. +By default the `import` command runs if no command is specified. * `import` - kick off an API-powered import of repos (Targets) into existing Snyk Organizations defined in the import configuration file. All support available for all Project types is provided through the [Import](../../../snyk-api/reference/import-projects-v1.md) API endpoints, [Import targets](../../../snyk-api/reference/import-projects-v1.md#org-orgid-integrations-integrationid-import) and [Get Import job details](../../../snyk-api/reference/import-projects-v1.md#org-orgid-integrations-integrationid-import-jobid). * `help` - show help and all available commands and their options. @@ -70,9 +70,9 @@ The logs can be explored using the [Bunyan CLI](http://trentm.com/node-bunyan/bu Error: ENFILE: file table overflow, open or Error: EMFILE, too many open files -If you see these errors, you may need to bump **ulimit** to allow more open file operations. In order to keep the operations performing well, the tool logs as soon as it is convenient rather than waiting until the very end of a loop and logging a huge data structure. This means that depending on the number of concurrent imports set, the tool may exceed the system default **ulimit**. +If you see these errors, you might need to bump **ulimit** to allow more open file operations. To keep the operations performing well, the tool logs as soon as it is convenient rather than waiting until the end of a loop and logging a huge data structure. This means that depending on the number of concurrent imports set, the tool might exceed the system default **ulimit**. -Some of these resources may help you bump the **ulimit**: +Some of these resources can help you bump the **ulimit**: * [ss64.com](https://ss64.com/bash/ulimit.html) * [StackOverflow](https://stackoverflow.com/questions/45004352/error-enfile-file-table-overflow-scandir-while-run-reaction-on-mac) @@ -94,7 +94,7 @@ If your GitHub, GitLab, Bitbucket, or Azure instance is using a self-signed cert Does this work with brokered integrations? -Yes. Because Snyk reuses the existing integration with your SCM (Git) repository to perform the imports, the brokered connection will be used when configured. +Yes. Because Snyk reuses the existing integration with your SCM (Git) repository to perform the imports, the brokered connection is used when configured. diff --git a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/contributing-to-snyk-api-import.md b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/contributing-to-snyk-api-import.md index a8912c47be52..6bfc65493008 100644 --- a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/contributing-to-snyk-api-import.md +++ b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/contributing-to-snyk-api-import.md @@ -2,7 +2,7 @@ ## Contributor Agreement -A pull-request will only be considered for merging into the upstream codebase after you have signed Snyk's contributor agreement, assigning to Snyk the rights to the contributed code and granting you a license to use it in return. If you submit a pull request, you will be prompted to review and sign the agreement with one click (Snyk uses [CLA assistant](https://cla-assistant.io/)). +Snyk considers a pull request for merging into the upstream codebase only after you have signed the Snyk contributor agreement, assigning to Snyk the rights to the contributed code and granting you a license to use it in return. If you submit a pull request, Snyk prompts you to review and sign the agreement with one click (Snyk uses [CLA assistant](https://cla-assistant.io/)). ## Pull requests @@ -16,7 +16,7 @@ fix: minified scripts being removed Also includes tests ``` -This allows for the automatic change log to generate correctly. +This lets the automatic change log generate correctly. Commit types must be one of the following: @@ -40,10 +40,10 @@ Ensure that your code adheres to the included `.eslintrc` config by running `npm * New command line options are generally discouraged unless there's a _really_ good reason. * Add tests for newly added code (and try to mirror directory and file structure if possible). * Spell check. -* PRs will not be code reviewed unless all tests are passing. +* PRs are not code reviewed unless all tests are passing. {% hint style="info" %} -When fixing a bug, commit a failing test first so that CircleCI (or the approver) can show the code failing. Once that commit is in place, then commit the bug fix so that Snyk can test before and after. +When fixing a bug, commit a failing test first so that CircleCI (or the approver) can show the code failing. After that commit is in place, commit the bug fix so that Snyk can test before and after. {% endhint %} -Remember that you're developing for multiple platforms and versions of Node.js, so if the tests pass on your Mac or Linux or Windows machine, the tests may not pass elsewhere. +Remember that you're developing for multiple platforms and versions of Node.js, so if the tests pass on your Mac or Linux or Windows machine, the tests might not pass elsewhere. diff --git a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/creating-import-targets-data-for-import-command.md b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/creating-import-targets-data-for-import-command.md index d0b064dcbd1d..0fe42bcd213d 100644 --- a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/creating-import-targets-data-for-import-command.md +++ b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/creating-import-targets-data-for-import-command.md @@ -34,7 +34,7 @@ You need the organizations data in JSON as an input to this command to help map } ``` -Note: the `"name`" of the GitHub or GitHub Enterprise Organization is required in order to list all repos belonging to that Organization using the GitHub API. The Snyk-specific data accompanying that Organization name will be used as the information to generate import data, assuming all repos in that Organization will be imported into a given Snyk Organization. This utility is opinionated. If you want to customize the import data, create it manually as described on [Kicking off an import](kicking-off-an-import.md). +Note: the `"name`" of the GitHub or GitHub Enterprise Organization is required to list all repos belonging to that Organization using the GitHub API. Snyk uses the Snyk-specific data accompanying that Organization name to generate import data, assuming all repos in that Organization are imported into a given Snyk Organization. This utility is opinionated. If you want to customize the import data, create it manually as described on [Kicking off an import](kicking-off-an-import.md). * You can list GitHub and GitHub Enterprise organizations using the GitHub [/orgs API](https://docs.github.com/en/free-pro-team@latest/rest/reference/orgs). * You can list integrations using the Snyk API endpoint [List](../../../snyk-api/reference/integrations-v1.md#org-orgid-integrations-1) (integrations). @@ -68,7 +68,7 @@ You need the organization's data in JSON as an input to this command to help map } ``` -Note: the "name" of the GitLab Group is required in order to list all projects belonging to that group using the GitLab API. The Snyk-specific data accompanying that Group name will be used as the information to generate import data assuming all projects in that group will be imported into a given Snyk Organization. This utility is opinionated. If you want to customize the import data, create it manually as described on [Kicking off an import](kicking-off-an-import.md). +Note: the "name" of the GitLab Group is required to list all projects belonging to that group using the GitLab API. Snyk uses the Snyk-specific data accompanying that Group name to generate import data, assuming all projects in that group are imported into a given Snyk Organization. This utility is opinionated. If you want to customize the import data, create it manually as described on [Kicking off an import](kicking-off-an-import.md). * GitLab Groups can be listed using the GitLab [/groups API](https://docs.gitlab.com/ee/api/groups.html) * You can list integrations using the Snyk API endpoint [List](../../../snyk-api/reference/integrations-v1.md#org-orgid-integrations-1) (integrations). @@ -104,7 +104,7 @@ You need the organizations data in JSON as an input to this command to help map } ``` -Note: the "name" of the Azure organization is required in order to list all projects and repos belonging to that organization using the Azure API. The Snyk-specific data accompanying that organization name will be used as the information to generate import data assuming all projects in that organization will be imported into a given Snyk Organization. This utility is opinionated. If you want to customize the import data, create it manually as described on [Kicking off an import](kicking-off-an-import.md). +Note: the "name" of the Azure organization is required to list all projects and repos belonging to that organization using the Azure API. Snyk uses the Snyk-specific data accompanying that organization name to generate import data, assuming all projects in that organization are imported into a given Snyk Organization. This utility is opinionated. If you want to customize the import data, create it manually as described on [Kicking off an import](kicking-off-an-import.md). * Your Org name in Azure is listed on the left pane in the [Azure-Devops-site](https://dev.azure.com/) * You can list integrations using the Snyk API endpoint [List](../../../snyk-api/reference/integrations-v1.md#org-orgid-integrations-1) (integrations). @@ -140,7 +140,7 @@ You need the organizations data in JSON as an input to this command to help map } ``` -Note: the "name" of the Bitbucket server project is required in order to list all repos belonging to that project using the Bitbucket server API. The Snyk-specific data accompanying that project name will be used as the information to generate import data, assuming all repos in that project will be imported into a given Snyk Organization. If you want to customize the import data, create it manually as described on [Kicking off an import](kicking-off-an-import.md). +Note: the "name" of the Bitbucket server project is required to list all repos belonging to that project using the Bitbucket server API. Snyk uses the Snyk-specific data accompanying that project name to generate import data, assuming all repos in that project are imported into a given Snyk Organization. If you want to customize the import data, create it manually as described on [Kicking off an import](kicking-off-an-import.md). * Bitbucket Server Projects can be listed using the BitBucket [/projects API](https://docs.atlassian.com/bitbucket-server/rest/7.19.2/bitbucket-rest.html). * You can list integrations using the Snyk API endpoint [List](../../../snyk-api/reference/integrations-v1.md#org-orgid-integrations-1) (integrations). @@ -175,7 +175,7 @@ You need the organizations data in JSON as an input to this command to help map } ``` -Note: the "name" of the Bitbucket Cloud workspace is required in order to list all repositories belonging to that workspace using the Bitbucket Cloud API. The Snyk-specific data accompanying that workspace name will be used as the information to generate import data assuming all repositories in that workspace will be imported into a given Snyk Organization. This utility is opinionated. If you want to customize the import data, create it manually as described on [Kicking off an import](kicking-off-an-import.md). +Note: the "name" of the Bitbucket Cloud workspace is required to list all repositories belonging to that workspace using the Bitbucket Cloud API. Snyk uses the Snyk-specific data accompanying that workspace name to generate import data, assuming all repositories in that workspace are imported into a given Snyk Organization. This utility is opinionated. If you want to customize the import data, create it manually as described on [Kicking off an import](kicking-off-an-import.md). * Bitbucket Cloud workspaces can be listed using the BItBucket [/workspaces API](https://developer.atlassian.com/cloud/bitbucket/rest/api-group-workspaces/#api-group-workspaces). * You can list integrations using the Snyk API endpoint [List](../../../snyk-api/reference/integrations-v1.md#org-orgid-integrations-1) (integrations). diff --git a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/creating-organizations-in-snyk.md b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/creating-organizations-in-snyk.md index ad83639f9b7e..04603018acee 100644 --- a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/creating-organizations-in-snyk.md +++ b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/creating-organizations-in-snyk.md @@ -13,13 +13,13 @@ This page has instructions for creating Organizations (Orgs) in Snyk: * [Using the `orgs:create` utility](creating-organizations-in-snyk.md#using-the-orgs-create-utility) * [Recommendations](creating-organizations-in-snyk.md#recommendations) -Before an import can begin you must set up Snyk with the Organizations you will populate with Projects. +Before an import can begin, you must set up Snyk with the Organizations you populate with Projects. -Snyk recommends that you have as many Organizations in Snyk as you have in the source you are importing from. For GitHub, this means mirroring the GitHub organizations in Snyk. The `snyk-api-import` tool provides a utility to use to make this simpler when using Groups and Organizations in Snyk. +Snyk recommends that you have as many Organizations in Snyk as you have in the source you are importing from. For GitHub, this means mirroring the GitHub organizations in Snyk. The `snyk-api-import` tool provides a utility to make this simpler when using Groups and Organizations in Snyk. ## Generating the data required to create Organizations in Snyk with the `orgs:data` utility -This utility helps generate data needed to mirror the GitHub.com, GitHub Enterprise, GitLab, Bitbucket Server, or Bitbucket Cloud organization structure in Snyk. This opinionated utility will assume every organization in GitHub.com, GitHub Enterprise, GitLab, Bitbucket Server, or Bitbucket Cloud should become an Organization in Snyk. If this is not what you are looking for, consider using the API endpoint [Create a new organization](../../../snyk-api/reference/organizations-v1.md#org) directly to create the structure you need. +This utility helps generate data needed to mirror the GitHub.com, GitHub Enterprise, GitLab, Bitbucket Server, or Bitbucket Cloud organization structure in Snyk. This opinionated utility assumes every organization in GitHub.com, GitHub Enterprise, GitLab, Bitbucket Server, or Bitbucket Cloud should become an Organization in Snyk. If this is not what you are looking for, consider using the API endpoint [Create a new organization](../../../snyk-api/reference/organizations-v1.md#org) directly to create the structure you need. ### Options diff --git a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/kicking-off-an-import.md b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/kicking-off-an-import.md index 0e280b498ca5..9ae4af1265ad 100644 --- a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/kicking-off-an-import.md +++ b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/kicking-off-an-import.md @@ -1,8 +1,8 @@ # Kicking off an import -`snyk-api-import` supports the same Project sources that you can import using the Snyk API: Git repositories, Docker images, containers, configuration files and much more. You can configure integrations using the Integrations settings on your Snyk Organization settings page. For more information, see the definition of [Target](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/scan-with-snyk/snyk-projects#target) on the Snyk Projects documentation page. +`snyk-api-import` supports the same Project sources that you can import using the Snyk API: Git repositories, Docker images, containers, configuration files, and much more. You can configure integrations using the Integrations settings on your Snyk Organization settings page. For more information, see the definition of [Target](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/scan-with-snyk/snyk-projects#target) on the Snyk Projects documentation page. -Note that any logs will be generated at `SNYK_LOG_PATH` directory. +Note that Snyk generates any logs in the `SNYK_LOG_PATH` directory. The steps to start an import follow. @@ -40,9 +40,9 @@ Each **import target** has the following keys: * `exclusionGlobs` - Comma-separated list of up to ten folder names to exclude from scanning (each folder name must not exceed 100 characters). If not specified, defaults to "fixtures, tests, tests, node\_modules". If an empty string is provided, no folders will be excluded. * `files` - An object array. Each path must be the full relative path to the file from the root of the Target. Only those files found at that location will be imported. -Note that for a repository that may have 200+ manifest files, Snyk recommends that you split the import into multiple imports by targeting specific files. Importing hundreds of files at once from one repository can cause the import to result in some errors or failures. +Note that for a repository that has 200+ manifest files, Snyk recommends that you split the import into multiple imports by targeting specific files. Importing hundreds of files at once from one repository can cause the import to result in some errors or failures. -Splitting the import to import some files or some folders only will benefit from the re-tries and produce a smaller load on the source control management system being used. Populate the `files` property to accomplish this in the import JSON. +Splitting the import to import some files or some folders only benefits from the re-tries and produces a smaller load on the source control management system being used. Populate the `files` property to accomplish this in the import JSON. If you have any tests or fixtures that should be ignored, set the `exclusionGLobs` property: @@ -168,20 +168,20 @@ Download a binary from the [releases page](https://github.com/snyk/snyk-api-impo ### **Skip all previously imported targets** -This utility can be used to skip previously imported Targets (repos), so only remaining Targets will be imported. +You can use this utility to skip previously imported Targets (repos), so Snyk imports only the remaining Targets. -The utility helps generate the `imported-targets.log` file by analyzing the Projects already in a given Snyk Group. When present in the logging path, this file is used to look up Targets that should be skipped during the import. +The utility helps generate the `imported-targets.log` file by analyzing the Projects already in a given Snyk Group. When present in the logging path, this file looks up Targets to skip during the import. ### Example -* All GitHub repositories have been imported into Snyk into their respective Organizations during initial onboarding. +* All GitHub repositories are imported into Snyk into their respective Organizations during initial onboarding. * New GitHub repositories have since been added and now need to be added to Snyk. * To avoid importing everything again, you can use this utility and run `import` again to import only "new" GitHub repositories. This is much faster and removes unnecessary calls to Snyk and GitHub to fetch files and do the import for everything again. ### Importing the same Target -* The same Target imported into a different Organization can be imported. -* The same Target from a different source can be imported; for example, the same repository that is present in GitHub can now be imported through GitHub Enterprise into the same Organization. +* You can import the same Target into a different Organization. +* You can import the same Target from a different source. For example, you can now import the same repository that is present in GitHub through GitHub Enterprise into the same Organization. ### Command to run diff --git a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/mirroring-bitbucket-cloud-organizations-and-repos-in-snyk.md b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/mirroring-bitbucket-cloud-organizations-and-repos-in-snyk.md index 3ab074636f3b..b8b3a3d27304 100644 --- a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/mirroring-bitbucket-cloud-organizations-and-repos-in-snyk.md +++ b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/mirroring-bitbucket-cloud-organizations-and-repos-in-snyk.md @@ -14,7 +14,7 @@ Refer to individual documentation pages for detailed information. The general st ## Re-importing new repos and Orgs only while mirroring -Once initial import is complete you can periodically check for new repos and make sure they are added into Snyk by following these steps, which are similar to the preceding steps to import repos. +After the initial import is complete, you can periodically check for new repos and ensure they are added to Snyk by following these steps, which are similar to the preceding steps to import repos. 1. `export BITBUCKET_CLOUD_USERNAME=***`, `export BITBUCKET_CLOUD_PASSWORD=***` and `export SNYK_TOKEN=***` 2. Generate organization data in Snyk and skip any that do not have any repos by using `--skipEmptyOrg` `snyk-api-import orgs:data --source=bitbucket-cloud --groupId= --skipEmptyOrg` Full instructions: [Creating organizations in Snyk](creating-organizations-in-snyk.md) diff --git a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/mirroring-bitbucket-server-organizations-and-repos-in-snyk.md b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/mirroring-bitbucket-server-organizations-and-repos-in-snyk.md index 69bec2f95be7..645e31719757 100644 --- a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/mirroring-bitbucket-server-organizations-and-repos-in-snyk.md +++ b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/mirroring-bitbucket-server-organizations-and-repos-in-snyk.md @@ -1,6 +1,6 @@ # Mirroring Bitbucket Server organizations and repos in Snyk -You can use four commands in the available utils to import the entirety of Bitbucket Server repos into Snyk. You must configure both the both the Bitbucket Server token and Snyk token as environment variables to proceed. +You can use four commands in the available utils to import the entirety of Bitbucket Server repos into Snyk. You must configure both the Bitbucket Server token and Snyk token as environment variables to proceed. ## General steps to import Bitbucket Server repos @@ -14,7 +14,7 @@ Refer to individual documentation pages for detailed information. The general st ## Re-importing new repos and Orgs only while mirroring -Once initial import is complete you can periodically check for new repos and make sure they are added into Snyk by following these steps, which are similar to the preceding steps to import repos. +After the initial import is complete, you can periodically check for new repos and ensure they are added to Snyk by following these steps, which are similar to the preceding steps to import repos. 1. `export BITBUCKET_SERVER_TOKEN=***` and `export SNYK_TOKEN=***` 2. Generate organization data in Snyk and skip any that do not have any repos by using `--skipEmptyOrg` `snyk-api-import orgs:data --source=bitbucket-server --groupId= --skipEmptyOrg` Full instructions: [Creating organizations in Snyk](creating-organizations-in-snyk.md) diff --git a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/mirroring-gitlab-organizations-and-repos-in-snyk.md b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/mirroring-gitlab-organizations-and-repos-in-snyk.md index d6a0a4b936d8..5962ad1feb38 100644 --- a/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/mirroring-gitlab-organizations-and-repos-in-snyk.md +++ b/developer-tools/scan-with-snyk/snyk-tools/tool-snyk-api-import/mirroring-gitlab-organizations-and-repos-in-snyk.md @@ -14,7 +14,7 @@ Refer to individual documentation pages for detailed information. The general st ## Re-importing new repos and Orgs only while mirroring -Once initial import is complete you can periodically check for new repos and make sure they are added into Snyk by following these steps, which are similar to the preceding steps to import repos. +After the initial import is complete, you can periodically check for new repos and ensure they are added to Snyk by following these steps, which are similar to the preceding steps to import repos. 1. `export GITLAB_TOKEN=***` and `export SNYK_TOKEN=***` 2. Generate organization data in Snyk and skip any that do not have any repos by using `--skipEmptyOrg` `snyk-api-import orgs:data --source=gitlab --groupId= --skipEmptyOrg` Full instructions: [Creating organizations in Snyk](creating-organizations-in-snyk.md) diff --git a/developer-tools/scm-integrations/README.md b/developer-tools/scm-integrations/README.md index 12f857da9b6b..744691b1e415 100644 --- a/developer-tools/scm-integrations/README.md +++ b/developer-tools/scm-integrations/README.md @@ -1,8 +1,8 @@ # SCMs -Snyk supports SCM integrations that allow you to implement security at each point in your workflow: importing a Project, writing your code, and building and deployment. Snyk can also [automatically create pull requests (PRs)](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/fix/snyk-pull-or-merge-requests/enable-automatic-upgrade-prs-for-new-dependency-upgrades) on your behalf to upgrade your dependencies based on scan results, compatible with a variety of SCM integrations. +Snyk supports SCM integrations that let you implement security at each point in your workflow: importing a Project, writing your code, and building and deployment. Snyk can also [automatically create pull requests (PRs)](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/fix/snyk-pull-or-merge-requests/enable-automatic-upgrade-prs-for-new-dependency-upgrades) on your behalf to upgrade your dependencies based on scan results, compatible with a variety of SCM integrations. -Snyk Source Control Manager (SCM) integrations allow you to: +Snyk Source Control Manager (SCM) integrations let you: * Continuously perform security scanning across all integrated repositories * Detect vulnerabilities in your open-source components @@ -25,7 +25,7 @@ If you have added the GitHub integration at Organizational and/or Group levels a This feature is available for GitHub, GitHub Enterprise, GitHub Cloud App, GitLab, Bitbucket Server, Bitbucket Cloud App, Bitbucket Cloud (Legacy), and Azure Repos (TFS) integrations. {% endhint %} -The Workspaces feature enables Snyk to ingest a temporary snapshot of repository contents, and all commit metadata through your configured SCM integrations. +The Workspaces feature enables Snyk to ingest a temporary snapshot of repository contents and all commit metadata through your configured SCM integrations. For detailed information on this feature, including enablement steps, see [Workspaces for SCM integrations](workspaces.md). @@ -35,7 +35,7 @@ If you are an Enterprise customer, see [Choose rollout integrations](https://app ### GitHub vs GitHub Enterprise -As an Enterprise plan user, Snyk recommends using the GitHub Enterprise integration as it enables you to use a single GitHub service account personal access token (PAT) across your Snyk Organization rather than depending on a PAT for an individual user account. You can use this integration whether or not you have a GitHub Enterprise (GHE) license or subscription. +As an Enterprise plan user, Snyk recommends using the GitHub Enterprise integration as it lets you use a single GitHub service account personal access token (PAT) across your Snyk Organization rather than depending on a PAT for an individual user account. You can use this integration whether or not you have a GitHub Enterprise (GHE) license or subscription. Another benefit to using the GitHub Enterprise integration is that you can choose to clone integration settings when you are creating new Snyk Organizations. This means you can use one GitHub Enterprise integration for all Organizations in your Snyk Group. @@ -55,9 +55,9 @@ See [Migrate to the Snyk Bitbucket Cloud App](organization-level-integrations/bi #### Main capabilities unlocked by the new app integration -* Allows using Snyk with Bitbucket's [allowlisting IP addresses](https://support.atlassian.com/bitbucket-cloud/docs/control-access-to-your-private-content/) premium tier feature. +* Lets you use Snyk with the [allowlisting IP addresses](https://support.atlassian.com/bitbucket-cloud/docs/control-access-to-your-private-content/) premium tier feature in Bitbucket. * Helps handle rate-limiting issues for companies who spread their repos across multiple workspaces in Bitbucket Cloud. -* Supports the first-party interface in Bitbucket Cloud (Snyk's Security tab) out-of-the-box, meaning you need not install and maintain the first-party extension app to consume Snyk's security insights from Bitbucket Cloud. +* Supports the first-party interface in Bitbucket Cloud (the Security tab in Snyk) out-of-the-box, meaning you need not install and maintain the first-party extension app to consume Snyk security insights from Bitbucket Cloud. #### Limitations of the new app integration @@ -67,6 +67,6 @@ See [Migrate to the Snyk Bitbucket Cloud App](organization-level-integrations/bi #### Are there any plans for end-of-life for the Personal Access Token (PAT) integration? -To improve security, the use of app passwords in Bitbucket Cloud is transitioning to API tokens. Existing integrations that use app passwords will continue to function temporarily until 9 June, 2026: +To improve security, the use of app passwords in Bitbucket Cloud is transitioning to API tokens. Existing integrations that use app passwords continue to function temporarily until 9 June 2026. To ensure continued support and functionality, update your Bitbucket Cloud integration in Snyk to use an API token. diff --git a/developer-tools/scm-integrations/application-context-for-scm-integrations/README.md b/developer-tools/scm-integrations/application-context-for-scm-integrations/README.md index 66b7cee69f96..ecf9f6e84655 100644 --- a/developer-tools/scm-integrations/application-context-for-scm-integrations/README.md +++ b/developer-tools/scm-integrations/application-context-for-scm-integrations/README.md @@ -4,7 +4,7 @@ The application context for SCM integrations provides a comprehensive and interconnected overview of application assets. This context is crucial for assessing security risks and their potential implications, as it outlines the entire structure and components of the applications involved. -Use Application Context to integrate with Internal Developer Portals (IDPs) and service catalogs such as ServiceNow CMDB, Atlassian Compass, and others. These platforms allow Snyk to automate the collection of essential context, including asset type, ownership, and lifecycle. +Use Application Context to integrate with Internal Developer Portals (IDPs) and service catalogs such as ServiceNow CMDB, Atlassian Compass, and others. These platforms let Snyk automate the collection of essential context, including asset type, ownership, and lifecycle. The application context provides broader access to resources and services in an application. You can use it to: @@ -12,7 +12,7 @@ The application context provides broader access to resources and services in an * Gather relevant information to effectively assess and manage application security vulnerabilities and identify potential risks. * Create a streamlined data flow by working cohesively with assets identified through Snyk Essentials SCM integrations -By leveraging Application context, you can achieve a deeper understanding of your application's security posture. After the integration is set, use the application context that can be leveraged across Snyk to classify repositories, set Asset policies, or filter reports. +By using Application context, you can achieve a deeper understanding of your application's security posture. After the integration is set, use the application context across Snyk to classify repositories, set Asset policies, or filter reports. These are the available integrations that you can set up for the application context: @@ -24,7 +24,7 @@ These are the available integrations that you can set up for the application con * [Datadog Service Catalog](./#datadog-service-catalog) {% hint style="info" %} -The Application Context integrations on this page work in conjunction with assets found through Snyk Essentials SCM integrations. If there is no Snyk Essentials SCM integration configured at the Group level on the Integrations page, then data will not populate from these integrations. +The Application Context integrations on this page work in conjunction with assets found through Snyk Essentials SCM integrations. If there is no Snyk Essentials SCM integration configured at the Group level on the Integrations page, then data does not populate from these integrations. {% endhint %} ## Backstage file for SCM integrations @@ -32,10 +32,10 @@ The Application Context integrations on this page work in conjunction with asset {% hint style="info" %} **Release status** -The ackstage file integration is in Early Access and available with Snyk Enterprise plans. +The Backstage file integration is in Early Access and available with Snyk Enterprise plans. {% endhint %} -Backstage is a service catalog that allows users to add metadata or annotations to their repositories, helping to organize and categorize the available resources for easier navigation and understanding. You can leverage your SCM integration to pull metadata associated with backstage catalog files into Snyk Essentials. +Backstage is a service catalog that lets users add metadata or annotations to their repositories, helping to organize and categorize the available resources for easier navigation and understanding. You can use your SCM integration to pull metadata associated with backstage catalog files into Snyk Essentials. You can use the backstage catalog file for GitHub, GitLab, Azure DevOps, BitBucket Cloud, and BitBucket on-prem SCM integrations. @@ -88,7 +88,7 @@ The ServiceNow CMDB integration is in Early Access and available with Snyk Enter 5. Add the **CMDB field to map Repo URL** - Add the URL of the repository. {% hint style="info" %} -* The data gathered by Snyk from ServiceNow CMDB will be correlated with the Repository Assets. +* Snyk correlates the data gathered from ServiceNow CMDB with the Repository Assets. * The ServiceNow CMDB integration uses basic authentication and suggests enabling the "Web service access only" option for Service Accounts. {% endhint %} @@ -106,7 +106,7 @@ The ServiceNow CMDB integration is in Early Access and available with Snyk Enter * Category: application\_type * Owner: business\_unit * Click **Done**. -* When the connection is established, the status of the ServiceNow CMDB integration is changed to **Connected**. +* When the connection is established, the status of the ServiceNow CMDB integration changes to **Connected**. {% hint style="warning" %} When you set up the catalog attributes, you can customize the name of the attribute but must ensure that the same name is used in the catalog and in the Integration setup. @@ -138,7 +138,7 @@ The Atlassian Compass integration is in Early Access and available with Snyk Ent 4. Add your Atlassian Compass instance **Token**. Navigate to the [Manage API tokens for your Atlassian account](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) page for more details about creating an Atlassian API token. {% hint style="info" %} -The gathered data from Atlassian Compass will be correlated with the Repository Assets. +Snyk correlates the gathered data from Atlassian Compass with the Repository Assets. This feature is available only for the integration with Atlassian Compass. {% endhint %} @@ -159,7 +159,7 @@ This feature is available only for the integration with Atlassian Compass. * **Owner** - the `ownerId` (finding owner name from ownerId). * **Application** - the `typeId` (all component types, Application, Service, Library, and so on receive an ID). 9. Click **Done**. -10. When the connection is established, the status of the Atlassian Compass integration is changed to **Connected**, and Snyk Essentials will start enriching repository assets with the data found in Atlassian Compass. +10. When the connection is established, the status of the Atlassian Compass integration changes to **Connected**, and Snyk Essentials starts enriching repository assets with the data found in Atlassian Compass. {% hint style="warning" %} When you set up the catalog attributes, you must use the specific service-level attributes, for example `attribute.name.` @@ -199,7 +199,7 @@ This integration is focused on [Harness’s](https://developer.harness.io/docs/i * Owner - If you select this metadata, it is mandatory to add the **Owner key**. * Application - If you select this metadata, it is mandatory to add the **Application key**. 8. Click **Done**. -9. When the connection is established, the status of the Harness integration is changed to **Connected**, and Snyk Essentials will start enriching repository assets with the data found in Harness. +9. When the connection is established, the status of the Harness integration changes to **Connected**, and Snyk Essentials starts enriching repository assets with the data found in Harness. {% hint style="warning" %} When you set up the catalog attributes, you can customize the name of the attribute but must ensure that the same name is used in the catalog and in the Integration setup. @@ -234,7 +234,7 @@ The OpsLevel integration is in Early Access and available with Snyk Enterprise p * Owner - Identified with `owner.name` in OpsLevel. * Application - Identified with `product` in OpsLevel. 8. Click **Done**. -9. When the connection is established, the status of the OpsLevel integration is changed to **Connected**, and Snyk Essentials will start enriching repository assets with the data found in OpsLevel. +9. When the connection is established, the status of the OpsLevel integration changes to **Connected**, and Snyk Essentials starts enriching repository assets with the data found in OpsLevel. {% hint style="warning" %} When you set up the catalog attributes, you must use the specific service-level attributes, for example `attribute.name.` @@ -271,7 +271,7 @@ The Datadog Service Catalog integration is in Early Access and available with Sn * Owner - If you select this metadata, it is mandatory to add the **Owner key**. * Application - If you select this metadata, it is mandatory to add the **Application key**. 9. Click **Done**. -10. When the connection is established, the status of the Datadog Service Catalog integration is changed to **Connected**, and Snyk Essentials will start enriching repository assets collected by a Snyk Essentials SCM Integration with the data found in Datadog Service Catalog. +10. When the connection is established, the status of the Datadog Service Catalog integration changes to **Connected**, and Snyk Essentials starts enriching repository assets collected by a Snyk Essentials SCM Integration with the data found in Datadog Service Catalog. {% hint style="warning" %} When you set up the catalog attributes, you can customize the name of the attribute but must ensure that the same name is used in the catalog and in the Integration setup. diff --git a/developer-tools/scm-integrations/application-context-for-scm-integrations/backstage-file-in-asset-inventory-use-case.md b/developer-tools/scm-integrations/application-context-for-scm-integrations/backstage-file-in-asset-inventory-use-case.md index c93c4ec60749..782466dcedb7 100644 --- a/developer-tools/scm-integrations/application-context-for-scm-integrations/backstage-file-in-asset-inventory-use-case.md +++ b/developer-tools/scm-integrations/application-context-for-scm-integrations/backstage-file-in-asset-inventory-use-case.md @@ -13,7 +13,7 @@ Components have several attributes and most of them are optional: * `Metadata.name` (mandatory) - represents the name of the component. * `Metadata.title` (optional) - represents the name of the component. -The backstage data is dynamic and may change over time: +The backstage data is dynamic and can change over time: * If new commits or updates are made to the `catalog-info.yaml` file, then Snyk Essentials updates the asset attribute for that specific repository asset. * If the`catalog-info.yaml` file is removed from the repository, then Snyk Essentials deletes the asset attribute from that specific repository assets. diff --git a/developer-tools/scm-integrations/deployment-recommendations.md b/developer-tools/scm-integrations/deployment-recommendations.md index fe3f679fab62..5f475a29f396 100644 --- a/developer-tools/scm-integrations/deployment-recommendations.md +++ b/developer-tools/scm-integrations/deployment-recommendations.md @@ -1,6 +1,6 @@ # Deployment recommendations -If you try to implement all the SCM integration features at the same time, you risk causing friction in your software development life cycle ([SDLC](https://snyk.io/learn/secure-sdlc/)), which in turn leads to a poor developer experience. +If you try to implement all the SCM integration features at the same time, you risk causing friction in your software development lifecycle ([SDLC](https://snyk.io/learn/secure-sdlc/)), which in turn leads to a poor developer experience. To ensure a smooth rollout of Snyk across your organization, Snyk provides a suggested deployment timeline consisting of deployment stages, configuration steps, and the desired outcome for each stage. @@ -8,7 +8,7 @@ To ensure a smooth rollout of Snyk across your organization, Snyk provides a sug | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

Stage 1:
Set up an Organization-level SCM integration in your first Snyk Organization.

Set up a Group-level SCM integration in Snyk Essentials.

|

See the setup documentation for the applicable SCM integration, and read the User permissions and access scope requirements section to ensure accessibility for the right users in your Snyk hierarchy.

See the setup documentation for the applicable Essentials SCM integration.

|

A configured integration, ready to import Projects.

Essentials will detect your Git repositories so you can track your progress in rolling out Snyk scanning.

| |

Stage 2:
Import all of the relevant projects from your integrated SCM.

|

• Test both public and private repos

• Disable all user notifications

• Disable Snyk PR status checks

• Disable Automatic fix pull requests

• Disable Automatic dependency upgrade pull requests

• Disable Update Dockerfile base images

|

Snyk will scan your imported repositories to detect all supported files and create them as Projects where you can view the vulnerabilities detected.

Disabling these features removes potential blockers for your initial setup and use of Snyk. This way, you have scheduled scans and high visibility of reporting without blocking deployments.

| -|

Stage 3:
Build a fix plan using Snyk prioritization reporting capabilities.

| Learn more about [Snyk Priority Score](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/fix/prioritize-issues-for-fixing/priority-score) and [Snyk Risk Score](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/fix/prioritize-issues-for-fixing/risk-score) to understand how you can leverage these features to help prioritize which issues to fix. | Alignment between Developers and Security on what should be fixed and when to streamline the fix process. | +|

Stage 3:
Build a fix plan using Snyk prioritization reporting capabilities.

| Learn more about [Snyk Priority Score](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/fix/prioritize-issues-for-fixing/priority-score) and [Snyk Risk Score](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/fix/prioritize-issues-for-fixing/risk-score) to understand how you can use these features to help prioritize which issues to fix. | Alignment between Developers and Security on what should be fixed and when to streamline the fix process. | |

Stage 4:
Configure Snyk PR Checks and auto-fix PRs to alert developers to issues in real-time, with available fixes.

| Enable [Snyk PR status checks](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/fix/pull-requests) so developers know whether their PR contains high-severity issues with available fixes. | Make it easy for your developers to see new issues before they are merged into the repository, decreasing the number of new vulnerabilities added and enabling them to make decisions on blocking a merge. | |

Stage 5:
Prevent developers from introducing any new vulnerabilities.

| Enable branch protection in your SCM tool so that PRs with failing Snyk PR status checks cannot be merged. | This change will prevent PRs from being merged into your repository if Snyk detects new vulnerabilities. Over time, you can adjust the sensitivity of the check to include all high or critical severity issues, regardless of whether a fix is available. | |

Stage 6:
Enable Snyk automated features to fix issues and keep dependencies up-to-date to reduce technical security debt.

|

Enable Automatic fix pull requests.
Enable Automatic dependency upgrades.

| Snyk will automatically raise PRs to fix issues with the highest severity. Keeping your dependencies up to date helps to reduce future design headaches and hot fixes, which can be time consuming to research and address. | @@ -27,11 +27,11 @@ For details on these permissions, see [User permissions and access scope require ### Change notification settings -By default, Snyk emails every Org user when a new issue or fix in a Project’s dependencies is found, and provides each user with a weekly update of the security status across the Organization. If you plan to import many Projects to an Organization, to avoid sending multiple email notifications sent to users, consider disabling all the notifications for that Organization. +By default, Snyk emails every Org user when it finds a new issue or fix in a Project’s dependencies, and provides each user with a weekly update of the security status across the Organization. If you plan to import many Projects to an Organization, to avoid sending multiple email notifications to users, consider disabling all the notifications for that Organization. -To customize the emails your Org users receive, go to **Settings** > **Notifications** > **Notification Settings**. The changes you make here will affect all of your Organization’s members, although Org users can override these default settings in their user-level account settings. +To customize the emails your Org users receive, navigate to **Settings** > **Notifications** > **Notification Settings**. The changes you make here affect all of your Organization’s members, although Org users can override these default settings in their user-level account settings. -To disable notifications for all the users in an Org ahead of your import, deselect the appropriate notification boxes. See [Manage notifications](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-hierarchy/manage-notifications) for more details. +To disable notifications for all the users in an Org before your import, deselect the appropriate notification boxes. See [Manage notifications](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-hierarchy/manage-notifications) for more details. ## Stage 2: Import Projects @@ -44,7 +44,7 @@ Navigate to the **Projects** page in the Snyk UI, select **Add projects**, selec After a Project is imported, it is continuously checked for vulnerabilities. {% hint style="info" %} -To confirm that a Project was imported, go to the **Add project** import page for the integration. Imported Projects are indicated by a checkmark next to the repository name. +To confirm that a Project was imported, navigate to the **Add project** import page for the integration. A checkmark next to the repository name indicates imported Projects. {% endhint %} For details, see [Import a Project](https://app.gitbook.com/s/L7HyJj9FsK1W4pNt8Gzl/getting-started-guides/getting-started#import-a-project-to-scan-and-identify-issues). @@ -89,7 +89,7 @@ When you first roll out your SCM integration, Snyk recommends that you start wit ## Stage 4: Enable Blocking PRs -After you have embedded Snyk into your software development life cycle (SDLC), and have built good developer awareness, you can start to apply stricter policies to improve your overall security posture, for example: +After you have embedded Snyk into your software development lifecycle (SDLC), and have built good developer awareness, you can start to apply stricter policies to improve your overall security posture, for example: * Low-priority Projects: you can fail the PR only for new high-severity issues that are fixable. * Medium-priority Projects: fail the PR only for high-severity issues. diff --git a/developer-tools/scm-integrations/group-level-integrations/README.md b/developer-tools/scm-integrations/group-level-integrations/README.md index 4b6ec19a0f59..35d754c34ebd 100644 --- a/developer-tools/scm-integrations/group-level-integrations/README.md +++ b/developer-tools/scm-integrations/group-level-integrations/README.md @@ -1,6 +1,6 @@ # Group-level integrations -Group-level SCM integrations provide broader visibility into all the application assets for a given customer and pull in the additional application context and, or metadata, for example, information on developers, commits, and so on. +Group-level SCM integrations provide broader visibility into all the application assets for a given customer and pull in the additional application context and metadata, for example, information on developers, commits, and so on. At the Group level, you can set up and customize your Snyk Essentials integrations from the **Integrations** page, where the following SCMs are available: @@ -18,7 +18,7 @@ The Integrations page at the Group-level shows all active integrations, includin {% hint style="warning" %} The SCM integrations use an incremental approach to retrieve repositories. This means that when a sync is initiated, it checks the last update time of the repository and only transfers the repositories that have been modified since then. -If there have been changes to the scope of the user or PAT used for the integration, any repositories that are newly within scope will only be identified after either a change to trigger the incremental collection or a change to the integration configuration itself. +If there have been changes to the scope of the user or PAT used for the integration, Snyk identifies any repositories that are newly in scope only after either a change to trigger the incremental collection or a change to the integration configuration itself. {% endhint %} The following supported Snyk data are automatically synced: @@ -28,12 +28,12 @@ The following supported Snyk data are automatically synced: * Snyk IaC * Snyk Container -Each connected integration enables you to: +Each connected integration lets you: * Pause data syncing * Modify integration profiles and configurations * Delete the integration -* Check when the integration was last synced and when the next sync is scheduled. +* Check when the integration was last synced and when the next sync is scheduled See the [Integration syncing time](../../integrations/integrate-with-snyk.md#integrations-syncing-time) for more details about the time required to sync for each action. @@ -43,7 +43,7 @@ To configure a Group-level integration, you must be a Group Admin or have a cust ### Wildcard SCM integration -The wildcard integration allows you to use a special character to detect and integrate multiple SCM organizations simultaneously. +The wildcard integration lets you use a special character to detect and integrate multiple SCM organizations simultaneously. {% hint style="info" %} The wildcard integration applies to the GitHub integration and offers support when you set it up using [Snyk Broker](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-broker/using-snyk-essentials-with-snyk-broker). @@ -53,12 +53,12 @@ You can use the wildcards while setting up your integration using the **Integrat * Navigate to **Integrations**. * Select the **SCM** tag and search for GitHub or Azure DevOps. -* Click the **Add** button. +* Click **Add**. * In the **Organizations** field, add the Organization details by using the `*` symbol. For example, using `*snyk` integrates all SCM Organizations that have Snyk in their name. -* All the Organizations that match with the wildcard, `*` symbol will be added. +* Snyk adds all the Organizations that match the wildcard `*` symbol. {% hint style="info" %} -The wildcard, `*` symbol is considered a living command and will be applied every time you are rescanning your repositories. +The wildcard `*` symbol is considered a living command and applies every time you rescan your repositories. {% endhint %} ### Snyk Essentials integrations ecosystem diff --git a/developer-tools/scm-integrations/group-level-integrations/azure-devops-for-snyk-essentials.md b/developer-tools/scm-integrations/group-level-integrations/azure-devops-for-snyk-essentials.md index e7fda2d8232e..1310d01c9f17 100644 --- a/developer-tools/scm-integrations/group-level-integrations/azure-devops-for-snyk-essentials.md +++ b/developer-tools/scm-integrations/group-level-integrations/azure-devops-for-snyk-essentials.md @@ -29,7 +29,7 @@ The following PAT token permissions requirements are for Snyk Essentials integra ## Generate a Personal access token from your Azure DevOps settings {% hint style="warning" %} -The user account that owns the PAT needs `Basic` access level on the Azure organisation. +The user account that owns the PAT needs `Basic` access level on the Azure organization. {% endhint %} 1. Open Azure DevOps and click the **Settings** menu for your profile. diff --git a/developer-tools/scm-integrations/group-level-integrations/github-for-snyk-essentials.md b/developer-tools/scm-integrations/group-level-integrations/github-for-snyk-essentials.md index 781bc49191ee..ae6f7db25de6 100644 --- a/developer-tools/scm-integrations/group-level-integrations/github-for-snyk-essentials.md +++ b/developer-tools/scm-integrations/group-level-integrations/github-for-snyk-essentials.md @@ -43,17 +43,17 @@ If you want to pull data from both organization and personal repositories, then ## Generate a Personal access token from your GitHub settings -1. Open GitHub and click the Settings menu for your profile. -2. Select Developer settings from the left sidebar. -3. Select Personal access tokens and then Tokens (classic). -4. Click Generate new token and, from the dropdown, select Generate new token (classic). -5. Add a description for your token in the Note field. +1. Open GitHub and click the **Settings** menu for your profile. +2. Select **Developer settings**. +3. Select **Personal access tokens** and then **Tokens (classic)**. +4. Click **Generate new token** and, from the dropdown, select **Generate new token (classic)**. +5. Add a description for your token in the **Note** field. 6. Select the required permissions: * `repo` * `read:org` * `read:user` * `user:email`. -7. Click Generate token. +7. Click **Generate token**. 8. Copy and store the displayed key. {% hint style="info" %} @@ -66,4 +66,4 @@ You can use the[ GitHub REST API](https://docs.github.com/en/rest?apiVersion=202 You can use as the host Address the IP/URL of the GitHub server. The default URL is [`https://api.github.com`](https://api.github.com). -The user associated with the token needs to have write permissions on relevant repositories to collect a breakdown of scan issues. +The user associated with the token must have write permissions on relevant repositories to collect a breakdown of scan issues. diff --git a/developer-tools/scm-integrations/group-level-integrations/gitlab-for-snyk-essentials.md b/developer-tools/scm-integrations/group-level-integrations/gitlab-for-snyk-essentials.md index 2ffc10cdcee5..7b2323719750 100644 --- a/developer-tools/scm-integrations/group-level-integrations/gitlab-for-snyk-essentials.md +++ b/developer-tools/scm-integrations/group-level-integrations/gitlab-for-snyk-essentials.md @@ -20,20 +20,20 @@ To configure a Group-level integration, you must be a Group Admin or have a cust 3. Broker Token (`mandatory`): Create and add your Broker token if you use Snyk Broker. * Generate your Broker token by following the instructions from the [Obtain your Broker token for Snyk Broker](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-broker/classic-broker/prepare-snyk-broker-for-deployment/obtain-the-tokens-required-to-set-up-snyk-broker) page. * Copy and paste the Broker token on the integration setup menu from the Integration Hub. -4. Pull personal repositories (`optional`): Enable the option If you only want to pull the repositories you own. +4. Pull personal repositories (`optional`): Enable the option if you only want to pull the repositories you own. 5. Add Backstage Catalog (`optional`): If you want to add your Backstage catalog, follow the instructions from the [Backstage file for SCM Integrations](../application-context-for-scm-integrations/) page. ## Generate a [Personal access token](../organization-level-integrations/gitlab.md#gitlab-access-tokens) from your GitLab settings 1. Navigate to your GitLab profile. -2. Select Edit Profile. -3. On the left sidebar, select Access Token. -4. Select Add New Token. +2. Select **Edit Profile**. +3. Select **Access Token**. +4. Select **Add New Token**. 5. Enter a name and expiry date for the token. 6. Ensure to enable this permission: * `read_api` - Grants read access to the API, including all groups and projects, the container registry, and the package registry. * `read_repository` - Grants read-only access to repositories on private projects using Git-over-HTTP or the Repository Files API. -7. Click the Create personal access token button. +7. Click **Create personal access token**. 8. Copy and store the displayed key. ## API version diff --git a/developer-tools/scm-integrations/organization-level-integrations/README.md b/developer-tools/scm-integrations/organization-level-integrations/README.md index caf2e95ec461..f128e0b0e166 100644 --- a/developer-tools/scm-integrations/organization-level-integrations/README.md +++ b/developer-tools/scm-integrations/organization-level-integrations/README.md @@ -1,8 +1,8 @@ # Organization-level integrations -Snyk provides seamless integrations with various source control management systems such as GitHub, GitLab, Bitbucket, and Azure Repos at the Organizational level. These integrations enable you to automatically scan for vulnerabilities and receive actionable insights to enhance the security of your repositories. By integrating at this level, you can ensure comprehensive protection for all your Projects within the Organization. +Snyk provides integrations with various source control management systems such as GitHub, GitLab, Bitbucket, and Azure Repos at the Organization level. These integrations let you automatically scan for vulnerabilities and receive actionable insights to enhance the security of your repositories. By integrating at this level, you can protect all your Projects in the Organization. -Snyk can integrate with the following SCMs at the Organization-level to help you track, monitor, and fix the issues and vulnerabilities in your code: +Snyk can integrate with the following SCMs at the Organization level to help you track, monitor, and fix the issues and vulnerabilities in your code: * [GitHub](github.md) * [GitHub Enterprise](github-enterprise.md) diff --git a/developer-tools/scm-integrations/organization-level-integrations/azure-repositories-tfs.md b/developer-tools/scm-integrations/organization-level-integrations/azure-repositories-tfs.md index 5868be1ddad1..0a1a1e0085d8 100644 --- a/developer-tools/scm-integrations/organization-level-integrations/azure-repositories-tfs.md +++ b/developer-tools/scm-integrations/organization-level-integrations/azure-repositories-tfs.md @@ -4,7 +4,7 @@ **Feature availability**\ Integration with Azure DevOps Server 2020 and above, also known as TFS, is available only with Enterprise plans. For more information, see [plans and pricing](https://snyk.io/plans/). -Snyk supports only Git. Snyk does not currently support integration with Team Foundation Version Control (TFVC). +Snyk supports only Git. Snyk does not support integration with Team Foundation Version Control (TFVC). {% endhint %} ### Prerequisites for Azure Repositories (TFS) integration @@ -46,7 +46,7 @@ Generate and copy a unique PAT to use for Snyk. For more information on the PAT 1. Log in to [your Snyk account](https://app.snyk.io) and navigate to **Integrations**. 2. On the **Azure Repos** tile, click the settings icon to open **Organization Settings** > **Integrations** > **Azure Repos** > **Account credentials**. -3. Pay special attention to the instructions given on the **Account Credentials** page. Depending on your plan, you may need to enter just the Azure DevOps Organization, or you may need to enter the entire URL. +3. Pay special attention to the instructions given on the **Account Credentials** page. Depending on your plan, you may need to enter only the Azure DevOps Organization, or you may need to enter the entire URL. * **Set your organization**: Enter the slug for your Organization only.\ For example, enter `your-azure-devops-org` * **Set your host**: enter the entire url.\ @@ -57,7 +57,7 @@ Generate and copy a unique PAT to use for Snyk. For more information on the PAT Snyk tests the connection values and the page reloads, displaying the Azure Repos integration information. A message to confirm that the details were updated appears at the top of the screen. {% hint style="info" %} -If the connection to Azure fails, a notification will appear under the **Azure Repos** card title. +If the connection to Azure fails, a notification appears under the **Azure Repos** card title. {% endhint %} ### Add Projects to Snyk for Azure Repos diff --git a/developer-tools/scm-integrations/organization-level-integrations/bitbucket-cloud-app.md b/developer-tools/scm-integrations/organization-level-integrations/bitbucket-cloud-app.md index 45c9d6dff4bf..a66d844bea5b 100644 --- a/developer-tools/scm-integrations/organization-level-integrations/bitbucket-cloud-app.md +++ b/developer-tools/scm-integrations/organization-level-integrations/bitbucket-cloud-app.md @@ -1,13 +1,13 @@ # Bitbucket Cloud App -The Bitbucket Cloud App is positioned to be the default Bitbucket Cloud integration +The Bitbucket Cloud App is the default Bitbucket Cloud integration. -The Bitbucket Cloud App integration lets you connect your Snyk Organization to a Bitbucket Cloud Workspace and get all Snyk's core SCM integration features: +The Bitbucket Cloud App integration lets you connect your Snyk Organization to a Bitbucket Cloud Workspace and get all the core SCM integration features in Snyk: * Continuously perform security scanning across all the integrated repositories * Detect vulnerabilities in your Open Source components * Provide automated fixes and upgrades -* Provides developer teams with first-party visibility for security issues directly in the Bitbucket interface +* Provide developer teams with first-party visibility for security issues directly in the Bitbucket interface {% hint style="info" %} Snyk recommends using the Bitbucket Cloud App integration for smoother integration and to ensure long-term support. @@ -17,7 +17,7 @@ If you are using the [Bitbucket Cloud API token integration](bitbucket-cloud.md) ### Setting up a Bitbucket Cloud App -To give Snyk access to your Bitbucket account, you need to install the Snyk App on your Bitbucket Cloud workspace. +To give Snyk access to your Bitbucket account, you must install the Snyk App on your Bitbucket Cloud workspace. {% hint style="info" %} To install the Snyk App on your Bitbucket Cloud workspace, you must have **Admin** permissions for the Workspace in Bitbucket. @@ -126,7 +126,7 @@ The first-party interface currently supports only the [Snyk Open Source](https:/ You can **associate a first-party interface with a different Snyk account or Organization**. -During the first-time Bitbucket Cloud App onboarding process, the first-party interface is associated with a specific Snyk Organization. This is the Snyk Organization to which Bitbucket users will import repositories and for which they will view Snyk issues. +During the first-time Bitbucket Cloud App onboarding process, the first-party interface is associated with a specific Snyk Organization. This is the Snyk Organization to which Bitbucket users import repositories and for which they view Snyk issues. To change the Snyk Organization after onboarding, go to the workspace settings > **Security for Bitbucket Cloud** > **Integration Settings** and click **Connect via a different Snyk user/organization**. @@ -154,5 +154,5 @@ To disable this integration, in **Organization settings** > **Integrations** > * 2. Scroll to the **Disconnect** section and click **Remove** to remove the integration. {% hint style="info" %} -Disconnecting the integration from the Snyk side does not uninstall the app from your workspace in Bitbucket Cloud. To uninstall the Bitbucket app, navigate to your workspace settings in Bitbucket.org --> Installed Apps and remove the Snyk Security for Bitbucket Cloud app. +Disconnecting the integration from the Snyk side does not uninstall the app from your workspace in Bitbucket Cloud. To uninstall the Bitbucket app, navigate to your workspace settings in Bitbucket.org > **Installed Apps** and remove the Snyk Security for Bitbucket Cloud app. {% endhint %} diff --git a/developer-tools/scm-integrations/organization-level-integrations/bitbucket-cloud.md b/developer-tools/scm-integrations/organization-level-integrations/bitbucket-cloud.md index b2e18f02fc1e..b8592360eb18 100644 --- a/developer-tools/scm-integrations/organization-level-integrations/bitbucket-cloud.md +++ b/developer-tools/scm-integrations/organization-level-integrations/bitbucket-cloud.md @@ -13,7 +13,7 @@ The Bitbucket Cloud API token integration lets you: ### How to set up the Bitbucket Cloud Integration {% hint style="info" %} -Admin permissions are required; however, Snyk's access is ultimately limited by the [permissions assigned to the API Token](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/).\ +Admin permissions are required. However, Snyk access is ultimately limited by the [permissions assigned to the API Token](https://support.atlassian.com/bitbucket-cloud/docs/create-an-api-token/).\ \ To improve security, the use of app passwords in Bitbucket Cloud is transitioning to API tokens. Existing integrations that use app passwords will continue to function temporarily until 9 June 2026.\ To ensure continued support and functionality, update your Bitbucket Cloud integration in Snyk to use an API token. @@ -38,11 +38,11 @@ After you connect Snyk to your Bitbucket Cloud account, you can select repositor After you add the selected repositories, Snyk scans them for dependency files in the entire directory tree, that is, `package.json`, `pom.xml`, and so on, and imports them to Snyk as Projects. -The imported projects appear on your **Projects** page and are continuously checked for vulnerabilities. +The imported Projects appear on your **Projects** page and are continuously checked for vulnerabilities. ### Bitbucket integration features -After the integration is in place, you will be able to use capabilities such as: +After the integration is in place, you can use capabilities such as: * [Project-level security reports](bitbucket-cloud.md#project-level-security-reports) * [Project monitoring and automatic fix pull requests](bitbucket-cloud.md#project-monitoring-and-automatic-fix-pull-requests) diff --git a/developer-tools/scm-integrations/organization-level-integrations/bitbucket-data-center-server.md b/developer-tools/scm-integrations/organization-level-integrations/bitbucket-data-center-server.md index f2251c356442..562593e5df87 100644 --- a/developer-tools/scm-integrations/organization-level-integrations/bitbucket-data-center-server.md +++ b/developer-tools/scm-integrations/organization-level-integrations/bitbucket-data-center-server.md @@ -1,6 +1,6 @@ # Bitbucket Data Center/Server -The Bitbucket Data Center/Server integration allows you to continuously perform security scanning across all the integrated repositories, detect vulnerabilities in your open-source components, and use automated fixing. This integration supports Bitbucket Data Center/Server versions 4.0 and above. +The Bitbucket Data Center/Server integration lets you continuously perform security scanning across all the integrated repositories, detect vulnerabilities in your open-source components, and use automated fixing. This integration supports Bitbucket Data Center/Server versions 4.0 and above. For a quick reference, see the [Snyk and Bitbucket best practices cheat sheet](https://snyk.io/blog/snyk-bitbucket-best-practices-cheat-sheet/) on the Snyk blog. @@ -8,7 +8,7 @@ For a quick reference, see the [Snyk and Bitbucket best practices cheat sheet](h 1. To give Snyk access to your Bitbucket DC/Server account, set up a dedicated service account in Bitbucket DC/Server with admin permissions.\ Visit [Bitbucket Server documentation ](https://confluence.atlassian.com/bitbucketserver/users-and-groups-776640439.html#Usersandgroups-Creatingauser)to learn more about creating users.\ - Ensure the newly-created user has **Admin** permissions to all the repositories you need to monitor with Snyk. + Ensure the newly created user has **Admin** permissions to all the repositories you need to monitor with Snyk. 2. In Snyk, navigate to the **Integrations** page and click on the **Bitbucket Server** card. 3. Enter your Bitbucket DC/Server URL and the username and password for the service account you created. Alternatively, you can create a [personal access token](https://confluence.atlassian.com/bitbucketserver075/personal-access-tokens-1018784848.html) and use it instead of a password. 1. If your Bitbucket DC/Server instance has Basic Auth disabled, you must use a personal access token. @@ -24,7 +24,7 @@ To select the repositories for Snyk to monitor: 1. Click **Add your Bitbucket Server repositories to Snyk** to start importing repositories to Snyk. 2. When prompted, select the repositories to import to Snyk and click **Add selected repositories**. -After they are added, Snyk scans the selected repositories for dependency files in the entire directory tree, (that is, `package.json`, `pom.xml`, and so on) and imports them to Snyk as projects.\ +After they are added, Snyk scans the selected repositories for dependency files in the entire directory tree, (that is, `package.json`, `pom.xml`, and so on) and imports them to Snyk as Projects.\ \ The imported Projects appear on your Snyk **Projects** page and are continuously checked for vulnerabilities. @@ -106,15 +106,15 @@ Snyk performs all the Bitbucket DC/Server operations on behalf of the integrated For Snyk to perform the required operations on monitored repositories, such as reading manifest files on a frequent basis and opening fix or upgrade PRs, the integrated Bitbucket DC/Server service account needs **Admin** permissions on the imported repositories. -**Admin** permissions are also needed to set secure webhooks. Snyk relies on webhooks to perform a variety of tasks, from PR checks, to commit tests upon merge events, and upcoming auto imports. To ensure the events come from your system and your system only, with no tampering or spoofing, we secure the webhooks using the recommended method shared by the systems we are connecting to. For Bitbucket Server, please see [this link](https://confluence.atlassian.com/bitbucketserver/manage-webhooks-938025878.html#Managewebhooks-webhooksecretsSecuringyourwebhook).\ -To do this, a secret token is generated for each secure webhook we create. Snyk setting the webhooks resolves scalability constraints, eliminates token leakage, and reduces the integration workload for you. +**Admin** permissions are also needed to set secure webhooks. Snyk relies on webhooks to perform a variety of tasks, from PR checks, to commit tests upon merge events, and upcoming auto imports. To ensure the events come from your system and your system only, with no tampering or spoofing, Snyk secures the webhooks using the recommended method shared by the systems Snyk connects to. For Bitbucket Server, see the [Manage webhooks](https://confluence.atlassian.com/bitbucketserver/manage-webhooks-938025878.html#Managewebhooks-webhooksecretsSecuringyourwebhook) documentation.\ +To do this, Snyk generates a secret token for each secure webhook it creates. Snyk setting the webhooks resolves scalability constraints, eliminates token leakage, and reduces the integration workload for you. For detailed information on the permission scopes required, see [Bitbucket permission requirements](../user-permissions-and-access-scopes.md#bitbucket-cloud-and-bitbucket-data-center-server-scopes). ### How to disconnect the Bitbucket Data Center/Server integration {% hint style="warning" %} -When you disconnect Snyk from your Bitbucket repository projects, your credentials are removed from Snyk, and any integration-specific projects that Snyk is monitoring are deactivated in Snyk.\ +When you disconnect Snyk from your Bitbucket repository Projects, your credentials are removed from Snyk, and any integration-specific Projects that Snyk is monitoring are deactivated in Snyk.\ To re-enable this integration later, you must re-enter your credentials and activate your Projects. {% endhint %} diff --git a/developer-tools/scm-integrations/organization-level-integrations/github-cloud-app.md b/developer-tools/scm-integrations/organization-level-integrations/github-cloud-app.md index a3016248eae6..b46b2972effb 100644 --- a/developer-tools/scm-integrations/organization-level-integrations/github-cloud-app.md +++ b/developer-tools/scm-integrations/organization-level-integrations/github-cloud-app.md @@ -29,7 +29,7 @@ The GitHub Cloud App improves on many features as compared to the current GitHub * RBAC (Role-Based Access Control) Compliance: With the GitHub Cloud App, the access control mechanism is decoupled from individual user accounts. Instead, it is associated with the app entity itself. This separation allows for better management and enforcement of RBAC policies, as access control is handled at the application level rather than being tied to individual user accounts. * Granular access control: The GitHub Cloud App allows for fine-grained control over access permissions at the repository level. -* Increased API rate limit: The GitHub Cloud App provides higher rate limits, allowing Snyk to make a larger number of API requests. This increased limit will assist in handling large-scale use cases, such as monorepos with a large number of Projects, GitHub organizations with a large number of repositories, and more. +* Increased API rate limit: The GitHub Cloud App provides higher rate limits, allowing Snyk to make a larger number of API requests. This increased limit helps handle large-scale use cases, such as monorepos with a large number of Projects, GitHub organizations with a large number of repositories, and more. * Enabler for an enhanced developer experience: * Pull request checks: The Checks tab experience in GitHub is exclusively accessible through the GitHub Cloud App, enabling an SCM native experience as part of potential future PR check workflow improvements. * Fix and upgrade pull requests: Pull requests initiated by Snyk are performed directly by the GitHub App rather than a service account. @@ -70,7 +70,7 @@ Specify whether you wish to install the app in all of the repositories belonging
Install and Authorize settings for the GitHub organization you are installing the GitHub Cloud App into

Install and authorize settings for the GitHub organization you are installing the GitHub Cloud App into

{% hint style="warning" %} -The GitHub Cloud App will lose access to Snyk if it is uninstalled from the GitHub organization or if the repositories to which the app instance has access are edited. +The GitHub Cloud App loses access to Snyk if it is uninstalled from the GitHub organization or if the repositories to which the app instance has access are edited. {% endhint %} ## How to migrate to the GitHub Cloud App diff --git a/developer-tools/scm-integrations/organization-level-integrations/github-enterprise.md b/developer-tools/scm-integrations/organization-level-integrations/github-enterprise.md index 64cf9a3b5c93..bce9af49805a 100644 --- a/developer-tools/scm-integrations/organization-level-integrations/github-enterprise.md +++ b/developer-tools/scm-integrations/organization-level-integrations/github-enterprise.md @@ -50,7 +50,7 @@ See [GitHub and GitHub Enterprise permissions requirements](../user-permissions- 1. In Snyk, navigate to the **Integrations** page and click the **GitHub Enterprise** card. 2. Enter your GitHub Enterprise URL and the personal access token (PAT) for the service account you created, and **Save** your changes. After Snyk has successfully connected to the GitHub instance, the list of available repositories displays for your selection. 3. If your GitHub Enterprise organization enforces SAML/SSO, select **Configure SSO** next to the PAT in GitHub after the PAT has been created.\ - Occasionally, SSO is enforced in your GitHub Enterprise organizations after a PAT and Integration are configured. If this happens, any Projects that have already been imported show in Snyk, but retests, PR Checks, and so on, will not be performed. To fix this, check the **Configure SSO** settings to ensure the GitHub Enterprise organization is **Authorized**.\ + Occasionally, SSO is enforced in your GitHub Enterprise organizations after a PAT and Integration are configured. If this happens, any Projects that have already been imported show in Snyk, but Snyk does not perform retests, PR Checks, and so on. To fix this, check the **Configure SSO** settings to ensure the GitHub Enterprise organization is **Authorized**.\ If the organization is showing as **Authorized**, but the issue still persists, try de-authorizing the organization and then re-authorizing. {% hint style="info" %} @@ -60,7 +60,7 @@ Ensure that there are no trailing characters such as `/` following the url. An i {% endhint %} {% hint style="warning" %} -If the PAT token changes or expires in GitHub, the integration with Snyk will not function. To resolve this, update the token in the Snyk **GitHub Enterprise Integration settings**. +If the PAT token changes or expires in GitHub, the integration with Snyk does not function. To resolve this, update the token in the Snyk **GitHub Enterprise Integration settings**. {% endhint %} #### How to import GitHub repositories @@ -123,7 +123,7 @@ The Auto-assign PRs feature is supported only for private repositories. Snyk can automatically assign the pull requests it creates to ensure that they are handled by the right team members. -Auto-assign for PRs can be enabled for the GitHub and GitHub Enterprise integration and all Projects imported via GitHub, or on a per-Project basis. +Auto-assign for PRs can be enabled for the GitHub and GitHub Enterprise integration and all Projects imported through GitHub, or on a per-Project basis. Users can either be manually specified, and all will be assigned, or automatically selected based on the last commit user account. @@ -164,9 +164,9 @@ Disconnecting the Snyk GitHub Enterprise integration halts all scans for importe
Confirm disconnecting from GitHub Enterprise

Confirm disconnecting from GitHub Enterprise

-After GitHub Enterprise is disconnected, imported Snyk Projects will be set to inactive, and you will no longer get alerts, pull requests, or Snyk tests on pull requests. +After GitHub Enterprise is disconnected, Snyk sets imported Projects to inactive, and you no longer get alerts, pull requests, or Snyk tests on pull requests. -You can re-connect anytime; however, re-initiating GitHub Enterprise projects for monitoring requires setting up the integration again. +You can re-connect anytime. However, re-initiating GitHub Enterprise Projects for monitoring requires setting up the integration again. 4. Broker Token (`mandatory`): Create and add your Broker token if you use Snyk Broker. * Generate your Broker token by following the instructions from the [Obtain your Broker token for Snyk Broker](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-broker/classic-broker/prepare-snyk-broker-for-deployment/obtain-the-tokens-required-to-set-up-snyk-broker) page. diff --git a/developer-tools/scm-integrations/organization-level-integrations/github-read-only-projects.md b/developer-tools/scm-integrations/organization-level-integrations/github-read-only-projects.md index 178e4f3fc539..371ee8b9dc77 100644 --- a/developer-tools/scm-integrations/organization-level-integrations/github-read-only-projects.md +++ b/developer-tools/scm-integrations/organization-level-integrations/github-read-only-projects.md @@ -2,11 +2,11 @@ ### How GitHub Read-only Projects work -Snyk offers GitHub Read-only Projects, providing the ability to monitor a public GitHub repository that is not owned by your Organization. +Snyk offers GitHub Read-only Projects, which let you monitor a public GitHub repository that your Organization does not own. Adding a read-only Project lets you track the vulnerabilities in a Project you are considering using as a dependency, a Project you are already using as a stand-alone independent tool within your business, or any other public repository where you do not need to actively prevent or fix issues using Snyk. -The repository is tested daily using your Organization's GitHub credentials. These automated tests are not counted as part of the test limits of your Snyk plan. +Snyk tests the repository daily using your Organization's GitHub credentials. These automated tests do not count as part of the test limits of your Snyk plan. Unlike Projects imported through the Snyk GitHub integration, Projects that are imported or monitored with the read-only status cannot do the following: @@ -21,8 +21,8 @@ Unlike Projects imported through the Snyk GitHub integration, Projects that are Import a read-only Project using the **Add project** > **Monitor public GitHub repos** menu in the **Dashboard** and **Projects** tabs, or by going to [Monitor public GitHub repositories](https://app.snyk.io/add/github-readonly). 1. Enter a public repository to monitor, following the format `owner/repository.` -2. When you have entered a valid repository name, click **+ Add repo**.\ - The repository is quickly tested for a supported manifest file. -3. Enter the public repositories you want to monitor and select **Import N repository/ies**. +2. After you enter a valid repository name, click **+ Add repo**.\ + Snyk tests the repository for a supported manifest file. +3. Enter the public repositories you want to monitor and select **Import N repositories**.
Add repo and Import repository or repositories

Add repo and Import repository or repositories

diff --git a/developer-tools/scm-integrations/organization-level-integrations/github-server-app.md b/developer-tools/scm-integrations/organization-level-integrations/github-server-app.md index 54d2ab0cc61f..8b61613d850c 100644 --- a/developer-tools/scm-integrations/organization-level-integrations/github-server-app.md +++ b/developer-tools/scm-integrations/organization-level-integrations/github-server-app.md @@ -20,11 +20,11 @@ This feature supports self-hosted instances of GitHub and Snyk [Universal Broker The Snyk GitHub Server App improves on many features compared to the Snyk GitHub Enterprise integration, including role-based granular access control, increased API rate limits, and the creation of an entry point for expanded and enhanced developer experiences. * RBAC (Role-Based Access Control) Compliance: - * With the GitHub Server App, the access control mechanism is decoupled from individual user accounts. Instead, it is associated with the app entity itself. This separation allows for better management and enforcement of RBAC policies, as access control is handled at the application level rather than being tied to individual user accounts. + * With the GitHub Server App, the access control mechanism is decoupled from individual user accounts. Instead, it is associated with the app entity itself. This separation allows better management and enforcement of RBAC policies, because access control is handled at the application level rather than being tied to individual user accounts. * Granular access control: - * The GitHub Server App allows for fine-grained control over access permissions at the repository level. + * The GitHub Server App provides fine-grained control over access permissions at the repository level. * Increased API rate limit: - * The GitHub Server App provides higher rate limits, allowing Snyk to make a larger number of API requests. This increased limit will assist in handling large-scale use cases, such as monorepos with a large number of Projects, GitHub organizations with a large number of repositories, and more. + * The GitHub Server App provides higher rate limits, letting Snyk make a larger number of API requests. This increased limit helps in handling large-scale use cases, such as monorepos with a large number of Projects, GitHub organizations with a large number of repositories, and more. * Enabler for an enhanced developer experience: * Pull request checks: The Checks tab experience in GitHub is exclusively accessible through the GitHub Cloud App, enabling an SCM native experience as part of potential future PR check workflow improvements. * Fix and upgrade pull requests: Pull requests initiated by Snyk are performed directly by the GitHub App rather than a service account. @@ -38,11 +38,11 @@ When setting up the GitHub Server App, you can implement only one of the followi * One GitHub organization connected to multiple Snyk Organizations {% endhint %} -In the Snyk UI navigate to the integrations page and select the **GitHub Server App** tile. +In the Snyk Web UI, navigate to the integrations page and select the **GitHub Server App** tile.

GitHub Server App tile highlighted in the Snyk UI

-Clicking on the tile opens a modal that allows you to enter the URL of your GitHub Server. Entering the URL of your GitHub Server instance will redirect you to your GitHub instance, where you will be able to create the app. +Clicking the tile opens a modal where you can enter the URL of your GitHub Server. Entering the URL of your GitHub Server instance redirects you to your GitHub instance, where you can create the app.

Integration model prompting you for your GitHub Server's URL

@@ -65,7 +65,7 @@ Specify whether you wish to install the app in all or a select number of the rep

Install and authorize settings for the GitHub organization you are installing the GitHub Cloud App into

{% hint style="danger" %} -The GitHub Server App will lose access to Snyk if it is uninstalled from the GitHub organization. If this happens, you can create a fresh integration in Snyk to regain access. +The GitHub Server App loses access to Snyk if it is uninstalled from the GitHub organization. If this happens, you can create a fresh integration in Snyk to regain access. {% endhint %} ### Migrate from an existing GitHub Enterprise integration @@ -75,7 +75,7 @@ If you are an Enterprise plan customer, you can migrate Snyk Targets to the GitH ### How to disconnect a non-brokered GitHub Server App integration {% hint style="warning" %} -Disconnecting the Snyk GitHub Server App integration halts all scans for imported repositories. PR checks cannot be executed and Projects are deactivated in the Snyk Web UI. +Disconnecting the Snyk GitHub Server App integration halts all scans for imported repositories. Snyk cannot run PR checks, and Projects are deactivated in the Snyk Web UI. Note that the GitHub App will remain listed on your GitHub organization until removed manually. {% endhint %} @@ -86,20 +86,20 @@ Note that the GitHub App will remain listed on your GitHub organization until re

Confirm disconnecting from GitHub Server App

-After the integration is disconnected, imported Snyk Projects will be set to inactive, and you will no longer get alerts, pull requests, or Snyk tests on pull requests. +After the integration is disconnected, imported Snyk Projects are set to inactive, and you no longer get alerts, pull requests, or Snyk tests on pull requests. -You can re-connect anytime; however, re-initiating the Snyk Projects for monitoring requires setting up the integration again. +You can re-connect anytime. However, re-initiating the Snyk Projects for monitoring requires setting up the integration again. ### How to disconnect a brokered GitHub Server App integration {% hint style="warning" %} -Disconnecting the Snyk GitHub Server App integration halts all scans for imported repositories. PR checks cannot be executed and Projects are deactivated in the Snyk Web UI. +Disconnecting the Snyk GitHub Server App integration halts all scans for imported repositories. Snyk cannot run PR checks, and Projects are deactivated in the Snyk Web UI. Note that the GitHub App will remain listed on your GitHub organization until the app is removed manually. {% endhint %} Run `snyk-broker-config workflows connections disconnect` and select the connection you want to disconnect. -After the integration is disconnected, imported Snyk Projects will be set to inactive, and you will no longer get alerts, pull requests, or Snyk tests on pull requests. +After the integration is disconnected, imported Snyk Projects are set to inactive, and you no longer get alerts, pull requests, or Snyk tests on pull requests. -You can re-connect anytime; however, re-initiating the Snyk Projects for monitoring requires setting up the integration again. +You can re-connect anytime. However, re-initiating the Snyk Projects for monitoring requires setting up the integration again. diff --git a/developer-tools/scm-integrations/organization-level-integrations/github.md b/developer-tools/scm-integrations/organization-level-integrations/github.md index 763b414fbde7..d3deb68b32bc 100644 --- a/developer-tools/scm-integrations/organization-level-integrations/github.md +++ b/developer-tools/scm-integrations/organization-level-integrations/github.md @@ -9,13 +9,13 @@ ### Known limitations of the GitHub integration -You cannot use the GitHub integration with a Snyk [Service Account](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/service-accounts/service-accounts), as the GitHub integration is associated with your user account, not with the Snyk Organization. +You cannot use the GitHub integration with a Snyk [Service Account](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/service-accounts/service-accounts), because the GitHub integration is associated with your user account, not with the Snyk Organization. Use the [GitHub Enterprise integration](github-enterprise.md) to import public and private Projects using the API with a Snyk Service Account. ### GitHub integration features -The GitHub integration allows you to: +The GitHub integration lets you: * Continuously perform security scanning across all the integrated repositories * Detect vulnerabilities in your open-source components @@ -33,9 +33,9 @@ To connect your GitHub repositories to Snyk for scanning, you need to set up the ### GitHub integration settings -To see all settings for your GitHub integration, go to the GitHub Integration settings page, then navigate to Organization **Settings**, and select **GitHub** in the **Integrations** section: +To see all settings for your GitHub integration, navigate to the GitHub Integration settings page, then navigate to Organization **Settings**, and select **GitHub** in the **Integrations** section: -You can then scroll down to the section required, and set the options accordingly: +You can then scroll to the section required, and set the options accordingly: * [General settings](github.md#general-github-integration-settings) * Pull requests: @@ -62,7 +62,7 @@ Select **General** to view general settings: ### GitHub integration features -After you have connected GitHub to Snyk, you can use: +After you connect GitHub to Snyk, you can use: * [Project-level security reports](github.md#project-level-security-reports) * [Project monitoring and automatic fix pull requests](github.md#project-monitoring-and-automatic-fix-pull-requests) @@ -85,7 +85,7 @@ This example shows a Project-level security report. #### Project monitoring and automatic fix pull requests -Snyk scans your Projects on either a daily or a weekly basis. When new vulnerabilities are found, Snyk notifies you via email and opens automated pull requests with fixes for your repositories. +Snyk scans your Projects on either a daily or a weekly basis. When Snyk finds new vulnerabilities, it notifies you by email and opens automated pull requests with fixes for your repositories. The example that follows shows a fix pull request opened by Snyk. @@ -105,11 +105,11 @@ Scroll down to the **Automatic fix PRs** section and set the options. For defini For availability with Snyk Broker, see the [Commit signing](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-broker/snyk-broker-commit-signing) page in the Broker docs. {% endhint %} -All the commits in Snyk's pull requests are done by `snyk-bot@snyk.io` (a verified user on GitHub), and signed with a PGP key. All Snyk pull requests appear as verified on GitHub, thus providing your developers with the confidence that the fix and upgrade pull requests are generated by a trusted source. +All the commits in Snyk pull requests are done by `snyk-bot@snyk.io` (a verified user on GitHub), and signed with a PGP key. All Snyk pull requests appear as verified on GitHub, giving your developers the confidence that a trusted source generates the fix and upgrade pull requests. #### Pull request status checks -The Snyk [PR Checks](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/prevent/pull-request-checks) feature allows Snyk to test any new PR in your repositories for security vulnerabilities and sends a status check to GitHub. This lets you see, directly in GitHub, whether or not the pull request introduces new security issues. +The Snyk [PR Checks](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/prevent/pull-request-checks) feature lets Snyk test any new PR in your repositories for security vulnerabilities and sends a status check to GitHub. This lets you see, directly in GitHub, whether the pull request introduces new security issues. This example shows how Snyk PR checks appear on the GitHub pull request page. @@ -123,16 +123,16 @@ You can review and adjust the pull request test settings using the Snyk GitHub I In non-brokered GitHub integrations, operations that are triggered through the Snyk Web UI, for example, opening a Fix PR or re-testing a Project, are performed on behalf of the acting user. -Therefore, a user who wants to perform this operation on GitHub through the Snyk UI must connect their GitHub account to Snyk with the required permission scope for the repositories where they want to perform these operations. See [GitHub and GitHub Enterprise permissions requirements](../user-permissions-and-access-scopes.md#github-and-github-enterprise-permissions-requirements) for details. +Therefore, a user who wants to perform this operation on GitHub through the Snyk Web UI must connect their GitHub account to Snyk with the required permission scope for the repositories where they want to perform these operations. See [GitHub and GitHub Enterprise permissions requirements](../user-permissions-and-access-scopes.md#github-and-github-enterprise-permissions-requirements) for details. Operations that are not triggered through the Snyk Web UI, such as daily and weekly tests and automatic PRs (fix and upgrade), are performed on behalf of random Snyk Organization members who have connected their GitHub accounts to Snyk and have the required permission scope for the repository. -For public repositories that are non-brokered, some operations, such as creating the PR, may occasionally be performed by `snyk-bot@snyk.io`. +For public repositories that are non-brokered, `snyk-bot@snyk.io` occasionally performs some operations, such as creating the PR. {% hint style="info" %} A Snyk Organization administrator can [designate a specific GitHub account to use for opening fix and upgrade PRs](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/fix/snyk-pull-or-merge-requests/opening-fix-and-upgrade-pull-requests-from-a-fixed-github-account). -Note that Snyk will continue to use a random Snyk Organization member's GitHub account to perform all the other operations. Therefore using this feature does not eliminate the need to connect users' GitHub accounts to Snyk. +Note that Snyk continues to use a random Snyk Organization member's GitHub account to perform all the other operations. Therefore, using this feature does not eliminate the need to connect users' GitHub accounts to Snyk. {% endhint %} ### How to set up a GitHub account to open Snyk PRs and enable the Pull Request Experience @@ -140,12 +140,12 @@ Note that Snyk will continue to use a random Snyk Organization member's GitHub a You can designate a specific GitHub account to open fix and upgrade pull requests, and enable the [Pull Request Experience](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/prevent/pull-request-checks/pull-request-experience). {% hint style="info" %} -The configured account is only used for opening PRs and posting issue summary and inline comments. All other operations are still performed on behalf of a randomly selected Snyk Organization member who has connected their GitHub accounts to Snyk. +The configured account is used only for opening PRs and posting issue summary and inline comments. All other operations are still performed on behalf of a randomly selected Snyk Organization member who has connected their GitHub accounts to Snyk. {% endhint %} To use this feature, follow these steps: -1. Navigate to the GitHub Integrations settings page in the Snyk Web UI using Organization **Settings** **Integrations** > **Source control** > **GitHub**. +1. Navigate to the GitHub Integrations settings page in the Snyk Web UI using Organization **Settings** > **Integrations** > **Source control** > **GitHub**. 2. In the **Open Snyk automatic PRs from a fixed GitHub account** section, enter your GitHub personal access token.\ You can [generate this from your GitHub account](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). 3. Click **Save** to enable this feature. @@ -168,13 +168,13 @@ The Auto-assign PRs feature is supported only for private repositories. Snyk can automatically assign the pull requests it creates to ensure that they are handled by the right team members. -Auto-assign for PRs can be enabled for the GitHub and GitHub Enterprise integration and all Projects imported via GitHub, or on a per-Project basis. +You can enable Auto-assign for PRs for the GitHub and GitHub Enterprise integration and all Projects imported using GitHub, or on a per-Project basis. -Users can either be manually specified, and all will be assigned, or automatically selected based on the last commit user account. +You can either specify users manually, and Snyk assigns all of them, or select them automatically based on the last commit user account. #### Enable Auto-assign for all Projects in the GitHub integration -To configure the Auto-assign settings for all the Projects from an imported private repository, go to the Github integration settings using Organization **Settings** > **Integrations** > **Source control** > **GitHub** and select **Enable pull request assignees**. +To configure the Auto-assign settings for all the Projects from an imported private repository, navigate to the Github integration settings using Organization **Settings** > **Integrations** > **Source control** > **GitHub** and select **Enable pull request assignees**. You can then choose to assign PRs to the last user to change the manifest file or specified contributors. @@ -191,7 +191,7 @@ To configure the Auto-assign settings for a specific Project from an imported pr 1. In the **Projects** tab for your Organization, select and expand the relevant private repository, select a Target, and click the **Settings** cog. This opens the Project page. 2. On the Project page, apply unique settings for that specific Project.\ Select the **Settings** tab in the upper right and the **Github integration** \_\_ option in the left sidebar. -3. Go to the **Pull request assignees for private repos** section at the bottom of the page and choose to **Inherit from integration settings** or **Customize only for this Project**. +3. Navigate to the **Pull request assignees for private repos** section at the bottom of the page and choose to **Inherit from integration settings** or **Customize only for this Project**. 4. Ensure **Auto-assign PRs for this private Project** is enabled. 5. Choose to assign PRs to the last user to change the manifest file or named contributors. @@ -199,32 +199,32 @@ To configure the Auto-assign settings for a specific Project from an imported pr ### How to disable the GitHub integration -The GitHub SCM integration leverages the OAuth app integration. If you integrated GitHub without using Snyk Broker, you can disconnect it by following these steps: +The GitHub SCM integration uses the OAuth app integration. If you integrated GitHub without using Snyk Broker, you can disconnect it by following these steps: 1. In GitHub, log in to the GitHub account that you used to create the integration. -2. Go to your GitHub account settings and select the **Applications** option in the left sidebar. +2. Navigate to your GitHub account settings and select the **Applications** option. 3. Select the **Authorized OAuth Apps** tab.\ You can also reach the [Authorized OAuth Apps tab directly](https://github.com/settings/applications). -4. Find the **Snyk** entry, click the three (3) dots on the right, and select **Revoke**. +4. Find the **Snyk** entry, click the three dots, and select **Revoke**.
Revoke OAuth authorization

Revoke OAuth authorization

-Revoking this access effectively disconnects Snyk’s access to that GitHub account. +Revoking this access disconnects Snyk access to that GitHub account. -* Existing imported snapshots will persist in Snyk and continue to be re-scanned based on the existing snapshots until deleted. -* Snyk will no longer be able to import new Projects from the GitHub integration and will no longer re-scan on new code merges. +* Existing imported snapshots persist in Snyk and continue to be re-scanned based on the existing snapshots until deleted. +* Snyk can no longer import new Projects from the GitHub integration and no longer re-scans on new code merges. In addition, you must confirm that Snyk is not enabled on any existing **Branch protection rules**. {% hint style="info" %} -Note that branch protection is active only after a PR has been raised. +Note that branch protection is active only after a PR is raised. {% endhint %} -1. From the main page of your GitHub repository, go to **Settings** > **Branches** > **Branch protection rules**. +1. From the main page of your GitHub repository, navigate to **Settings** > **Branches** > **Branch protection rules**. 2. Ensure there are no **Status checks found in the last week for this repository**. {% hint style="info" %} -A disconnected GitHub integration will still appear as configured in the Integrations menu of the Snyk UI. However, clicking on the integration settings will show that it is not connected. In this case, the "configured" integration can safely be ignored. +A disconnected GitHub integration still appears as configured in the Integrations menu of the Snyk Web UI. However, clicking the integration settings shows that it is not connected. In this case, you can safely ignore the "configured" integration. {% endhint %} ### Migrate to the GitHub Enterprise integration @@ -235,19 +235,19 @@ Before deleting Snyk Projects imported using the GitHub integration, consider th Before you configure and Import Projects using the [GitHub Enterprise integration](github-enterprise.md), Snyk recommends removing all Projects imported using the GitHub integration. This avoids having duplicate Snyk Projects. -You can remove Projects imported using the GitHub integration manually by removing the Projects from Snyk. However, depending on how many Projects you have already imported using the GitHub integration, it may be easier for you to create a new Snyk Organization. +You can remove Projects imported using the GitHub integration manually by removing the Projects from Snyk. However, depending on how many Projects you have already imported using the GitHub integration, it might be easier for you to create a new Snyk Organization. -If you have already created multiple Snyk Organizations and Projects have been imported from GitHub to each Organization, it may be easier to re-create the Snyk Organizations to use the Snyk GitHub Enterprise integration than to update each one manually. If you choose to do this, you can copy integration settings from an existing Organization to avoid having to re-configure other integrations. +If you have already created multiple Snyk Organizations and imported Projects from GitHub to each Organization, it might be easier to re-create the Snyk Organizations to use the Snyk GitHub Enterprise integration than to update each one manually. If you choose to do this, you can copy integration settings from an existing Organization to avoid having to re-configure other integrations. #### Migration steps If you already have multiple Snyk Organizations with Projects imported using the GitHub integration, follow these steps to migrate from GitHub integration to GitHub Enterprise integration. -1. Create a new Snyk Organization that will be used as the template for all others. You can copy integration settings from an existing Organization if required. -2. In this new template Organization, set up the Snyk GitHub Enterprise integration using the steps on the page [GitHub Enterprise integration](github-enterprise.md#how-to-set-up-the-github-enterprise-integration). The dedicated GitHub service account in those steps is a separate user account that you will use as the connection between Snyk and GitHub. -3. When the Snyk GitHub Enterprise integration is configured, you can import a Project to your template Organization to test that the integration is working as expected. -4. You can now create new Organizations that will replace the existing Organizations that were configured using the GitHub integration. As you create each new Organization, ensure that you copy the integration settings from this template Organization so that the GitHub Enterprise integration is available. +1. Create a new Snyk Organization to use as the template for all others. You can copy integration settings from an existing Organization if required. +2. In this new template Organization, set up the Snyk GitHub Enterprise integration using the steps on the page [GitHub Enterprise integration](github-enterprise.md#how-to-set-up-the-github-enterprise-integration). The dedicated GitHub service account in those steps is a separate user account that you use as the connection between Snyk and GitHub. +3. When the Snyk GitHub Enterprise integration is configured, you can import a Project to your template Organization to test that the integration works as expected. +4. You can now create new Organizations to replace the existing Organizations that were configured using the GitHub integration. As you create each new Organization, ensure that you copy the integration settings from this template Organization so that the GitHub Enterprise integration is available. 5. Now that your new Organizations are created, you can import your Projects, choosing the GitHub Enterprise integration when you select the source. 6. You can now remove the previous Organizations that were configured using the GitHub integration. -You may want to [disconnect your GitHub integration](github-enterprise.md#how-to-disconnect-the-github-enterprise-integration) to avoid unintentionally importing Projects using the GitHub integration in the future. Because the GitHub integration is configured per user account, rather than per Organization, each user who has set up the GitHub integration must complete this disconnection process individually. +You might want to [disconnect your GitHub integration](github-enterprise.md#how-to-disconnect-the-github-enterprise-integration) to avoid unintentionally importing Projects using the GitHub integration in the future. Because the GitHub integration is configured per user account, rather than per Organization, each user who has set up the GitHub integration must complete this disconnection process individually. diff --git a/developer-tools/scm-integrations/organization-level-integrations/gitlab.md b/developer-tools/scm-integrations/organization-level-integrations/gitlab.md index 302d3dcaa4fc..b9688c7bedc3 100644 --- a/developer-tools/scm-integrations/organization-level-integrations/gitlab.md +++ b/developer-tools/scm-integrations/organization-level-integrations/gitlab.md @@ -5,7 +5,7 @@ The GitLab integration is available only with Enterprise plans. For more information, see [plans and pricing](https://snyk.io/plans/). -[Snyk Broker](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-broker/snyk-broker) is required if you are integrating from a private network. +You need [Snyk Broker](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-broker/snyk-broker) if you are integrating from a private network. {% endhint %} ### Prerequisites for GitLab integration @@ -15,7 +15,7 @@ The GitLab integration is available only with Enterprise plans. For more informa ### GitLab integration features -The GitLab integration allows you to: +The GitLab integration lets you: 1. Check for vulnerabilities in your pull requests. 2. From the **Report** page or the **Project** page on the Snyk Web UI, [trigger a Snyk pull request](gitlab.md#fix-vulnerabilities-with-snyk-merge-requests) for the fixes listed. @@ -28,13 +28,13 @@ To set up the GitLab integration with Snyk, create a GitLab access token and ent Typically, the first user in a Snyk Organization, a [Snyk admin](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/#user-types) and GitLab Owner or Maintainer, sets up an integration with a **GitLab Personal Access Token** or **Group Access Token**. This token is then authenticated with GitLab, enabling access by Snyk to the repositories in that GitLab account. -* A **GitLab Personal Access Token** is used to perform actions on and manage personal GitLab projects individually. These differ from Group Access Tokens as they are attached to a user rather than a GitLab group. For Snyk Essentials to show all repositories from GitLab, the user generating the PAT should be part of the GitLab group where their GitLab permissions can be a minimum of Guest. -* A **GitLab Group Access Token** is used to perform actions for and manage more than one GitLab project within a GitLab group. The Group Access Token also grants access to all GitLab projects in a GitLab group or subgroup without contributing to GitLab's licensed user count. +* A **GitLab Personal Access Token** performs actions on and manages personal GitLab projects individually. These differ from Group Access Tokens because they are attached to a user rather than a GitLab group. For Snyk Essentials to show all repositories from GitLab, the user generating the PAT must be part of the GitLab group where their GitLab permissions can be a minimum of Guest. +* A **GitLab Group Access Token** performs actions for and manages more than one GitLab project in a GitLab group. The Group Access Token also grants access to all GitLab projects in a GitLab group or subgroup without contributing to the licensed user count in GitLab. -To trigger the creation of fix pull requests manually, all users in a Snyk Organization can add and work with any related Snyk Projects, while the merge requests themselves will appear in GitLab as having been opened by the Snyk admin who set up the configuration. +To trigger the creation of fix pull requests manually, all users in a Snyk Organization can add and work with any related Snyk Projects, while the merge requests themselves appear in GitLab as opened by the Snyk admin who set up the configuration. {% hint style="warning" %} -Group Access Tokens can only be created by a GitLab Owner using a GitLab Premium or Ultimate [account tier](https://about.gitlab.com/pricing/). This can be done in [GitLab's web UI](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html), their Rails console, or through the GitLab API. +Only a GitLab Owner using a GitLab Premium or Ultimate [account tier](https://about.gitlab.com/pricing/) can create Group Access Tokens. You can do this in the [GitLab web UI](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html), the Rails console, or through the GitLab API. {% endhint %} ### How to set up the GitLab integration @@ -52,7 +52,7 @@ Group Access Tokens can only be created by a GitLab Owner using a GitLab Premium Generating a GitLab Group Access Token requires selecting the Maintainer role for access. -Selecting the **api** scope with a **Maintainer** role allows Snyk to authenticate user accounts and create webhooks, enabling the following: +Selecting the **api** scope with a **Maintainer** role lets Snyk authenticate user accounts and create webhooks, enabling the following: * Automation of fix pull requests and Snyk tests on your pull requests. * Manual creation of fix pull requests. @@ -73,12 +73,12 @@ Selecting the **api** scope with a **Maintainer** role allows Snyk to authentica #### Fix vulnerabilities with Snyk merge requests -When viewing a Snyk test report for a Snyk Project that you own or when looking at a GitLab Project that you are watching with Snyk, you see two options for fixing a vulnerability: +When viewing a Snyk test report for a Snyk Project that you own or when looking at a GitLab Project that you are watching with Snyk, you see two (2) options for fixing a vulnerability: * **Fix these vulnerabilities**: generate a Snyk merge request with the minimal changes needed to fix all the Snyk Project's detected vulnerabilities. * **Fix this vulnerability**: generate a Snyk merge request on an individual issue that fixes the vulnerability. -You can review the vulnerabilities that will be fixed, change your selection with the checkboxes, and choose to ignore any vulnerabilities that cannot be fixed now before opening the merge request on the **Open a Fix Merge Request** page. +You can review the vulnerabilities that Snyk fixes, change your selection with the checkboxes, and choose to ignore any vulnerabilities that cannot be fixed now before opening the merge request on the **Open a Fix Merge Request** page. {% hint style="info" %} GitLab webhooks send out an event to Snyk when merge requests occur. This starts a series of other events, such as pulling GitLab project files, running the test process, and posting the results to GitLab, all of which occur on the Snyk side. @@ -86,14 +86,14 @@ GitLab webhooks send out an event to Snyk when merge requests occur. This starts #### Receive email alerts for new vulnerabilities -When a new vulnerability is detected on a Snyk Project you are watching, Snyk will send you an email with a generated Snyk merge request to address the vulnerability. +When Snyk detects a new vulnerability on a Snyk Project you are watching, it sends you an email with a generated Snyk merge request to address the vulnerability. #### Receive email alerts for new upgrades or patches -You may find yourself in a situation where no upgrade is found for a vulnerability, and only a patch is available. When a fix does become available, Snyk notifies you by email and generates a merge request containing the new fix. +You might find yourself in a situation where no upgrade is found for a vulnerability, and only a patch is available. When a fix does become available, Snyk notifies you by email and generates a merge request containing the new fix. {% hint style="warning" %} -Patching is only available on Node.js Projects. +Patching is available only on Node.js Projects. {% endhint %} ### How to disconnect the GitLab integration @@ -101,7 +101,7 @@ Patching is only available on Node.js Projects. {% hint style="warning" %} Disconnecting the GitLab integration removes all Snyk webhooks, along with the Snyk credentials, and deactivates the GitLab Projects in the Snyk Web UI. -The Projects will be set to inactive, and you will no longer get alerts, pull requests, or Snyk tests on your pull requests. +The Projects are set to inactive, and you no longer get alerts, pull requests, or Snyk tests on your pull requests. {% endhint %} 1. Navigate to the Snyk GitLab integration **Settings**. @@ -110,9 +110,9 @@ The Projects will be set to inactive, and you will no longer get alerts, pull re
Confirm diconnecting from GitLab

Confirm disconnecting from GitLab

-After GitLab is disconnected, Snyk Projects imported from GitLab will be set to inactive, and you will no longer get alerts, pull requests, or Snyk tests on pull requests. The webhook that enables the integration for this repository will be removed. +After GitLab is disconnected, Snyk Projects imported from GitLab are set to inactive, and you no longer get alerts, pull requests, or Snyk tests on pull requests. Snyk removes the webhook that enables the integration for this repository. -You can re-connect anytime; however, re-initiating GitLab projects for monitoring requires setting up the integration again. +You can re-connect anytime. However, re-initiating GitLab projects for monitoring requires setting up the integration again. ### GitLab integration Troubleshooting diff --git a/developer-tools/scm-integrations/scm-integrations-and-snyk-broker.md b/developer-tools/scm-integrations/scm-integrations-and-snyk-broker.md index 90431c89c035..90e046de669f 100644 --- a/developer-tools/scm-integrations/scm-integrations-and-snyk-broker.md +++ b/developer-tools/scm-integrations/scm-integrations-and-snyk-broker.md @@ -10,7 +10,7 @@ You can find on [GitHub](https://github.com/snyk/broker/tree/565242baf003f06f445 ## Integrated SCM tokens for classic Broker -An integrated SCM token is required for [Broker client setup](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-broker/classic-broker/prepare-snyk-broker-for-deployment). It is used in the `-e _TOKEN` parameter, for example, `-e GITHUB_TOKEN=xxx…`, to enable access to the SCM. These meet certain permissions needed for the operation of Broker and Snyk Code. +An integrated SCM token is required for [Broker client setup](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-broker/classic-broker/prepare-snyk-broker-for-deployment). You use it in the `-e _TOKEN` parameter, for example, `-e GITHUB_TOKEN=xxx…`, to enable access to the SCM. These tokens meet certain permissions needed for the operation of Broker and Snyk Code. An integrated SCM token can be generated for the following SCM integrations: @@ -67,15 +67,15 @@ https://github.com/settings/apps/new?name=Snyk&description=Snyk%20helps%20you%20 * Snyk EU: `https%3A%2F%2Fapp.eu.snyk.io` * Snyk AU: `https%3A%2F%2Fapp.au.snyk.io` -3. After the value is replaced, navigate to that URL in your browser.\ - This will take you to the app creation screen in your GitHub Cloud instance with all the required details pre-filled. +3. After you replace the value, navigate to that URL in your browser.\ + This takes you to the app creation screen in your GitHub Cloud instance with all the required details pre-filled. 4. Scroll to the end of the page. Ensure that **Any account** is selected, and then click **Create GitHub App**. 5. Make a note of the `ClientId` and `AppId`. Store these safely and treat them as secrets. You must enter these credentials when you create the Universal Broker connection to your GitHub Cloud app. 6. Click the **generate a private key** link.\ This initiates the download of a `.pem` file. Store this file safely and treat it as a secret. You must enter the path to this file when you create the Universal Broker connection to your GitHub Cloud app.\ - Your GitHub Cloud App is now ready to be installed in repositories in your Snyk Organization. + Your GitHub Cloud App is now ready to install in repositories in your Snyk Organization. 7. Scroll to the top of the page and click **Install App** on the navigation panel. Click the **Install** button for your app. -8. Choose where you want to install the app in your GitHub organization. It can be installed in specific repositories or all of them. +8. Choose where you want to install the app in your GitHub organization. You can install it in specific repositories or all of them. {% hint style="info" %} If you choose to install the app only in specific repositories, the app works only in those repositories. You can return to this screen and edit where the app is installed if you want to add it to additional repositories. @@ -105,7 +105,7 @@ Before the GitHub Cloud App can be used with the Universal Broker, you must crea 1. Run the `snyk-broker-config workflows connections create` command. Choose the `github-cloud-app` option and provide the information you are prompted for in the workflow. 2. Run `snyk-broker-config workflows connections integrate` to integrate the newly created connection to the Organization of your choice. Enter the Organization ID when you are prompted. -Visit the integrations page in Snyk to verify that the integration has been configured. +Visit the integrations page in Snyk to verify that the integration is configured. See the [Universal Broker](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-broker/universal-broker) documentation for more details. @@ -137,15 +137,15 @@ To use the GitHub Server App with Universal Broker you must create your own GitH * Snyk AU: https%3A%2F%2Fapp.au.snyk.io * Snyk US-02: https%3A%2F%2Fapp.us.snyk.io -3. After these values are replaced, navigate to that URL in your browser.\ - This will take you to the app creation screen in your GitHub Server instance with all the required details pre-filled. +3. After you replace these values, navigate to that URL in your browser.\ + This takes you to the app creation screen in your GitHub Server instance with all the required details pre-filled. 4. Scroll to the end of the page. Ensure that **Any account** is selected, and then click **Create GitHub App**. 5. Make a note of the `ClientId` and `AppId`. Store these safely and treat them as secrets. You must enter these credentials when you create the Universal Broker connection to your GitHub Server app. 6. Click the **generate a private key** link.\ This initiates the download of a `.pem` file. Store this file safely and treat it as a secret. You must enter the path to this file when you create the Universal Broker connection to your GitHub Server app.\ - Your GitHub Server App is now ready to be installed in repositories in your Snyk Organization. + Your GitHub Server App is now ready to install in repositories in your Snyk Organization. 7. Scroll to the top of the page and click **Install App** on the navigation panel. Click the **Install** button for your app. -8. Choose where you want to install the app in your GitHub organization. It can be installed in specific repositories or all of them. +8. Choose where you want to install the app in your GitHub organization. You can install it in specific repositories or all of them. {% hint style="info" %} If you choose to install the app only in specific repositories, the app works only in those repositories. You can return to this screen and edit where the app is installed if you want to add it to additional repositories. @@ -158,7 +158,7 @@ If you choose to install the app only in specific repositories, the app works on ### Create the Universal Broker connection for your GitHub Server App -Before the GitHub Server App can be used with the Universal Broker, you must create a connection of the `github-server-app` type using the `snyk-broker-config` tool. For more details, see the [Universal Broker](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-broker/universal-broker) documentation. After the connection is created, it can be integrated with one or more Organization(s) of your choice. +Before the GitHub Server App can be used with the Universal Broker, you must create a connection of the `github-server-app` type using the `snyk-broker-config` tool. For more details, see the [Universal Broker](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-broker/universal-broker) documentation. After you create the connection, you can integrate it with one or more Organizations of your choice. #### Prerequisites @@ -174,6 +174,6 @@ Before the GitHub Server App can be used with the Universal Broker, you must cre 1. Run the `snyk-broker-config workflows connections create` command. Choose the `github-server-app` option and provide the information you are prompted for in the workflow. 2. Run `snyk-broker-config workflows connections integrate` to integrate the newly created connection to the Organization of your choice. Enter the Organization ID when you are prompted. -Visit the integrations page in Snyk to see that the integration has been configured. +Visit the integrations page in Snyk to see that the integration is configured. See the [Universal Broker](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-broker/universal-broker) documentation for more details. diff --git a/developer-tools/scm-integrations/user-permissions-and-access-scopes.md b/developer-tools/scm-integrations/user-permissions-and-access-scopes.md index b6922b9a3eb7..cec35aecc1e2 100644 --- a/developer-tools/scm-integrations/user-permissions-and-access-scopes.md +++ b/developer-tools/scm-integrations/user-permissions-and-access-scopes.md @@ -1,6 +1,6 @@ # User permissions and access scopes -Snyk SCM integrations may require different permission requirements based on the connection method. +Snyk SCM integrations can require different permissions based on the connection method. See the following for detailed permission requirements: @@ -28,7 +28,7 @@ A PAT generated for the Group-level GitHub integration requires the following pe For information about token permissions in a brokered integration, see [GitHub - prerequisites and steps to install and configure Broker](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/snyk-broker/classic-broker/install-and-configure-snyk-broker/github-prerequisites-and-steps-to-install-and-configure-broker) and [Integrated SCM tokens for Snyk Broker](scm-integrations-and-snyk-broker.md#integrated-scm-tokens-for-classic-broker). {% endhint %} -The Snyk GitHub Enterprise integration is bound to a single user, preferably a GitHub service account. The level of access for the integration is defined by the combination of the user's permissions in GitHub and the access defined for the Personal Access Token (PAT) on that user's account. If the PAT is defined with more permission than the user's GitHub account, the integration will not be able to use that permission. +The Snyk GitHub Enterprise integration is bound to a single user, preferably a GitHub service account. The combination of the user's permissions in GitHub and the access defined for the Personal Access Token (PAT) on that user's account defines the level of access for the integration. If the PAT has more permission than the user's GitHub account, the integration cannot use that permission. The following table details the access scopes required in GitHub and GitHub Enterprise for Personal Access Tokens (PAT) and the scopes required for Snyk to perform the required operations on monitored repositories, such as reading manifest files on a frequent basis and opening fix or upgrade PRs. GitHub custom roles are not supported. @@ -55,7 +55,7 @@ Snyk uses SCM webhooks to: ### GitHub Cloud App permission requirements -The [Snyk GitHub Cloud App](organization-level-integrations/github-cloud-app.md) integration uses role-based access control, meaning access control is not dependent on individual users or their role, it is instead tied to the app entity. +The [Snyk GitHub Cloud App](organization-level-integrations/github-cloud-app.md) integration uses role-based access control. Access control does not depend on individual users or their role; instead, it is tied to the app entity. To set up the GitHub Cloud app integration, you must be a: @@ -64,7 +64,7 @@ To set up the GitHub Cloud app integration, you must be a: * GitHub Repository Admin (if installing through the GitHub UI). {% hint style="info" %} -While some permissions may be optional from GitHub’s perspective, they are necessary to support Snyk functions. These permissions cannot be customized for your individual needs because the app is registered under the Snyk Organization. +While some permissions are optional from GitHub’s perspective, they are necessary to support Snyk functions. You cannot customize these permissions for your individual needs because the app is registered under the Snyk Organization. {% endhint %} The following table states the required GitHub App permissions and scopes: @@ -130,7 +130,7 @@ Scope by Purpose |

Importing new projects to Snyk:
Lists available repos in the Bitbucket instance in the Add Projects screen.

|

read:project:bitbucket

read:workspace:bitbucket

read:account

read:user:bitbucket

| |

Snyk Group Level Integrations:
Required for Inventory and Essentials

|

read:repository:bitbucket

read:user:bitbucket
read:workspace:bitbucket

| -When reviewing the token scopes, they are listed by access level. Please review to ensure that you have the correct scopes: +Bitbucket lists the token scopes by access level. Review them to ensure that you have the correct scopes: | READ | WRITE | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | diff --git a/developer-tools/scm-integrations/workspaces.md b/developer-tools/scm-integrations/workspaces.md index 3dfd4c302ab3..ff617c85602c 100644 --- a/developer-tools/scm-integrations/workspaces.md +++ b/developer-tools/scm-integrations/workspaces.md @@ -1,22 +1,22 @@ # Workspaces {% hint style="info" %} -Workspaces improve the accuracy and reliability of Snyk’s SCM integration results, especially for large-scale enterprise environments. This capability also supports additional functionality and improvements we have planned in the future. For these reasons, Snyk strongly recommends [enabling this option](workspaces.md#manage-workspaces) by default at your Group level. +Workspaces improve the accuracy and reliability of the SCM integration results in Snyk, especially for large-scale enterprise environments. This capability also supports additional functionality and improvements we have planned in the future. For these reasons, Snyk strongly recommends [enabling this option](workspaces.md#manage-workspaces) by default at your Group level. {% endhint %} Workspaces represents a significant step forward in providing you with the most reliable and accurate vulnerability detection possible. -Traditionally, Snyk has accessed repository contents using SCM APIs, which impose primary and secondary rate limits, and content limits. For example, the GitHub.com APIs are rate-limited to allow only a certain number of requests per hour, and there is a limit on the number of tree entries that can be retrieved from the Git database. +Traditionally, Snyk accessed repository contents using SCM APIs, which impose primary and secondary rate limits, and content limits. For example, the GitHub.com APIs are rate-limited to allow only a certain number of requests per hour, and there is a limit on the number of tree entries that can be retrieved from the Git database. -When repository contents are retrieved over these APIs, these limitations inhibit Snyk’s providing a complete analysis in a number of ways, especially across a very large number of repositories, or for repositories containing more than 100,000 files, sometimes referred to as monorepos. +When Snyk retrieves repository contents over these APIs, these limitations inhibit Snyk from providing a complete analysis in a number of ways, especially across a large number of repositories, or for repositories containing more than 100,000 files, sometimes referred to as monorepos. -Through Workspaces, these limitations are removed. +Workspaces removes these limitations. -The accuracy of results is improved in a number of ways through cloning. Since Snyk can access a complete view of a source code repository at a specific commit SHA, including repositories containing more than 100,000 files, the analysis is also more complete through cloning. +Cloning improves the accuracy of results in a number of ways. Because Snyk can access a complete view of a source code repository at a specific commit SHA, including repositories containing more than 100,000 files, the analysis is also more complete through cloning. ## Snyk data ingestion -When Workspaces is enabled, Snyk will ingest, through configured SCM integrations, a temporary and shallow clone of repository contents at a given commit and all commit metadata (including the commit message, authors, and timestamp). +When Workspaces is enabled, Snyk ingests, through configured SCM integrations, a temporary and shallow clone of repository contents at a given commit and all commit metadata (including the commit message, authors, and timestamp). {% hint style="info" %} For more information on Snyk data processing and safeguards concerning Git repo cloning, see [Cache retention period related to vulnerability source data](https://app.gitbook.com/s/ELvljsaLKPkSpffOkmsQ/how-snyk-handles-your-data#cache-retention-period-related-to-vulnerability-source-data) and [Snyk integrations: workspaces](https://app.gitbook.com/s/ELvljsaLKPkSpffOkmsQ/how-snyk-handles-your-data#snyk-integrations-workspaces). @@ -28,15 +28,15 @@ Repositories are cloned using HTTPS. SSH-based clones are unavailable. ## Manage Workspaces -The Workspaces feature is managed through the **Integrations settings** page on the Group or Organization level. To do so, you must be a Snyk Group Admin or Snyk Organization Admin. +You manage the Workspaces feature through the **Integrations settings** page on the Group or Organization level. To do so, you must be a Snyk Group Admin or Snyk Organization Admin. -When Workspaces is enabled at the Group level, all Organizations within that Group have Workspaces enabled. This Group level setting can be overridden by the individual Organization level setting. +When Workspaces is enabled at the Group level, all Organizations in that Group have Workspaces enabled. The individual Organization level setting can override this Group level setting. {% hint style="warning" %} -When a Group level setting is overridden by an Organization level setting, the Organization level setting cannot be modified by any future changes made to the Group level setting. +When an Organization level setting overrides a Group level setting, no future changes to the Group level setting can modify the Organization level setting. {% endhint %} -While you can choose to disable the Workspaces feature, it is important to understand doing so will hinder Snyk’s ability to scan repositories in two specific ways: +While you can choose to disable the Workspaces feature, it is important to understand that doing so hinders the ability of Snyk to scan repositories in two specific ways: -1. Frequency of scanning: With Workspaces disabled, Snyk will analyze repository content through SCM APIs, which typically impose primary and secondary rate limits, and content limits. For example, the GitHub.com APIs are rate-limited to allow only a certain number of requests per hour, which hinders Snyk’s ability to analyze a large number of repositories in any one hour. -2. Completeness of scanning: With the Workspaces feature disabled, Snyk will analyze repo content through SCM APIs, which typically limit the number of tree entries that can be retrieved from the Git database, potentially leading to missed vulnerabilities. This impacts analysis of repositories containing a large number of files, sometimes referred to as monorepos. +1. Frequency of scanning: With Workspaces disabled, Snyk analyzes repository content through SCM APIs, which typically impose primary and secondary rate limits, and content limits. For example, the GitHub.com APIs are rate-limited to allow only a certain number of requests per hour, which hinders the ability of Snyk to analyze a large number of repositories in any one hour. +2. Completeness of scanning: With the Workspaces feature disabled, Snyk analyzes repo content through SCM APIs, which typically limit the number of tree entries that can be retrieved from the Git database, potentially leading to missed vulnerabilities. This impacts analysis of repositories containing a large number of files, sometimes referred to as monorepos. diff --git a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/README.md b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/README.md index 0772b0bbb376..1288a346dc7b 100644 --- a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/README.md +++ b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/README.md @@ -1,6 +1,6 @@ # API End of Life (EOL) process and migration guides -This page explains the process, key dates, and milestones associated with the end-of-life (EOL) cycle for all API endpoints. In this documentation, you will also find detailed information about [key dates](api-eol-endpoints-and-key-dates.md) and [migration guides](guides-to-migration/) for API endpoints that are in the end-of-life process. +This page explains the process, key dates, and milestones associated with the end-of-life (EOL) cycle for all API endpoints. In this documentation, you can also find detailed information about [key dates](api-eol-endpoints-and-key-dates.md) and [migration guides](guides-to-migration/) for API endpoints that are in the end-of-life process. ## API End of Life (EOL) process @@ -11,25 +11,25 @@ Snyk GA REST APIs are an evolution of Snyk V1 APIs because the GA REST APIs hav * Improved performance * Specifications for client generation -Snyk EOL for V1 APIs and replacement with GA REST APIs will implement this improvement over the equivalent V1 APIs. As Snyk delivers more GA REST APIs, experimental and beta versions of the REST API will also reach end-of-life. +Snyk EOL for V1 APIs and replacement with GA REST APIs implements this improvement over the equivalent V1 APIs. As Snyk delivers more GA REST APIs, experimental and beta versions of the REST API also reach end-of-life. -Migrating from V1 API to GA REST can be a time-consuming process, and Snyk wants to ensure that you have enough time to factor in and execute migrations so that you can have the best API experience as soon as possible. The process for taking an endpoint (V1, experimental, or beta API) to EOL for seamless migration to GA REST is as follows: +Migrating from V1 API to GA REST can be a time-consuming process, and Snyk wants to ensure that you have enough time to factor in and execute migrations so that you can have the best API experience as soon as possible. The process for taking an endpoint (V1, experimental, or beta API) to EOL for migration to GA REST is as follows: -1. Batches of endpoints will be part of an EOL cycle that begins twice a year: one batch in January and one batch in July. +1. Batches of endpoints are part of an EOL cycle that begins twice a year: one batch in January and one batch in July. 2. API endpoints can be included for EOL only if they have: * A GA REST equivalent or equivalents (except in the rare case where a V1 API does not have or need a GA REST equivalent) * Functionality parity between V1 and GA REST (unless explicitly stated otherwise in the migration guide) * A migration guide by our field specialists for ease of migration -3. Snyk will [publicly announce](http://updates.snyk.io/) which endpoints will be part of an EOL cycle one month before the cycle begins. -4. On the date the EOL begins, the endpoints are deemed **deprecated**. At that point, the documentation of each endpoint will either be **removed** or have a statement added that the endpoint is deprecated. In addition, no new customers will be able to integrate with the endpoint. The endpoint will remain functional for existing customers until the end-of-life date. You can find all of the endpoints reaching end of life and the associated timelines on the [API EOL endpoints and key dates](api-eol-endpoints-and-key-dates.md) page. -5. On a monthly basis during the EOL cadence, Snyk will temporarily halt functionality for the nominated endpoints for a period of time, increasing in duration over the course of the EOL. -6. When we reach the EOL date, the endpoint will stop working, and you will receive an error. +3. Snyk [publicly announces](http://updates.snyk.io/) which endpoints are part of an EOL cycle one month before the cycle begins. +4. On the date the EOL begins, the endpoints are deemed **deprecated**. At that point, Snyk either **removes** the documentation of each endpoint or adds a statement that the endpoint is deprecated. In addition, no new customers can integrate with the endpoint. The endpoint remains functional for existing customers until the end-of-life date. You can find all of the endpoints reaching end of life and the associated timelines on the [API EOL endpoints and key dates](api-eol-endpoints-and-key-dates.md) page. +5. On a monthly basis during the EOL cadence, Snyk temporarily halts functionality for the nominated endpoints for a period of time, increasing in duration over the course of the EOL. +6. When we reach the EOL date, the endpoint stops working, and you receive an error. ## Types of API EOL -The following types of EOL will take place during each cycle: +The following types of EOL take place during each cycle: -1. V1 API: When a GA REST equivalent or equivalents are released, Snyk will aim to include the V1 API in an end-of-life cycle as soon as possible. Users will have a six-month window to migrate off the endpoint, beginning at the public announcement in January and July. -2. Experimental and beta: When Snyk upgrades a REST endpoint to GA that has earlier experimental or beta endpoints or both, Snyk will aim to include them in the EOL cycle as soon as possible. Users will have a 3-month window to migrate off the endpoint (starting from the public announcement in January and July). +1. V1 API: When a GA REST equivalent or equivalents are released, Snyk aims to include the V1 API in an end-of-life cycle as soon as possible. Users have a six-month window to migrate off the endpoint, beginning at the public announcement in January and July. +2. Experimental and beta: When Snyk upgrades a REST endpoint to GA that has earlier experimental or beta endpoints or both, Snyk aims to include them in the EOL cycle as soon as possible. Users have a three-month window to migrate off the endpoint (starting from the public announcement in January and July). -In exceptional circumstances, Snyk may have to announce an EOL for an endpoint outside of the two announcements each year in January and July. Users will receive a one-month notice of the EOL cycle. The time window to migrate off the endpoint will follow the same windows identified for each type of EOL: a V1 API or an experimental or beta endpoint. +In exceptional circumstances, Snyk might have to announce an EOL for an endpoint outside of the two announcements each year in January and July. Users receive a one-month notice of the EOL cycle. The time window to migrate off the endpoint follows the same windows identified for each type of EOL: a V1 API or an experimental or beta endpoint. diff --git a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/api-eol-endpoints-and-key-dates.md b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/api-eol-endpoints-and-key-dates.md index 2663cfcfc0ab..6c7bbe3ac9b1 100644 --- a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/api-eol-endpoints-and-key-dates.md +++ b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/api-eol-endpoints-and-key-dates.md @@ -2,7 +2,7 @@ ## APIs at EOL -Beginning July 22, 2024, the following endpoints will follow the EOL process: +Beginning July 22, 2024, the following endpoints follow the EOL process: | Endpoint | Endpoint type | EOL date | Migration guide | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -18,7 +18,7 @@ Beginning July 22, 2024, the following endpoints will follow the EOL process: A brownout occurs when Snyk temporarily suspends an endpoint from being usable, returning a `410 gone` response when a user calls the endpoint. -Snyk brownouts for APIs that are part of an end-of-life cycle will occur at 12:00 UTC. For the end-of-life cycle beginning July 22, 2024, the brownouts will occur on the following dates. Users will see a reminder two weeks before the brownout through an announcement on [updates.snyk.io](http://updates.snyk.io/): +Snyk brownouts for APIs that are part of an end-of-life cycle occur at 12:00 UTC. For the end-of-life cycle beginning July 22, 2024, the brownouts occur on the following dates. Users see a reminder two weeks before the brownout through an announcement on [updates.snyk.io](http://updates.snyk.io/): | Endpoints | Brownout date | Duration | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------- | diff --git a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/candidates-for-upcoming-api-end-of-life-cadences.md b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/candidates-for-upcoming-api-end-of-life-cadences.md index ae51e102dba8..9c5fa15bac20 100644 --- a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/candidates-for-upcoming-api-end-of-life-cadences.md +++ b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/candidates-for-upcoming-api-end-of-life-cadences.md @@ -2,7 +2,7 @@ This page contains the list of V1, non-GA REST, and older versions of GA REST endpoints that are potential candidates for future end-of-life cadences. To see which endpoints are end-of-life'd, see [API EOL endpoints and key dates](api-eol-endpoints-and-key-dates.md). -If an endpoint is listed in the table below, it does not guarantee that the endpoint will be included in the next end-of-life cadence. In addition, an endpoint can go straight into the next end-of-life cadence without having to be listed in the table below. +If an endpoint is listed in the following table, it does not guarantee that Snyk includes the endpoint in the next end-of-life cadence. In addition, an endpoint can go straight into the next end-of-life cadence without having to be listed in the following table. The endpoints in this list, and in any end-of-life cadence, must adhere to our end-of-life criteria, which require that the endpoints have: @@ -10,7 +10,7 @@ The endpoints in this list, and in any end-of-life cadence, must adhere to our e * Functionality parity between V1 and GA REST (unless explicitly stated otherwise in the migration guide) * A migration guide by our field specialists for ease of migration -Endpoints that are end-of-life'd do not appear in the list that follows, as the list is for future candidates for end-of-life, and can be found on the [API EOL endpoints and key dates](api-eol-endpoints-and-key-dates.md) page. +Endpoints that are end-of-life'd do not appear in the list that follows, because the list is for future candidates for end-of-life, and can be found on the [API EOL endpoints and key dates](api-eol-endpoints-and-key-dates.md) page. | Endpoint | Endpoint Type | Migration Guide | Date Added | | -------- | ------------- | --------------- | ---------- | diff --git a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/list-all-projects-v1-api-to-rest-api-migration-guide-completed-migration.md b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/list-all-projects-v1-api-to-rest-api-migration-guide-completed-migration.md index ebba6f81379a..89af3122b1cd 100644 --- a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/list-all-projects-v1-api-to-rest-api-migration-guide-completed-migration.md +++ b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/list-all-projects-v1-api-to-rest-api-migration-guide-completed-migration.md @@ -17,7 +17,7 @@ Based on OpenAPI specifications, the Snyk REST API is designed to provide a cons The Projects REST API introduces improved data architecture to facilitate enhanced performance and separation of domains. -Snyk understands that migrating to a new API can be a significant undertaking and wants to support you throughout the process. This comprehensive migration guide is intended to facilitate a seamless transition by providing step-by-step instructions, code examples, and best practices to help you smoothly integrate with the new API. +Snyk understands that migrating to a new API can be a significant undertaking and wants to support you throughout the process. This comprehensive migration guide is intended to facilitate the transition by providing step-by-step instructions, code examples, and best practices to help you integrate with the new API. If you are using the deprecated endpoint, Snyk encourages you to review this migration guide and move all your automations over before Friday, December 22, 2023. @@ -32,7 +32,7 @@ If you are using the deprecated endpoint, Snyk encourages you to review this mig | List all projects v1 API documentation removal | September 22, 2023 | No action needed | | End-of-life: All access to List all projects v1 API will result in a 410 Gone response. | December 22, 2023 | Ensure migration has been completed by this time to avoid disruption to automated workflows | -The following Snyk Tools that use the List all projects v1 API have been updated to use the [REST List all projects API](https://apidocs.snyk.io/?version=2023-05-29#get-/orgs/-org_id-/projects) instead: +The following Snyk Tools that use the List all projects v1 API are updated to use the [REST List all projects API](https://apidocs.snyk.io/?version=2023-05-29#get-/orgs/-org_id-/projects) instead: * [snyk-jira-tickets-for-new-vulns](https://github.com/snyk-tech-services/jira-tickets-for-new-vulns): version 5.0.0 or newer * [snyk-api-ts-client](https://github.com/snyk-labs/snyk-api-ts-client): version 1.11.1 or newer diff --git a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/rest-issues-experimental-api-to-ga-api-migration-guide.md b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/rest-issues-experimental-api-to-ga-api-migration-guide.md index 52a9bee63a9e..75b7ff6fb311 100644 --- a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/rest-issues-experimental-api-to-ga-api-migration-guide.md +++ b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/rest-issues-experimental-api-to-ga-api-migration-guide.md @@ -3,7 +3,7 @@ {% hint style="info" %} **Important information about Experimental APIs** -An experimental endpoint should be considered unstable and regarded as a tech preview. Experimental versions may introduce breaking changes and may be discontinued at any time. +Consider an experimental endpoint unstable and regard it as a tech preview. Experimental versions can introduce breaking changes and can be discontinued at any time. {% endhint %} ## What's new in the GA REST Issues API? @@ -17,9 +17,9 @@ This version of the API delivers: * **Consistency:** Improved performance and reliability of the REST Issues API * **Depth:** detailed representations for Open Source packages and fixes * **Flexibility:** new filters for tailored API responses -* **Usability:** improved pagination and response management, simplifying the API interaction +* **Usability:** improved pagination and response management for the API interaction -Snyk understands that migrating to a new API can be a significant undertaking and wants to support you throughout the process. This comprehensive migration guide is intended to facilitate a seamless transition by providing step-by-step instructions, code examples, and best practices to help you smoothly integrate with the new API. +Snyk understands that migrating to a new API can be a significant undertaking and wants to support you throughout the process. This comprehensive migration guide is intended to facilitate the transition by providing step-by-step instructions, code examples, and best practices to help you integrate with the new API. If you are using the deprecated endpoint, Snyk encourages you to review this migration guide and move all your automations over. @@ -28,7 +28,7 @@ If you are using the deprecated endpoint, Snyk encourages you to review this mig {% hint style="info" %} **Mapping experimental API issues to GA API issues** -One of the main differences you will see in the table below is that the format of the ID for an issue changes from URI format (consists of key & scan\_item.id) in the Experimental API to UUID in the GA API. To match an issue in the experimental api response to the same issue in the GA API response you can use **key** and the **scan\_item.id**. Note that **scan\_item** is part of the **relationships** block and **key** is part of the **attributes** block. +One of the main differences you see in the following table is that the format of the ID for an issue changes from URI format (consists of key & scan\_item.id) in the Experimental API to UUID in the GA API. To match an issue in the experimental api response to the same issue in the GA API response you can use **key** and the **scan\_item.id**. Note that **scan\_item** is part of the **relationships** block and **key** is part of the **attributes** block. {% endhint %}
FieldsExperimentalGA
classesPresentNo change
coordinatesOnly available for cloud issuesAvailable for cloud and SCA issues and has new fixability fields.

coordinates.is_fixable_manually

coordinates.is_fixable_snyk

coordinates.is_fixable_upstream

coordinates.is_patchable

coordinates.is_pinnable

coordinates.is_upgradeable


Not presentNewly introduced fixability data
coordinates.reachabilityNot presentNewly introduced
coordinates.remediesPresentNo change
representationsPresentNew fields
representations.resourcePathPresentNo change
respresentations.dependencyChainPresentRemoved in favor of representations.dependency
representations.dependencyNot present

Newly introduced replaces representations.

dependencyChain

representations.dependency

.package_name

representations.dependency.

package_version


Not presentNewly introduced as part of represenations.dependency
cloud_resourcePresentNo change
sourceLocationPresentNo change
created_atPresentNo change
description
No change
effective_severity_levelPresentNo change
ignoredPresentNo change
keyPresentNo change
priorityPresentRemoved and replaced with risk
priority.factorsPresentReplaced with risk.factors
priority.scorePresentReplaced with risk.score
riskNot presentNewly introduced - replaces priority
risk.factorsNot presentNewly introduced - replaces priority.factors

risk.factors[i].included_in_score

risk.factors[i].links

risk.factors[i].links.evidence

risk.factors[i].links.evidence.href

risk.factors[i].links.evidence.meta

risk.factors[i].name

risk.factors[i].updated_at

risk.factors[i].value

Not presentNewly introduced
risk.scoreNot presentNewly introduced replaces priority.score

risk.score.model

risk.score.updated_at

risk.score.value

Not present
problemsPresentNo change
resolutionOnly for cloud issuesFor all issue types
severitiesPresent - Not populatedRemoved as not populated and will not be
statusPresentNo change
titlePresentNo change
toolPresentNo change
typePresentNo change
updated_atPresentNo change
idURI format (consists of key & scan_item.id)UUID format
relationships.ignorePresentNo change
relationships.organizationPresentNo change
relationships.policiesPresent - Not populatedRemoved as not populated and will not be
relationships.previousPresent - Not populatedRemoved as not populated and will not be
relationships.scan_itemPresentNo change
relationships.test_executionPresentNo change
diff --git a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/search-audit-logs-group-and-org-v1-api-to-ga-rest-audit-logs-api-migration-guide.md b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/search-audit-logs-group-and-org-v1-api-to-ga-rest-audit-logs-api-migration-guide.md index 638dc20b7bb9..de1f6be4d958 100644 --- a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/search-audit-logs-group-and-org-v1-api-to-ga-rest-audit-logs-api-migration-guide.md +++ b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/search-audit-logs-group-and-org-v1-api-to-ga-rest-audit-logs-api-migration-guide.md @@ -7,11 +7,11 @@ Based on OpenAPI specifications, the Snyk REST API is designed to provide a cons * Consistent versioning * Improved performance -The Search Audit Logs REST API deprecates offset-based pagination in favour of more performant and consistent cursor-based pagination. Our v1 APIs get slower the higher your page offset becomes and will eventually time out at very high page counts. We’ve improved this considerably in our REST API by using a cursor-based approach that consistently returns results at greater speeds regardless of page count. +The Search Audit Logs REST API deprecates offset-based pagination in favor of more performant and consistent cursor-based pagination. Our v1 APIs get slower the higher your page offset becomes and eventually time out at high page counts. We’ve improved this considerably in our REST API by using a cursor-based approach that consistently returns results at greater speeds regardless of page count. -As well as performance improvements we have also improved filtering capabilities, allowing users to provide multiple include or exclude events for finer-tuned filtering. In a addition to this, the API was only capable of searching for logs within a minimum time-frame of 24 hours, we’ve improved this with higher granularity time stamps [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339), which allows users to search within windows of minutes on a given day. +As well as performance improvements, we have also improved filtering capabilities, letting users provide multiple include or exclude events for finer-tuned filtering. In addition to this, the API was only capable of searching for logs in a minimum time-frame of 24 hours; we’ve improved this with higher granularity time stamps [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339), which lets users search in windows of minutes on a given day. -`` `api.access` `` logs are now excluded by default on all search queries unless explicitly provided as part of the \`events\` parameter. These are typically high-volume low-information logs that are superseded by our explicit action logs, e.g. group.create. Explicit action logs will contain richer contextual information for an action and should be favoured in all cases. +`` `api.access` `` logs are now excluded by default on all search queries unless explicitly provided as part of the \`events\` parameter. These are typically high-volume low-information logs that are superseded by our explicit action logs, for example, group.create. Explicit action logs contain richer contextual information for an action and you should favor them in all cases. Here is what you could use in the v1 endpoints, and their GA REST equivalents: @@ -19,7 +19,7 @@ Here is what you could use in the v1 endpoints, and their GA REST equivalents: ## Response -Audit log event payloads have not changed as part of the REST migration, however, the structure of the response is different to conform to our standardised JSON API responses. +Audit log event payloads have not changed as part of the REST migration; however, the structure of the response is different to conform to our standardized JSON API responses. The V1 response is returned as an array, e.g. @@ -63,7 +63,7 @@ The V1 response is returned as an array, e.g. ` ``` ` -The REST response will contain the same event payload information, however, it will be in the following format: +The REST response contains the same event payload information; however, it is in the following format: ` ``` ` diff --git a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/v1-reporting-apis-to-export-api-migration-guide.md b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/v1-reporting-apis-to-export-api-migration-guide.md index 3e6b501be0ec..c160ca8d1686 100644 --- a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/v1-reporting-apis-to-export-api-migration-guide.md +++ b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/v1-reporting-apis-to-export-api-migration-guide.md @@ -3,7 +3,7 @@ {% hint style="warning" %} **End of life** -The v1 Reporting API is being deprecated, and future development and support are focused on the [Dataset Export API](../../using-specific-snyk-apis/export-api-specifications-columns-and-filters.md) and the [Issues REST API](../../reference/issues.md). Snyk recommends migrating to the new [Export API](../../using-specific-snyk-apis/export-api-specifications-columns-and-filters.md). +Snyk is deprecating the v1 Reporting API, and future development and support are focused on the [Dataset Export API](../../using-specific-snyk-apis/export-api-specifications-columns-and-filters.md) and the [Issues REST API](../../reference/issues.md). Snyk recommends migrating to the new [Export API](../../using-specific-snyk-apis/export-api-specifications-columns-and-filters.md). {% endhint %} This guide outlines the migration path for all routes in the legacy v1 Reporting API. @@ -25,7 +25,7 @@ The most significant change is the shift from a direct, synchronous request/resp To replace any v1 Reporting API call, follow these steps: 1. Initiate the Export: - 1. Send a `POST` request with your filters to create an export job. You will receive an `export_id`. + 1. Send a `POST` request with your filters to create an export job. You receive an `export_id`. 2. Endpoint: `POST /groups/{group_id}/export` 3. Required Parameters: The body must include the filters (including at least one date filter: introduced or updated) and specify the dataset (issues or usage) in the request header. 2. Validate the Export Status: @@ -33,7 +33,7 @@ To replace any v1 Reporting API call, follow these steps: 2. Endpoint: `GET /groups/{group_id}/jobs/export/{export_id}` 3. Statuses: `PENDING`, `STARTED`, `FINISHED`, `ERROR`. 3. Fetch Results in a CSV: - 1. After `FINISHED`, fetch the results, which will return a self-signed URL to the CSV file. + 1. After `FINISHED`, fetch the results, which return a self-signed URL to the CSV file. 2. Endpoint: `GET /groups/{group_id}/export/{export_id}` {% hint style="info" %} @@ -53,7 +53,7 @@ The v1 issue count endpoints (`/v1/reporting/counts/issues` and `/latest`) relie Key issue: * The legacy v1 issue count endpoints do not include issues from Snyk Code, and do not include issues generated by the most recent Snyk Infrastructure as Code (IaC) engines. -* Action: Migrating to the Export API with the issues dataset will provide a more complete and accurate count of all issues across all Snyk products, including IaC. Any count migration should be aware that the new number will likely be higher and more representative of your total issue landscape. +* Action: Migrating to the Export API with the issues dataset provides a more complete and accurate count of all issues across all Snyk products, including IaC. For any count migration, be aware that the new number is likely to be higher and more representative of your total issue landscape. #### Filter parameter migration @@ -86,11 +86,11 @@ For any v1 filter not listed above (for example, `severity`, `fixable`, `languag #### CSV to JSON Conversion Tool -Since the Export API returns data as CSV, and the legacy API returned JSON, you will likely need to convert the exported file for structured consumption by your application. +Because the Export API returns data as CSV, and the legacy API returned JSON, you likely need to convert the exported file for structured consumption by your application. **Native JSON output** -We are prioritizing adding the ability to export data directly in JSON format. It will be available early November. This feature will simplify data consumption for users migrating from the v1 API. +We are prioritizing adding the ability to export data directly in JSON format. It is available early November. This feature streamlines data consumption for users migrating from the v1 API. **Current workaround script** diff --git a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/v1-reporting-issues-and-v1-aggregated-issues-apis-to-rest-issues-api-migration-guide.md b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/v1-reporting-issues-and-v1-aggregated-issues-apis-to-rest-issues-api-migration-guide.md index e9f1f8a0b127..e524d25f4ee0 100644 --- a/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/v1-reporting-issues-and-v1-aggregated-issues-apis-to-rest-issues-api-migration-guide.md +++ b/developer-tools/snyk-api/api-end-of-life-eol-process-and-migration-guides/guides-to-migration/v1-reporting-issues-and-v1-aggregated-issues-apis-to-rest-issues-api-migration-guide.md @@ -11,7 +11,7 @@ This page applies to the following V1 API endpoints: * [Get list of latest issues](../../reference/reporting-api-v1.md#post-reporting-issues-latest) (`POST /reporting/issues/latest`) - not available for customers or partners in the `Snyk-US-02`, `Snyk-EU-01`, and `Snyk-AU-01` regions. * [List all aggregated issues](../../reference/projects-v1.md#post-org-orgid-project-projectid-aggregated-issues) (`POST /org/{orgId}/project/{projectId}/aggregated-issues`) -These APIs are subject to deprecation, and migrating to the REST Issues API immediately is highly recommended. The REST Issues API accommodates multiple regions. +These APIs are subject to deprecation, and Snyk highly recommends migrating to the REST Issues API immediately. The REST Issues API accommodates multiple regions. {% endhint %} ## Key benefits of the REST Issues API @@ -30,7 +30,7 @@ The REST Issues API provides: * Flexibility through new filters for tailored API responses. * Enhanced usability through better pagination and response handling, streamlining API interactions. -This migration guide is intended to facilitate a seamless transition by providing step-by-step instructions, code examples, and best practices to help you smoothly integrate with the new API. +This migration guide is intended to facilitate the transition by providing step-by-step instructions, code examples, and best practices to help you integrate with the new API. If you are using the V1 Issues endpoints, Snyk recommends that you migrate all your automation, API-based reporting, and integrations accordingly, by using the guidance provided here. diff --git a/developer-tools/snyk-api/api-endpoints-index-and-tips/README.md b/developer-tools/snyk-api/api-endpoints-index-and-tips/README.md index 0d69b68dac4e..f038ab03d516 100644 --- a/developer-tools/snyk-api/api-endpoints-index-and-tips/README.md +++ b/developer-tools/snyk-api/api-endpoints-index-and-tips/README.md @@ -19,7 +19,7 @@ See also the following sections on specific APIs: For additional information, see the [API support articles](https://support.snyk.io/s/topic/0TOPU00000BgWMv4AN/snyk-api). -This index includes the categories and names of REST GA and beta and V1 API endpoints, with the URL in the reference docs for each endpoint, and links to related information where available. REST is the default, and GA is the status unless beta is noted. V1 API is specified where applicable. This index is a work in progress; additional information is being added continually. +This index includes the categories and names of REST GA and beta and V1 API endpoints, with the URL in the reference docs for each endpoint, and links to related information where available. REST is the default, and GA is the status unless beta is noted. V1 API is specified where applicable. This index is a work in progress; Snyk adds additional information continually. ## AccessRequests (beta) @@ -337,7 +337,7 @@ The View Project History permission is needed to use this API. Projects can be Git repositories, Docker images, containers, configuration files, and much more. For more information, see [Snyk Projects](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/scan-with-snyk/snyk-projects); the page includes the [Targets definition](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/scan-with-snyk/snyk-projects#target). -A typical import starts with using the endpoint [Import targets](../reference/import-projects-v1.md#org-orgid-integrations-integrationid-import) to request a target to be processed. Then, use the endpoint [Get import job details](../reference/import-projects-v1.md#org-orgid-integrations-integrationid-import-jobid) to poll the Import Job AP I for further details on completion and resulting Snyk Projects. +A typical import starts with using the endpoint [Import targets](../reference/import-projects-v1.md#org-orgid-integrations-integrationid-import) to request a target to be processed. Then, use the endpoint [Get import job details](../reference/import-projects-v1.md#org-orgid-integrations-integrationid-import-jobid) to poll the Import Job API for further details on completion and resulting Snyk Projects. ### [Import targets](../reference/import-projects-v1.md#org-orgid-integrations-integrationid-import) and [Get import job details](../reference/import-projects-v1.md#org-orgid-integrations-integrationid-import-jobid) @@ -347,10 +347,10 @@ For information on when and how you can use Import targets, see [Gain visibility If a call to the Import targets endpoint fails, use [Get import job detail](../reference/import-projects-v1.md#org-orgid-integrations-integrationid-import-jobid)s to help determine why. There are two types of failures: -* The repository was rejected for processing, that is, HTTP status code 201 was not returned. This happens if there is an issue Snyk can see quickly for example: +* The repository was rejected for processing, that is, HTTP status code 201 was not returned. This happens if there is an issue Snyk can see quickly, for example: * The repository does not exist. * The repository is unreachable by Snyk because the token is invalid or does not have sufficient permissions; there is no default branch. -* The repository was accepted for processing, that is, the user got back HTTP status code 201 and a url to poll, but no projects were detected or some failed. This may occur because: +* The repository was accepted for processing, that is, the user got back HTTP status code 201 and a url to poll, but no projects were detected or some failed. This can occur because: * There are no Snyk-supported manifests in this repository. * The repository is archived and the Snyk API calls to fetch files fail. * The individual project or manifest had issues during processing. In this case Snyk returns success: false with a message in the log. @@ -610,11 +610,11 @@ More information: [Project type responses from the API](project-type-responses-f ### [Applying (project) attributes](../reference/projects-v1.md#org-orgid-project-projectid-attributes) -By using the API endpoint Applying attributes, you can set attributes for Snyk Projects including business criticality, lifecycle stage, and environment once the project has been created . To do so: +By using the API endpoint Applying attributes, you can set attributes for Snyk Projects including business criticality, lifecycle stage, and environment after the project is created. To do so: * Import the project using the API endpoint [Import targets](../reference/import-projects-v1.md#org-orgid-integrations-integrationid-import). * Get the status API ID from [Import targets](../reference/import-projects-v1.md#org-orgid-integrations-integrationid-import). -* Poll using the endpoint [Import job details](../reference/import-projects-v1.md#org-orgid-integrations-integrationid-import-jobid) until all imports have completed. +* Poll using the endpoint [Import job details](../reference/import-projects-v1.md#org-orgid-integrations-integrationid-import-jobid) until all imports are completed. * Parse the project IDs from the `projectURL` field. * Use the endpoint [Applying attributes](../reference/projects-v1.md#org-orgid-project-projectid-attributes) to set the project attributes. @@ -632,7 +632,7 @@ The Snyk V1 API endpoint [List all aggregated issues](../reference/projects-v1.m ### [List all Projects for an Org with the given Org ID](../reference/projects.md#orgs-org_id-projects) -The query-string parameter for types is optional. The endpoint does not enforce specific project types and will return `no matching projects` if you enter a string that does not match a requested project type. See [Project type responses from the AP](project-type-responses-from-the-api.md)I for a list of project types. +The query-string parameter for types is optional. The endpoint does not enforce specific project types and returns `no matching projects` if you enter a string that does not match a requested project type. See [Project type responses from the API](project-type-responses-from-the-api.md) for a list of project types. **More information:** [Slack app (for Jira integration)](../../integrations/jira-and-slack-integrations/slack-app.md) (Use: Find your Project ID);\ [Snyk Projects](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/scan-with-snyk/snyk-projects);\ @@ -670,7 +670,7 @@ The V1 Reporting endpoints support only Snyk legacy reporting, not the latest re The V1 Reporting API underlies Snyk legacy reporting. Using the V1 Reporting API, you can find answers to questions like how many issues your Organization has, or how many tests have been conducted in a given time period. -The rate limit is up to 70 requests per minute, per user. For all requests above the limit, the response will have the status code `429: Too many requests`, until requests stop for the duration of the rate-limiting interval (one minute). For more information see [Rate limiting for V1 API](../v1-api.md#rate-limiting). +The rate limit is up to 70 requests per minute, per user. For all requests above the limit, the response has the status code `429: Too many requests`, until requests stop for the duration of the rate-limiting interval (one minute). For more information, see [Rate limiting for V1 API](../v1-api.md#rate-limiting). **More information:** [Dependencies and licenses](https://app.gitbook.com/s/BJO0IZx7zB6bOkotxQP2/prevent/dependencies-and-licenses) @@ -832,7 +832,7 @@ To get a list of issues that have been fixed, use the endpoint [Get list of late ### [Get target by target ID](../reference/targets.md#orgs-org_id-targets-target_id) -This endpoint retrieves a list of Snyk Targets, which is used if you want to delete Targets by target ID. +This endpoint retrieves a list of Snyk Targets, which you use if you want to delete Targets by target ID. ### [Delete target by target ID](../reference/targets.md#orgs-org_id-targets-target_id-1) diff --git a/developer-tools/snyk-api/api-endpoints-index-and-tips/project-issue-paths-api-endpoints.md b/developer-tools/snyk-api/api-endpoints-index-and-tips/project-issue-paths-api-endpoints.md index 3221bc8f95d1..4a0fce3d62f3 100644 --- a/developer-tools/snyk-api/api-endpoints-index-and-tips/project-issue-paths-api-endpoints.md +++ b/developer-tools/snyk-api/api-endpoints-index-and-tips/project-issue-paths-api-endpoints.md @@ -2,7 +2,7 @@ The following provides information in addition to the information in the API Reference for the endpoints [List all project issue paths](../reference/projects-v1.md#org-orgid-project-projectid-issue-issueid-paths) and [List all project snapshot issue paths](../reference/snapshots-v1.md#org-orgid-project-projectid-history-snapshotid-issue-issueid-paths). -The `paths` endpoints provide details of the paths through which an issue has been introduced. +The `paths` endpoints provide details of the paths through which an issue is introduced. **Requests** to the `paths` endpoint are `GET` requests. The endpoints are available at the following URLs: @@ -51,4 +51,4 @@ In this example, an issue is introduced through two different versions of the `l The shortest path is provided first. If an issue applies to the Project itself, it appears as the only element in the path. For issues that apply to dependencies, each path starts with a direct dependency. -The `fixVersion` attribute is provided on the first element of each path when that path is upgradable. If the `version` attribute and `fixVersion` attributes are the same, then the upgrade will only involve re-locking transitive dependencies. +The `fixVersion` attribute is provided on the first element of each path when that path is upgradable. If the `version` attribute and `fixVersion` attributes are the same, then the upgrade involves only re-locking transitive dependencies. diff --git a/developer-tools/snyk-api/api-endpoints-index-and-tips/project-type-responses-from-the-api.md b/developer-tools/snyk-api/api-endpoints-index-and-tips/project-type-responses-from-the-api.md index 39f1830bc655..c4084aac0f50 100644 --- a/developer-tools/snyk-api/api-endpoints-index-and-tips/project-type-responses-from-the-api.md +++ b/developer-tools/snyk-api/api-endpoints-index-and-tips/project-type-responses-from-the-api.md @@ -2,7 +2,7 @@ The Snyk Project type, defined in the V1 API only as `the package manager of the project`, is returned from the [API v1 Projects endpoints](../reference/projects-v1.md) and from the endpoint [List all Projects for an Org with the given Org ID](../reference/projects.md#orgs-org_id-projects). -The following is a list of the possible `type` values that may be returned. +The following is a list of the possible `type` values that the API can return. `apk`\ `armconfig`\ diff --git a/developer-tools/snyk-api/api-endpoints-index-and-tips/scenarios-for-using-the-snyk-api.md b/developer-tools/snyk-api/api-endpoints-index-and-tips/scenarios-for-using-the-snyk-api.md index e17fbcea2539..5e94ec6f6781 100644 --- a/developer-tools/snyk-api/api-endpoints-index-and-tips/scenarios-for-using-the-snyk-api.md +++ b/developer-tools/snyk-api/api-endpoints-index-and-tips/scenarios-for-using-the-snyk-api.md @@ -26,7 +26,7 @@ Scenario: [assign-users-to-all-orgs](https://github.com/snyk-playground/cx-tools ### Add users to organizations at scale ahead of the first login -Scenario: [Provision users to Orgs via API](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/user-management/user-management-with-the-api/provision-users-to-organizations-using-the-api) +Scenario: [Provision users to Orgs using the API](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/user-management/user-management-with-the-api/provision-users-to-organizations-using-the-api) **Endpoint used:**\ [Provision a user to the organization](../reference/organizations-v1.md#org-orgid-provision) @@ -93,7 +93,7 @@ Scenario: [Broker-token-rotation](https://github.com/snyk-playground/cx-tools/bl [Add new integration](../reference/integrations-v1.md#org-orgid-integrations)\ [Update existing integration](../reference/integrations-v1.md#org-orgid-integrations-integrationid) (to enable Broker) -### For a specific event or time, disable all interactions (pull requests, tests) from Snyk to the code base (source control management repository) +### For a specific event or time, disable all interactions (pull requests, tests) from Snyk to the codebase (source control management repository) Scenario: [disable-all-interaction-from-snyk](https://github.com/snyk-playground/cx-tools/blob/main/scripts/disable-all-interaction-from-snyk.md) (complete procedure) diff --git a/developer-tools/snyk-api/authentication-for-api/README.md b/developer-tools/snyk-api/authentication-for-api/README.md index 9b549678662d..fa887de1fa0b 100644 --- a/developer-tools/snyk-api/authentication-for-api/README.md +++ b/developer-tools/snyk-api/authentication-for-api/README.md @@ -18,7 +18,7 @@ Enterprise users have [access to a personal access token under their profile](./ * Authenticating with the IDE manually * Running API calls one time, for example, to test something -Note that for free and team plan users, the personal token does not have access to the API and may be used for authenticating to IDE, CLI, and CI/CD integrations only. For details, see [Obtain and use your PAT token](https://app.gitbook.com/s/L7HyJj9FsK1W4pNt8Gzl/getting-started-guides/getting-started#obtain-and-use-your-snyk-api-token). +Note that for free and team plan users, the personal token does not have access to the API and can be used for authenticating to IDE, CLI, and CI/CD integrations only. For details, see [Obtain and use your PAT token](https://app.gitbook.com/s/L7HyJj9FsK1W4pNt8Gzl/getting-started-guides/getting-started#obtain-and-use-your-snyk-api-token). For additional information, see [Snyk PAT token permissions users can control](snyk-api-token-permissions-users-can-control.md). @@ -30,11 +30,11 @@ You can create a personal access token through your [account settings](https://a You can find your personal API token in your personal [account settings](https://app.snyk.io/account) after you register with Snyk and log in. In the **key** field, **Click to show**. Then highlight and copy the API key. -If you want a new API token, select **Revoke & Regenerate.** This will make the previous API token invalid. For details, see [Revoke and regenerate a Snyk API token](revoke-and-regenerate-a-snyk-api-token.md). +If you want a new API token, select **Revoke & Regenerate.** This makes the previous API token invalid. For details, see [Revoke and regenerate a Snyk API token](revoke-and-regenerate-a-snyk-api-token.md). ## Authenticating with a personal API token -When using the API directly, provide the API token in an `Authorization: token` header, as in the following example request, replacing `API_TOKEN` with your token +When using the API directly, provide the API token in an `Authorization: token` header, as in the following example request, replacing `API_TOKEN` with your token. ```bash curl --request GET \ @@ -54,4 +54,4 @@ curl --request GET \ --header "Authorization: bearer API_TOKEN" ``` -Otherwise, a `401 Unauthorized` error will be returned. +Otherwise, Snyk returns a `401 Unauthorized` error. diff --git a/developer-tools/snyk-api/authentication-for-api/personal-access-tokens-pats.md b/developer-tools/snyk-api/authentication-for-api/personal-access-tokens-pats.md index 06bd8ed45e87..1e89a2094873 100644 --- a/developer-tools/snyk-api/authentication-for-api/personal-access-tokens-pats.md +++ b/developer-tools/snyk-api/authentication-for-api/personal-access-tokens-pats.md @@ -4,34 +4,34 @@ A Personal Access Token (PAT) is a credential used to authenticate API, CLI, and IDE workflows. -At any given time, you can have up to three active PATs. This is primarily to allow for downtime-free rotation journeys, where the new token can be created ahead of the old one expiring. PATs can be named, and you can choose their expiration up to a maximum of 90 days ahead. Names are solely there to help you identify tokens; they have no functional impact. Users cannot create PATs that live for more than 90 days. +At any given time, you can have up to three active PATs. This allows for downtime-free rotation, where you can create the new token before the old one expires. You can name PATs and choose their expiration up to a maximum of 90 days ahead. Names help you identify tokens and have no functional impact. You cannot create PATs that live for more than 90 days. -PATs are revealed only upon creation, and never after this point. Users must ensure they safely store the token itself, as the only option after this will be to revoke and create another. +Snyk reveals PATs only upon creation, never after this point. You must safely store the token itself, because the only option afterward is to revoke and create another. -PATs can only be created through the UI, but can be revoked through the UI and API. +You can create PATs only through the UI, but you can revoke them through the UI and API. -You can see the name, created date and expiry for each token of a PAT (but not the token), and these details can be seen in the UI and through the API. +You can see the name, created date, and expiry for each PAT, but not the token, in the UI and through the API. -## Generating a new token (UI Only) +## Generating a new token (UI only) 1. In your account settings area, select the **Personal access tokens** tab.
-2. In the Name field, enter the name that you would like to provide your PAT. The names are solely there to help you distinguish between your PATs, and provide no other purpose. -3. To set an expiry date, select the Expiry drop-down and select a date for your PAT to expire. The maximum date you can pick is 90 days ahead. No PAT can be created with a longer expiry. +2. In the **Name** field, enter a name for your PAT. Names help you distinguish between your PATs and serve no other purpose. +3. To set an expiry date, select the **Expiry** dropdown and select a date for your PAT to expire. The maximum date you can pick is 90 days ahead. You cannot create a PAT with a longer expiry.
-4. Click **Generate new token**. You have generated your PAT and will see a window appear with your token. Click **Copy** to copy your token. This is the only time the Snyk Platform will share this token with you. You must store it in a secure and accessible location as you cannot retrieve it later. +4. Click **Generate new token**. Snyk generates your PAT and a window appears with your token. Click **Copy** to copy your token. This is the only time the Snyk Platform shares this token with you. You must store it in a secure and accessible location, because you cannot retrieve it later.
-5. If you have three PATs already, you will not be able to create another one. You must revoke one of them before being able to create any more. +5. If you already have three PATs, you cannot create another one. You must revoke one of them before you can create any more. ## Revoking a token 1. In your account settings area, select the **Personal access tokens** tab. -2. Next to the token that you would like to revoke, click Revoke. This results in your token being revoked. Token revocation cannot be reverted. +2. Next to the token you want to revoke, click **Revoke**. Snyk revokes your token. You cannot revert token revocation.
diff --git a/developer-tools/snyk-api/authentication-for-api/revoke-and-regenerate-a-snyk-api-token.md b/developer-tools/snyk-api/authentication-for-api/revoke-and-regenerate-a-snyk-api-token.md index 5683fef42253..7ff8a9dd6890 100644 --- a/developer-tools/snyk-api/authentication-for-api/revoke-and-regenerate-a-snyk-api-token.md +++ b/developer-tools/snyk-api/authentication-for-api/revoke-and-regenerate-a-snyk-api-token.md @@ -1,7 +1,7 @@ # Revoke and regenerate a Snyk API token {% hint style="warning" %} -When an API token is revoked, all integrations using that key immediately stop working. Proceed with caution! +When you revoke an API token, all integrations using that key immediately stop working. Proceed with caution. {% endhint %} If you suspect an API token has been leaked, it is good practice to revoke that token and generate a new one to use in its place. @@ -10,4 +10,4 @@ To revoke your Snyk user API token, navigate to your personal General Account Se ![API token screen, Revoke & Regenerate button](../../.gitbook/assets/account-settings-general-auth-token.png) -Click the **Revoke & Regenerate** button to revoke your API token. A new one will be generated in its place. You can now copy the newly generated API token and update integrations that used the old token. +Click **Revoke & Regenerate** to revoke your API token. Snyk generates a new one in its place. You can now copy the newly generated API token and update integrations that used the old token. diff --git a/developer-tools/snyk-api/authentication-for-api/snyk-api-token-permissions-users-can-control.md b/developer-tools/snyk-api/authentication-for-api/snyk-api-token-permissions-users-can-control.md index 25a0f026abc6..8010cd09d134 100644 --- a/developer-tools/snyk-api/authentication-for-api/snyk-api-token-permissions-users-can-control.md +++ b/developer-tools/snyk-api/authentication-for-api/snyk-api-token-permissions-users-can-control.md @@ -1,7 +1,7 @@ # Snyk API token permissions users can control -To set an API token to have read-only permissions so the user is unable to write to the platform, use a service account and set it to Group Viewer. +To set an API token to have read-only permissions so the user cannot write to the platform, use a service account and set it to Group Viewer. -Service accounts at the Organization level have only Organization Admin and Organization Collaborator permissions. Thus, to set a service account to view only, you must use a Group-level service account. +Service accounts at the Organization level have only Organization Admin and Organization Collaborator permissions. So, to set a service account to view only, you must use a Group-level service account. For more information see [Service accounts](https://app.gitbook.com/s/IgtgtomLQ2TUgSKOMSAm/service-accounts/service-accounts). diff --git a/developer-tools/snyk-api/reference/aibom.md b/developer-tools/snyk-api/reference/aibom.md index 8bb00b8202c9..a65b15ef02dc 100644 --- a/developer-tools/snyk-api/reference/aibom.md +++ b/developer-tools/snyk-api/reference/aibom.md @@ -1,4 +1,4 @@ -# AiBom +# AI-BOM {% hint style="info" %} This document uses the REST API. For more details, see the [Authentication for API](../authentication-for-api/) page. diff --git a/developer-tools/snyk-api/reference/dependencies-v1.md b/developer-tools/snyk-api/reference/dependencies-v1.md index 0c1291fd61dd..b46fa791b7a6 100644 --- a/developer-tools/snyk-api/reference/dependencies-v1.md +++ b/developer-tools/snyk-api/reference/dependencies-v1.md @@ -1,7 +1,7 @@ # Dependencies (v1) {% hint style="info" %} -This document uses the v1 API, which will eventually be deprecated, as further Snyk developments are now focused on the REST API. For more details, see the [v1 API](../v1-api.md). +This document uses the v1 API, which Snyk plans to deprecate, because Snyk now focuses development on the REST API. For more details, see the [v1 API](../v1-api.md). {% endhint %} Dependencies are packages or modules that your Projects depend on. diff --git a/developer-tools/snyk-api/reference/entitlements-v1.md b/developer-tools/snyk-api/reference/entitlements-v1.md index 5ecc16571747..ce1e84224824 100644 --- a/developer-tools/snyk-api/reference/entitlements-v1.md +++ b/developer-tools/snyk-api/reference/entitlements-v1.md @@ -1,7 +1,7 @@ # Entitlements (v1) {% hint style="info" %} -This document uses the v1 API, which will eventually be deprecated, as further Snyk developments are now focused on the REST API. For more details, see the [v1 API](../v1-api.md). +This document uses the v1 API, which Snyk plans to deprecate, because Snyk now focuses development on the REST API. For more details, see the [v1 API](../v1-api.md). {% endhint %} {% openapi src="../../.gitbook/assets/v1-api-spec.yaml" path="/org/{orgId}/entitlements" method="get" %} diff --git a/developer-tools/snyk-api/reference/import-projects-v1.md b/developer-tools/snyk-api/reference/import-projects-v1.md index d817dc77eb52..3fa4343cbcae 100644 --- a/developer-tools/snyk-api/reference/import-projects-v1.md +++ b/developer-tools/snyk-api/reference/import-projects-v1.md @@ -4,7 +4,7 @@ This document uses the v1 API, which will eventually be deprecated, as further Snyk developments are now focused on the REST API. For more details, see the [v1 API](../v1-api.md). {% endhint %} -You can use this API to import projects into Snyk. Projects imported can be Git repositories, Docker images, containers, configuration files, and much more. See the [Projects and Targets documentation](https://docs.snyk.io/scan-fix-and-prevent/scan-with-snyk/snyk-projects#target) for more information. A typical import would start with requesting a target to be processed and then polling the Import Job API for more details on completion of an import and the resulting Snyk Projects. +You can use this API to import Projects into Snyk. Imported Projects can be Git repositories, Docker images, containers, and configuration files. See the [Projects and Targets documentation](https://docs.snyk.io/scan-fix-and-prevent/scan-with-snyk/snyk-projects#target) for more information. A typical import starts by requesting a target to be processed, then polls the Import Job API for details about the completion of an import and the resulting Snyk Projects. {% openapi src="../../.gitbook/assets/v1-api-spec.yaml" path="/org/{orgId}/integrations/{integrationId}/import" method="post" %} [v1-api-spec.yaml](../../.gitbook/assets/v1-api-spec.yaml) diff --git a/developer-tools/snyk-api/reference/licenses-v1.md b/developer-tools/snyk-api/reference/licenses-v1.md index 465b0b9907ba..83b841883c1e 100644 --- a/developer-tools/snyk-api/reference/licenses-v1.md +++ b/developer-tools/snyk-api/reference/licenses-v1.md @@ -4,7 +4,7 @@ This document uses the v1 API, which will eventually be deprecated, as further Snyk developments are now focused on the REST API. For more details, see the [v1 API](../v1-api.md). {% endhint %} -**Note:** When you import or update Projects, changes will be reflected in the endpoint results after a one-hour delay. +**Note:** When you import or update Projects, the endpoint results reflect the changes after a one-hour delay. {% openapi src="../../.gitbook/assets/v1-api-spec.yaml" path="/org/{orgId}/licenses" method="post" %} [v1-api-spec.yaml](../../.gitbook/assets/v1-api-spec.yaml) diff --git a/developer-tools/snyk-api/reference/reporting-api-v1.md b/developer-tools/snyk-api/reference/reporting-api-v1.md index cfe3d999bf2f..7c5b0c3897f2 100644 --- a/developer-tools/snyk-api/reference/reporting-api-v1.md +++ b/developer-tools/snyk-api/reference/reporting-api-v1.md @@ -9,7 +9,7 @@ The endpoints in this category support only Snyk legacy reporting, not the lates {% endhint %} Using the Reporting API, you can find answers to questions like how many issues your Organization has, or how many tests have been conducted in a given time period. -The rate limit is up to **70 requests per minute, per user**. All requests above the limit will get a response with the status code `429 - Too many requests` until requests stop for the duration of the rate-limiting interval (one minute). +The rate limit is up to **70 requests per minute, per user**. Requests above the limit receive a response with the status code `429 - Too many requests` until requests stop for the duration of the rate-limiting interval (one minute). {% openapi src="../../.gitbook/assets/v1-api-spec.yaml" path="/reporting/issues" method="post" %} [v1-api-spec.yaml](../../.gitbook/assets/v1-api-spec.yaml) diff --git a/developer-tools/snyk-api/rest-api/about-the-rest-api.md b/developer-tools/snyk-api/rest-api/about-the-rest-api.md index 6c333e1423d7..5ad5e358880c 100644 --- a/developer-tools/snyk-api/rest-api/about-the-rest-api.md +++ b/developer-tools/snyk-api/rest-api/about-the-rest-api.md @@ -16,13 +16,13 @@ This API is available only over HTTPS. Calling this API over HTTP will yield a 4 The Snyk REST API generally adheres to the [JSON:API standard](https://jsonapi.org/), with some [caveats](https://github.com/snyk/sweater-comb/blob/main/docs/principles/jsonapi.md). JSON:API is an opinionated specification for how a client should request and modify resources and how a server should respond to requests. -When using the REST API, send all requests which contain data with the header: +When using the REST API, send all requests that contain data with the header: ``` Content-Type: application/vnd.api+json ``` -Otherwise a 400 "Bad Request" response will be returned. +Otherwise, Snyk returns a 400 "Bad Request" response. ```json HTTP/1.1 400 Bad Request @@ -42,9 +42,9 @@ HTTP/1.1 400 Bad Request ### Using versions dated on or after 2024-10-15 -The API Reference examples include `?version=text` as a placeholder, where `text` represents the required date-formatted version string. Snyk recommends using `2024-10-15` for the version number unless you are using an earlier version for a specific reason. You can use the current day's date; this will call the most recent version of the API. The format for the date is `YYYY-MM-DD`. +The API Reference examples include `?version=text` as a placeholder, where `text` represents the required date-formatted version string. Snyk recommends using `2024-10-15` for the version number unless you are using an earlier version for a specific reason. You can use the current day's date to call the most recent version of the API. The format for the date is `YYYY-MM-DD`. -### Using versions dated prior to 2024-10-15 +### Using versions dated before 2024-10-15 The following information applies to calling versions earlier than 2024-10-15. The Snyk REST API has per-endpoint version contracts. For information about the differences in GA versions, see the [API Changelog](../changelog.md). Each endpoint can have its own release and support lifecycle, independent of any other endpoint in the Snyk REST API. In its most explicit form, the endpoint version number includes a date and stability tree, for example: @@ -54,9 +54,9 @@ The following information applies to calling versions earlier than 2024-10-15. T This version number indicates that the requested endpoint should be at stability level `2023-11-27` or older `beta`. The possible stability levels are: -* `ga` - Generally Available, the default. Snyk will support these for at least six months after the next GA release. -* `beta` - Beta. Snyk will support these for at least three months after the next beta or GA release. -* `experimental` - Experimental. An experimental endpoint should be considered unstable and regarded as a tech preview. Experimental versions may introduce breaking changes and may be discontinued at any time. +* `ga` - Generally Available, the default. Snyk supports these for at least six months after the next GA release. +* `beta` - Beta. Snyk supports these for at least three months after the next beta or GA release. +* `experimental` - Experimental. Consider an experimental endpoint to be unstable and a tech preview. Experimental versions can introduce breaking changes and Snyk can discontinue them at any time. In the default case of Generally Available, there is no stability level specified in the version number itself, that is, only the date is present, for example: @@ -68,9 +68,9 @@ This means the requested endpoint should be 2023-11-27 or older on the Generally When the requested endpoint is at a specific stability level, Snyk serves the latest version, the version released on or before the requested date, or that stability or higher. For example, if the requested endpoint has a beta version at 2023-09-29 and GA version at 2024-01-23, and the requested endpoint is after 2024-01-23\~beta, Snyk resolves to the GA version. -Granular version controls enable Snyk to introduce progressive enhancements. These may require small or minor backward-incompatible changes. However, using granular version controls means Snyk can deliver rapid enhancements more quickly while supporting existing endpoints for a guaranteed period of time. +Granular version controls let Snyk introduce progressive enhancements. These can require small or minor backward-incompatible changes. However, using granular version controls means Snyk can deliver rapid enhancements more quickly while supporting existing endpoints for a guaranteed period of time. -After an endpoint is marked as deprecated, it will contain a `Sunset` header indicating the date at which that endpoint contract will no longer be supported. For example: +After an endpoint is marked as deprecated, it contains a `Sunset` header indicating the date on which that endpoint contract is no longer supported. For example: ``` Sunset: "2021-11-11" @@ -82,7 +82,7 @@ All endpoints in the Snyk REST API are paginated using _cursor-based_ pagination To mitigate the possibility of inconsistent results, by default, Snyk sorts by insertion order, so it is not possible to have items inserted on a prior page. However, if you specify the `sort` parameter, consistent pagination is no longer guaranteed. If you see inconsistent results, you can submit a new request. If consistent pagination is important to your workflow, use the default insertion sort order. -Whenever you receive an API response, it will contain appropriate links in the body of the response as follows: +Whenever you receive an API response, it contains appropriate links in the body of the response as follows: ```json { @@ -121,6 +121,6 @@ Errors conform to the JSON:API specification and include path-based information ## Rate limiting -There is a limit of **1620 requests per minute**, per API key. All requests above the limit will get a response with the status code `429` - `Too many requests` until requests stop for the duration of the rate-limiting interval (one minute). +There is a limit of **1620 requests per minute**, per API key. All requests above the limit get a response with the status code `429` - `Too many requests` until requests stop for the duration of the rate-limiting interval (one minute). -From time to time, Snyk may introduce new rate limits to maintain overall system health. This is not considered a breaking change. All clients are expected to handle the `429` responses correctly and such requests can be retried later safely. +From time to time, Snyk can introduce new rate limits to maintain overall system health. This is not considered a breaking change. All clients are expected to handle the `429` responses correctly, and such requests can be retried later safely. diff --git a/developer-tools/snyk-api/snyk-api.md b/developer-tools/snyk-api/snyk-api.md index 27f61b91c0fc..5b9777d30ffc 100644 --- a/developer-tools/snyk-api/snyk-api.md +++ b/developer-tools/snyk-api/snyk-api.md @@ -6,22 +6,22 @@ The majority of Snyk APIs are restricted to use by Enterprise plan customers onl For more information, see [Plans and pricing](https://snyk.io/plans). {% endhint %} -The Snyk API allows customers to integrate programmatically with Snyk. +The Snyk API lets customers integrate programmatically with Snyk. The [Snyk REST API ](rest-api/about-the-rest-api.md) and the [V1 API](v1-api.md) are available in the Snyk API [Reference](reference/). Additional endpoints are available in the [OAuth2 API reference](oauth2-api.md). ## Automating Snyk processes -The Snyk API enables developers to automate Snyk processes to accomplish their specific workflows, ensuring consistency in both developer experience and platform governance. +The Snyk API lets developers automate Snyk processes to accomplish their specific workflows, ensuring consistency in both developer experience and platform governance. Use the API when you want to customize, integrate, and automate Snyk processes as part of your specific workflows. ## Deciding to use the API, the CLI, or an SCM integration -You may decide to use an API rather than the CLI or an integration. When you decide, consider possible differences in the output for the API, the CLI, and integrations. +You can decide to use an API rather than the CLI or an integration. When you decide, consider possible differences in the output for the API, the CLI, and integrations. -For example, for many package managers, using the API will be less accurate than running the Snyk CLI as part of your build pipe or locally on your package. More than one version of a package may fit the requirements in manifest files. +For example, for many package managers, using the API is less accurate than running the Snyk CLI as part of your build pipe or locally on your package. More than one version of a package can fit the requirements in manifest files. Running the CLI locally tests the actual deployed code and creates an accurate snapshot of the dependency versions in use. The API infers a snapshot, with inferior accuracy. Note that the Snyk CLI can output machine-readable JSON (`snyk test --json`). -You can allow Snyk access to your development flow by using Snyk integrations. The advantage is having Snyk monitor every new pull request and suggest fixes by opening new pull requests. You can integrate Snyk directly with your source code management (SCM) tool, or by using a Broker to allow greater security and auditability. +You can allow Snyk access to your development flow by using Snyk integrations. The advantage is having Snyk monitor every new pull request and suggest fixes by opening new pull requests. You can integrate Snyk directly with your source code management (SCM) tool, or by using a Broker for greater security and auditability. diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/export-api-specifications-columns-and-filters.md b/developer-tools/snyk-api/using-specific-snyk-apis/export-api-specifications-columns-and-filters.md index e01110fd27e8..92321319d111 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/export-api-specifications-columns-and-filters.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/export-api-specifications-columns-and-filters.md @@ -1,6 +1,6 @@ # Export API: Specifications, columns, and filters -The Export API, which Snyk Analytics supports, makes it easier to export data by allowing users to create and manage CSV files. These files are safely stored by Snyk. Designed for efficiency and security, the Export API helps users organize and scale the export of large datasets, which is useful for reporting and analytics tasks. +The Export API, which Snyk Analytics supports, makes it easier to export data by letting users create and manage CSV files. Snyk stores these files safely. Designed for efficiency and security, the Export API helps users organize and scale the export of large datasets, which is useful for reporting and analytics tasks. You can use the Export API to export the Snyk `issues`, `usage events`, `pr checks`, `pr checks project adoption`, and `pr checks integration adoption` datasets in the scope of `Snyk Organization` or `Snyk Group`. Navigate to the [available columns and filters](export-api-specifications-columns-and-filters.md#available-columns-and-filters) section to see the full lists. @@ -48,7 +48,7 @@ GET /groups/{group_id}/export/{export_id} ### Data freshness -The data provided by the Export API service updates approximately every two hours. Given the data freshness, cyclic exports should not be scheduled more frequently than once every two hours. +The data provided by the Export API service updates approximately every two hours. Given the data freshness, do not schedule cyclic exports more frequently than once every two hours. ### Rate limits @@ -57,12 +57,12 @@ The API is limited by: * The export `POST` endpoint allows up to 20 export requests per hour, while the status checks and results retrieval are unlimited. {% hint style="info" %} -Given that the data is typically refreshed every two hours, Snyk anticipates that the applied rate limits will allow comfortable consumption. Snyk recommends requesting an export per relevant Group once in a few hours or on a daily basis. +Given that the data is typically refreshed every two hours, Snyk anticipates that the applied rate limits allow comfortable consumption. Snyk recommends requesting an export per relevant Group once in a few hours or on a daily basis. {% endhint %} ### Data retention -The exported CSV files will remain available for a period of three days. +The exported CSV files remain available for a period of three days. {% hint style="danger" %} While the files are accessible for three days, the self-signed link to retrieve the export results is available only for 60 minutes after its creation by default. Users can limit the link expiration by passing a value between 0 and 3600 to the `url_expiration_seconds` attribute. diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/issues-list-issues-for-a-package.md b/developer-tools/snyk-api/using-specific-snyk-apis/issues-list-issues-for-a-package.md index baf32227c905..a0dc1b53c6c6 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/issues-list-issues-for-a-package.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/issues-list-issues-for-a-package.md @@ -1,8 +1,8 @@ # Issues: List issues for a package -The Snyk REST API endpoint [List issues for a package](../reference/issues.md#orgs-org_id-packages-purl-issues) can be used to get all direct (non-transitive) vulnerabilities for a package using its `purl`, which is a uniform way of identifying software packages across ecosystems as defined in the [package URL specification](https://github.com/package-url/purl-spec). +Use the Snyk REST API endpoint [List issues for a package](../reference/issues.md#orgs-org_id-packages-purl-issues) to get all direct (non-transitive) vulnerabilities for a package using its `purl`, which is a uniform way of identifying software packages across ecosystems as defined in the [package URL specification](https://github.com/package-url/purl-spec). -When you pass a `purl` to the endpoint, Snyk will find any known vulnerabilities for that package and return them as part of the response body. +When you pass a `purl` to the endpoint, Snyk finds any known vulnerabilities for that package and returns them as part of the response body. The API is useful when you have a list of packages and want to retrieve a list of vulnerabilities for a package version. @@ -12,7 +12,7 @@ The examples on this page use [HTTPie](https://httpie.io/), but you can use any ## Supported purl types -The current release supports the following `purl` types: `apk`, `cargo`, `cocoapods`, `conan`, `composer`, `deb`, `gem`, `generic`, `golang`, `hex`, `npm`, `nuget`, `pub`, `pypi`, `rpm`, `swift` and `maven`. +The current release supports the following `purl` types: `apk`, `cargo`, `cocoapods`, `conan`, `composer`, `deb`, `gem`, `generic`, `golang`, `hex`, `npm`, `nuget`, `pub`, `pypi`, `rpm`, `swift`, and `maven`. If you are interested in support for additional ecosystems, submit a request to [Snyk Support](https://support.snyk.io). @@ -38,7 +38,7 @@ $ http \ version==2024-06-26 ``` -For operating system packages, a vendor must be specified in the namespace portion, and a `distro` qualifier must be specified. Supported vendors include: `debian`, `alpine`, `rhel`, `ubuntu`, `amzn`, `centos`, `oracle`, `rocky`, `sles`. +For operating system packages, you must specify a vendor in the namespace portion and a `distro` qualifier. Supported vendors include `debian`, `alpine`, `rhel`, `ubuntu`, `amzn`, `centos`, `oracle`, `rocky`, and `sles`. An example using a valid url-encoded operating system purl follows: @@ -240,7 +240,7 @@ Where applicable, **pagination links for the results** are included as follows: ## Troubleshooting for the List issues for a package endpoint -The following are **error states** that you may receive when using the API. If you experience issues not covered here or are having trouble resolving these, contact your Solution Engineer or Technical Success Manager, or submit a request to [Snyk Support](https://support.snyk.io). +The following are **error states** that you can receive when using the API. If you experience issues not covered here or are having trouble resolving these, contact your Solution Engineer or Technical Success Manager, or submit a request to [Snyk Support](https://support.snyk.io). **Invalid PURL**\ 400\ @@ -264,7 +264,7 @@ To get access, contact your Solutions Engineer or Technical Success Manager, or **Rate limit exceeded**\ 429\ -180 requests per minute per user are permitted on this API endpoint. If you exceed this volume, you will receive a 429 error response code. +180 requests per minute per user are permitted on this API endpoint. If you exceed this volume, you receive a 429 error response code. **Invalid pagination parameters**\ 400\ diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/sbom-apis/README.md b/developer-tools/snyk-api/using-specific-snyk-apis/sbom-apis/README.md index 8d945a0572e6..6723b158d06f 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/sbom-apis/README.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/sbom-apis/README.md @@ -1,6 +1,6 @@ # SBOM APIs -Information about how to use the following API endpoints is provided: +This section describes how to use the following API endpoints: * [Get a project’s SBOM document](rest-api-get-a-projects-sbom-document.md) * [Test an SBOM document for vulnerabilities](rest-api-endpoint-test-an-sbom-document-for-vulnerabilities.md) diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/sbom-apis/rest-api-endpoint-test-an-sbom-document-for-vulnerabilities.md b/developer-tools/snyk-api/using-specific-snyk-apis/sbom-apis/rest-api-endpoint-test-an-sbom-document-for-vulnerabilities.md index 658fbd6090c5..766f7bbce39a 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/sbom-apis/rest-api-endpoint-test-an-sbom-document-for-vulnerabilities.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/sbom-apis/rest-api-endpoint-test-an-sbom-document-for-vulnerabilities.md @@ -5,7 +5,7 @@ The Snyk REST API is available only for Enterprise plans. For more information, see [Plans and pricing](https://snyk.io/plans). -These endpoints are beta API versions. Some of the functionality may change. For more information, see the [Versioning](../../rest-api/about-the-rest-api.md#versioning) information for the REST API. +These endpoints are beta API versions. Some of the functionality can change. For more information, see the [Versioning](../../rest-api/about-the-rest-api.md#versioning) information for the REST API. {% endhint %} Snyk offers a [collection of API endpoints](https://apidocs.snyk.io/?version=2024-09-03%7Ebeta#post-/orgs/-org_id-/sbom_tests) to asynchronously test a software bill of materials (SBOM) document. You can use these endpoints to learn more about the vulnerabilities impacting your SBOM and its packages. @@ -89,7 +89,7 @@ curl --request POST \ You can check the status of the test at any time after the initial request. 1. Using the `job_id` returned from the initial request to the endpoint [Create an SBOM test run](https://apidocs.snyk.io/?version=2024-09-03%7Ebeta#post-/orgs/-org_id-/sbom_tests), make a request to the endpoint [Gets an SBOM test run status](https://apidocs.snyk.io/?version=2024-09-03%7Ebeta#get-/orgs/-org_id-/sbom_tests/-job_id-). -2. A successful request to this endpoint returns the status of your test, which can either be `processing` or `finished`. If the call is not successful, an error will be returned. +2. A successful request to this endpoint returns the status of your test, which can either be `processing` or `finished`. If the call is not successful, Snyk returns an error. ```bash curl --get \ @@ -116,9 +116,9 @@ The following response code indicates success. **201 Created** -The SBOM test run was successfully created. The response body contains the job ID of the test run. +Snyk successfully created the SBOM test run. The response body contains the job ID of the test run. -The following are error states that you may receive when using the API. If you experience issues not covered here or are having trouble resolving these, contact your Solutions Engineer or Technical Success Manager, or submit a request to [Snyk Support](https://support.snyk.io). +The following are error states that you can receive when using the API. If you experience issues not covered here or are having trouble resolving these, contact your Solutions Engineer or Technical Success Manager, or submit a request to [Snyk Support](https://support.snyk.io). **400 Bad Request** @@ -134,7 +134,7 @@ You do not have the permissions required to make the request. This can happen if **429 Too Many Requests** -Since the Snyk API is rate-limited, an excessive number of requests will eventually start to be rejected. You need to wait before making any further requests. +Since the Snyk API is rate-limited, an excessive number of requests eventually starts to be rejected. You need to wait before making any further requests. **500 Internal Server Error** diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/sbom-apis/rest-api-get-a-projects-sbom-document.md b/developer-tools/snyk-api/using-specific-snyk-apis/sbom-apis/rest-api-get-a-projects-sbom-document.md index 9d5292434071..79c0fecd0b7d 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/sbom-apis/rest-api-get-a-projects-sbom-document.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/sbom-apis/rest-api-get-a-projects-sbom-document.md @@ -9,7 +9,7 @@ Snyk offers the endpoint [Get a project's SBOM document](../../reference/sbom.md The SBOM document represents the latest state of a Project’s dependencies and their relationships. -SBOM documents can be generated in [CycloneDX](https://cyclonedx.org/) v1.4, v1.5, v1. 6 (JSON, XML) and [SPDX](https://spdx.dev/) v2.3 (JSON) formats. +You can generate SBOM documents in [CycloneDX](https://cyclonedx.org/) v1.4, v1.5, v1.6 (JSON, XML) and [SPDX](https://spdx.dev/) v2.3 (JSON) formats. ## How to generate the SBOM for a Project @@ -18,15 +18,15 @@ SBOM documents can be generated in [CycloneDX](https://cyclonedx.org/) v1.4, v1. 2. Determine the format you want for the SBOM you will generate.\ Available options are CycloneDX 1.4 JSON (`cyclonedx1.4+json`), CycloneDX 1.4 XML (`cyclonedx1.4+xml`), CycloneDX 1.5 JSON (`cyclonedx1.5+json`), CycloneDX 1.5 XML (`cyclonedx1.5+xml`), CycloneDX 1.6 JSON (`cyclonedx1.6+json`), CycloneDX 1.6 XML (`cyclonedx1.6+xml`) or SPDX v2.3 JSON (`spdx2.3+json`). 3. Using any HTTP client, for example, Postman or `curl`, make a request to the endpoint, specifying the latest stable version.\ - Note that the `format` parameter must be URL-encoded.\ - Example: To retrieve a CycloneDX 1.4 JSON document, set `format=cyclonedx1.4%2Bjson` on the query. Note that the example has a placeholder for the version; use version 2024-08-22 or later. + The `format` parameter must be URL-encoded.\ + Example: To retrieve a CycloneDX 1.4 JSON document, set `format=cyclonedx1.4%2Bjson` on the query. The example has a placeholder for the version; use version 2024-08-22 or later. `$ curl --location 'https://api.snyk.io/rest/orgs//projects//sbom?version=yyyy-mm-dd&format='`\ `--header 'Authorization: token '` ## Custom CycloneDX properties -An SBOM document generated by Snyk will include some Snyk-specific metadata about what has been exported. This is included in the `metadata.properties` section of the document when exported as CycloneDX. +An SBOM document generated by Snyk includes some Snyk-specific metadata about what has been exported. This is included in the `metadata.properties` section of the document when exported as CycloneDX.
Property NameDescription
snyk:org_idThe organization ID (UUID), if applicable
snyk:collection_idThe project collection’s ID (UUID), if applicable
snyk:project_idThe project’s ID (UUID), if applicable
snyk:target_idThe target’s ID (UUID), if applicable
@@ -36,9 +36,9 @@ The following response code indicates success. **200 OK** -The SBOM document was successfully generated. The response body contains the document in the requested format. +Snyk successfully generated the SBOM document. The response body contains the document in the requested format. -The following are **error states** that you may receive when using the API. If you experience issues not covered here or are having trouble resolving these, contact your Solution Engineer or Technical Success Manager or submit a request to [Snyk Support](https://support.snyk.io). +The following are **error states** that you can receive when using the API. If you experience issues not covered here or are having trouble resolving these, contact your Solution Engineer or Technical Success Manager, or submit a request to [Snyk Support](https://support.snyk.io). **401 Unauthorized** @@ -50,7 +50,7 @@ You do not have the permissions required to make the request. This can happen if **429 Too Many Requests** -Since the Snyk API is rate-limited, an excessive number of requests will eventually start to be rejected. Wait before making any further requests. +Since the Snyk API is rate-limited, an excessive number of requests eventually starts to be rejected. Wait before making any further requests. **500 Internal Server Error** diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/README.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/README.md index fc87549ab8a3..8addf0d49eda 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/README.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/README.md @@ -1,6 +1,6 @@ # How to use Snyk Apps APIs -This section provides an introduction to Snyk Apps and instructions for using the API and the CLI to create an App, for using the OAuth2 API to set up a Snyk App, and for using the API to manage Snyk Apps. +This section introduces Snyk Apps and provides instructions for using the API and the CLI to create an App, using the OAuth2 API to set up a Snyk App, and using the API to manage Snyk Apps. * [About Snyk Apps](about-snyk-apps.md) * [Prerequisites for Snyk Apps](prerequisites-for-snyk-apps.md) diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/about-snyk-apps.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/about-snyk-apps.md index f9ca4bce652c..2b1f98fce259 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/about-snyk-apps.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/about-snyk-apps.md @@ -1,8 +1,8 @@ # About Snyk Apps -Snyk Apps are integrations that extend the functionality of the Snyk platform, allowing you to create a Snyk experience to suit your specific needs. +Snyk Apps are integrations that extend the functionality of the Snyk platform, letting you create a Snyk experience to suit your specific needs. -For example, a Snyk App might automate Snyk [application security testing](https://snyk.io/learn/application-security/testing/) as part of a build tool. Another Snyk App might stream Snyk security testing results into an incident management tool. You can create your own reporting, metrics, or even a user management App. You can move your automated Snyk API scripts and transform them into a Snyk App, which will add a better UX/UI experience for your Snyk Organization users. +For example, a Snyk App might automate Snyk [application security testing](https://snyk.io/learn/application-security/testing/) as part of a build tool. Another Snyk App might stream Snyk security testing results into an incident management tool. You can create your own reporting, metrics, or even a user management App. You can move your automated Snyk API scripts and transform them into a Snyk App, which adds a better UX/UI experience for your Snyk Organization users. The easiest way to start building a new Snyk App is to clone the [Demo Snyk Apps ](https://github.com/snyk/snyk-apps-demo)GitHub repository. You can either modify the demo to suit your App design or use it as a base for creating your own Snyk App. See the [Snyk Apps blog post](https://snyk.io/blog/snyk-apps-beta-build-custom-apps-extend-snyk-security-into-workflows/) for more details. @@ -12,17 +12,17 @@ Snyk Apps are based on the [Snyk API](../../snyk-api.md) so that your integratio ## Integrating Apps with Snyk -The Snyk Apps platform uses an [OAuth 2.0](http://oauth.net/2/) authorization flow. This allows your Snyk App to get an access token to act on behalf of the user or Tenant, depending on the scopes you request. There are many OAuth 2.0 libraries available that will greatly simplify the integration. The [Snyk Apps Demo](https://github.com/snyk/snyk-apps-demo) uses the popular JavaScript library [passport.js](http://www.passportjs.org/packages/passport-oauth2/). +The Snyk Apps platform uses an [OAuth 2.0](http://oauth.net/2/) authorization flow. This lets your Snyk App get an access token to act on behalf of the user or Tenant, depending on the scopes you request. There are many OAuth 2.0 libraries available that greatly simplify the integration. The [Snyk Apps Demo](https://github.com/snyk/snyk-apps-demo) uses the popular JavaScript library [passport.js](http://www.passportjs.org/packages/passport-oauth2/). See the Snyk [OAuth2 API documentation](../../oauth2-api.md) for details. ## How do Apps connect? -When a Snyk App is created, it is set up to use `a specific context`, either `tenant` or `user`. Set this with the `context` field if you are creating a Snyk App with the API or the `--context` flag if you are using the CLI. If the `context` is not specified, a Snyk App will default to the `tenant` context, which is preferred unless your Snyk App specifically needs to perform operations as an individual user. +When you create a Snyk App, it is set up to use `a specific context`, either `tenant` or `user`. Set this with the `context` field if you are creating a Snyk App with the API or the `--context` flag if you are using the CLI. If you do not specify the `context`, a Snyk App defaults to the `tenant` context, which is preferred unless your Snyk App specifically needs to perform operations as an individual user. ### User context -Authorizing a Snyk App that has the `user` context grants the Snyk App access to perform actions on behalf of the user. The Snyk App will have access to the same set of Organizations and Groups as the installing user, as well as access to any new Snyk Organizations and Groups the user is added to. If the installing user deactivates their account, any installed apps having the `user` context that user has installed will lose access to Snyk. +Authorizing a Snyk App that has the `user` context grants the Snyk App access to perform actions on behalf of the user. The Snyk App has access to the same set of Organizations and Groups as the installing user, as well as access to any new Snyk Organizations and Groups the user is added to. If the installing user deactivates their account, any installed apps having the `user` context that user has installed lose access to Snyk. ### Tenant context @@ -48,13 +48,13 @@ You can also navigate directly to the [Authorized Snyk Apps page](https://app.sn ### Revoking a Snyk App from the management UI -On the Authorized Snyk Apps page, you will see a list of all the Snyk Apps that you have integrated and authorized. The page displays relevant information about each App, including the date when it was authorized. +On the Authorized Snyk Apps page, you see a list of all the Snyk Apps that you have integrated and authorized. The page displays relevant information about each App, including the date when it was authorized. -If you wish to revoke access for a particular Snyk App: +To revoke access for a particular Snyk App: * Locate the specific App in the list of authorized Apps. -* Click the **Revoke** button next to the App. +* Click **Revoke** next to the App. -Revoking access will prevent the App from further accessing your Snyk account and performing actions on your behalf. This gives you full control over which Apps can interact with your Snyk data and ensures that you can manage your App integrations securely. +Revoking access prevents the App from further accessing your Snyk account and performing actions on your behalf. This gives you full control over which Apps can interact with your Snyk data and ensures that you can manage your App integrations securely. By using the Snyk Apps management UI, you can maintain a clear overview of your authorized Apps and make adjustments to their access as needed, enhancing the security and customization of your Snyk experience. diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/create-a-snyk-app-using-the-snyk-api.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/create-a-snyk-app-using-the-snyk-api.md index 7c2dffc48572..413bc2e8f15e 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/create-a-snyk-app-using-the-snyk-api.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/create-a-snyk-app-using-the-snyk-api.md @@ -31,10 +31,10 @@ curl -L \ }' ``` -The request body should contain the details for your new App, including the `name`, `context`, `redirect_uris`, and [`scopes`](scopes-to-request.md). +The request body must contain the details for your new App, including the `name`, `context`, `redirect_uris`, and [`scopes`](scopes-to-request.md). The response includes details necessary to complete the integration: `client_id` and `client_secret`. Use these values with Snyk API endpoints within your App; consider storing them as part of the configuration of your App. {% hint style="info" %} -Never share the `client_secret` publicly, as it is used to authenticate your App. This is the only time you will see the `client_secret`, so keep it secure and private. If you lose it or if the secret is leaked, you can [rotate your App's clientSecret](manage-app-details.md#rotate-app-clientsecret). +Never share the `client_secret` publicly, as it is used to authenticate your App. This is the only time you see the `client_secret`, so keep it secure and private. If you lose it or if the secret is leaked, you can [rotate your App's clientSecret](manage-app-details.md#rotate-app-clientsecret). {% endhint %} diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/create-a-snyk-app-using-the-snyk-cli.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/create-a-snyk-app-using-the-snyk-cli.md index 13a9d8d49d0a..e108a0d6da2b 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/create-a-snyk-app-using-the-snyk-cli.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/create-a-snyk-app-using-the-snyk-cli.md @@ -48,11 +48,11 @@ A comma-separated list of scopes required by your Snyk App. This forms a list of `--context=` -The `context` your Snyk App will use when installed. +The `context` your Snyk App uses when installed. -Can be either `tenant` or `user`. The default is `tenant` if `context` is not specified. +Can be either `tenant` or `user`. The default is `tenant` if you do not specify `context`. -A Snyk App that has the `tenant` context will act as a bot user so it is not tied to any individual user and thus will persist even if the installing user leaves the Snyk Organization. In contrast, a Snyk App that has the `user` context will perform actions as the installing user. Specify the `user` context only if your Snyk App is performing operations that are specific to individual users. If there is any doubt, use `tenant`. +A Snyk App that has the `tenant` context acts as a bot user, so it is not tied to any individual user and persists even if the installing user leaves the Snyk Organization. In contrast, a Snyk App that has the `user` context performs actions as the installing user. Specify the `user` context only if your Snyk App is performing operations that are specific to individual users. If there is any doubt, use `tenant`. ## Sub-commands of `snyk apps` diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/manage-app-details.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/manage-app-details.md index da7296d6bef2..8254d1a1c5f7 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/manage-app-details.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/manage-app-details.md @@ -30,7 +30,7 @@ The `app_id` path parameter is the `id` in the response to a [`GET` request to t For details, see the endpoint [Delete an app by its App ID](../../reference/apps.md#orgs-org_id-apps-client_id-2). -Deleting an App revokes your App credentials and removes all of your App's installations. If you have active users, they will no longer be able to connect to Snyk through the App. +Deleting an App revokes your App credentials and removes all of your App's installations. If you have active users, they can no longer connect to Snyk through the App. ## Rotate App clientSecret @@ -62,18 +62,18 @@ Snyk recommends you adopt the following procedure when rotating your secrets: ### Create a clientSecret -It is recommended that in normal operation you periodically rotate your client secrets. To start the process, send the request body `{"mode": "create"}` to the endpoint which will create a new secret. The returned value of this call will be your app with the newly generated secret. Both the new secret and any existing secrets will be valid until they are manually replaced or deleted. You can also immediately replace a client secret. +In normal operation, Snyk recommends that you periodically rotate your client secrets. To start the process, send the request body `{"mode": "create"}` to the endpoint, which creates a new secret. The returned value of this call is your app with the newly generated secret. Both the new secret and any existing secrets are valid until they are manually replaced or deleted. You can also immediately replace a client secret. An App can have a maximum of two active secrets at any time. This endpoint fails with the error `cannot update secrets` if you try to call `create` when you already have the maximum number of secrets active. ### Replace a clientSecret -In the event that your App's `clientSecret` is leaked, you can generate a new one by using `{"mode": "replace"}`. +If your App's `clientSecret` is leaked, you can generate a new one by using `{"mode": "replace"}`. -When you replace your `clientSecret`, your current secret is immediately invalid. Your App will not be able to connect to Snyk until you update the App's configuration with the new secret. +When you replace your `clientSecret`, your current secret is immediately invalid. Your App cannot connect to Snyk until you update the App's configuration with the new secret. ### Delete a clientSecret To clean up any unused secrets, call the endpoint with `{"mode": "delete", "secret": "{clientSecret}"}` where `{clientSecret}` is your client secret that you want to delete. This action invalidates the secret immediately so it can no longer be used. -An App must have at least one active secret; calling delete with your last secret will fail. +An App must have at least one active secret. Calling delete with your last secret fails. diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/prerequisites-for-snyk-apps.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/prerequisites-for-snyk-apps.md index 31508a91691c..e3a6364f5bc2 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/prerequisites-for-snyk-apps.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/prerequisites-for-snyk-apps.md @@ -2,7 +2,7 @@ To create a Snyk App, you must have access to the Snyk API. To get started, follow the instructions to [authenticate for the API](../../authentication-for-api/). -You must also retrieve the ID of the Snyk Organization you intend the App to be owned by (your `orgId`). You can get the Organization ID from the Organization settings in the Snyk Web UI or by using the [List accesible organizations](../../reference/orgs.md#get-orgs) endpoint (`https://api.snyk.io/rest/orgs` ) with the Snyk API token in the Authorization header. +You must also retrieve the ID of the Snyk Organization you intend to own the App (your `orgId`). You can get the Organization ID from the Organization settings in the Snyk Web UI or by using the [List accessible organizations](../../reference/orgs.md#get-orgs) endpoint (`https://api.snyk.io/rest/orgs` ) with the Snyk API token in the Authorization header. {% hint style="info" %} Snyk Apps have first-class access to the API, regardless of whether users installing the App have paid for access or not. To take advantage of this feature, Apps must use API endpoints with the domain https://api.snyk.io/ rather than the deprecated `https://snyk.io/api/` to call the API within the App. diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/scopes-to-request.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/scopes-to-request.md index ca33acbcf0d4..c837b37be0f2 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/scopes-to-request.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/scopes-to-request.md @@ -2,12 +2,12 @@ Scopes define the permissions your Snyk App has to perform actions in a user’s account. When a user authorizes your Snyk App to access their Snyk account, they see the list of scopes the App is requesting and then decide whether or not they approve the connection. -When deciding which scopes your Snyk App will request, consider the actions your App will be performing. It may seem better to request every available scope, but users may refuse to install an App that asks for more permissions than needed. Also, a user installing your App will not be able to complete the authorization process if they do not have all the permissions matching the scopes the App is requesting. +When deciding which scopes your Snyk App requests, consider the actions your App performs. It can seem better to request every available scope, but users can refuse to install an App that asks for more permissions than needed. Also, a user installing your App cannot complete the authorization process if they do not have all the permissions matching the scopes the App is requesting. The following lists the **available scopes**. {% hint style="info" %} -`org.read` is a mandatory scope and should always be included. +`org.read` is a mandatory scope and must always be included. {% endhint %} | Scope | Description | @@ -26,7 +26,7 @@ The following lists the **available scopes**. | `org.project.ignore.edit` | Configure Project ignores | | `org.project.ignore.delete` | Permanently remove Project ignores | | `org.project.attributes.edit` | Apply and remove project attributes | -| `org.project.tag.edit` | Create, apply and remove Project tags | +| `org.project.tag.edit` | Create, apply, and remove Project tags | | `org.project.pr.create` | Create fix pull requests for Projects | | `org.project.pr.skip` | Skip failed security tests on pull requests by marking checks as successful | | `org.project.jira.issue.read` | View Jira issue information | diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/quick-setup.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/quick-setup.md index 0f51bf73de17..521cf95a42d2 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/quick-setup.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/quick-setup.md @@ -5,14 +5,14 @@ Snyk Apps uses the Authorization code with the Proof Key for Code Exchange (PKCE * Authorization: `/oauth2/authorize` * Token: `/oauth2/token` -The Snyk Apps authorization flow should work with any popular OAuth2-compatible client library, providing it supports PKCE. +The Snyk Apps authorization flow works with any popular OAuth2-compatible client library, providing it supports PKCE. The basic steps to set up a Snyk App using the OAuth2 API follow: 1. Generate a code verifier and code challenge. 2. Request the authorization code by directing the installing user to `/oauth2/authorize` with the generated code challenge, as well as all other required OAuth2 parameters. 3. The user is asked to approve the request, selecting the Organization or Group to which the Snyk App is being installed. -4. The user is returned to the redirect URI defined by the Snyk App with an authorization code. You have to extract the authorization code from the user request +4. The user is returned to the redirect URI defined by the Snyk App with an authorization code. You must extract the authorization code from the user request. 5. Exchange the authorization code for an access token and refresh the token pair, using the code verifier generated in the first step. The following pages go into more detail about each step. diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/retrieve-the-app-org-ids.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/retrieve-the-app-org-ids.md index d0be440c6b7d..bb63b7e815d4 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/retrieve-the-app-org-ids.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/retrieve-the-app-org-ids.md @@ -1,6 +1,6 @@ # Retrieve the App Org IDs -Users may connect with a single Organization or a single Group. Most of the Snyk API endpoints require an `orgid` in the path, which is used for authorizing the action being performed. +Users can connect with a single Organization or a single Group. Most of the Snyk API endpoints require an `orgid` in the path, which is used for authorizing the action being performed. To retrieve the `orgid` that is used by your App, send a GET request to the `orgs` endpoint, [List accessible organizations](../../../reference/orgs.md#get-orgs) at the following URL: diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/revoke-compromised-refresh-tokens.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/revoke-compromised-refresh-tokens.md index f70b7b326053..89fa92bd178c 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/revoke-compromised-refresh-tokens.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/revoke-compromised-refresh-tokens.md @@ -1,8 +1,8 @@ # Revoke compromised refresh tokens -If you believe that a refresh token has been compromised then it is recommended that you revoke that token as soon as possible. This is to prevent misuse of the token to gain access to Snyk systems. +If you believe that a refresh token has been compromised, Snyk recommends that you revoke that token as soon as possible. This prevents misuse of the token to gain access to Snyk systems. -To do this issue a POST request to the revoke endpoint: +To do this, issue a POST request to the revoke endpoint: ``` https://api.snyk.io/oauth2/revoke @@ -16,4 +16,4 @@ token=(refresh token to be revoked) &client_secret=(clientSecret from the app creation) ``` -This endpoint will return an empty response on success and the given refresh token will immediately be revoked. +This endpoint returns an empty response on success, and the given refresh token is immediately revoked. diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/set-up-the-authorization-code-exchange.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/set-up-the-authorization-code-exchange.md index a0b4b1d3a8b1..d7f546babfd5 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/set-up-the-authorization-code-exchange.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/set-up-the-authorization-code-exchange.md @@ -21,8 +21,8 @@ grant_type=authorization_code The response includes details necessary for your app to communicate with the Snyk APIs: `access_token` and `refresh_token`, as well as their expiry. -Both tokens must be stored in a secured data store. It is highly recommended to encrypt the values before storing them. +Both tokens must be stored in a secured data store. Snyk highly recommends that you encrypt the values before storing them. -The `access_token` will be used for future API calls on behalf of the user and Organization. The access-token has a much shorter lifespan than the `refresh_token`. +The `access_token` is used for future API calls on behalf of the user and Organization. The access-token has a much shorter lifespan than the `refresh_token`. -The `refresh_token` can be used a single time to get a new `access_token` when it expires. In other words, the `refresh_token` will no longer be usable if its own expiry time passes or if it is used to refresh the `access_token`. +The `refresh_token` can be used a single time to get a new `access_token` when it expires. In other words, the `refresh_token` is no longer usable if its own expiry time passes or if it is used to refresh the `access_token`. diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/set-up-the-refresh-token-exchange.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/set-up-the-refresh-token-exchange.md index 2583c5e85725..4944eed185f0 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/set-up-the-refresh-token-exchange.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/set-up-the-refresh-token-exchange.md @@ -1,6 +1,6 @@ # Set up the refresh token exchange -As the `access_token` will expire in a short time, the App will need to frequently request a new one using the `refresh_token`. This must be done while the `refresh_token` itself is still valid. +As the `access_token` expires in a short time, the App needs to frequently request a new one using the `refresh_token`. This must be done while the `refresh_token` itself is still valid. To exchange for a fresh `access_token`, make a POST request to the token endpoint: @@ -19,4 +19,4 @@ grant_type=refresh_token The response to this call provides a new `access_token`, `refresh_token`, and expiry for each. -Be sure to store the new `refresh_token`, as the old one is now invalid. Be aware that concurrent calls to this endpoint may result in refresh tokens being marked invalid unexpectedly, make sure to only request a new refresh token pair once per given refresh token. If this process fails then a user will need to perform the authorization flow again. +Be sure to store the new `refresh_token`, as the old one is now invalid. Be aware that concurrent calls to this endpoint can result in refresh tokens being marked invalid unexpectedly. Request a new refresh token pair only once per given refresh token. If this process fails, a user needs to perform the authorization flow again. diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/set-up-to-authorize-users.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/set-up-to-authorize-users.md index d529e7d75a5a..5003cb112c0e 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/set-up-to-authorize-users.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/set-up-a-snyk-app-using-the-oauth2-api/set-up-to-authorize-users.md @@ -2,11 +2,11 @@ When users connect their Snyk account to your App, they must authorize access to their chosen Organization or Group and approve the requested scopes. This process starts when you direct users to the Snyk Apps authorization web page and pass the appropriate parameters: `https://app.snyk.io/oauth2/authorize?response_type=code&client_id={clientId}&redirect_uri={redirectURI}&state={state}&code_challenge={codeChallenge}&code_challenge_method=S256` -If your Snyk App is configured with multiple redirect URIs, passing `redirect_uri` will select which redirect URI to use. The given value must match exactly one of the values that are defined for your Snyk App. If not specified the first value defined on the Snyk App is used. +If your Snyk App is configured with multiple redirect URIs, passing `redirect_uri` selects which redirect URI to use. The given value must match exactly one of the values that are defined for your Snyk App. If you do not specify it, the first value defined on the Snyk App is used. The `state` value is used to carry any App-specific state from this `/authorize` call to the callback on the `redirect_uri` (such as a user’s id). It must be verified in your callback to [prevent CSRF attacks](https://datatracker.ietf.org/doc/html/rfc6749#section-10.12). -The `code_challenge` value is a URL-safe base64-encoded string of the SHA256 hash of a generated code verifier. This code verifier must be a highly randomised string generated on the app side before calling `/authorize`, the code verifier is sent when exchanging the returned authorization code for an access token. For more information see [Proof Key for Code Exchange by OAuth Public Clients](https://datatracker.ietf.org/doc/html/rfc7636). Note that Snyk Apps only supports `S256` for the code challenge method. +The `code_challenge` value is a URL-safe base64-encoded string of the SHA256 hash of a generated code verifier. This code verifier must be a highly randomized string generated on the app side before calling `/authorize`. The code verifier is sent when exchanging the returned authorization code for an access token. For more information, see [Proof Key for Code Exchange by OAuth Public Clients](https://datatracker.ietf.org/doc/html/rfc7636). Snyk Apps support only `S256` for the code challenge method.
Authorize access to Organization

Authorize access to Organization

diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/README.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/README.md index e4c4bed06862..0630cb704d06 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/README.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/README.md @@ -1,10 +1,10 @@ # Tutorial: create a Snyk App -In this tutorial, we'll create a simple Snyk App using TypeScript to show users a list of their projects within Snyk. +In this tutorial, we'll create a Snyk App using TypeScript to show users a list of their Projects in Snyk. ## Prerequisites -* NodeJS +* Node.js * A Snyk account ## Configure the basics @@ -19,7 +19,7 @@ Now that we have a place to save dependency information, use `npm` to install Ty npm install typescript --save-dev ``` -At this point, TypeScript has been installed, but we'll need a configuration file to provide compilation options to the `tsc` binary. Create a TypeScript configuration file called `tsconfig.json` in the root of the project. Use the template that follows: +At this point, TypeScript is installed, but we'll need a configuration file to provide compilation options to the `tsc` binary. Create a TypeScript configuration file called `tsconfig.json` in the root of the project. Use the template that follows: ```json { @@ -53,7 +53,7 @@ mkdir ./src ## Test it out -Now that we have the basic parameters in place, we'll create a simple Hello World by creating the file `./src/index.ts`. +Now that we have the basic parameters in place, we'll create a Hello World by creating the file `./src/index.ts`. ``` const world = 'world'; diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/configuring-express.js.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/configuring-express.js.md index 80b70f613706..fecab26ce83e 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/configuring-express.js.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/configuring-express.js.md @@ -2,7 +2,7 @@ ## Set up Express to serve the application -So far, we've configured our project directories, set the TypeScript compiler options, and created a very simple TypeScript application to print out `Hello World`. +So far, we've configured our project directories, set the TypeScript compiler options, and created a TypeScript application to print out `Hello World`. In this section, we'll expand our application by adding `ExpressJS` to serve our application and configure middleware to handle different kinds of requests. @@ -32,7 +32,7 @@ npm install --save-dev \ > This tutorial makes use of Object-oriented programming (OOP) concepts. If you aren't familiar with OOP, refer to [this MDN page](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Object-oriented\_JS) for a brief primer. -To begin, create a new file to house the application code we'll be working on in this portion of the tutorial. If you've just come from the previous module where we configured a simple 'Hello world' app, you can leave your `index.ts` file alone; we'll come back to it. +To begin, create a new file to house the application code we'll be working on in this portion of the tutorial. If you have come from the previous module where we configured a 'Hello world' app, you can leave your `index.ts` file alone. We'll come back to it. ```bash touch ./src/app.ts @@ -40,9 +40,9 @@ touch ./src/app.ts Add an import statement for Express and its TypeScript type / interface definitions at the top of the new file (`./src/app.ts`), then create an `App` class to house all the related functions and configuration required to run our application. -The class constructor will initialize Express on port 3000 when the class is instantiated. We'll create a private function `listen()` for the constructor to call which will handle the actual start of the Express server. +The class constructor initializes Express on port 3000 when the class is instantiated. We'll create a private function `listen()` for the constructor to call, which handles the start of the Express server. -Don't forget to export the class at the bottom, we'll need it later. +Remember to export the class at the bottom. We'll need it later. ```typescript import express from 'express'; @@ -71,15 +71,15 @@ class App { export default App; ``` -Test the new file using `npx tsc` and ensure an `app.js` file is successfully created in the `./dist` directory. If there are no errors, great! You're ready to start adding routes. +Test the new file using `npx tsc` and ensure an `app.js` file is created in the `./dist` directory. If there are no errors, you're ready to start adding routes. ## Basic routes Express will listen to any request on our given port, but it doesn't know _what to do_ when it receives a request. We need to tell Express _how_ to handle the various types of requests it might receive. How you configure this depends heavily on the architecture of your application, and which routes / pages you expect your app to respond to when hit. -For this tutorial, we'll keep things simple. Since our end goal is to provide users with a list of their projects within Snyk, assume we'll want at least two routes: an index route (`/`) to handle any initial connections and a projects route (`/projects`) to present the data from Snyk. +For this tutorial, we'll keep things simple. Since our end goal is to provide users with a list of their Projects in Snyk, assume we'll want at least two routes: an index route (`/`) to handle any initial connections and a projects route (`/projects`) to present the data from Snyk. -To keep our project organized, we'll create a `routes` directory to house our collection of routes and we'll give each route its own subdirectory which will contain the main controller file for the route and any extras we might need. +To keep our project organized, we'll create a `routes` directory to house our collection of routes, and we'll give each route its own subdirectory that contains the main controller file for the route and any extras we need. We'll focus on the index route for this module: @@ -88,9 +88,9 @@ mkdir -p ./src/routes/index touch ./src/routes/index/indexController.ts ``` -Before we start working on the index controller, we should also create a [TypeScript interface](https://www.typescriptlang.org/docs/handbook/interfaces.html) definition to describe a common shape for controller data. This will help keep our controllers consistent and allow TypeScript to warn us early if a controller is missing something important. +Before we start working on the index controller, we should also create a [TypeScript interface](https://www.typescriptlang.org/docs/handbook/interfaces.html) definition to describe a common shape for controller data. This keeps our controllers consistent and lets TypeScript warn us early if a controller is missing something important. -Let's use a similar separation pattern to the one we decided on for routes. Since interface definitions in TypeScript are typically self-contained and descriptive, we'll skip creating a directory for each definition and store any interface files we create as siblings: +Let's use a separation pattern similar to the one we decided on for routes. Since interface definitions in TypeScript are typically self-contained and descriptive, we'll skip creating a directory for each definition and store any interface files we create as siblings: ```bash mkdir -p ./src/interfaces @@ -139,7 +139,7 @@ Here we've imported a handful of TypeScript type/interface definitions as well a We've set our `IndexController` to respond to `/` requests with the `indexPage` function, which renders 'index', but our App class doesn't yet have a way to register the route when it instantiates. Let's go back to our `./src/app.ts` file and add an `initRoutes()` function to establish that. -We'll also modify the App's constructor function to take an array of Controllers and a port value as arguments. +We'll also modify the constructor function for the App to take an array of Controllers and a port value as arguments. Edit `./src/app.ts` and update the contents to match the following: @@ -180,15 +180,15 @@ export default App; ## Running the Express server -So far, we've created an App class that, when instantiated, will run an Express server that responds to requests at `/` and we've added an interface definition to ensure all our controllers follow the same data pattern. +So far, we've created an App class that, when instantiated, runs an Express server that responds to requests at `/`, and we've added an interface definition to ensure all our controllers follow the same data pattern. -Let's run our project and try it out! +Let's run our project and try it out. -If you run the compiled `./dist/app.js` at this point, nothing interesting happens. This is because we've yet to instantiate our exported class. In the previous module, we initialized our `package.json`. During that command, we were presented with questions pertaining to our app. One of the questions asked what our project's entrypoint was. If you were following along and selected the default value, this should be set to `index.js` in your `package.json`. This entrypoint is where we'll instantiate the App class. +If you run the compiled `./dist/app.js` at this point, nothing interesting happens. This is because we've yet to instantiate our exported class. In the previous module, we initialized our `package.json`. During that command, questions about our app appeared. One of the questions asked what our project's entrypoint was. If you were following along and selected the default value, this should be set to `index.js` in your `package.json`. This entrypoint is where we'll instantiate the App class. Edit `./src/index.ts` (where we had that hello world code) and clear it out if there's any content left over, then add import statements for our App and other required objects. -Our entrypoint will only do one thing, instantiate the App class with the `new` keyword: +Our entrypoint does only one thing, instantiate the App class with the `new` keyword: ```typescript import IndexController from './routes/indexController'; @@ -202,16 +202,14 @@ new App( ); ``` -That's it! - -Build the project using `npx tsc` then run the compiled entrypoint with `node`: +Build the project using `npx tsc`, then run the compiled entrypoint with `node`: ```bash npx tsc && node ./dist/index.js ``` -Provided everything was successful, you'll see the message `App listening on port: 3000` in the console. +When everything is successful, you'll see the message `App listening on port: 3000` in the console. -Now visit http://localhost:3000 in your browser or use curl to check the response. If you see `index route!`, then congratulations! Express is serving the application and responding to routes! +Now visit http://localhost:3000 in your browser or use curl to check the response. If you see `index route!`, Express is serving the application and responding to routes. -In the next module of this tutorial, we'll dive deeper into routes and authentication and start working with the Snyk API. +In the next module of this tutorial, we'll go deeper into routes and authentication and start working with the Snyk API. diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/register-the-app-and-configure-user-authorization.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/register-the-app-and-configure-user-authorization.md index 33a7f2fe9d3a..b3dcf363238b 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/register-the-app-and-configure-user-authorization.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/register-the-app-and-configure-user-authorization.md @@ -1,10 +1,10 @@ # Register the App and configure user authorization -In the previous sections of this tutorial, we set up our TypeScript project, added an Express server, and configured some basic routing. We'll be building on top of the project we created in the previous sections. It is highly recommended that you complete the previous portions of this tutorial before continuing if you have not done so already. +In the previous sections of this tutorial, we set up our TypeScript project, added an Express server, and configured some basic routing. We'll be building on top of the project we created in the previous sections. Snyk recommends that you complete the previous portions of this tutorial before continuing if you have not done so already. ## Creating and registering a Snyk App -We've made some good progress with our TypeScript application so far, but at the moment, that's all it is - a TypeScript application. To turn it into a bonafide Snyk App, we'll need to register our project as a new App using Snyk's API +We've made good progress with our TypeScript application so far, but at the moment, that's all it is - a TypeScript application. To turn it into a bonafide Snyk App, we'll need to register our project as a new App using the Snyk API. ### Prerequisites @@ -14,7 +14,7 @@ We've made some good progress with our TypeScript application so far, but at the ### Obtaining an `orgid` -There are two methods for retrieving an `orgid`. The first is to log in to your Snyk account and visit the Organization settings page of the Organization for which you wish to retrieve the ID. The path to the Organization settings page is: +There are two methods for retrieving an `orgid`. The first is to log in to your Snyk account and visit the Organization settings page of the Organization for which you want to retrieve the ID. The path to the Organization settings page is: ``` https://app.snyk.io/org/{your-org-name}/manage/settings @@ -28,21 +28,21 @@ Snyk Apps have first-class access to the API, regardless of whether users instal ### Registering our app with Snyk -Registration of a new Snyk App is performed through a simple POST request to Snyk's API. While we could configure the App we've been building throughout this tutorial to perform the request, we'll instead make the request directly using `curl` to avoid creating a function that can only be run a single time. +You register a new Snyk App through a POST request to the Snyk API. While we could configure the App we've been building throughout this tutorial to perform the request, we'll instead make the request directly using `curl` to avoid creating a function that can only be run a single time. The body of the request requires the following details: * `name`: The name of the Snyk App -* `redirectUris`: The accepted callback location(s) during end-user authentication -* `scopes`: The account permissions the Snyk App will ask a user to grant +* `redirectUris`: The accepted callback locations during end-user authentication +* `scopes`: The account permissions the Snyk App asks a user to grant -A note on scopes: Once registered, Snyk Apps scopes cannot currently be changed. The only recourse is deleting the Snyk App using the [Delete App](../../../reference/apps.md#orgs-org_id-apps-creations-app_id-2) API endpoint and registering the app again as a new Snyk App. +A note on scopes: after registration, Snyk Apps scopes cannot be changed. The only recourse is deleting the Snyk App using the [Delete App](../../../reference/apps.md#orgs-org_id-apps-creations-app_id-2) API endpoint and registering the app again as a new Snyk App. -At the time of this writing, **Snyk Apps is still in beta**. At the moment, t**here is only one available scope: `apps:beta`**. This scope **allows** the App to test and monitor existing projects, as well as read information about Snyk Organizations, existing Projects, issues, and reports. +At the time of this writing, **Snyk Apps is still in beta**. There is only one available scope: **`apps:beta`**. This scope **lets** the App test and monitor existing Projects, as well as read information about Snyk Organizations, existing Projects, issues, and reports. -One of the **limitations of the Snyk Apps beta** is that **a Snyk App may be authorized only by users who have administrator access to the Organization to which the Snyk App is registered**. +One of the **limitations of the Snyk Apps beta** is that **only users who have administrator access to the Organization to which the Snyk App is registered can authorize a Snyk App**. -With your API token and `orgid` in hand, perform the following command in your terminal, substituting the values as necessary. For this tutorial, use `http://localhost:3000/callback` for the `redirectUris` value. +With your API token and `orgid` in hand, run the following command in your terminal, substituting the values as necessary. For this tutorial, use `http://localhost:3000/callback` for the `redirectUris` value. {% hint style="info" %} You can avoid inputting your API Token and other secrets directly into your shell by adding them as export statements in a file and sourcing the file to set them as environment variables. @@ -63,13 +63,13 @@ curl --include \ The response from Snyk contains two important values needed to complete our Snyk App's integration: `clientId` and `clientSecret`. Store these values somewhere safe. This is the only time you will see your `clientSecret` from Snyk. As a warning, **never share your `clientSecret` publicly**. This is used to authenticate your App with Snyk. -Now that we've registered the app as a Snyk App, we can start adjusting our TypeScript project to allow users to authorize it. +Now that we've registered the app as a Snyk App, we can start adjusting our TypeScript project to let users authorize it. ## User authorization with a Snyk App -User authentication for Snyk Apps is done by way of a webpage URL containing query parameters that match up with our Snyk App's data. We'll need to replace the query parameter values in this URL and send users to the final link in a web browser. From there they can grant account access to the Snyk App. +User authentication for Snyk Apps works by way of a webpage URL containing query parameters that match up with the data for our Snyk App. We'll need to replace the query parameter values in this URL and send users to the final link in a web browser. From there they can grant account access to the Snyk App. -After access has been provisioned, the user will be kicked back to our app's registered `callbackURL`, which we defined as `http://localhost:3000/callback`. +After access is provisioned, the user returns to our app's registered `callbackURL`, which we defined as `http://localhost:3000/callback`. Essentially, our app needs to generate a link like the following and then send the user to it when it's time to authorize: @@ -77,13 +77,13 @@ Essentially, our app needs to generate a link like the following and then send t https://app.snyk.io/oauth2/authorize?response_type=code&client_id={clientId}&redirect_uri={redirectURI}&state={state}&code_challenge={codeChallenge}&code_challenge_method=S256 ``` -Though some of the query parameters may be somewhat obvious, we will go over them. We're going to modify our Snyk App to generate this URL for our users. +Though some of the query parameters may be obvious, we will go over them. We're going to modify our Snyk App to generate this URL for our users. -* `redirect_uri`: Optional values must match one of the values sent with our registration command from [Registering our app with Snyk](register-the-app-and-configure-user-authorization.md#registering-our-app-with-snyk). If not passed then the first value on the Snyk App is assumed. -* `state`: This is used to carry any App-specific state from this `/authorize` call to the callback on the `redirect_uri` (such as a user's ID). It must be verified in our callback to [prevent CSRF attacks](https://datatracker.ietf.org/doc/html/rfc6749#section-10.12). +* `redirect_uri`: Optional values must match one of the values sent with our registration command from [Registering our app with Snyk](register-the-app-and-configure-user-authorization.md#registering-our-app-with-snyk). If not passed, the first value on the Snyk App is assumed. +* `state`: This carries any App-specific state from this `/authorize` call to the callback on the `redirect_uri` (such as a user's ID). You must verify it in our callback to [prevent CSRF attacks](https://datatracker.ietf.org/doc/html/rfc6749#section-10.12). * `code_challenge`: A URL-safe base64-encodes string of the SHA256 hash of a code verifier. The code verifier is a highly randomized string stored alongside the app side before calling `/authorize`, then sent when exchanging the returned authorization code for a token pair. This is part of Proof Key for Code Exchange (PKCE) which helps prevent authorization code interception attacks. -Once a connection is complete, the user is redirected to the provided redirect URI (our `/callback` route in this case) with query string parameters `code` and `state` added on, which are necessary for the next steps of authorization. +After a connection is complete, the user is redirected to the provided redirect URI (our `/callback` route in this case) with query string parameters `code` and `state` added on, which are necessary for the next steps of authorization. That next step involves taking the authorization code received as a query parameter in the response of the previous step and turning it into an _access token_. To do this, a Snyk App makes a POST request to the token endpoint: `https://api.snyk.io/oauth2/token`. That POST request needs some specific data in its request body, including the _authorization code_, `client id`, `client secret`, `code_verifier` and so on. @@ -106,9 +106,9 @@ Based on the preceding information, our Snyk App has some new requirements. We w 5. Refresh those authorization tokens. 6. Handle errors and inform users of authorization success or failure. -From here on, we'll be doing a lot of refactoring in our Snyk App and we'll be jumping into a number of different files. To help make the process easier to follow, this tutorial uses the convention of adding a commented filepath to the first line of code snippets, describing where they belong. In your own code; these comments aren't necessary. +From here on, we'll be doing a lot of refactoring in our Snyk App and we'll be jumping into a number of different files. To help make the process easier to follow, this tutorial uses the convention of adding a commented filepath to the first line of code snippets, describing where they belong. In your own code, these comments aren't necessary. -We'll also add a number of new packages to help address our new requirements. For convenience, go ahead and run the following in the root of your Project: +We'll also add a number of new packages to help address our new requirements. For convenience, run the following in the root of your Project: ```bash npm install --save passport \ @@ -138,7 +138,7 @@ npm install --save-dev @types/cryptr \ #### Application configuration -Application config (for example, client secrets, api tokens, other config, and so on) should generally be stored securely and kept outside of the App itself. However, for brevity, this tutorial adds the configuration info as exportable constants in the `App.ts` file and leaves the actual implementation details to you. These are values that the Snyk App references in many different places. +Application config (for example, client secrets, api tokens, and other config) should generally be stored securely and kept outside of the App itself. However, for brevity, this tutorial adds the configuration info as exportable constants in the `App.ts` file and leaves the implementation details to you. These are values that the Snyk App references in many different places. ```typescript // ./src/app.ts @@ -294,11 +294,11 @@ export async function updateDb( ### Prepare for API calls -Earlier, we installed the popular `axios` package to handle API calls. We know that we'll need to make some repetitive calls to the same API, so we abstract some helper functions to make our code easily re-usable across the project. Create an `APIHelpers.ts` file in the `util` directory. +Earlier, we installed the popular `axios` package to handle API calls. We know that we'll need to make some repetitive calls to the same API, so we abstract some helper functions to make our code reusable across the project. Create an `APIHelpers.ts` file in the `util` directory. -Before we fill that out, take note that while we are consistently hitting Snyk's API, we'll likely need to make requests against multiple versions of the API, depending on the endpoint's status in the migration from Snyk API v1 to Snyk REST API. One way we can handle this is by defining a TypeScript Enum and within our functions, swapping any necessary query parameters by comparing an argument to the enum's possible values. +Before we fill that out, take note that while we are consistently hitting the Snyk API, we'll likely need to make requests against multiple versions of the API, depending on the endpoint's status in the migration from Snyk API v1 to Snyk REST API. One way we can handle this is by defining a TypeScript Enum and, within our functions, swapping any necessary query parameters by comparing an argument to the enum's possible values. -Add the following content to a new file, or to `APIHelpers.ts` if you prefer; just make sure to export it for later use. +Add the following content to a new file, or to `APIHelpers.ts` if you prefer. Make sure to export it for later use. ```typescript // ./interfaces/API.ts @@ -333,7 +333,7 @@ export function callSnykApi(tokenType: string, token: string, version: APIVersio } ``` -Because this function is an `AxiosInstance`, we can easily talk to the API's different endpoints by calling `.get()`, `.post()`, or any other methods usually available to such an object. +Because this function is an `AxiosInstance`, we can talk to the API's different endpoints by calling `.get()`, `.post()`, or any other methods usually available to such an object. We will see it in action by defining a second async function to retrieve our Snyk Apps' Organization ID: @@ -407,7 +407,7 @@ export class EncryptDecrypt { We've laid the groundwork; now it's time to start doing things. -As discussed in a previous section, our app needs to send would-be authorizers to a specific token URL. We'll add an `/auth` route in our Snyk App and add some authentication middleware to Express. For this, we'll use the excellent [passportjs](https://www.passportjs.org), the [passport-oauth2](https://www.passportjs.org/packages/passport-oauth2/) authentication strategy, along with Snyk's [@snyk/passport-snyk-oauth2](https://www.npmjs.com/package/@snyk/passport-snyk-oauth2). `passport` and its friends handle a large portion of what would otherwise be a lengthy and complicated authentication process. +As discussed in a previous section, our app needs to send would-be authorizers to a specific token URL. We'll add an `/auth` route in our Snyk App and add some authentication middleware to Express. For this, we'll use [passportjs](https://www.passportjs.org), the [passport-oauth2](https://www.passportjs.org/packages/passport-oauth2/) authentication strategy, along with the Snyk package [@snyk/passport-snyk-oauth2](https://www.npmjs.com/package/@snyk/passport-snyk-oauth2). `passport` and its friends handle a large portion of what would otherwise be a lengthy and complicated authentication process. Because `passport` takes its encapsulation philosophy seriously, we'll need to handle everything else about the auth process. We need to set up an instance of the passport strategy we'll be using. We'll put our database helpers from earlier to use here as well, adding an entry into our database when we receive successful authorization. @@ -571,7 +571,7 @@ touch ./src/routes/callback/callbackController.ts The `AuthController` handles authentication of the App via the previously described authorization flow. This is the third step of `passport` setup. Every controller class implements the controller interface which has two members: the path and the router. -This controller handles the `/auth` route, which is what we'll use to send users (via `passport`) to the Snyk website for authorization approval. +This controller handles the `/auth` route, which is what we'll use to send users (through `passport`) to the Snyk website for authorization approval. ```typescript // ./src/routes/auth/authController.ts @@ -602,7 +602,7 @@ class AuthController implements Controller { export default AuthController; ``` -Once a user approves authorization to our Snyk App via the Snyk website, the user is kicked back to our callback URI, `/callback`. We'll handle this route similarly, invoking passport again. This is the final step of user authorization. +After a user approves authorization to our Snyk App through the Snyk website, the user returns to our callback URI, `/callback`. We'll handle this route similarly, invoking passport again. This is the final step of user authorization. The `CallbackController` accepts requests on `/callback`, but also creates two sub-routes, `/callback/success` and `/callback/failure`, to handle the different possible outcomes it might receive from Snyk. @@ -670,7 +670,7 @@ new App([ ### Refresh token management -If we build and run our Snyk App at this point, hitting the `/auth` route will successfully jump us out to the Snyk authorization portal and, provided we confirm the authorization, we'll get kicked back to our local app's callback route at `/callback`. If we had a very simplistic, one-off use case, we could end things here. But there's one more piece of the puzzle we should figure out if we're going to keep our user's authorization fresh; that is token expiry. +If we build and run our Snyk App at this point, hitting the `/auth` route jumps us out to the Snyk authorization portal and, after we confirm the authorization, we return to our local app's callback route at `/callback`. If we had a simplistic, one-off use case, we could end things here. But there's one more piece of the puzzle we should figure out if we're going to keep our user's authorization fresh, that is token expiry. If you ran the app to test things, take a look at database entries. If you've been following along, you should see something like this: @@ -695,7 +695,7 @@ That `expires_in` value will continue to count down until 0. If it does, the use To keep our access token from going stale, we need to make a POST request using our `refresh_token` to get an updated `access_token`. See [Set up the refresh token exchange](../set-up-a-snyk-app-using-the-oauth2-api/set-up-the-refresh-token-exchange.md). -We can automate this process in our Snyk App by utilizing [Axios interceptors](https://axios-http.com/docs/interceptors) to _intercept_ the requests we make and ensure we have an up-to-date `access_token`. +We can automate this process in our Snyk App by using [Axios interceptors](https://axios-http.com/docs/interceptors) to _intercept_ the requests we make and ensure we have an up-to-date `access_token`. Create the file `./src/util/interceptors.ts`, importing all the packages, classes, and so on that we'll need at the top: @@ -802,7 +802,7 @@ async function refreshAndUpdateDb(data: AuthData): Promise { } ``` -With our interceptors defined, the only thing we need to do is update our `callSnykApi` function to utilize them. Interceptors are methods of the `axiosInstance` object, so we'll add them after the `axios.create()` call and before the function's `return`. +With our interceptors defined, the only thing we need to do is update our `callSnykApi` function to use them. Interceptors are methods of the `axiosInstance` object, so we'll add them after the `axios.create()` call and before the function's `return`. ```typescript // ./src/util/APIHelpers.ts @@ -837,6 +837,6 @@ export function callSnykApi(tokenType: string, token: string, version: APIVersio ## Wrap-up -If you've made it this far, congratulations! You've learned how to register a Snyk App with Snyk, configure the authorization flow, keep the `auth_token` from getting stale, and set up a great starting point using TypeScript. +You've now learned how to register a Snyk App with Snyk, configure the authorization flow, keep the `auth_token` from getting stale, and set up a starting point using TypeScript. -In the next module of this tutorial, we'll add a template system and configure our app to show users all of their projects from Snyk in our App. +In the next module of this tutorial, we'll add a template system and configure our app to show users all of their Projects from Snyk in our App. diff --git a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/render-content-for-users.md b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/render-content-for-users.md index 773329bc6df6..910de03aa28c 100644 --- a/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/render-content-for-users.md +++ b/developer-tools/snyk-api/using-specific-snyk-apis/snyk-apps-apis/tutorial-create-a-snyk-app/render-content-for-users.md @@ -1,12 +1,12 @@ # Render content for users -In the previous module, we covered registering our Snyk App, setting up the authorization flow, and handling user authorization within our App. All of those topics are integral to the functionality of every Snyk App, but they're all what you might call "behind the scenes" topics. +In the previous module, we covered registering our Snyk App, setting up the authorization flow, and handling user authorization in our App. All of those topics are integral to the functionality of every Snyk App, but they're all what you might call "behind the scenes" topics. -In this module, we'll switch gears to focus on displaying content to the users who have authorized with our Snyk App. Specifically, we want to show unauthorized users a big button they can click to authorize and authorized users a list of their projects from Snyk. +In this module, we'll focus on displaying content to the users who have authorized with our Snyk App. Specifically, we want to show unauthorized users a button they can click to authorize and authorized users a list of their Projects from Snyk. ## Add a template engine to the Snyk App -While Express is perfectly capable of printing content to the screen and even rendering HTML server-side, life is much easier when using a template engine. For this tutorial we are using [EJS](https://ejs.co). +While Express is capable of printing content to the screen and even rendering HTML server-side, life is much easier when using a template engine. For this tutorial we are using [EJS](https://ejs.co). First, install the node packages needed in this part of the tutorial: @@ -50,7 +50,7 @@ class App { } ``` -For each route that we'll provide a template for, we'll need to modify the corresponding controller and ensure that we're using `res.render("