Tools used to develop and release a product with Ketryx Lifecycle Management are provided in MAN-01 Ketryx Lifecycle Management. The release process is described in detail in MAN-02 Software Release Process, while setting up code repositories is described in MAN-03 Supply Chain Management.

2. Repository access

The integration process with GitLab varies slightly depending on whether you are working with public or private repositories. Here's a breakdown of the key differences:

2.1. Public Repositories

• Accessibility: Public repositories are open to the public, meaning that anyone can view the repository content and its history.

• Integration Setup: For public repositories, the setup process for integrating with Ketryx is generally straightforward. You do not need to use an access token for basic integration tasks, such as SOUP dependency analysis.

2.2. Private Repositories

• Accessibility: Private repositories restrict access to authorized individuals or collaborators. Only those with permission can view and interact with the repository.

• Integration Setup: When integrating with private repositories, you typically require an access token. This token ensures secure and authorized communication between GitLab and Ketryx for tasks like SOUP dependency analysis.

It's important to consider your repository's visibility when setting up the integration, as public and private repositories have distinct access requirements. The integration guide provides specific instructions based on the type of repository you are working with, ensuring a seamless and secure integration experience.

3. Access tokens

3.1. Creating a Personal Access Token for GitLab

Please see GitLab's documentation. The scope read_repository scope should be selected.

3.2. Creating a Project Access Token for GitLab

An alternative to the Personal Access Token is the Project Access Token. Steps on how to create one can be found in GitLab's documentation. For the scope, read_repository scope should be selected. For the role of the token, Reporter should be selected.

4. Related features

4.1. Using the Code Change Review feature with GitLab

Ketryx does not support Code Change Reviews with GitLab at this time. We are working on adding this feature in the future. Please reach out if you this feature is a priority for you.

This guide provides step-by-step instructions for installing, configuring, and using the Chrome extension.

2. Installation and Setup

To install and set up the Ketryx Chrome extension:

1. Open the Chrome Web Store and search for "Ketryx" (or use this link)

2. Click "Add to Chrome" to install the extension

3. Click the extension icon in your Chrome toolbar

4. Click on the options page

5. Configure your settings:

   • Enter your Ketryx instance URL

   • (Optional) Enter your custom TestRail instance URL if using a self-hosted version

   • Save your settings

3. Using the Extension

3.1. Basic Navigation

When viewing a TestRail test case, test run or testplan:

1. The extension automatically detects the current TestRail record

2. A "See in Ketryx" button appears in the TestRail interface

3. Click the button to open the corresponding record in Ketryx in a new tab

3.2. Configuration Options

The extension provides the following configuration options:

• TestRail Instance URL: (Optional) Custom URL for self-hosted TestRail instances

4. Frequently Asked Questions

4.1. Q: How do I update my TestRail instance URL?

1. Click the extension icon in your Chrome toolbar

2. Click "open options page"

3. Update the TestRail Instance URL field

4. Click Save

4.2. Q: The extension isn't detecting my TestRail records. What should I do?

• Ensure you're logged into both TestRail and Ketryx

• Verify that your TestRail instance URL is correctly configured

• Check if your Ketryx project has been correctly synced

4.3. Q: The extension opens the projects page

This can happen when we don't find the item, make sure you are in a project that is being synced to Ketryx, and force the sync to make sure you have all the latest items.

5. Security and Privacy

The Ketryx Chrome extension:

• Only stores configuration data locally

• Does not collect or transmit personal information

1.2. Tools

Tools used to develop and release a product with Ketryx Lifecycle Management are provided in MAN-01 Ketryx Lifecycle Management. The release process is described in detail in MAN-02 Software Release Process, while setting up code repositories is described in MAN-03 Supply Chain Management.

2. Supported platforms

Ketryx supports Git repository data fetching for repositories hosted on GitHub, Bitbucket, GitLab, and Azure Repos. If you need support for other protocols like SVN, etc., please contact our support.

3. Adding your repository to Ketryx

On the project creation, or for existing projects on their settings page, you can add a repository:

• To pull the Code Change Reviews (CCR)

• For SOUP dependency analysis

• Use Git-based configuration items

The URL of the repository is required, and you can also add authentication information for the repository. This is required for private repositories, and for public repositories if you want to fetch CCR data.

Additionally, the analyzed branch can be set, which is the branch that is used for SOUP dependency analysis, CCR data fetching or configuration items syncing. The default is main or, in lieu of that, master.

Instead of a branch, you can also set a tag, which will be used for SOUP dependency analysis, CCR data fetching or configuration items syncing. This is useful if you want to analyze a specific release version, e.g., refs/tags/v1.0.0.

You can also define a release ref pattern. The naming pattern used to detect release branches or tags. These can be version-specific. Use # as a SemVer-compatible version placeholder. For example, release/# will match release/3.2.1, release/3.2, or release/3 (considered in this order of precedence) for a version with version number 3.2.1. The default is refs/tags/#.

3.1. Private repositories

For private repositories, you need to add authentication information. This is done on the project settings page, where you can enable repository authentication. You can set a username and password, which will be used to authenticate with the repository.

For more information about specific hosting services, see the guides for Bitbucket, GitHub, and GitLab.

4. Related features and guides

Please see MAN-03 Supply Chain Management: Software Dependencies for more information on how to use the SOUP dependency analysis feature.

Please see MAN-09 Git-Based Configuration Items for more information on how to use Git-based configurations items.

Please see the guide on Code Change Reviews using Ketryx for more information on how to use that feature, which is supported for GitHub and Bitbucket.

Please see the documentation of the builds API and how to set up GitHub Actions for integration with CI/CD systems.

This guide provides answers to common questions around this integration.

2. Setting up the integration

To install the Ketryx app in Jira Cloud, you need to have administrative privileges on the Jira organization and the Manage connections permission in Ketryx (which, by default, is only assigned to organization owners). Then you can do the following:

1. Log into Ketryx

2. In Jira, install the Ketryx Connector for Jira app from the Atlassian Marketplace

3. Complete the installation process of the Jira app by pressing Get started and Complete installation in Ketryx

4. In Ketryx, confirm the connection by pressing Connect Jira organization

Once the connection between your Ketryx organization and your Jira instance is established, you can create Ketryx projects that are connected to individual Jira space (formerly project).

Note that each Jira instance can only be connected to one Ketryx organization, and each Jira space can only be connected to one Ketryx project (and vice-versa).

3. Frequently Asked Questions

3.1. Q: Do I have to use the provided Ketryx scheme for work types?

Ketryx maintains four predefined work type schemes for common use cases, based on the full schema with all the Ketryx item types. If this does not fit your use exactly, you can either copy a Ketryx work type schema and tweak it, or use a completely custom work type scheme. When using a custom work type scheme, you will usually want to configure a custom mapping from Jira work types to Ketryx items, using the advanced setting Issue mapping.

3.2. Q: Why does Ketryx introduce custom relation fields rather than using Jira's native links?

There are two main reasons for this:

1. Native links can go from any work item to any other work item, so you can't restrict the target of a particular relation. For instance, a has parent relation might point to any other item, while the Parent requirements fields can be restricted to only contain other Requirements as options.

2. You can edit native links even when a ticket is otherwise read-only, i.e. even when the work item is already Resolved or Closed.

That being said, Ketryx also recognizes native Jira links as long as they match the Ketryx relation names. These names can also be configured using the advanced setting Relation names. If you prefer to work with Jira links, you can use these, and potentially remove certain relation fields using the advanced setting Item fields.

3.3. Q: How can I rename fields in the Ketryx schema?

To rename fields, you can use the advanced setting Field names in the Ketryx organization configuration.

Note that fields with custom names are created as custom fields in Jira, rather than using the fields provided by the Ketryx Jira app. Previous field values might have to be migrated from the previous field to the new field in Jira. This is why it is recommended to define the desired field names before starting to work with those fields in Jira.

When switching from one custom name to another custom name (not for the initial switch from the default name to a custom name), you can also use the advanced setting Superseded field names to effectively rename the existing field rather than creating a new one, to avoid having to migrate field values from one to the other.

Immediately after creating an API key, a secret token is displayed and can be copied and pasted into a secure location. This token can be used as the Authorization header in direct HTTP requests to the Ketryx API, in the following form:

API keys can also be used as the api-key parameter to the Ketryx GitHub Action.

Tools used to develop and release a product with Ketryx Lifecycle Management are provided in MAN-01 Ketryx Lifecycle Management. The release process is described in detail in MAN-02 Software Release Process, while setting up code repositories is described in MAN-03 Supply Chain Management.

2. Repository access

The integration process with Azure DevOps varies slightly depending on whether you are working with public or private repositories. Here's a breakdown of the key differences:

2.1. Public Repositories

• Accessibility: Public repositories are open to the public, meaning that anyone can view the repository content and its history.

• Integration Setup: For public repositories, the setup process for integrating with Ketryx is generally straightforward. You do not need to use an access token for basic integration tasks, such as SOUP dependency analysis.

2.2. Private Repositories

• Accessibility: Private repositories restrict access to authorized individuals or collaborators. Only those with permission can view and interact with the repository.

• Integration Setup: When integrating with private repositories, you typically require an access token. This token ensures secure and authorized communication between Azure DevOps and Ketryx for tasks like SOUP dependency analysis.

It's important to consider your repository's visibility when setting up the integration, as public and private repositories have distinct access requirements. The integration guide provides specific instructions based on the type of repository you are working with, ensuring a seamless and secure integration experience.

3. Access tokens

3.1. Creating a Personal Access Token for Azure DevOps

Please see Azure DevOps's documentation.

3.2. Creating a fine-grained Personal Access Token for Azure DevOps

The following Read-only permissions are required for the integration with Ketryx:

• Code

When creating the personal access token please make sure to select all necessary permissions for your application.

This token will serve as the authentication method to fetch the Git repository for SOUP dependency analysis from Azure DevOps.

When entering the authentication credentials in Ketryx, the username has no effect, but the password should be the PAT.

4. Related features

4.1. Using the Code Change Review feature with Azure DevOps

Ketryx does not support Code Change Reviews with Azure DevOps at this time. We are working on adding this feature in the future. Please reach out if you this feature is a priority for you.

If this is activated, an item can only be approved once all its design inputs are in a controlled state.

Require re-verification of affected items after change control

If this is activated, after an item is changed and enters a controlled state again, Ketryx will automatically unclose any other items affected by the change, i.e. transition any design outputs of the changed design input that are currently Closed back to Resolved, so they will need re-verification before entering a controlled state again themselves.

You can see all affected items using a filter on the items screen called Re-verify affected items.

Create re-verification flags for affected design outputs when design inputs change

When enabled, Ketryx will automatically create re-verification flags for design output items that may be affected when a design input item completes change control (re-transitions to a controlled state after being modified). More information can be found here.

These flags serve as reminders to review and verify that the design output items are still valid and up-to-date, given the changes to their related design inputs.

Flags can be dismissed explicitly by clicking "Dismiss" or can be dismissed implicitly by the flagged item completing change control (re-transitioning to a controlled state after being modified).

You are able to filter for flagged items using the KQL filter (which can be used in settings like the Invalid items filters or Custom KQL filters):

is:flagged

Test management

The test management settings are used to configure the test management process for a project to customize the behavior of Ketryx for a specific project.

Require a manual test execution for each effective automated test execution

If enabled, a manual Test Execution item has to be created for the latest automated test execution, before the test is considered passing.

This provides a way to enforce that each automated test is reviewed and electronically signed by itself, in addition to signing the overall testing report.

This applies to automated test executions associated with a Test Case, not to automated tests that are directly associated with a Software Item Spec or other item.

Require automated tests to be associated with test cases

If enabled, automated tests reported to Ketryx are only considered if they are directly associated with a Test Case item. Automated tests associated with Software Item Specs or other items are not considered part of the test plan and testing report.

Allow controlled failed test executions

If this is activated, failing test executions do not block a release, as long as they are in a controlled state.

Inherit excluded tests

If this is activated, Test Executions from the previous release will be considered effective for Test Cases that have been excluded from a version's release test plan.

Require test executions after controlled test cases

If enabled, a Test Execution will only be taken into account if it was created after the Test Case entered a controlled state.

Automatically update release test plan based on external test plan(s)

If enabled and there are external test plans items defined for a version, the overall Ketryx release test plan for the version will be updated automatically to include the tests from those external test plans items.

Release controls

The release control settings are used to configure the release control process for a project to customize the behavior of Ketryx for a specific project. This enables you to enforce certain controls on the release process, or disable them if they are not needed.

Require controlled dependencies

If this is activated, a release can only be approved if all dependencies are in a controlled state.

Require controlled items

If this is activated, a release can only be approved if all items are in a controlled state.

Require a controlled test plan

If this is activated, a release can only be approved if the test plan is in a controlled state.

Require generated release documents

If this is activated, a release can only be approved if all required release documents are generated.

Require uploaded build documents

If this is activated, a release can only be approved if all required build documents are uploaded.

Require up-to-date release documents

If this is activated, a release can only be approved if all required release documents are up-to-date.

Require approved release documents

If this is activated, a release can only be approved if all required release documents are approved.

Require full traceability

If this is activated, a release can only be approved if all items are fully traceable. See the Traceability Configuration reference and MAN-07 Traceability for more information.

Require controlled milestones

If this is activated, a release can only be approved if all milestones are in a controlled state.

Training

Require training

If this is activated, users will be required to complete training before they can approve items. For example, if a group has assigned training, Members must perform that training, or they will not be able to perform actions (i.e., approvals) as part of the Group.

Risk management

The risk management settings are used to configure the risk management process for a project to customize the behavior of Ketryx for a specific project.

For even more fine-grained control over risk management using the advanced settings, please see MAN-08 Risk Management.

Require harm and initial severity selection

If enabled, users are not able to set a custom harm or initial severity value. Instead, they may only select a pre-defined harm, and the associated initial severity of that harm is enforced.

Require derived risk analysis fields

If enabled, users are not able to modify the derived risk analysis fields (i.e. initial and residual risk evaluation, risk acceptability).

Require hazard selection

If enabled, users are not able to set a custom hazard. Instead, they may only select a pre-defined hazard.

Require hazardous situation selection

If enabled, users are not able to set a custom hazardous situation. Instead, they may only select a pre-defined hazardous situation.

Deleting a project

If a user wants to delete a project in Ketryx, click the 'Delete project' button at the bottom of the project settings. Doing this will require the user to type the name of the project they are currently attempting to delete and provide their security key. After checking the 'I confirm I want to delete this project' box, the user will be able to delete the Ketryx project. Once a Ketryx project is deleted, there is no way to recover it.

Automatic two-way visibility that displays both forward and reverse relations when you link items

Use custom relations when the default relation types (fulfills, tests, etc.) don't capture the specific dependencies and connections in your system architecture or development process.

This guide explains how to configure and use custom relations in your Ketryx organization.

NOTE:

• Adding custom relations should only be performed by your Ketryx organization owner.

Getting started

The following will explain the full workflow for configuring a custom relation in Ketryx. In this example, we'll create a relation called "uses HW" that allows Software Item Spec items to link to Hardware Item Spec items.

Configuration in Ketryx

1. Navigate to Organization > Advanced

2. Add your custom relation to the Custom Relations setting

Field Descriptions:

• Key (SW_USES_HW): A unique identifier for this relation. This key must be unique across all custom relations and should be descriptive.

• direction: Either "upstream" or "downstream". Defaults to "downstream".

  • "downstream" means the relation points forward (e.g., Software → Hardware)

  • "upstream" means the relation points backward

• fieldName: The human-readable name shown when viewing the source item (e.g., "Uses HW component")

• reverseFieldName: The human-readable name shown when viewing the target item (e.g., "Is used by SW component")

• relationName: The short name for the relation in the forward direction (e.g., "uses HW")

  • Warning: This value becomes permanent once the relation is used to link items (see Limitations section below).

• reverseRelationName: The short name for the relation in the reverse direction (e.g., "is used by SW")

  • Warning: This value becomes permanent once the relation is used to link items (see Limitations section below).

• sourceItemTypes: An array of item type names that can use this relation. Can include both system item types (e.g., "Software Item Spec", "Requirement") and custom item types (e.g., "Folder")

• targetItemFilter: A KQL filter that defines which items can be targeted by this relation (e.g., "type:HW" for Hardware Item Spec items or "type:FOL" for custom Folder items)

• traceabilityWidgetAddLabel: The label shown on the button in the traceability widget (e.g., "Add used HW component")

1. Click Save changes and confirm

At this point, every project in the Ketryx organization is ready to use the custom relation between Software Item Spec and Hardware Item Spec items.

Limitations

1. Relation Names are Permanent: Once a custom relation is used to link items, relationName and reverseRelationName become permanent. These values are stored in the backend database, and changing them will break existing traceability links.

   1. Best Practice: Choose your relation names carefully the first time. Plan your naming convention before implementation and test with a pilot relation before creating multiple relations.

2. Reverse Relations Cannot Be Created from the Traceability Widget: Relations must always be created from the source item type. For example, for the SW → HW relation above (Software uses Hardware):

   1. You can create the link from the Software Item Spec

   2. You cannot create the link from Hardware Item Spec

The reverse relations ("Is used by SW component") will be visible on Hardware Items, but new links must be created from the Software Item side

Workaround: Always navigate to the source item type to create custom relation links. The reverse relation will automatically appear in the target item's traceability widget once created.

Recipes

Match everything but exclude a certain file

If you want to match all files but exclude dev/requirements.txt, you can use the following glob patterns:

The first pattern ** matches all files. The second pattern !dev/requirements.txt negates the match for dev/requirements.txt, effectively excluding it.

Ignore package-lock.json but keep package.json

If you want to match all files but exclude package-lock.json while keeping package.json, you can use the following glob patterns:

The first pattern ** matches all files. The second pattern !package-lock.json negates the match for package-lock.json, effectively excluding it. Since package.json is not explicitly excluded, it will still be matched by the ** pattern.

As a result, package.json will be included in the analysis, while package-lock.json will be excluded. This way, Ketryx would only pick up the versions declared in package.json and ignore the lock file and the locked versions.

An alternative glob pattern to just select package.json would be:

This pattern will match any package.json file in any directory, compared to the previous pattern that matches all files except package-lock.json in the root directory.

Matching a file path when multiple glob patterns have been provided

• Matching occurs from the first defined pattern to the last defined pattern

• During the matching, it keeps a match / no match state that is updated based on the current matching result of each glob pattern

• The given file path is matched against each glob pattern

• As soon as a non-negated glob pattern matches the file path, the matching state would be true

• From there on, negated patterns (starting with !) matching the file path may set the matching state back to false

• Following negation, subsequent matches of non-negated patterns can revert the matching state back to true, allowing for toggling between inclusion and exclusion of files or paths

• Alternating matches of negated and non-negated patterns can toggle the matching state, allowing fine-grained control over which files or paths are ultimately selected

• The final matching result will be returned, i.e. "the last match wins", and whether the file is included in the analysis is based on whether that match is negated or not

The scope of this manual is the configuration of approval rules within Ketryx.

2. Project-level approval rules

The most common way of configuring approval rules for a project and its configuration items is to use the project-level approval rules. These rules are applied to all items in the project and are configured in Project Settings > Approval Rules.

2.1. Approval options

There are four different approval options available:

1. Separate owner approval: When activated, the approval by the owner of a configuration item only counts as the owner approval, regardless of which approval groups the owner might also be a member of.

2. Separate group approval: When activated, each approval only counts for one approval group, namely the first group that the approver is a member of and that has not approved the item yet.

3. Enforce approval order: When activated, approvals need to happen in the order defined by the approval steps. Furthermore, the owner of the item must approve first.

4. Enforce initial owner approval: When activated, the owner of an item must be the first to approve. Any approvals afterwards may happen in any order. If Enforce approval order is enabled, then the owner has to approve first regardless of this setting.

NOTE: Out of the above four, the first two are only relevant for group-based approval steps.

2.2. Approval steps

Approval steps can be configured for all of the project's approval types, which are based on a combination of the project's work type schema, the organization's enabled modules (e.g. ALM, SBOM) as well as the custom document types and custom item types configured in the organization's advanced settings.

Approval steps can be based on either groups or users. Every project will have a default set of approval steps based on the default groups configured in the organization. For group-based approval steps, it is also possible to define the minimum number of approvals required for each group.

NOTE: If a specific user is selected as an approval step, their approval will only apply to that step and will not count toward any groups they belong to. Additionally, if the selected user is also the owner of the item, their owner approval will automatically fulfill their individual approval step.

An example of the above would be:

In the above example configuration, Test User's approval will only ever count for their own approval step, even if they are a member of R&D Leads or Quality Managers. Additionally, if Test User is the owner of any Anomaly item in the project, their owner approval will fulfill their individual approval step. This is also reflected on all approval-related widgets in Ketryx by only showing the owner approval step for any Anomaly items owned by Test User.

2.3. Release document rules

By default, Ketryx applies the "Release" rule to all release document approvals.

However, this behavior can be overridden by creating custom rules for specific system document types. This is done using the Add new release document rule dropdown.

These custom rules can be removed at any time, reverting the behavior back to the default "Release" rule.

NOTE: These rules do not affect user-uploaded documents or custom release documents.

2.4. Advanced settings

The project-level approval rules can be configured further using the following advanced settings:

• Approval rules

• Approval workflow

3. Item-level approval rules

Users with the Manage item-level approval rules permission can configure approval rules for individual items in a project. This is an organization-level permission.

The configuration of item-level approval rules happens on the Record details page of an item by clicking on the Edit approval rules button.

This will open a dialog that allows the user to configure the approval rules for the item.

NOTE: There are a few specific limitations/behaviors related to item-level approval rules:

1. Editing an item-level approval rule always requires MFA to be enabled.

2. Editing an item-level approval rule will result in the creation of a new record.

3. Editing item-level approval rules is only possible when the item is not in a "Resolved" or "Closed" state. An exception to this is Git-based items, which can be edited even when the item is in a "Resolved" state.

4. The item-level approval rule will get reset whenever the item is transitioned out of a "Closed" state.

5. The "Approval rules" and "Approval workflow" advanced settings will not have an effect on items that have item-level approval rules configured.

4. Milestone-level approval rules

Users are able to configure approval rules for individual milestones in a project, similar to the item-level approval rules.

The configuration of milestone-level approval rules happens on the Milestones configuration page.

When a milestone has a milestone-level approval rule configured, the rule will apply to both the milestone itself and all of its documents.

NOTE: The milestone-level approval rule will not be applied to the milestone's items (in case of a configuration item milestone).

Automated Triggers:

API:

Furthermore, data can be ingested via the Ketryx API, as is done, for instance, by the Ketryx GitHub Action which uses the Build API to report automated test results.

Set up domain-wide delegation for Ketryx’s Service Account

1. Log into Ketryx.

2. Navigate to Connections in the organization settings menu.

3. Find the Google Workspace section and take note of the Client ID and Client Email. You will need both in subsequent steps.

1. Follow these instructions to set up domain-wide delegation for Ketryx’s Service Account.

   1. This is a one-time setup for each Google workspace.

   2. Use the Client ID from the previous step.

   3. Grant the non-sensitive scope https://www.googleapis.com/auth/drive.file

Prepare a Google Drive folder

1. In your Google Drive, either create a new designated Shared Drive or select an existing one.

2. Create or select a designated folder in the Shared Drive (e.g. containing your QM documents)

3. Share the folder with the Ketryx Service Account using the Client Email found on the Ketryx Connections page, and grant at least Editor access.

1. Open the folder and copy its ID from the URL, e.g., given the URL https://drive.google.com/drive/folders/1G7X8jRTKjCmyIaZE-fnIznRNHFD8DjQq, the ID is 1G7X8jRTKjCmyIaZE-fnIznRNHFD8DjQq

Configure Ketryx to read in the Google Drive folder

1. In Ketryx, create a new folder in your organization or a project, to which you want to sync documents from your Google Drive. Copy the name of that folder (e.g. GDrive)

1. Navigate to the Advanced settings of your organization or a project for which you want to enable the integration.

2. Find the External EDMS mapping setting and enable Google using the Google Workspace folder ID and Ketryx folder name copied earlier:

Syncing documents & turning them into Ketryx configuration items

1. In Ketryx, navigate to the folder you have configured to sync to Google Workspace and click on “Import new documents”.

1. To pull in changes made to a document in Google Drive, open the details view of the document in Ketryx and click “Sync”.

1. If you want to turn a document into a configuration item, please follow the steps in this guide.

The Guest role provides read-only access to your Ketryx organization. Users with the Guest role (hereafter, guest) can view content within the organization and its permitted projects, but cannot make any changes or modifications. This role is ideal for staff who need context without editing capabilities, external auditors requiring system access, or stakeholders who need visibility into your quality management system.

Guest Capabilities

What a Guest CAN do

• The user can view any data, including audit trails.

• The user can trigger a synchronization of Ketryx with external systems.

What a Guest CANNOT do

• The user cannot create, edit, or delete any data, configuration, or files.

• The user cannot take any action that would alter the audit trail (e.g., acknowledging documents, approving items).

Guests are prohibited from editing any data under any circumstances. Even if a guest is given edit permissions on a project, they will still not be able to exercise this permission. To achieve granular permissions, use the member role and groups. The Guest role can be seen as a security feature for users who should never, under any circumstances, get write access to Ketryx (e.g., auditors).

Note: UI elements that trigger data modifications appear greyed out and disabled for Guests. For example, the "Create Item" button will be visible but non-functional:

Setting Up Guest Access

Inviting New Guests

Organization Owners can invite Guests:

1. Go to Organization

2. Navigate to Members

3. Use the Invite Member button

4. Enter the following information:

   1. User's full name

   2. Email address

   3. The role the user has at your company

   4. Ketryx user role: Change Member (default) to Guest
   5. [Optional] Add a rationale for inviting this member. For example: "External auditor for internal audit"

5. Use the Invite button

6. The invited user should receive an invitation email.

Change Role of an Existing User to Guest

Organization Owners can change an existing user's role to Guest:

1. Go to Organization

2. Navigate to Members

3. Find the user you want to change to Guest

4. Use the Make guest button within the Action column of the table
5. Confirm the user role change

View Guest Status

Organization Owners can view which users have Guest access:

1. Go to Organization

2. Navigate to Members

3. Find the user within the table

4. Look for Guest in the Role column

For fine-grained tokens: Contents, Metadata, and Pull requests permissions

The definitions of this document conform to the ones of ISO/IEC 62304.

3. AWS support

For each AWS resource, Ketryx will track the following data:

• Resource type

• Resource ID

• Creation timestamp

• Snapshot timestamp

• Matched environment (as defined by the Ketryx AWS cloud configuration settings)

• Raw JSON configuration (as provided by AWS Config)

3.1. Prerequisites

• An AWS account with access to all the resources that should be tracked for cloud configuration data. This account also requires AWS Config to be enabled.

• An IAM user/role with relevant permissions to create new roles and policies for the relevant AWS account.

• A Ketryx admin user with organization and project editing permissions.

Note: Adding Cloud Configuration Management to Ketryx will require giving AssumeRole permissions to the Ketryx AWS account. Ketryx will only require the minimal set of permissions to get relevant configuration data from AWS Config.

3.2. AWS Config

Ketryx relies on AWS Config to fetch configuration data from an AWS account. Use the AWS Config dashboard to verify that all relevant resources for your project are listed.

3.3. Resource tags

All resources that should be tracked by Ketryx require a proper project tag and environment tag. If the AWS account is dedicated to a single project, the project tag may be omitted.

Environment tag examples:

• Key: Environment, Value: production

• Key: Environment, Value: staging

Project tag example:

• Key: Project, Value: ketryx-app

3.4. Manage AWS connections

Login to Ketryx and go to your organization’s Connections page. There, you will find a dedicated AWS section to add and manage your connections.

3.5. Add a new connection

Press the Add AWS connection button and follow the instructions to set up the necessary Ketryx connection role and policies via the AWS IAM service.

As soon as the role has been created, copy the role ARN into the Role ARN field, and select the relevant AWS region for accessing your AWS Config data. Ketryx will only access data in the selected region.

Click the Save & Test Connection button to verify your connection. Ketryx will store your new ARN when a connection could be established.

On successful save, the connection will now show up in your AWS connections section. You may add multiple connections or remove existing connections. All configured AWS connections will be available for every project within your organization. It is impossible to add multiple connections for the same AWS account ID.

3.6. Enabling AWS tracking in a Ketryx project

After configuring your AWS connection, you can now add project-specific AWS settings to track all relevant AWS cloud configuration items.

Open a Ketryx project you want to track cloud configuration items for, and navigate to Settings > Cloud Configuration.

The cloud configuration settings page will automatically pre-select your newly created AWS connection. You may now configure your project to fetch data from your AWS account with the following settings:

• Enable AWS cloud: When enabled, Ketryx will automatically fetch resources according to the configuration. Data will be fetched after each settings change, later on every 6 hours.

• Project Filter: If your AWS account is used for multiple independent projects, you may provide a general tag filter that will instruct Ketryx to only fetch tagged resources with the relevant project tag. If your AWS account only hosts resources for your selected Ketryx project, this setting may be omitted to fetch all resources.

• Environments: You may define one or more environment matchers for your target environments. All resources captured by Ketryx will be categorized by the given environment tags. Environments will be listed on the Cloud item page and in the generated Cloud Configuration report.

3.7. Test and save settings

Click the Run test button in the Test settings section to see the number of resources fetched for each environment. If you are satisfied with the result, press the Save changes button to save your settings. When Enable AWS cloud configuration is activated, Ketryx will start fetching data from AWS.

4. List cloud configuration data

Within your project, navigate to the Cloud page to show all cloud configuration items. You may pick a version and/or environment to narrow down to a particular dataset. When Current is selected, all the latest up-to-date record data will be shown. When selecting a released version, all records recorded at the point of release will be displayed.

4.1. Show cloud configuration item details

Selecting a listed Cloud Configuration Item will show you the record details with all configuration parameters.

4.2. Download a cloud configuration report

You may download a cloud configuration report for a particular version. Select the target version and click the Download cloud configuration report button to start the process.

The cloud configuration report will contain all version-related cloud configuration items grouped by all recorded environments.

Item re-verification flagging is a Ketryx feature that:

• Detects when a controlled item has changed since a design output (e.g., a test case, child requirement, or software item spec) was last approved.

• Automatically adds a flag on each directly design ouput that traces to the changed item.

• Provides context and diff views so reviewers understand why the flag exists.

• Records how the flag was resolved in the item and project audit trails.

How It Works

A re-verification flag is created for a design output when all of the following are true:

1. Relationship exists

   • There is a direct traceability link between two items (e.g., “has parent”, “fulfills”, “tests”, or a custom relation), from the design output to the design input.

2. Design input was previously controlled

   • The design input item was in a controlled/approved state according to your project’s approval rules.

3. Design input is modified and re-approved

   • A new record of the design input item is created, and its content is changed.

   • The item is then moved through your workflow and re-approved, becoming the new effective controlled record.

4. Design output is still based on the previous version

   • The downstream item has not been changed and re-approved since this reapproval of the design input.

   • At that point, Ketryx marks the downstream item as “review required” (flagged for re-verification).

On the flagged item's record page in Ketryx

When you open an item record that has a re-verification flag, you’ll see a notification at the top of the page that says something similar to:

“Review required: design input has been updated. View flags to assess if this item needs to be updated accordingly. If so, move this item to an editable state and make changes. The flag will be resolved once this item is reapproved. If not, then you can dismiss the flag below.”

You can click in this notification to navigate down the page to the Re-verification flags section. This section typically includes:

• A link to the design input that was changed.

• An action to view the change that was made to the design input.

• An action to dismiss/clear the flag (if no change is needed).

In lists and filters

Flagged items can be surfaced globally so they can’t be missed during release preparation:

• On any page in Ketryx, you can filter for items with a re-verification flag by using the is:flagged KQL (which can also be used to configure a custom KQL filter or an invalid items filter)

Flag lifecycle

Re-verification flags follow a defined lifecycle:

• Creation: Flags are automatically created when a design input item is modified and re-approved

• Review: Team members can view the specific changes that triggered the flag

• Resolution: Flags can be resolved through:

  • Manual dismissal: A user with approval permissions for the flagged item explicitly dismisses the flag.

  • Automatic clearing: The flag clears automatically when the item is reopened, modified, and re-approved.

Example Scenario

Scenario: Parent requirement change and child impact

Given

• A Ketryx project “Project A”

• Requirements:

  • RQ 1

  • RQ 2

  • RQ 3

• Relations:

  • RQ 3 > "has parent" > RQ 2 > "has parent" > RQ 1

• All three items are controlled

When

• RQ 2 is:

  • Reopened

  • Edited (e.g., updated description or acceptance criteria)

  • Re-approved and returned to a controlled state

Then

• Only RQ 3 is flagged for re-verification, because it is the direct design output of RQ 2.

• The flag on RQ 3:

  • Provides context that the flag originates from RQ 2.

  • Allows the user to see how RQ 2 changed (redlines)

• A user in the approval rules for RQ 3 can dismiss the flag if no change is required, or

• Someone on the team can reopen RQ 3, update it, and the flag will be automatically cleared upon re-approval.

Blocking Releases with Flagged Items

Re-verification flags can be integrated into Ketryx’s release checks so you can ensure no flagged items are included in a release version by using the is:flagged KQL in an invalid items filter. As long as flagged items exist in the version when an invalid items filter is configured, approval of the release will be blocked by the Items valid release checklist item.

• You must be an Organization Owner to add multiple users

• Groups must already exist in your organization before assigning users to them

• Users can only be assigned the role of Member or Guest (not Owner)

How to Add Multiple Users

Step 1: Navigate to Members Page

Go to your organization's Members page by selecting Organization → Members from the main navigation.

Step 2: Initiate Bulk User Import

Click the Bulk invite button located at the top left of the Members page.

Step 3: Download CSV Template

Click Download template to get the CSV file template. This template contains the required format and column headers for successful user import, including the currently existing groups in the organization.

The CSV template includes the following columns:

• Email (required): User's email address

• First Name (required): User's first name

• Last Name (required): User's last name

• Ketryx user role (required): Either "Member" or "Guest"

• Groups (optional): Current existing group in the organization

Step 4: Prepare Your CSV File

Open the CSV and fill out the CSV template with your user information:

1. Enter one user per row

2. Ensure all email addresses are unique

3. Specify either "Member" or "Guest" for the Role column

4. For group assignments, select the group the user should be assigned to by marking it with a character (e.g., "x").

5. Save the file as a CSV file

Important Notes:

• All specified groups must already exist in your organization

• Duplicate email addresses will cause the import to fail

Step 5: Upload Your CSV File

1. Click Upload CSV or drag and drop your prepared file

2. Wait for the file to upload

3. The system will validate your file for any errors

The system will alert you to:

• Duplicate users: If any email already exists in the organization

• Invalid groups: If any specified group doesn't exist

• Format errors: If required fields are missing or invalid

Step 6: Confirm and Send Invitations

Once validated

1. Click Invite members to proceed with adding all users

2. The system will process the bulk import

3. Each new user will receive an invitation email automatically

1.2. Scope

This document covers the fundamental concepts and procedures for creating and managing variants of vulnerability impact assessments across multiple product versions. Note that variant management currently only works for vulnerability impact assessments.

1.3. Key Concepts

To effectively manage vulnerability impact assessments across versions, it is important to understand the following terms:

• Version: Each version has a specific version number, which is extracted from the version name by default. Different versions might have the same effective version number, depending on your naming scheme and the configuration of Version number pattern.

• Vulnerability Impact Assessment (VIA): A configuration item that documents the impact, severity, and mitigations for a vulnerability. In Ketryx, these are long-lived items.

• Variant: When the impact of a vulnerability changes in a new version, you can create a new VIA as a variant of the original one. This allows you to have distinct assessments for the same vulnerability that are specific to each version.

• Base Assessment: The original impact assessment from which a variant is created.

• Effective Assessment: For any given version, only one impact assessment is considered effective. By default, Ketryx uses the most recently created assessment that is applicable to that version based on its Introduced in version and Obsolete in version fields. If an impact assessment has a variant, the variant will be considered the effective assessment.

1.4. Responsibilities

• Product Security Team: Responsible for assessing vulnerabilities and creating or updating impact assessments for each product version.

• R&D Lead / Engineering Lead: Responsible for ensuring that development teams are aware of the effective vulnerability impact assessments for the versions they are working on.

• Team Members: Can create variants of impact assessments when working on new product versions.

2. Prerequisites

Before you can manage vulnerability impact assessments, you must have vulnerabilities in your project. Vulnerabilities are typically introduced by:

• Connecting a source code repository from systems like GitHub, GitLab, or Bitbucket. For more details, see Source Code Integrations.

• Uploading a Software Bill of Materials (SBOM) file, such as a CycloneDX or SPDX file. For instructions, see the integration guides for CycloneDX and SPDX.

• It is also highly recommended to enable the Enable vulnerabilities as configuration items setting in your project's Advanced settings. This ensures that vulnerability impact assessments are treated as full configuration items, requiring them to be controlled before a release, which is critical for regulated environments. You can find more details in the Advanced Settings documentation.

3. Procedure description

The following sections describe how to manage vulnerability impact assessments (VIAs) when a vulnerability affects multiple versions of a product.

3.1. Step 1: Create the initial version

To create an impact assessment for a version, the version must first exist in Ketryx. While versions can be synchronized from connected systems like Jira, you can also create them directly in Ketryx.

1. Navigate to the Releases page in your project.

2. Click the Create version button.

3. In the dialog that appears, enter a name for your new version (e.g., 1.0.0).

4. Click Create.

The new version will now appear on the Releases page and can be selected throughout Ketryx.

3.2. Step 2: Create the first impact assessment

When a vulnerability is identified, you create an initial impact assessment.

1. Navigate to the SBOM > Vulnerabilities page in your project.

2. Select the vulnerability you want to assess.

3. Click the Create impact assessment button.

4. Fill in the details for the assessment, such as severity, resolution, and rationale.

5. In the Introduced in version field, select the version where this assessment first becomes effective (e.g., 1.0.0).

6. Leave the Obsolete in version field empty. This ensures the assessment remains effective for all subsequent versions until a new variant is created.

7. Save the assessment.

This first assessment now applies to version 1.0.0 and all future versions.

3.3. Step 3: Create a new version from an existing one

Before you create a variant for a new version, the version itself must exist in Ketryx.

1. Navigate to the Releases page.

2. From an existing version (e.g., 1.0.0), click the Create new version from baseline button.

3. A dialog appears where you can configure the new version.

4. Enter a name for the new version. It is strongly recommended to use a unique and higher version number (e.g., 1.0.1 or 2.0.0). If you use the same version number as an existing, unreleased version, Ketryx treats them as equivalent, which can lead to unexpected behavior with variants.

5. Select the Lock records from this version checkbox. This is important for stability. It ensures your new version starts with all items in the exact state they were in version 1.0.0, and later changes to version 1.0.0 will not affect your new version.

6. Click Create new version.

7. If your dependencies and vulnerabilities come from an SBOM file (as mentioned in the prerequisites), you must ensure that your new version can see them. Go to the version's settings page and confirm the Inherit builds option is enabled. This option is enabled by default when creating a version using Create new version from baseline.

The new version is now created and inherits the items from the version it was created from.

Important: While locking records provides a stable base, a variant item will always take precedence. If you create a variant of a locked item, the variant will be the effective item in the new version, not the locked base item.

3.4. Step 4: Create a variant for a new version

Suppose you are working on version 2.0.0, and the impact of the same vulnerability is different. You now need a new assessment. Instead of starting from scratch, you can create a variant of the existing assessment.

1. From the Vulnerabilities page, select version 2.0.0 from the version picker.

2. Select the same vulnerability. You will see the existing assessment from version 1.0.0 is currently effective.

3. You will be presented with an option to Create variant for the existing impact assessment.

4. Clicking this will open a new assessment form, pre-populated with the information from the original assessment.

5. The Introduced in version field will be automatically set to 2.0.0.

6. Update the fields to reflect the new assessment for version 2.0.0.

7. Save the new assessment.

You have now created a new variant of the impact assessment.

3.5. Step 5: View and understand effective assessments

Ketryx makes it easy to see which assessment is effective for each version, and to compare assessments.

1. Navigate to the SBOM > Vulnerabilities page.

2. Use the version picker above the table to switch between versions. The table updates to show the effective impact assessment for each vulnerability in the selected version.

3. Click the expand icon on the right of a vulnerability's row to expand its detail panel.

4. The panel shows the details of the effective assessment for the version you selected.

5. In the impact assessment dropdown menu, you can see a list of all impact assessments for this vulnerability (both base and variants). Select any assessment to view its details. This selection does not change the version shown on the main page, but allows you to easily compare information between variants and their base assessment and how they change over time.

6. To view the history of a specific impact assessment configuration item, click the Record details link in the detail panel. This will take you to the records details page where you can see the complete history of records for that assessment.

4. Advanced scenarios

4.1. Making an assessment obsolete

If you want an impact assessment to stop being effective after a certain version, you can edit it and set the Obsolete in version field.

For example, if you set the Obsolete in version of the assessment for 1.0.0 to 2.0.0, it will no longer apply to 2.0.0 or any later versions. If no other assessment is created for 2.0.0, the vulnerability will have no effective assessment in that version.

4.2. Re-using assessments across versions

If an impact assessment is created for version 1.0.0 with an empty Obsolete in version field, it will automatically be the effective assessment for versions 1.1.0, 2.0.0, and so on, as long as no new variant is created for those versions. This allows you to reuse an assessment without creating unnecessary variants.

To fetch data from Xray, Ketryx needs an Xray API key. The following steps need to be completed:

1. Create an Xray API key in Xray

2. Provide the Xray API key in Ketryx

3. Review how Xray is now connected with your Ketryx projects

2.1 Create an Xray API key in Xray

In Jira, navigate to Apps > Manage your apps > XRAY > API Keys, and select "Create API Key." You will need the Client Id and Client Secret for the next step.

2.2 Provide the Xray API key in Ketryx