# Defining ownership
Ownership is a core use case of Cortex, as many organizations seek to establish accurate ownership of services, data, and other entities. Accurate ownership is foundational for accountability, incident response, security reviews, compliance, and developer productivity. Without clear ownership, critical issues can go unresolved and services can fall through the cracks.
{% hint style="success" %}
Avoid inefficient manual processes: Use [Cortex's ownership prediction model](#recommendation) to solve entity ownership quickly. Cortex automatically predicts entity owners so your developers don't waste time hunting down the wrong person.
{% endhint %}
Ownership can be defined by accepting Cortex's automated recommendations for ownership, pulled in from third-party integrations, or defined manually in the Cortex UI. Ownership can also be inherited from an entity's [fallback or append configuration](https://docs.cortex.io/ingesting-data-into-cortex/adding-entities/domains#domain-entity-descriptor).
Ownership drives which users will receive [notifications](https://docs.cortex.io/configure/settings/notifications) from Cortex, including alerts for on-call changes, when [verification](https://docs.cortex.io/configure/settings/entity-settings/verification) is needed on an assigned entity, when an entity is re-evaluated and its Scorecard changes, and more.
### Where to view entity owners
When viewing an entity, the owners appear in the metadata bar on the right side of the page:
Click into the team name to view the team's entity page, including a list of members and a list of entities owned by that team.
You can [create or import the teams and users](https://docs.cortex.io/ingesting-data-into-cortex/adding-entities/teams#creating-a-team) who will be defined as owners for your entities.
## View entities without owners
There are a few ways to determine which of your entities in Cortex don't have owners assigned yet:
* Use the [Ownership tool](https://app.getcortexapp.com/admin/ownership) to see unowned entities and Cortex's automated recommendations for owners
* Learn more about [using the Ownership tool](#cortex-automated-recommendations-for-ownership) below.
* View the [Executive Report](https://app.getcortexapp.com/admin/reports/executive), which lists unowned entities
* Launch an Ownership Verification Scorecard, which will automatically add tasks to your [Engineering homepage](https://docs.cortex.io/streamline/homepage) to ensure you add owners to entities
* When [creating a Scorecard](https://docs.cortex.io/standardize/scorecards/create), select the Ownership Verification template.
## Define owners for entities
#### Types of owners
You can define owners based on:
* A team: The user is a member of a team that is listed as the owner of an entity.
* We recommend setting up teams as owners. If you link a `group` in your YAML file from a different platform (such as Okta), the members of the team will be automatically updated in Cortex if anyone leaves your organization and is removed from your integrated identity provider.
* A user email address: The user is listed as the owner of an entity.
* [Fallback or append settings](#ownership-inheritance) configured in an entity's hierarchy.
#### Methods for defining ownership
Owners can be defined:
* By accepting Cortex's automated recommendations for owners, based on repository activity
* By pulling information from third-party integrations in the [entity descriptor YAML](https://docs.cortex.io/ingesting-data-into-cortex/entities/..#defining-entities-via-yaml-file)
* Ownership can also be inherited via [fallback or append configuration](https://docs.cortex.io/ingesting-data-into-cortex/adding-entities/domains#domain-entity-descriptor).
* Directly in the Cortex UI
* Automatically if Cortex detects that an entity is owned by a team that does not yet exist in Cortex
* If an entity's YAML references a team, but that team doesn't have a corresponding entry within Cortex, Cortex will automatically create a team. The team will include a label that says **Automatically created by Cortex**.
{% tabs %}
{% tab title="Recommendation" %}
**Cortex automated recommendations for ownership**
{% hint style="info" %}
**Research preview**
Not seeing the results you expect? This is an early version of the Ownership tool. Please send feedback and bug reports to us [via this form](https://docs.google.com/forms/d/e/1FAIpQLSdURosGQhMnmMCF7FA66v9DOdnk5rOSoK1SaUVGjpOy4ywt5g/viewform). Note the following considerations:
* This feature is supported for entities associated with a repository in GitHub, GitLab, or Azure DevOps. Mapping is done on per repository basis, so mapping teams owners to file paths within a monorepo is not supported.
* You must have teams configured in Cortex and team members must be [identity-mapped](https://docs.cortex.io/configure/settings/managing-users/identity-mapping) in order for Cortex to provide recommendations. The more teams and people you have mapped, the better the recommendations!
* Cortex analyzes the last 6 months of data, so if a repository has not had code changes within that time period, we will not have a recommendation.
* To accept or reject the recommended owner, the user must have the `Edit entities` permission.
* If you are using GitOps, you can view recommendations, but you cannot accept them from the UI.
{% endhint %}
Cortex analyzes a repository and automatically recommends a team owner for entities that do not have an owner.
If an entity does not have an owner and Cortex has recommendations for who the owner should be, it will be flagged in the ownership tool under **Tools > Ownership**, in the "Owners" section of an entity details page overview, in the "Owners" sidebar link on an entity details page, and it will appear during the import process when [adding entities](https://docs.cortex.io/ingesting-data-into-cortex/entities/adding-entities).
**Review ownership recommendations in bulk**
Users can edit ownership on this page only if they have edit access for all entities. If a user only has edit access for some entities, they can accept ownership recommendations from an entity's details page, [as described below under "Review ownership recommendations per entity."](#review-ownership-recommendations-per-entity)
To review and assign ownership across all unowned entities:
1. In the main nav of Cortex, click **Tools > Ownership**.
* A list of recommendations for ownership is displayed.\\
2. Review and accept the recommended owners.
* To apply all recommended owners: Ensure the checkboxes for all entities are selected, then at the top of the list, click **Accept recommendations**.
* To apply selected owners: On the left side of the list, check the box next to the entities whose recommended owners you want to accept. When you are finished selecting, click **Accept recommendations** at the top of the list.
**Review ownership recommendations per entity**
Users can accept ownership recommendations for an entity if they have edit access for that specific entity, and if UI editing is enabled for that entity type under [**Settings > GitOps**](https://app.getcortexapp.com/admin/settings/gitops).
1. On an [entity details page](https://docs.cortex.io/ingesting-data-into-cortex/entities/details) next to the "Owners" field, click **Recommendations**.\
2. Review the suggested owners. To accept a recommendation, check the box next to the recommended owner then click **Add owners**.\
{% endtab %}
{% tab title="Entity descriptor" %}
**Define owners in the entity descriptor**
The `x-cortex-owners` field allows you to define a list of owners of type email or group.
```yaml
x-cortex-owners:
# Groups can be pulled from various integrations
- type: group
name: my-team
provider: CORTEX
description: This is a description for this owner # optional
- type: email
email: user@example.com
description: This is a description for this owner # optional
```
Cortex recognizes groups from the following integrations:
* [Azure Active Directory](https://docs.cortex.io/ingesting-data-into-cortex/integrations/entraid)
* [Azure DevOps](https://docs.cortex.io/ingesting-data-into-cortex/integrations/azuredevops)
* [BambooHR](https://docs.cortex.io/ingesting-data-into-cortex/integrations/bamboohr)
* [GitHub](https://docs.cortex.io/ingesting-data-into-cortex/integrations/github)
* [GitLab](https://docs.cortex.io/ingesting-data-into-cortex/integrations/gitlab)
* [Google](https://docs.cortex.io/ingesting-data-into-cortex/integrations/google)
* [Okta](https://docs.cortex.io/ingesting-data-into-cortex/integrations/okta)
* [Opsgenie](https://docs.cortex.io/ingesting-data-into-cortex/integrations/opsgenie)
* [ServiceNow](https://docs.cortex.io/ingesting-data-into-cortex/integrations/servicenow)
* [Workday](https://docs.cortex.io/ingesting-data-into-cortex/integrations/workday)
The value of `provider` is the name of the integration that the group is coming from. The available list is:
* ACTIVE\_DIRECTORY
* AZURE\_DEVOPS
* BAMBOO\_HR
* CORTEX: Use when referring to a team defined in Cortex; these teams do not map to identities from a connected integration.
* GITHUB
* GITLAB
* GOOGLE
* OKTA
* OPSGENIE
* SERVICE\_NOW
* WORKDAY
`name` is a case-sensitive field that refers to the following:
* if your provider is `CORTEX`, `name` corresponds to the `x-cortex-tag` for the Cortex team you want to identify as an owner
* otherwise, `name` corresponds to the upstream identifier of your owner from your integration
{% endtab %}
{% tab title="Cortex UI" %}
**Define owners in the Cortex UI**
1. In Cortex, navigate to [**Catalogs > All entities**](https://app.getcortexapp.com/admin/entities).
2. Search for and select the entity whose ownership you want to edit.
3. In the upper right corner of the entity's page, click **Configure entity**.
* If this option isn't displayed, make sure you have [enabled UI editing for entities](https://docs.cortex.io/configure/settings/gitops-settings#options-by-entity-type).
4. Click the **Owners** tab, then click **+Add** next to Teams or Users.
* Add team:
* Select a team from the dropdown menu, then click **Add**.
* Add user:
* Select a user from the dropdown menu, then click **Add**.
* You can also add a user who is not listed in Cortex. To do this, enter an email address into the **Email address** field, then click **Add**.
{% endtab %}
{% endtabs %}
### **Ownership inheritance**
Instead of defining ownership individually for every entity in your catalog, you can define ownership at the parent entity level and have that pass down to all of the entity's children. You can configure this in the Cortex UI while [creating a domain](https://docs.cortex.io/ingesting-data-into-cortex/adding-entities/domains#creating-domains-and-a-hierarchy) entity and adding owners to it, or while [creating an entity relationship](https://docs.cortex.io/ingesting-data-into-cortex/defining-relationship-types#create-relationship-types-and-relationship-connections).
`inheritance` can also be defined in the entity descriptor under the `x-cortex-owners` block, as shown in the example below:
```yaml
openapi: 3.0.1
info:
title: Payments
description: This is my cool domain.
x-cortex-tag: payments-domain
x-cortex-type: domain
x-cortex-owners:
- type: GROUP
name: cortexapps/engineering
provider: GITHUB
inheritance: APPEND
```
The `inheritance` type for each owner can be one of `APPEND`, `FALLBACK`, or `NONE`. If not set, inheritance is defaulted to `NONE`.
* `APPEND`: This owner is appended to the list of owners for all child entities.
* `FALLBACK`: In the case where a child has no valid owners, including fallbacks, this fallback will be assigned as the owner. Note that this only applies to a child entity down the hierarchy; it is not the fallback for the parent domain itself.
* `NONE`: This owner owns the domain, but not necessarily any of its children (no inheritance).
### Automatic discovery for AWS
Cortex can automatically discover ownership for your AWS resources using their `owner` tag. To enable this, make sure that your AWS resources have an owner tag matching the `x-cortex-tag` of the corresponding Cortex team and enable the **Sync ownership from AWS** toggle in [Settings > AWS](https://app.getcortexapp.com/admin/settings/aws?activeTab=Settings).
You can pull in all resources from AWS, and Cortex syncs those owners automatically based on their tags in AWS, allowing you to easily keep the resource owners up to date.
{% hint style="info" %}
Cortex syncs ownership from AWS every day at 6 am UTC.
{% endhint %}
## Remove incorrect owners
To remove incorrect ownership in Cortex, the steps depend on how the ownership was added and your current configuration. Expand the tile below to learn more.
Remove incorrect ownership
**If ownership was set via YAML (`x-cortex-owners`):**
* Update the `x-cortex-owners` block in your YAML to reference only the correct teams or individuals. Ensure that all referenced teams actually exist in Cortex.
* If you are using [GitOps](https://docs.cortex.io/configure/gitops), make sure the YAML is updated and merged to your main branch, then allow Cortex to re-sync. This will update the ownership in the UI to match your YAML.
**If ownership was added via API:**
* Use the [Create or update entity API](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/catalog-entities#post-api-v1-open-api) to completely replace the entity YAML, or the [Create or patch entity API](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/catalog-entities#patch-api-v1-open-api) to remove one or more owner and not change the rest of the entity YAML.
**If ownership is inherited from a domain or parent:**
* Check if the entity is a child of a domain or group with [ownership inheritance](#ownership-inheritance) enabled. If so, the parent’s owners may be appended to the entity.
* To remove inherited owners, edit the domain or parent’s owner inheritance setting (e.g., change from `Append` to `None`).
## Viewing entity ownership
### View your owned entities
See entities you own directly:
To see a list of entities you own directly, navigate to [**Catalogs > All entities**](https://app.getcortexapp.com/admin/entities) then click the **Mine** tab:\
#### Child team visibility
See your enties and entities owned by your team's child teams:
To see a list of entities you own directly and entities that are owned by your team's child teams:
1. Navigate to [**Catalogs > All entities**](https://app.getcortexapp.com/admin/entities).
1. The list defaults to displaying the "Mine" tab, showing only the entities you own.
2. At the top of the list, click **Display**.
3. Enable the toggle next to **Include child teams**.\\
4. Click **Done**.
### View a team's owned entities
You can filter the entity list by owner:
1. Under [**Catalogs > All entities**](https://app.getcortexapp.com/admin/entities), click the **All** tab.
2. In the upper right corner, click **Filter**.
3. In the left side of the filter modal, click **Teams**. Select teams from the dropdown, then click **Apply** at the bottom.\
### View entities owned by all teams within a hierachy
View entites owned by the parent and children teams:
Teams can exist within hierarchies. You can view a list of all entities that are owned by the parent team and all children teams in the hierarchy:
1. Navigate to the parent team's page in Cortex.
2. Click the **Entities** tab.
3. Click Display, then enable the toggle next to **Inherited Children**.\\
While viewing owned entities, click Display then add inherited children to the view.
4. Click **Done**.
The list will now display all entities owned by the parent and its children teams. Note that this setting does not persist when you navigate away from the page.
Read more about hierarchies in [the Teams documentation](https://docs.cortex.io/ingesting-data-into-cortex/adding-entities/teams#understanding-hierarchies).
## Ownership settings in Cortex
Under [**Settings > Entities**](https://app.getcortexapp.com/admin/settings/entities), there are several settings relating to teams. Read more about these in the [Teams documentation](https://docs.cortex.io/ingesting-data-into-cortex/adding-entities/teams#adjusting-team-settings).
