diff --git a/docs/_data/main-nav.yaml b/docs/_data/main-nav.yaml index 888233b..fb64344 100644 --- a/docs/_data/main-nav.yaml +++ b/docs/_data/main-nav.yaml @@ -21,8 +21,6 @@ toc: url: /insomnia/accounts - title: Forgotten Passphrase url: /insomnia/forgot-passphrase - - title: Managing E2EE (End-to-End Encryption) - url: /insomnia/managing-e2ee - title: Insomnia Organizations collapse-id: organizations items: @@ -96,32 +94,6 @@ toc: url: /insomnia/unit-testing - title: Stress Testing url: /insomnia/stress-testing - - title: Insomnia Storage Options - collapse-id: insomnia-storage - items: - - title: Insomnia Storage Options Guide - url: /insomnia/insomnia-storage-options-guide - - title: Sync with Insomnia Cloud - url: /insomnia/insomnia-sync - - title: Sync with Git - url: /insomnia/git-sync - - title: Security - collapse-id: security - items: - - title: Key Security Features - url: /insomnia/security-features - - title: Security Standards - url: /insomnia/security-standards - - title: Signup and Authentication - url: /insomnia/signup-and-auth - - title: Analytics Collected - url: /insomnia/analytics-collected - - title: End to End Data Encryption - url: /insomnia/data-encryption - - title: Software Bill of Materials - url: /insomnia/sbom - - title: Verifying Build Provenance for Signed Insomnia Binaries - url: /insomnia/verify-binary-provenance - title: Built-In Features collapse-id: features items: @@ -195,15 +167,6 @@ toc: url: /inso-cli/inso-on-docker - title: Software Bill of Materials url: /inso-cli/sbom - - title: Verifying Signatures for Signed Inso CLI Images - url: /inso-cli/verify-signed-images - - title: Verifying Inso CLI Build Provenance - url: /inso-cli/provenance - subfolderitems: - - title: Verifying Build Provenance for Signed Inso CLI Images - url: /inso-cli/provenance/verify-image-provenance - - title: Verifying Build Provenance for Signed Inso CLI Binaries - url: /inso-cli/provenance/verify-binary-provenance - title: Continuous Integration url: /inso-cli/continuous-integration - title: Pre-request and After-Response Scripts @@ -218,3 +181,18 @@ toc: items: - title: Insomnia API Mocking Overview url: /insomnia/api-mocking + - title: Security and compliance + collapse-id: security-compliance + items: + - title: Storage options + url: /insomnia/security-compliance/storage + - title: Manage end-to-end encryption + url: /insomnia/security-compliance/e2e-encryption + - title: Software bill of materials + url: /insomnia/security-compliance/sbom + - title: Insomnia security standards + url: /insomnia/security-compliance/standards + - title: Verifying build provenance for signed Insomnia binaries + url: /insomnia/security-compliance/verify-binary-provenance + - title: Verify signatures for signed Inso CLI images for Docker + url: /insomnia/security-compliance/verify-signed-images diff --git a/docs/insomnia/analytics-collected.md b/docs/insomnia/analytics-collected.md deleted file mode 100644 index 2f9f5c4..0000000 --- a/docs/insomnia/analytics-collected.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -layout: article-detail -title: User Analytics Collected -category: Security -category-url: security ---- - -If you are logged into your Insomnia account or if you have not opted out of analytics in the desktop application, we collect information about your usage. If you use the Insomnia desktop application without an account, we provide you with the choice to opt out to avoid sending us this information in the desktop application user interface. - -We collect usage analytics to evaluate user behavior for the purpose of guiding product decisions. - -If you use the application without an Insomnia account, you can edit your preference on sharing analytics data with Insomnia via the Insomnia app Preference Page by scrolling down to the **Network Activity** section and checking or unchecking the box next to **Send Usage Statistics**. - -If you are logged into your Insomnia account, or if you are using the Insomnia application without an account and have not opted out of collection, this is the format of the JSON data body for a sent event: - -```json -{ - "anonymousId": "device-Specific-UUID-here", - "context": { - "app": { - "name": "Insomnia", - "version": "8.2.0" - }, - "library": { - "name": "@segment/analytics-node", - "version": "1.0.0" - }, - "os": { - "name": "mac", - "version": "14.0.0" - } - }, - "event": "Request Executed", - "integrations": {}, - "messageId": "node-next-message-specific-id-here", - "originalTimestamp": "2023-10-10T09:57:53.346Z", - "properties": { - "mimeType": "application/json", - "preferredHttpVersion": "default" - }, - "receivedAt": "2023-10-10T09:58:05.056Z", - "sentAt": null, - "timestamp": "2023-10-10T09:57:53.346Z", - "type": "track", - "writeKey": "REDACTED" -} -``` - -Please also see our [Privacy Policy](https://insomnia.rest/privacy) for information about personal data we process in connection with Insomnia products and services. diff --git a/docs/insomnia/data-encryption.md b/docs/insomnia/data-encryption.md deleted file mode 100644 index e0eb1d4..0000000 --- a/docs/insomnia/data-encryption.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -layout: article-detail -title: Data Encryption -category: data-encryption -category-url: data-encryption ---- - -HTTP requests often contain sensitive information like API keys, usernames, and passwords. This is why Insomnia treats security with such a high priority, implementing many of the same techniques used by industry-leading password managers like [1Password](https://1password.com/), [LastPass](https://www.lastpass.com/), [DashLane](https://www.dashlane.com/), and others. - -As detailed above, the user's password is used to derive a secret key, which is then used to encrypt the account private key. Once decrypted, the private key can then be used to decrypt the keys for the Resource Group. - -Now you may be asking why all these keys are necessary. Why not just encrypt and decrypt data using the user's password directly? There are few key scenarios that make having this many keys necessary. - -### Forgot Passphrase - -Due to the usage of [SRP](https://en.wikipedia.org/wiki/Secure_Remote_Password_protocol) to handle logging into the Insomnia App, the Insomnia Cloud never stores a user's passphrase in any form. In addition, the derivation of encryption keys based on the user's password means that all user data is encrypted in a manner that requires the user's password to decrypt. - -When Insomnia Passwords are forgotten, this means that synced Insomnia Request data cannot be decrypted. Please create passwords with care. - -### Sharing a Resource Group - -The ability to share Resource Groups is the reason that every Resource Group needs its own key, and every account needs a public/private key-pair to securely share said key. Here's an example involving two users, Jane and Bob. - -For Jane to share a Resource Group with Bob, she must encrypt the Resource Group's key with Bob's public key and store it on the server (`M_Link`). Now, Bob can use his account's private key to decrypt the Resource Group's key and gain access to the data. This is a classic example of the [Diffie-Hellman key exchange](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange) being put to good use. diff --git a/docs/insomnia/git-sync.md b/docs/insomnia/git-sync.md deleted file mode 100644 index b374a93..0000000 --- a/docs/insomnia/git-sync.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -layout: article-detail -title: Sync with Git -category: "Sync with Git" -category-url: git-sync ---- - -{:.alert .alert-primary} -**Note**: Sync with Git applies to users subscribed to [Team plan](https://insomnia.rest/pricing) and above, refer to [pricing](https://insomnia.rest/pricing). - -Sync with Git is a built-in feature for Design Documents and Collections that enables you to configure your repository to an external Git version control system like GitHub or Gitlab. - -Pushing to a remote Git repository creates the `.insomnia` directory that can also be used with [Inso CLI](/inso-cli/introduction#data-search-flow). - -## Clone an Existing Remote Repository - -Within a Team/Enterprise organization, you can clone a remote from Git via the **Create** dropdown on the Dashboard view. - -You will be prompted to fill out remote [**Repository Settings**](#remote-repository-settings) to gain remote access. - -![git sync git clone](../assets/images/git-sync-git-clone.jpg) - -The remote repository must contain the root `.insomnia` directory, otherwise it will create an empty Design Document by default. - -## Enable Git Sync on existing Collection/Design Document - -{:.alert .alert-primary} -**Note**: This section assumes that you already have an empty remote Git repository. - -Within a Team/Enterprise organization, you can convert an existing Insomnia Synced Collection/Design Document to use Git Sync instead. - -This can be done clicking on the **Switch to Git Repository** button on the Sync dropdown. - -![git sync enable](../assets/images/git-sync-enable.jpg) - -A **Configure Repository** modal will open. - -![git sync modal](../assets/images/git-sync-modal-input.jpg) - -Configure it according to your Git Sync setup and press "Sync". - -## Remote Repository Settings - -When configuring a remote repository, you can chose to connect with GitHub or GitLab, or manually set up a remote repository. - -### Set up a remote repository with GitHub - -1. Open a document in Insomnia, then click **Setup Git Sync** in the upper right corner of the Insomnia app. -2. Click "Configure Repository", then open the GitHub tab. -3. Click **Authenticate with GitHub**. -4. Click on **Continue**. If the browser has already been authenticated with Github, the page will say "Successfully authenticated Insomnia". -5. You might be prompted to continue by your browser through the Insomnia app via "Choose Application" box. If you are not, you can follow the instructions on the page to complete Github account authentication with the Insomnia App. -6. You can now clone any repository from GitHub! Copy the HTTPS URI for the GitHub repository you want to connect to and paste it into the "GitHub URI" field. - -### Set up a remote repository with GitLab - -1. Open a document in Insomnia, then click **Setup Git Sync** in the upper right corner of the Insomnia app. -2. Click "Configure Repository", then open the GitLab tab. -3. Click **Authenticate with GitLab**. Your default browser will open and automatically redirect you to GitLab. -4. Click **Authorize** to allow Insomnia to connect with your GitLab account. - - If successful, you will be redirected to the Insomnia website with the message "Successfully authenticated Insomnia". -5. Return to the Insomnia app and wait for sync to finish. - -6. You might be prompted to manually add your GitLab authentication to the Insomnia app. If you still see the option to manually paste in your GitLab authentication code, copy it from `app.insomnia.rest` into the Insomnia app, then click **Sync**. -7. You can now clone any repository from GitLab! Copy the HTTPS URI for the GitLab repository you want to connect to and paste it into the "GitLab URI" field. - -### Manually set up a remote repository - -* **Git URI**: The URI of the Git repository. Only HTTPS URLs are officially supported. -* **Author Name**: The Git author name to store with each commit. -* **Author Email**: The Git author email to store with each commit. -* **Username**: The Git author username to match with the authentication token. -* **Authentication Token**: The token needed to authenticate with remote repository provider, such as GitHub or BitBucket. If you have two-factor authentication (2FA) enabled on your account, it is unlikely you will be able to use your username and password. Instead, generate a personal access token or app password with the scope outlined below. - -### Token and App Password Scope - -{:.alert .alert-primary} -**Note**: You may fail to set up Git Sync properly due to not enough or the wrong types of Git permissions. - -Find instructions on how to create a personal access token or app password on the following platforms: - -* [Github](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) - * For public repos, scope at least [`public_repo`](https://github.com/settings/tokens/new?description=insomnia-git-sync&scopes=public_repo) when creating your token. - * For private repos, scope at least [`repo`](https://github.com/settings/tokens/new?description=insomnia-git-sync&scopes=repo) when creating your token. -* [Gitlab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) - * For public and private GitLab repos, scope at least `api` when creating your personal access token. -* [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/) - * For _private_ BitBucket repos, scope at least `Read` and `Write` in the `Repository` options when creating your app password. -* [Bitbucket Server](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) - -Once complete, click **Done** and the repository settings will be persisted for future operations. The author details and token can be updated as needed. - -## Manage Branches - -When working with Git, it's good practice to make changes in separate branches. This has two benefits: - -* Reduces the chances of merge conflicts when collaborators are making frequent changes -* Supports a pull-request workflow where collaborators can leave feedback before merging -Local branches can be created from the branch management dialog. This dialog presents both local branches and remote branches. - -{:.alert .alert-primary} -**Note**: Remote branches will only appear if they do not already exist locally. - -## Commit Changes - -Commit your changes via the branch dropdown menu. You'll be prompted to add a descriptive message as your commit message. - -![Click the branch dropdown menu and select commit](../assets/images/git-commit-example.jpg) - -## Push Changes - -Pushing your changes to your remote repository for the first time creates the `.insomnia` directory, which you can use with the [Inso CLI](/inso-cli/introduction#data-search-flow). - -{:.alert .alert-primary} -**Note**: If you'd like to push to an alternative branch than the default, click on the branch dropdown menu. Select **Branches**, and add your desired branch name. - -Commits and branches only exist locally when created. A push needs to be done to share the commits and history of a branch remotely. If pushing fails, you will be given the option to force push. - -The push or force push operation can fail for many reasons, and logs will be presented in the Developer Console prefixed with `git-event` with further debugging information. A likely cause is that your user does not have permissions to push to a protected branch. - -For instance, with GitLab, the main/master branch is protected by default, and those with the developer role are unable to push directly to it. In that case, push to a separate branch and create a pull request, or update the permissions for your user on the repository. - -## Pull Changes - -If a collaborator makes a change to the remote repository, pull the changes to access the work locally. Click the branch dropdown menu in a Document and then **Pull**. Any incoming changes will be merged to your local machine. - -## Conflict Resolution - -Git sync does not currently support the ability to resolve conflicts within the application. If changes were made locally and remotely, a pull may fail. - -Here are some strategies to help with conflicts: - -* Each collaborator should make changes in a separate branch to avoid conflicts. Changes should be merged into master once reviewed and approved by other collaborators (eg. GitHub pull request). -* If a conflict occurs on pull, delete the branch locally and re-fetch it from the branches dialog. - -## Sign out of Git account - -Sign out of a synced Git management account. - -1. Click on **Setup Git Sync**, then click on **Repository Settings**. -2. You should see a list of all synced accounts. Next to each account is a **Sign Out** button. Click on **Sign Out** for the accounts that need to be signed out. -3. In the box that appears, click **Sign Out** again. - -The **Configure Repository** box will no longer list the account that was signed out in its list of configured accounts. diff --git a/docs/insomnia/insomnia-storage-options-guide.md b/docs/insomnia/insomnia-storage-options-guide.md deleted file mode 100644 index 375b558..0000000 --- a/docs/insomnia/insomnia-storage-options-guide.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -layout: article-detail -title: Insomnia Storage Options Guide -category: "Insomnia Storage Options Guide" -category-url: insomnia-storage-options-guide ---- - -## Introduction - -Insomnia offers various storage options to cater to different user needs and preferences. Understanding these options is crucial for efficient and secure management of your API projects. This document outlines the three primary storage options available in Insomnia: Local Vault, Cloud Sync, and Git Sync. - -![storage options example image](../assets/images/storage-options-example-img.jpg) - -## 1. Local Vault - -### Overview - -Local Vault is a storage option that allows all project data to be stored locally on your device. This option is ideal for users who prefer or require their data to remain off the cloud for privacy or security reasons. - -### Key Features - -- **Local Storage**: All project files are stored on your local machine. -- **No Cloud Interaction**: No data is sent to or stored in the cloud. -- **Security**: Enhanced security as data remains within your local environment. -- **Independence from Internet**: Access and work on your projects without needing an internet connection. - -### Use Cases - -- Organizations with strict data privacy regulations. -- Users working on sensitive projects that require enhanced security. -- Environments with limited or restricted internet access. - -## 2. Cloud Sync - -### Overview - -Cloud Sync enables users to store and synchronize their project data in the cloud securely. This feature is beneficial for collaboration, providing easy access to projects from different devices and locations. - -### Key Features - -- **End-to-End Encryption (E2EE)**: Ensures data is encrypted during transmission and storage. -- **Real-Time Synchronization**: Keeps your projects up-to-date across all devices. -- **Collaboration**: Share and collaborate on projects with team members. -- **Remote Access**: Access your projects from anywhere with an internet connection. - -### Use Cases - -- Teams requiring collaboration on API projects. -- Users who work from multiple locations or devices. -- Projects that benefit from centralized, cloud-based management. - -## 3. Git Sync - -### Overview - -Git Sync allows users to use a third-party Git repository for storing project data. This option is independent of cloud access and is suitable for users familiar with Git workflows. - -{:.alert .alert-primary} -**Note**: Sync with Git applies to users subscribed to [Team plan](https://insomnia.rest/pricing) and above, refer to [pricing](https://insomnia.rest/pricing). - -### Key Features - -- **Version Control**: Leverage Git's version control capabilities for your projects. -- **Independence from Insomnia's Cloud**: Uses external Git repositories for storage. -- **Flexibility**: Choose any Git service provider like GitHub, GitLab, or Bitbucket. -- **Collaboration via Git**: Collaborate with others using standard Git practices. - -### Use Cases - -- Users comfortable with Git and its versioning system. -- Projects that require detailed version tracking and rollback capabilities. -- Teams that already use Git for other aspects of their development workflow. - -## Conclusion - -Understanding these storage options enables you to choose the most suitable one based on your project requirements, collaboration needs, and security preferences. Insomnia's flexibility in offering Local Vault, Cloud Sync, and Git Sync ensures that it can adapt to a wide range of user scenarios, from individual developers to large organizations. - -> Looking for something else? See information on [Scratch Pad](scratchpad). diff --git a/docs/insomnia/insomnia-sync.md b/docs/insomnia/insomnia-sync.md deleted file mode 100644 index 4cd32e9..0000000 --- a/docs/insomnia/insomnia-sync.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -layout: article-detail -title: Cloud Sync -category: "Get Started" -category-url: get-started ---- - -In this section, you will find documentation on [Cloud Sync](#cloud-sync) and [Commits](#commits). - -## Cloud Sync - -Cloud sync provides the following abilities on top of the base Insomnia functionality: - -* Commit and push the contents of projects -* Revert to a previous commit -* Share commits across devices or with members of your organization -* Create and work on separate branches - -## Enabling sync for projects - -When creating a new project you will be prompted to pick the **Project Type**. - -![Enabling remote project](/assets/images/secure-cloud-project.jpg) - -Any collections and design documents under a **Secure Cloud** project type will be automatically synced into Insomnia cloud. - -## Syncing workspaces from Cloud projects - -When navigating in a Cloud project you should see Un-synced collections, design documents or mock servers which you can pull from. - -![Auto pull](/assets/images/unsynced.jpg) - -## Commits - -This section provides information for Secure Cloud Projects. For pricing information, see our [Pricing](https://insomnia.rest/pricing) page. - -### Create Commit - -To create a Commit, open a **remote Collection/Design Document** and click on the branch dropdown menu next to Preferences, and then click **Commit**. - -![To create a new Commit, click on the branch dropdown next to Preferences and select Commit.](/assets/images/cloud-sync-commit.jpg) -_Within a remote Collection/Design Document, click on the branch dropdown and click on Commit._ - -A **Create Commit** modal will open. -![Create commit modal](../assets/images/create-commit-modal.jpg) - -Commits represent all data in a Collection/Design Document (requests, folders, environments) at a specific point in time. Besides the data within the Collection, a Commit also details: - -* The Commit author -* The time that the Commit was created -* A message describing any changes in the Commit - -Creating a Commit requires two actions: - -1. Describe the changes contained within the Commit -2. Select which changes to include - -### Write a Commit Message - -Commit messages should describe the included changes in as much detail as possible, as this description will help identify the Commit if you ever need to revert back to it. - -### Add Changes to a Commit - -Changes made to a request collection/design document can be added on a granular level. Modifications and deletions to existing requests, folders, etc (AKA objects) will appear under Modified Objects, while new additions will appear under Unversioned Objects and are unselected by default. - -### Share Commits - -Once a Commit is created, it can be shared to your Insomnia account or team. There are two ways to push Commits: - -* Use the Create and Push option when creating the Commit -* Push un-synced Commits from within the main sync menu - -If there are new Commits available that do not yet exist on your device (eg. from a team) these will be available to pull down from within the sync menu. - -### Work with Branches - -All Commits created for Sync are stored in a branch. Branches are identified by name and each one maintains a list of Commits that have been created for it (ie. its history). Branches can be created or deleted at any time, shared with team members, and even merged together. - -Branches can be useful for many reasons, but the two main use cases are the following: - -* Separate personal work from other team members -* Work on experimental changes that may or may not exist long-term - -Branches are managed within the branches dialog. Here, you can create local branches, merge branches, and fetch remote branches. - -### Revert to a Previous Commit - -You can revert a Collection/Design Document to a previous Commit. Find the Commit you want to revert to by going to the branch dropdown and clicking on **History**. Then click **Restore** on the Commit you want to revert to. - -When you restore a Commit, it will show the changes locally and you'll need to manually Commit the changes. - -## Things to Know - -If a team is using mixed versions of Insomnia, and one version supports a type of request (such as gRPC or WebSockets) that another version doesn't, then syncing that request type to a synced Collection/Design Document with Insomnia Cloud may cause the request to be silently deleted when the collection/Design document is pulled and updated by different members using different Insomnia versions. - -We highly recommend that teams be on the latest version of Insomnia to avoid losing request data due to version incompatibilities. diff --git a/docs/insomnia/scratchpad.md b/docs/insomnia/scratchpad.md deleted file mode 100644 index 767421e..0000000 --- a/docs/insomnia/scratchpad.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -layout: article-detail -title: Insomnia Scratch Pad Tutorial -category: "Insomnia Scratch Pad Tutorial" -category-url: scratchpad ---- -## Introduction - -The Scratch Pad feature in Insomnia is a powerful tool for quickly experimenting with API requests without requiring a User account and/or affecting your account's existing Local/Cloud projects or workspaces. -It's ideal for testing, debugging, or learning purposes. -This tutorial will guide you through using the Scratch Pad feature effectively. - -## Accessing Scratch Pad - -1. **Open Insomnia Application**: Launch Insomnia on your device. - - ![scratchpad option on start](../assets/images/scratchpad-option.jpg) - -2. **Find Scratch Pad**: In the Insomnia interface, look for the Scratch Pad option. It's typically located in the sidebar or top menu, depending on your version. - - ![empty scratchpad](../assets/images/scratchpad-empty.jpg) - -## Using Scratch Pad - -### Creating a New Request - -1. **Create Request**: In the Scratch Pad area, click on 'New Request'. -2. **Name Your Request** (optional): Give a descriptive name to your request for easy identification. -3. **Choose Request Type**: Select the type of request (GET, POST, PUT, DELETE, etc.) from the dropdown menu. -4. **Enter URL**: Type in the API endpoint you wish to test. - - ![Example new request](../assets/images/example-new-request.jpg) - -### Setting Up Request Parameters - -1. **Add Headers**: If your API requires headers (like content-type, authorization tokens), add them in the 'Headers' tab. -2. **Configure Body** (for POST/PUT requests): In the 'Body' tab, choose the appropriate format (like JSON, form data) and input the data you want to send. - -### Sending the Request - -1. **Send Request**: Once your request is set up, click the 'Send' button. -2. **View Response**: The response from the API will be displayed in the pane below the request configuration. You can view the status code, response body, headers, and more. - -## Managing Scratch Pad Requests - -- **Save Request**: You can save your request for later use by clicking 'Save'. -- **Organize Requests**: If you have multiple requests, organize them for easy access and reference. -- **Delete or Edit**: Requests can be deleted or edited as needed. diff --git a/docs/insomnia/managing-e2ee.md b/docs/insomnia/security-compliance/e2e-encryption.md similarity index 98% rename from docs/insomnia/managing-e2ee.md rename to docs/insomnia/security-compliance/e2e-encryption.md index 6418c2f..da2e3c5 100644 --- a/docs/insomnia/managing-e2ee.md +++ b/docs/insomnia/security-compliance/e2e-encryption.md @@ -1,10 +1,10 @@ --- layout: article-detail title: Managing E2EE (End-to-End Encryption) -category: "Insomnia Accounts" -category-url: managing-e2ee --- + + This tutorial will guide you through enabling or disabling E2EE in the Insomnia app, along with some critical considerations about handling your passphrase. By default, accounts created from June 4th 2024 onwards with a free subscription have E2EE disabled. While your data remains encrypted at rest and in transit, E2EE offers an additional layer of security by encrypting data such that only the parties involved in the communication can decrypt it. diff --git a/docs/insomnia/sbom.md b/docs/insomnia/security-compliance/sbom.md similarity index 92% rename from docs/insomnia/sbom.md rename to docs/insomnia/security-compliance/sbom.md index 1098fb1..a5ffb39 100644 --- a/docs/insomnia/sbom.md +++ b/docs/insomnia/security-compliance/sbom.md @@ -1,10 +1,10 @@ --- layout: article-detail title: Software Bill of Materials -category: "Insomnia SBOM" -category-url: security --- + + A software bill of materials (SBOM) is an inventory of all software components (proprietary and open source), open source licenses, and dependencies in a given product. A software bill of materials (SBOM) provides visibility into the software supply chain and any license compliance, security, and quality risks that may exist. ## Download SBOM diff --git a/docs/insomnia/security-compliance/standards.md b/docs/insomnia/security-compliance/standards.md new file mode 100644 index 0000000..69b848c --- /dev/null +++ b/docs/insomnia/security-compliance/standards.md @@ -0,0 +1,240 @@ +--- +layout: article-detail +title: Insomnia security standards +--- + + + +## Key Security Data Features + +When you create an Insomnia account, you gain access to end-to-end encrypted project data sync. Simply sign into your account and your data will be there, seamlessly synced across all of your (and optionally your teams') devices. + +Insomnia believes that it is your right to know how your sensitive project data is transported and handled, so this document is an effort to explain exactly how it works. + +If you find that any part of this document is incorrect, missing, or wrong, please don't hesitate to reach out. + +## Key Security Data Features + +This section gives a high level overview of Insomnia project data sync security. If you read anything in this document, it should be this section. + +### What End-To-End encryption means + +E2EE means that all encryption keys are generated locally, all encryption is performed before sending any data over the network, and all decryption is performed after receiving data from the network. At no point in the sync process can the Insomnia servers, or an intruder read or access sensitive application project data. + +## What is project data? + +Project data are your API design specifications, collections, tests and other files that you choose to share with others in your organization through Insomnia's hosted data synchronization service. + +Please note that the Insomnia service may provide you the ability to develop tests for your API design specifications, as well as other functionality, using artificial intelligence tools. Data you provide to use these AI tools are not end-to-end encrypted and so this document does not apply to such data. + +### Encryption algorithms we use + +All data is encrypted using randomly generated 256 bit symmetric keys for use with AES-GCM-256 (Galois Counter Mode). + +### Resetting Passphrases + +Losing your passphrase means losing the ability to decrypt your account keys. If you lose your passphrase there is no way to access your project data that is not stored by you locally, and there is nothing Insomnia can do to help apart from resetting your passphrase as well as your account. + +You can reset your passphrase through the "[Forgot Passphrase](/insomnia/forgot-passphrase)" flow. Once you go through the "[Forgot Passphrase](/insomnia/forgot-passphrase)" flow and define a new passphrase, you'll lose access to your previous encrypted project data. + +If you have been invited to collaborate with other organizations, you can reset your passphrase and then ask to be invited back. You will only be able to retrieve data for the organizations that you are invited back to. + +If you have shared your personal organizations or project data, you can ask other users with Admin permissions to also re-invite you after resetting the passphrase. + +### Unencrypted Fields + +By default, project data resources within the Insomnia application are fully encrypted before being sent to the server. However, both id and name of each resource are attached in plaintext before uploading. + +### Local data is not encrypted on disk + +Insomnia currently stores application project data locally on disk in raw form. E2EE only applies to project data that is transmitted over the network. It is still possible for malicious software to access the project data stored on your machine. Please take the usual precautions to keep your local project data safe. + +## Useful Definitions + +Here are definitions for the common things that will be talked about. + +### Data Models + +The following are data models we use. + +{:.table .table-striped} +Data Model | Definition +---------- | --------- +`M_Account` | A user that can log in +`M_Resource` | An entity that can be synced (eg. Request, Workspace, etc.) +`M_ResourceGroup` | A group of M_Resource that can be shared as one +`M_Link` | A relationship linking a M_Account to M_ResourceGroup + +### Keys and Salts + +The following are keys and salts we use. + +{:.table .table-striped} +Name | Description | Stored? +----- | ------ | ----- +`PUB_Account` | Public key for M_Account | Yes +`PRV_Account` | Private key for M_Account | Yes 🔒 +`SYM_Account` | Symmetric key for M_Account | Yes 🔒 +`SYM_ResourceGroup` | Symmetric Key for data encryption | No +`SYM_Link` | Encrypted form of SYM_ResourceGroup | Yes 🔒 +`SLT_Auth_1` | Salt for PBKDF2 of passphrase for auth | Yes +`SLT_Auth_2` | Salt for SRP authentication process | Yes +`SLT_Enc` | Salt for PBKDF2 of passphrase for encryption | Yes +`SEC_PWD_Auth` | Secret derived from passphrase using SLT_Auth_1 | No +`SEC_PWD_Enc` | Secret derived from passphrase using SLT_Enc | No +`SRP_Verifier` | Verification string used for SRP | Yes + +{:.alert .alert-primary} +**Note**: `SYM_Link` and `SYM_ResourceGroup` are essentially the same thing, but are defined separately for the purpose of discussion. This will become clear later on. + +## Security Standards + +This document addresses common questions we get about our security standards. + +**How is data processed when sent to Insomnia servers?** + +* Information is sent over TLS +* Information sent is end-to-end encrypted + +**Where is our information stored?** + +* Information is stored in GCP, in US Central region +* Information inside of GCP is stored within Postgres + +**Do we have any compliance certifications?** + +Not at the moment. + +**Do you have any penetration test results from external parties?** + +Not at the moment. + +**What authentication is implemented by the application?** + +* Secure Remote Passwords (SRP) encrypted key exchange protocol. + +**How often do you release major updates, and or security patches?** + +* We regularly update the Insomnia desktop application. +* Security, and hotfix patches are handled on a case-by-case basis and can occur at any time. + +**Do you retain server logs, or event logs?** + +* All server logs stored are kept within GCP and only accessed by engineers authorized to manage the Insomnia servers. + +**Do you maintain documentation when an incident/event occurs?** + +* When an incident occurs, we perform an internal post-mortem and disseminate information accordingly, either through the site in the form of a blog post, or through social media/support on a case-by-case basis. + +**In case of a breach, do you notify customers?** + +* Yes, via email. + +**What is your primary point of contact?** + +* [Open Source](https://github.com/kong/insomnia) +* [Support channels](https://insomnia.rest/support) + +## FAQ + +### Signup and Authentication + +Since the passphrase you choose at registration time is used during the encryption process (although indirectly), it's vital that it's never sent or stored on the server in an easily crackable form. To help with this goal, Insomnia uses the [Secure Remote Passwords (SRP)](http://srp.stanford.edu/) encrypted key exchange protocol. + +You can read more about the exact SRP implementation that Insomnia paid plans use in [RFC-2945](https://datatracker.ietf.org/doc/html/rfc2945). + +For a detailed description of SRP, see [Mozilla's Node SRP](https://github.com/mozilla/node-srp). + +#### How Account Creation Works + +These are the steps taken on the client during account creation. + +1. Randomly generate 256 bit keys and salts `SYM_Account`, `SLT_Auth_1`, `SLT_Auth_2`, `SLT_Encryption` +2. Generate `PUB_Account`/`PRV_Account` keypair for RSA-OAEP SHA-256 +3. Generate `SEC_PWD_Auth` using the following steps + 1. Combine `SLT_Auth1` with email address using HKDF SHA-256 to form a new salt `SLT_TMP_1` + 2. Run 100,000 iterations of PBKDF2 SHA-256 with SLT_TMP_1 +4. Generate SEC_PWD_Enc using the following steps + 1. Combine SLT_Enc with email address using HKDF SHA-256 to form a new salt `SLT_TMP_2` + 2. Run 100,000 iterations of PBKDF2 SHA-256 with `SLT_TMP_2` +5. Generate SRP_Verifier using `SLT_Auth_2`, email address, `SEC_PWD_Auth` +6. Encrypt SYM_Account using `SEC_PWD` +7. Encrypt PRV_Account using `SYM_Account` +8. Send `M_Account` object to server for creation + +Once the account is created, the server will send a verification email to the user. Once the user receives this email, they can attempt to log in. + +#### How Account Login Works + +These are the steps taken on the client during login. + +1. Derive `SEC_PWD_Auth` using same steps as in Account Creation +2. Use `SLT_Auth_2` to perform SRP exchange +3. Store SRP-generated `K` locally to use as session key + +Now that we know how signup and authentication are performed, we can talk about data encryption. + +### User Analytics Collected + +If you are logged into your Insomnia account or if you have not opted out of analytics in the desktop application, we collect information about your usage. If you use the Insomnia desktop application without an account, we provide you with the choice to opt out to avoid sending us this information in the desktop application user interface. + +We collect usage analytics to evaluate user behavior for the purpose of guiding product decisions. + +If you use the application without an Insomnia account, you can edit your preference on sharing analytics data with Insomnia via the Insomnia app Preference Page by scrolling down to the **Network Activity** section and checking or unchecking the box next to **Send Usage Statistics**. + +If you are logged into your Insomnia account, or if you are using the Insomnia application without an account and have not opted out of collection, this is the format of the JSON data body for a sent event: + +```json +{ + "anonymousId": "device-Specific-UUID-here", + "context": { + "app": { + "name": "Insomnia", + "version": "8.2.0" + }, + "library": { + "name": "@segment/analytics-node", + "version": "1.0.0" + }, + "os": { + "name": "mac", + "version": "14.0.0" + } + }, + "event": "Request Executed", + "integrations": {}, + "messageId": "node-next-message-specific-id-here", + "originalTimestamp": "2023-10-10T09:57:53.346Z", + "properties": { + "mimeType": "application/json", + "preferredHttpVersion": "default" + }, + "receivedAt": "2023-10-10T09:58:05.056Z", + "sentAt": null, + "timestamp": "2023-10-10T09:57:53.346Z", + "type": "track", + "writeKey": "REDACTED" +} +``` + +Please also see our [Privacy Policy](https://insomnia.rest/privacy) for information about personal data we process in connection with Insomnia products and services. + +### Data Encryption + +HTTP requests often contain sensitive information like API keys, usernames, and passwords. This is why Insomnia treats security with such a high priority, implementing many of the same techniques used by industry-leading password managers like [1Password](https://1password.com/), [LastPass](https://www.lastpass.com/), [DashLane](https://www.dashlane.com/), and others. + +As detailed above, the user's password is used to derive a secret key, which is then used to encrypt the account private key. Once decrypted, the private key can then be used to decrypt the keys for the Resource Group. + +Now you may be asking why all these keys are necessary. Why not just encrypt and decrypt data using the user's password directly? There are few key scenarios that make having this many keys necessary. + +### Forgot Passphrase + +Due to the usage of [SRP](https://en.wikipedia.org/wiki/Secure_Remote_Password_protocol) to handle logging into the Insomnia App, the Insomnia Cloud never stores a user's passphrase in any form. In addition, the derivation of encryption keys based on the user's password means that all user data is encrypted in a manner that requires the user's password to decrypt. + +When Insomnia Passwords are forgotten, this means that synced Insomnia Request data cannot be decrypted. Please create passwords with care. + +### Sharing a Resource Group + +The ability to share Resource Groups is the reason that every Resource Group needs its own key, and every account needs a public/private key-pair to securely share said key. Here's an example involving two users, Jane and Bob. + +For Jane to share a Resource Group with Bob, she must encrypt the Resource Group's key with Bob's public key and store it on the server (`M_Link`). Now, Bob can use his account's private key to decrypt the Resource Group's key and gain access to the data. This is a classic example of the [Diffie-Hellman key exchange](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange) being put to good use. diff --git a/docs/insomnia/security-compliance/storage.md b/docs/insomnia/security-compliance/storage.md new file mode 100644 index 0000000..22b7a14 --- /dev/null +++ b/docs/insomnia/security-compliance/storage.md @@ -0,0 +1,359 @@ +--- +layout: article-detail +title: Storage options +--- + + + +# Storage options guide + +## Introduction + +Insomnia offers various storage options to cater to different user needs and preferences. Understanding these options is crucial for efficient and secure management of your API projects. This document outlines the three primary storage options available in Insomnia: Local Vault, Cloud Sync, and Git Sync. + +![storage options example image](../assets/images/storage-options-example-img.jpg) + +## 1. Local Vault + +### Overview + +Local Vault is a storage option that allows all project data to be stored locally on your device. This option is ideal for users who prefer or require their data to remain off the cloud for privacy or security reasons. + +### Key Features + +- **Local Storage**: All project files are stored on your local machine. +- **No Cloud Interaction**: No data is sent to or stored in the cloud. +- **Security**: Enhanced security as data remains within your local environment. +- **Independence from Internet**: Access and work on your projects without needing an internet connection. + +### Use Cases + +- Organizations with strict data privacy regulations. +- Users working on sensitive projects that require enhanced security. +- Environments with limited or restricted internet access. + +## 2. Cloud Sync + +### Overview + +Cloud Sync enables users to store and synchronize their project data in the cloud securely. This feature is beneficial for collaboration, providing easy access to projects from different devices and locations. + +### Key Features + +- **End-to-End Encryption (E2EE)**: Ensures data is encrypted during transmission and storage. +- **Real-Time Synchronization**: Keeps your projects up-to-date across all devices. +- **Collaboration**: Share and collaborate on projects with team members. +- **Remote Access**: Access your projects from anywhere with an internet connection. + +### Use Cases + +- Teams requiring collaboration on API projects. +- Users who work from multiple locations or devices. +- Projects that benefit from centralized, cloud-based management. + +## 3. Git Sync + +### Overview + +Git Sync allows users to use a third-party Git repository for storing project data. This option is independent of cloud access and is suitable for users familiar with Git workflows. + +{:.alert .alert-primary} +**Note**: Sync with Git applies to users subscribed to [Team plan](https://insomnia.rest/pricing) and above, refer to [pricing](https://insomnia.rest/pricing). + +### Key Features + +- **Version Control**: Leverage Git's version control capabilities for your projects. +- **Independence from Insomnia's Cloud**: Uses external Git repositories for storage. +- **Flexibility**: Choose any Git service provider like GitHub, GitLab, or Bitbucket. +- **Collaboration via Git**: Collaborate with others using standard Git practices. + +### Use Cases + +- Users comfortable with Git and its versioning system. +- Projects that require detailed version tracking and rollback capabilities. +- Teams that already use Git for other aspects of their development workflow. + +## Conclusion + +Understanding these storage options enables you to choose the most suitable one based on your project requirements, collaboration needs, and security preferences. Insomnia's flexibility in offering Local Vault, Cloud Sync, and Git Sync ensures that it can adapt to a wide range of user scenarios, from individual developers to large organizations. + +> Looking for something else? See information on [Scratch Pad](scratchpad). + + +# scratchpad +## Introduction + +The Scratch Pad feature in Insomnia is a powerful tool for quickly experimenting with API requests without requiring a User account and/or affecting your account's existing Local/Cloud projects or workspaces. +It's ideal for testing, debugging, or learning purposes. +This tutorial will guide you through using the Scratch Pad feature effectively. + +## Accessing Scratch Pad + +1. **Open Insomnia Application**: Launch Insomnia on your device. + + ![scratchpad option on start](../assets/images/scratchpad-option.jpg) + +2. **Find Scratch Pad**: In the Insomnia interface, look for the Scratch Pad option. It's typically located in the sidebar or top menu, depending on your version. + + ![empty scratchpad](../assets/images/scratchpad-empty.jpg) + +## Using Scratch Pad + +### Creating a New Request + +1. **Create Request**: In the Scratch Pad area, click on 'New Request'. +2. **Name Your Request** (optional): Give a descriptive name to your request for easy identification. +3. **Choose Request Type**: Select the type of request (GET, POST, PUT, DELETE, etc.) from the dropdown menu. +4. **Enter URL**: Type in the API endpoint you wish to test. + + ![Example new request](../assets/images/example-new-request.jpg) + +### Setting Up Request Parameters + +1. **Add Headers**: If your API requires headers (like content-type, authorization tokens), add them in the 'Headers' tab. +2. **Configure Body** (for POST/PUT requests): In the 'Body' tab, choose the appropriate format (like JSON, form data) and input the data you want to send. + +### Sending the Request + +1. **Send Request**: Once your request is set up, click the 'Send' button. +2. **View Response**: The response from the API will be displayed in the pane below the request configuration. You can view the status code, response body, headers, and more. + +## Managing Scratch Pad Requests + +- **Save Request**: You can save your request for later use by clicking 'Save'. +- **Organize Requests**: If you have multiple requests, organize them for easy access and reference. +- **Delete or Edit**: Requests can be deleted or edited as needed. + +# Insomnia sync + +In this section, you will find documentation on [Cloud Sync](#cloud-sync) and [Commits](#commits). + +## Cloud Sync + +Cloud sync provides the following abilities on top of the base Insomnia functionality: + +* Commit and push the contents of projects +* Revert to a previous commit +* Share commits across devices or with members of your organization +* Create and work on separate branches + +## Enabling sync for projects + +When creating a new project you will be prompted to pick the **Project Type**. + +![Enabling remote project](/assets/images/secure-cloud-project.jpg) + +Any collections and design documents under a **Secure Cloud** project type will be automatically synced into Insomnia cloud. + +## Syncing workspaces from Cloud projects + +When navigating in a Cloud project you should see Un-synced collections, design documents or mock servers which you can pull from. + +![Auto pull](/assets/images/unsynced.jpg) + +## Commits + +This section provides information for Secure Cloud Projects. For pricing information, see our [Pricing](https://insomnia.rest/pricing) page. + +### Create Commit + +To create a Commit, open a **remote Collection/Design Document** and click on the branch dropdown menu next to Preferences, and then click **Commit**. + +![To create a new Commit, click on the branch dropdown next to Preferences and select Commit.](/assets/images/cloud-sync-commit.jpg) +_Within a remote Collection/Design Document, click on the branch dropdown and click on Commit._ + +A **Create Commit** modal will open. +![Create commit modal](../assets/images/create-commit-modal.jpg) + +Commits represent all data in a Collection/Design Document (requests, folders, environments) at a specific point in time. Besides the data within the Collection, a Commit also details: + +* The Commit author +* The time that the Commit was created +* A message describing any changes in the Commit + +Creating a Commit requires two actions: + +1. Describe the changes contained within the Commit +2. Select which changes to include + +### Write a Commit Message + +Commit messages should describe the included changes in as much detail as possible, as this description will help identify the Commit if you ever need to revert back to it. + +### Add Changes to a Commit + +Changes made to a request collection/design document can be added on a granular level. Modifications and deletions to existing requests, folders, etc (AKA objects) will appear under Modified Objects, while new additions will appear under Unversioned Objects and are unselected by default. + +### Share Commits + +Once a Commit is created, it can be shared to your Insomnia account or team. There are two ways to push Commits: + +* Use the Create and Push option when creating the Commit +* Push un-synced Commits from within the main sync menu + +If there are new Commits available that do not yet exist on your device (eg. from a team) these will be available to pull down from within the sync menu. + +### Work with Branches + +All Commits created for Sync are stored in a branch. Branches are identified by name and each one maintains a list of Commits that have been created for it (ie. its history). Branches can be created or deleted at any time, shared with team members, and even merged together. + +Branches can be useful for many reasons, but the two main use cases are the following: + +* Separate personal work from other team members +* Work on experimental changes that may or may not exist long-term + +Branches are managed within the branches dialog. Here, you can create local branches, merge branches, and fetch remote branches. + +### Revert to a Previous Commit + +You can revert a Collection/Design Document to a previous Commit. Find the Commit you want to revert to by going to the branch dropdown and clicking on **History**. Then click **Restore** on the Commit you want to revert to. + +When you restore a Commit, it will show the changes locally and you'll need to manually Commit the changes. + +## Things to Know + +If a team is using mixed versions of Insomnia, and one version supports a type of request (such as gRPC or WebSockets) that another version doesn't, then syncing that request type to a synced Collection/Design Document with Insomnia Cloud may cause the request to be silently deleted when the collection/Design document is pulled and updated by different members using different Insomnia versions. + +We highly recommend that teams be on the latest version of Insomnia to avoid losing request data due to version incompatibilities. + +# Git sync + + +{:.alert .alert-primary} +**Note**: Sync with Git applies to users subscribed to [Team plan](https://insomnia.rest/pricing) and above, refer to [pricing](https://insomnia.rest/pricing). + +Sync with Git is a built-in feature for Design Documents and Collections that enables you to configure your repository to an external Git version control system like GitHub or Gitlab. + +Pushing to a remote Git repository creates the `.insomnia` directory that can also be used with [Inso CLI](/inso-cli/introduction#data-search-flow). + +## Clone an Existing Remote Repository + +Within a Team/Enterprise organization, you can clone a remote from Git via the **Create** dropdown on the Dashboard view. + +You will be prompted to fill out remote [**Repository Settings**](#remote-repository-settings) to gain remote access. + +![git sync git clone](../assets/images/git-sync-git-clone.jpg) + +The remote repository must contain the root `.insomnia` directory, otherwise it will create an empty Design Document by default. + +## Enable Git Sync on existing Collection/Design Document + +{:.alert .alert-primary} +**Note**: This section assumes that you already have an empty remote Git repository. + +Within a Team/Enterprise organization, you can convert an existing Insomnia Synced Collection/Design Document to use Git Sync instead. + +This can be done clicking on the **Switch to Git Repository** button on the Sync dropdown. + +![git sync enable](../assets/images/git-sync-enable.jpg) + +A **Configure Repository** modal will open. + +![git sync modal](../assets/images/git-sync-modal-input.jpg) + +Configure it according to your Git Sync setup and press "Sync". + +## Remote Repository Settings + +When configuring a remote repository, you can chose to connect with GitHub or GitLab, or manually set up a remote repository. + +### Set up a remote repository with GitHub + +1. Open a document in Insomnia, then click **Setup Git Sync** in the upper right corner of the Insomnia app. +2. Click "Configure Repository", then open the GitHub tab. +3. Click **Authenticate with GitHub**. +4. Click on **Continue**. If the browser has already been authenticated with Github, the page will say "Successfully authenticated Insomnia". +5. You might be prompted to continue by your browser through the Insomnia app via "Choose Application" box. If you are not, you can follow the instructions on the page to complete Github account authentication with the Insomnia App. +6. You can now clone any repository from GitHub! Copy the HTTPS URI for the GitHub repository you want to connect to and paste it into the "GitHub URI" field. + +### Set up a remote repository with GitLab + +1. Open a document in Insomnia, then click **Setup Git Sync** in the upper right corner of the Insomnia app. +2. Click "Configure Repository", then open the GitLab tab. +3. Click **Authenticate with GitLab**. Your default browser will open and automatically redirect you to GitLab. +4. Click **Authorize** to allow Insomnia to connect with your GitLab account. + + If successful, you will be redirected to the Insomnia website with the message "Successfully authenticated Insomnia". +5. Return to the Insomnia app and wait for sync to finish. + +6. You might be prompted to manually add your GitLab authentication to the Insomnia app. If you still see the option to manually paste in your GitLab authentication code, copy it from `app.insomnia.rest` into the Insomnia app, then click **Sync**. +7. You can now clone any repository from GitLab! Copy the HTTPS URI for the GitLab repository you want to connect to and paste it into the "GitLab URI" field. + +### Manually set up a remote repository + +* **Git URI**: The URI of the Git repository. Only HTTPS URLs are officially supported. +* **Author Name**: The Git author name to store with each commit. +* **Author Email**: The Git author email to store with each commit. +* **Username**: The Git author username to match with the authentication token. +* **Authentication Token**: The token needed to authenticate with remote repository provider, such as GitHub or BitBucket. If you have two-factor authentication (2FA) enabled on your account, it is unlikely you will be able to use your username and password. Instead, generate a personal access token or app password with the scope outlined below. + +### Token and App Password Scope + +{:.alert .alert-primary} +**Note**: You may fail to set up Git Sync properly due to not enough or the wrong types of Git permissions. + +Find instructions on how to create a personal access token or app password on the following platforms: + +* [Github](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) + * For public repos, scope at least [`public_repo`](https://github.com/settings/tokens/new?description=insomnia-git-sync&scopes=public_repo) when creating your token. + * For private repos, scope at least [`repo`](https://github.com/settings/tokens/new?description=insomnia-git-sync&scopes=repo) when creating your token. +* [Gitlab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) + * For public and private GitLab repos, scope at least `api` when creating your personal access token. +* [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/) + * For _private_ BitBucket repos, scope at least `Read` and `Write` in the `Repository` options when creating your app password. +* [Bitbucket Server](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) + +Once complete, click **Done** and the repository settings will be persisted for future operations. The author details and token can be updated as needed. + +## Manage Branches + +When working with Git, it's good practice to make changes in separate branches. This has two benefits: + +* Reduces the chances of merge conflicts when collaborators are making frequent changes +* Supports a pull-request workflow where collaborators can leave feedback before merging +Local branches can be created from the branch management dialog. This dialog presents both local branches and remote branches. + +{:.alert .alert-primary} +**Note**: Remote branches will only appear if they do not already exist locally. + +## Commit Changes + +Commit your changes via the branch dropdown menu. You'll be prompted to add a descriptive message as your commit message. + +![Click the branch dropdown menu and select commit](../assets/images/git-commit-example.jpg) + +## Push Changes + +Pushing your changes to your remote repository for the first time creates the `.insomnia` directory, which you can use with the [Inso CLI](/inso-cli/introduction#data-search-flow). + +{:.alert .alert-primary} +**Note**: If you'd like to push to an alternative branch than the default, click on the branch dropdown menu. Select **Branches**, and add your desired branch name. + +Commits and branches only exist locally when created. A push needs to be done to share the commits and history of a branch remotely. If pushing fails, you will be given the option to force push. + +The push or force push operation can fail for many reasons, and logs will be presented in the Developer Console prefixed with `git-event` with further debugging information. A likely cause is that your user does not have permissions to push to a protected branch. + +For instance, with GitLab, the main/master branch is protected by default, and those with the developer role are unable to push directly to it. In that case, push to a separate branch and create a pull request, or update the permissions for your user on the repository. + +## Pull Changes + +If a collaborator makes a change to the remote repository, pull the changes to access the work locally. Click the branch dropdown menu in a Document and then **Pull**. Any incoming changes will be merged to your local machine. + +## Conflict Resolution + +Git sync does not currently support the ability to resolve conflicts within the application. If changes were made locally and remotely, a pull may fail. + +Here are some strategies to help with conflicts: + +* Each collaborator should make changes in a separate branch to avoid conflicts. Changes should be merged into master once reviewed and approved by other collaborators (eg. GitHub pull request). +* If a conflict occurs on pull, delete the branch locally and re-fetch it from the branches dialog. + +## Sign out of Git account + +Sign out of a synced Git management account. + +1. Click on **Setup Git Sync**, then click on **Repository Settings**. +2. You should see a list of all synced accounts. Next to each account is a **Sign Out** button. Click on **Sign Out** for the accounts that need to be signed out. +3. In the box that appears, click **Sign Out** again. + +The **Configure Repository** box will no longer list the account that was signed out in its list of configured accounts. diff --git a/docs/insomnia/verify-binary-provenance.md b/docs/insomnia/security-compliance/verify-binary-provenance.md similarity index 97% rename from docs/insomnia/verify-binary-provenance.md rename to docs/insomnia/security-compliance/verify-binary-provenance.md index 54ca714..f393aa0 100644 --- a/docs/insomnia/verify-binary-provenance.md +++ b/docs/insomnia/security-compliance/verify-binary-provenance.md @@ -1,10 +1,10 @@ --- layout: article-detail title: Verifying Build Provenance for Signed Insomnia Binaries -category: "Verifying Build Provenance for Signed Insomnia Binaries" -category-url: security --- + + Kong produces build provenance for Insomnia Application binary artifacts, which can be verified using `cosign` / `slsa-verifier`. This guide provides steps to verify build provenance for signed Insomnia Application binary artifacts in two different ways: diff --git a/docs/inso-cli/verify-signed-images.md b/docs/insomnia/security-compliance/verify-signed-images.md similarity index 87% rename from docs/inso-cli/verify-signed-images.md rename to docs/insomnia/security-compliance/verify-signed-images.md index bb669ac..7184a5a 100644 --- a/docs/inso-cli/verify-signed-images.md +++ b/docs/insomnia/security-compliance/verify-signed-images.md @@ -1,10 +1,10 @@ --- layout: article-detail title: Verify Signatures for Signed Inso CLI Images -category: "Inso CLI" -category-url: inso-cli --- + + Inso CLI Docker container images are now signed using `cosign` with signatures published to a Docker Hub repository. This guide provides steps to verify signatures for signed Inso CLI Docker container images in two different ways: diff --git a/docs/insomnia/security-features.md b/docs/insomnia/security-features.md deleted file mode 100644 index fc5616d..0000000 --- a/docs/insomnia/security-features.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -layout: article-detail -title: Key Security Data Features -category: Security -category-url: security ---- - -When you create an Insomnia account, you gain access to end-to-end encrypted project data sync. Simply sign into your account and your data will be there, seamlessly synced across all of your (and optionally your teams') devices. - -Insomnia believes that it is your right to know how your sensitive project data is transported and handled, so this document is an effort to explain exactly how it works. - -If you find that any part of this document is incorrect, missing, or wrong, please don't hesitate to reach out. - -## Key Security Data Features - -This section gives a high level overview of Insomnia project data sync security. If you read anything in this document, it should be this section. - -### What End-To-End encryption means - -E2EE means that all encryption keys are generated locally, all encryption is performed before sending any data over the network, and all decryption is performed after receiving data from the network. At no point in the sync process can the Insomnia servers, or an intruder read or access sensitive application project data. - -## What is project data? - -Project data are your API design specifications, collections, tests and other files that you choose to share with others in your organization through Insomnia's hosted data synchronization service. - -Please note that the Insomnia service may provide you the ability to develop tests for your API design specifications, as well as other functionality, using artificial intelligence tools. Data you provide to use these AI tools are not end-to-end encrypted and so this document does not apply to such data. - -### Encryption algorithms we use - -All data is encrypted using randomly generated 256 bit symmetric keys for use with AES-GCM-256 (Galois Counter Mode). - -### Resetting Passphrases - -Losing your passphrase means losing the ability to decrypt your account keys. If you lose your passphrase there is no way to access your project data that is not stored by you locally, and there is nothing Insomnia can do to help apart from resetting your passphrase as well as your account. - -You can reset your passphrase through the "[Forgot Passphrase](/insomnia/forgot-passphrase)" flow. Once you go through the "[Forgot Passphrase](/insomnia/forgot-passphrase)" flow and define a new passphrase, you'll lose access to your previous encrypted project data. - -If you have been invited to collaborate with other organizations, you can reset your passphrase and then ask to be invited back. You will only be able to retrieve data for the organizations that you are invited back to. - -If you have shared your personal organizations or project data, you can ask other users with Admin permissions to also re-invite you after resetting the passphrase. - -### Unencrypted Fields - -By default, project data resources within the Insomnia application are fully encrypted before being sent to the server. However, both id and name of each resource are attached in plaintext before uploading. - -### Local data is not encrypted on disk - -Insomnia currently stores application project data locally on disk in raw form. E2EE only applies to project data that is transmitted over the network. It is still possible for malicious software to access the project data stored on your machine. Please take the usual precautions to keep your local project data safe. - -## Useful Definitions - -Here are definitions for the common things that will be talked about. - -### Data Models - -The following are data models we use. - -{:.table .table-striped} -Data Model | Definition ----------- | --------- -`M_Account` | A user that can log in -`M_Resource` | An entity that can be synced (eg. Request, Workspace, etc.) -`M_ResourceGroup` | A group of M_Resource that can be shared as one -`M_Link` | A relationship linking a M_Account to M_ResourceGroup - -### Keys and Salts - -The following are keys and salts we use. - -{:.table .table-striped} -Name | Description | Stored? ------ | ------ | ----- -`PUB_Account` | Public key for M_Account | Yes -`PRV_Account` | Private key for M_Account | Yes 🔒 -`SYM_Account` | Symmetric key for M_Account | Yes 🔒 -`SYM_ResourceGroup` | Symmetric Key for data encryption | No -`SYM_Link` | Encrypted form of SYM_ResourceGroup | Yes 🔒 -`SLT_Auth_1` | Salt for PBKDF2 of passphrase for auth | Yes -`SLT_Auth_2` | Salt for SRP authentication process | Yes -`SLT_Enc` | Salt for PBKDF2 of passphrase for encryption | Yes -`SEC_PWD_Auth` | Secret derived from passphrase using SLT_Auth_1 | No -`SEC_PWD_Enc` | Secret derived from passphrase using SLT_Enc | No -`SRP_Verifier` | Verification string used for SRP | Yes - -{:.alert .alert-primary} -**Note**: `SYM_Link` and `SYM_ResourceGroup` are essentially the same thing, but are defined separately for the purpose of discussion. This will become clear later on. diff --git a/docs/insomnia/security-standards.md b/docs/insomnia/security-standards.md deleted file mode 100644 index 3507c0f..0000000 --- a/docs/insomnia/security-standards.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -layout: article-detail -title: Security Standards -category: Security -category-url: security ---- - -This document addresses common questions we get about our security standards. - -**How is data processed when sent to Insomnia servers?** - -* Information is sent over TLS -* Information sent is end-to-end encrypted - -**Where is our information stored?** - -* Information is stored in GCP, in US Central region -* Information inside of GCP is stored within Postgres - -**Do we have any compliance certifications?** - -Not at the moment. - -**Do you have any penetration test results from external parties?** - -Not at the moment. - -**What authentication is implemented by the application?** - -* Secure Remote Passwords (SRP) encrypted key exchange protocol. - -**How often do you release major updates, and or security patches?** - -* We regularly update the Insomnia desktop application. -* Security, and hotfix patches are handled on a case-by-case basis and can occur at any time. - -**Do you retain server logs, or event logs?** - -* All server logs stored are kept within GCP and only accessed by engineers authorized to manage the Insomnia servers. - -**Do you maintain documentation when an incident/event occurs?** - -* When an incident occurs, we perform an internal post-mortem and disseminate information accordingly, either through the site in the form of a blog post, or through social media/support on a case-by-case basis. - -**In case of a breach, do you notify customers?** - -* Yes, via email. - -**What is your primary point of contact?** - -* [Open Source](https://github.com/kong/insomnia) -* [Support channels](https://insomnia.rest/support) diff --git a/docs/insomnia/signup-and-auth.md b/docs/insomnia/signup-and-auth.md deleted file mode 100644 index 3512ba1..0000000 --- a/docs/insomnia/signup-and-auth.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -layout: article-detail -title: Signup and Authentication -category: Security -category-url: security ---- - -Since the passphrase you choose at registration time is used during the encryption process (although indirectly), it's vital that it's never sent or stored on the server in an easily crackable form. To help with this goal, Insomnia uses the [Secure Remote Passwords (SRP)](http://srp.stanford.edu/) encrypted key exchange protocol. - -You can read more about the exact SRP implementation that Insomnia paid plans use in [RFC-2945](https://datatracker.ietf.org/doc/html/rfc2945). - -For a detailed description of SRP, see [Mozilla's Node SRP](https://github.com/mozilla/node-srp). - -### How Account Creation Works - -These are the steps taken on the client during account creation. - -1. Randomly generate 256 bit keys and salts `SYM_Account`, `SLT_Auth_1`, `SLT_Auth_2`, `SLT_Encryption` -2. Generate `PUB_Account`/`PRV_Account` keypair for RSA-OAEP SHA-256 -3. Generate `SEC_PWD_Auth` using the following steps - 1. Combine `SLT_Auth1` with email address using HKDF SHA-256 to form a new salt `SLT_TMP_1` - 2. Run 100,000 iterations of PBKDF2 SHA-256 with SLT_TMP_1 -4. Generate SEC_PWD_Enc using the following steps - 1. Combine SLT_Enc with email address using HKDF SHA-256 to form a new salt `SLT_TMP_2` - 2. Run 100,000 iterations of PBKDF2 SHA-256 with `SLT_TMP_2` -5. Generate SRP_Verifier using `SLT_Auth_2`, email address, `SEC_PWD_Auth` -6. Encrypt SYM_Account using `SEC_PWD` -7. Encrypt PRV_Account using `SYM_Account` -8. Send `M_Account` object to server for creation - -Once the account is created, the server will send a verification email to the user. Once the user receives this email, they can attempt to log in. - -### How Account Login Works - -These are the steps taken on the client during login. - -1. Derive `SEC_PWD_Auth` using same steps as in Account Creation -2. Use `SLT_Auth_2` to perform SRP exchange -3. Store SRP-generated `K` locally to use as session key - -Now that we know how signup and authentication are performed, we can talk about data encryption. diff --git a/docs/vercel.json b/docs/vercel.json index 6c0e3b2..1e77100 100644 --- a/docs/vercel.json +++ b/docs/vercel.json @@ -123,6 +123,20 @@ { "source": "/category/(.*)", "destination": "/", "permanent": false }, { "source": "/collection/(.*)", "destination": "/", "permanent": false }, - { "source": "/insomnia/team-collaboration", "destination": "/insomnia/teams", "permanent": false} + { "source": "/insomnia/team-collaboration", "destination": "/insomnia/teams", "permanent": false}, + + { "source": "/insomnia/managing-e2ee", "destination": "/insomnia/security-compliance/e2e-encryption", "permanent": false}, + { "source": "/insomnia/scratchpad", "destination": "/insomnia/security-compliance/storage", "permanent": false}, + { "source": "/insomnia/insomnia-storage-options-guide", "destination": "/insomnia/security-compliance/storage", "permanent": false}, + { "source": "/insomnia/insomnia-sync", "destination": "/insomnia/security-compliance/storage", "permanent": false}, + { "source": "/insomnia/git-sync", "destination": "/insomnia/security-compliance/storage", "permanent": false}, + { "source": "/insomnia/sbom", "destination": "/insomnia/security-compliance/sbom", "permanent": false}, + { "source": "/insomnia/security-features", "destination": "/insomnia/security-compliance/standards", "permanent": false}, + { "source": "/insomnia/security-standards", "destination": "/insomnia/security-compliance/standards", "permanent": false}, + { "source": "/insomnia/signup-and-auth", "destination": "/insomnia/security-compliance/standards", "permanent": false}, + { "source": "/insomnia/analytics-collected", "destination": "/insomnia/security-compliance/standards", "permanent": false}, + { "source": "/insomnia/data-encryption", "destination": "/insomnia/security-compliance/standards", "permanent": false}, + { "source": "/insomnia/verify-binary-provenance", "destination": "/insomnia/security-compliance/verify-binary-provenance", "permanent": false}, + { "source": "/inso-cli/verify-signed-images", "destination": "/insomnia/security-compliance/verify-signed-images", "permanent": false} ] }