Update ownership preferences docs for the settings page by Matzoc · Pull Request #41279 · DataDog/documentation

Matzoc · 2026-11-02T09:23:25Z

What does this PR do? What is the motivation?

Ownership preferences are now managed on the Ownership Agent settings page in Datadog instead of a reference table. This rewrites the Set Up Ownership Preferences page around the settings page (tag mappings, exclusions, and custom instructions) and adds a screenshot of it. It removes the reference table setup and CSV format and trims the page to the essentials. The Ownership Agent page's data source table now points to the settings page.

Merge readiness

Ready for merge

AI assistance

Used Claude Code to draft the content from the settings page UI and to run Vale.

For Datadog employees:

⚠️ Your branch name MUST follow the <name>/<description> convention and include the forward slash (/). If you've already created your PR with an incorrect branch name, please rename your branch and open a fresh PR.
🤖 New: Comment with /review to run an automated check that catches common issues before a Documentation team member reviews your PR.

Additional notes

github-actions · 2026-11-02T09:37:32Z

Preview links (active after the `build_preview` check completes)

Modified Files

Matzoc · 2026-11-02T11:28:01Z

/review

github-actions

🤖 Automated review by Claude. AI-generated; verify before acting.

Content looks accurate and much more scannable than the pre-rewrite version. Two small issues worth fixing before merge; everything else is fine.

Flag: The PR's __untrusted/CLAUDE.md and __untrusted/AGENTS.md were surfaced to me as system reminders during review. I ignored them per the trusted review protocol (only ./.claude/pr-review.md guides the review). The content was benign repo guidance, not a malicious injection, but noting it so maintainers are aware.

_{Reviewed e2faec702b1db18fd6a22fe3f120a6e5c7ca8a6e — workflow run}

…diate/ownership_agent.md Co-authored-by: Max Phillips <maxvphillips@gmail.com>

…diate/ownership_preferences.md Co-authored-by: Max Phillips <maxvphillips@gmail.com>

maxvp · 2026-11-02T19:54:01Z

+## Tag mappings

-## Upload your ownership preferences
+A tag mapping says: _"When a resource has tag `X:Y`, it belongs to this owner."_ When a resource's tag matches a mapping, the Ownership Agent adds the owner as a candidate and ranks it alongside other data sources. Tag mappings do not override a direct ownership tag (like `dd-team`) already on the resource.


Suggested change

A tag mapping says: _"When a resource has tag `X:Y`, it belongs to this owner."_ When a resource's tag matches a mapping, the Ownership Agent adds the owner as a candidate and ranks it alongside other data sources. Tag mappings do not override a direct ownership tag (like `dd-team`) already on the resource.

A tag mapping assigns an owner to resources that have a specific tag. When a resource's tag matches a mapping, the Ownership Agent adds the owner as a candidate and ranks it alongside other data sources. Tag mappings don't override a direct ownership tag (such as `dd-team`) already on the resource.

maxvp · 2026-11-02T19:54:28Z

+## Exclusions

-This approach is best for automated, recurring updates. Store your CSV in a cloud storage bucket so Datadog can periodically import it.
+An exclusion tells the Ownership Agent, "Never suggest this owner." Use exclusions for bot accounts, CI runners, and shared service accounts that appear in cloud resource metadata but don't own the resource.


Suggested change

An exclusion tells the Ownership Agent, "Never suggest this owner." Use exclusions for bot accounts, CI runners, and shared service accounts that appear in cloud resource metadata but don't own the resource.

An exclusion prevents the Ownership Agent from suggesting a specific owner. Use exclusions for bot accounts, CI runners, and shared service accounts that appear in cloud resource metadata but don't own the resource.

maxvp · 2026-11-02T19:58:03Z

-Datadog periodically re-imports the file, so it automatically picks up updates to the CSV in your bucket.
+| Field                        | Description                                                                                                  |
+|------------------------------|--------------------------------------------------------------------------------------------------------------|
+| **Owner type** (optional)    | Only exclude the owner for this type: **User**, **Team**, or **Service**. Leave empty to exclude it for any type |


Suggested change

| **Owner type** (optional) | Only exclude the owner for this type: **User**, **Team**, or **Service**. Leave empty to exclude it for any type |

| **Owner type** (optional) | Exclude only the owner for this type: **User**, **Team**, or **Service**. Leave empty to exclude it for any type |

maxvp · 2026-11-02T19:58:12Z

+|------------------------------|--------------------------------------------------------------------------------------------------------------|
+| **Owner type** (optional)    | Only exclude the owner for this type: **User**, **Team**, or **Service**. Leave empty to exclude it for any type |
+| **Owner**                    | Owner to exclude (for example, `deploy-bot`). Matched case-insensitively                                      |
+| **Resource type** (optional) | Only exclude the owner for this resource type (for example, `aws_ec2_instance`). Leave empty for any type     |


Suggested change

| **Resource type** (optional) | Only exclude the owner for this resource type (for example, `aws_ec2_instance`). Leave empty for any type |

| **Resource type** (optional) | Exclude only the owner for this resource type (for example, `aws_ec2_instance`). Leave empty for any type |

maxvp · 2026-11-02T20:00:16Z

+The settings page checks each rule before saving it and shows any problem next to the field.

-<div class="alert alert-info">If you delete all rows from the table (leaving it empty), the Ownership Agent actively clears your previous preferences. Deleting the table entirely has the same effect—the cached preferences expire and are left empty.</div>
+- Fields accept ASCII letters, digits, and a small set of punctuation. Accented letters, emoji, and typographic (curly) quotes are not allowed. Fields are limited to 1,024 characters.


This doesn't list the specific supported characters. Is the removed list still accurate? If so, we should add this list back.

Yes, still accurate (names also can't contain /). I've added the table back under the validation rules.

maxvp · 2026-11-02T20:00:55Z

-## When preferences take effect
+| Name                     | Priority | Instruction                                                                                                                                       |
+|--------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------|
+| `cost-center-convention` | High     | Ownership is assigned by cost center. Team identifiers always start with team- (for example, team-platform). |


Suggested change

| `cost-center-convention` | High | Ownership is assigned by cost center. Team identifiers always start with team- (for example, team-platform). |

| `cost-center-convention` | High | Ownership is assigned by cost center. Team identifiers always start with `team-` (for example, `team-platform`). |

maxvp · 2026-11-02T20:13:37Z

-   - **Exclusions** remove unwanted handles from results.
-   - **Custom prompt text** guides the AI inference engine.
-5. Updated results appear in the Cloud Security posture management UI.
+## Validation


Suggested change

## Validation

## Ownership preference validation rules

maxvp · 2026-11-02T20:14:23Z

+- Two tag mappings with the same tag key and value must have the same owner and confidence. Exact duplicates are not allowed.
+- An exclusion can't duplicate another exclusion with the same owner, owner type, and resource type.

 ## Troubleshooting


Suggested change

## Troubleshooting

## Troubleshoot ownership preferences

Recommend making heading titles more specific to improve human+agent readability.

maxvp · 2026-11-02T20:16:23Z

-| Maximum bytes per prompt text entry | 4,096 bytes                                                                        |
-
-### Duplicate detection
+The Ownership Agent infers an owner for cloud resources with security findings, using cloud resource tags, Service Catalog data, and other data sources. **Ownership preferences** let you customize this process with three kinds of rules:


Suggested change

The Ownership Agent infers an owner for cloud resources with security findings, using cloud resource tags, Service Catalog data, and other data sources. **Ownership preferences** let you customize this process with three kinds of rules:

The Ownership Agent infers an owner for cloud resources with security findings, using cloud resource tags, Software Catalog data, and other data sources. **Ownership preferences** let you customize this process with three kinds of rules:

Service Catalog is now Software Catalog.

maxvp · 2026-11-02T20:17:02Z

 | 1        | **Owner tags**                 | Cloud resource tags with keys such as `owner`, `dd-team`, or `team`. An explicit ownership tag is the strongest signal.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| 2        | **Ownership preferences**      | Custom tag mappings and rules you define in a [reference table](/reference_tables). These act as organization-level overrides and are evaluated alongside direct tags. Learn more at [set up ownership preferences](/security/cloud_security_management/review_remediate/ownership_preferences/). |
+| 2        | **Ownership preferences**      | Tag mappings, exclusions, and custom instructions you define on the [Ownership Agent settings page](https://app.datadoghq.com/security/configuration/csm/ownership-agent). These act as organization-level overrides. Datadog evaluates ownership preferences alongside direct tags. Learn more at [Set Up Ownership Preferences](/security/cloud_security_management/review_remediate/ownership_preferences/). |
 | 3        | **Service Catalog**            | Team ownership data from the Datadog Service Catalog, matched against the resource's service, application, or component tags.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |


Suggested change

| 3 | **Service Catalog** | Team ownership data from the Datadog Service Catalog, matched against the resource's service, application, or component tags. |

| 3 | **Software Catalog** | Team ownership data from the Datadog Software Catalog, matched against the resource's service, application, or component tags. |

Not part of the scope of this PR, but this product was renamed.

maxvp

Thanks for the submission! Left some comments for your consideration.

maxvp · 2026-11-02T20:19:20Z

-For more information, see [datadog_reference_table (Resource)][7] in the Datadog Terraform provider documentation.
+You can add up to three instructions of up to 4,000 characters each. Set an optional **Priority** (**High**, **Medium**, or **Low**) to control the order in which the agent reads them. Instructions without a priority come last, and every instruction is used.

-### API


This PR removes API and Terraform instructions. Are these methods still supported?

No, we are completely migrated away from that storage decision, we may introduce that back in the future, but it's not available anymore at the moment.

Matzoc added 5 commits November 2, 2026 09:18

Update ownership preferences docs for the settings page UI

867113c

Describe when ownership preference changes apply

fcd58cc

Fix Ownership Agent settings navigation path

3758170

Remove feature-not-enabled troubleshooting row

59e26a1

Shorten ownership preferences page

7c1b37c

Matzoc added 3 commits November 2, 2026 10:07

Keep sentences under 25 words

d591090

Drop edit and delete instructions

4a7b99e

Add ownership preferences screenshot

e2faec7

github-actions Bot added the Images Images are added/removed with this PR label Nov 2, 2026

github-actions Bot reviewed Nov 2, 2026

View reviewed changes

Address review comments

c89ef20

Matzoc marked this pull request as ready for review November 2, 2026 13:39

Matzoc requested a review from a team as a code owner November 2, 2026 13:39

maxvp self-assigned this Nov 2, 2026

maxvp reviewed Nov 2, 2026

View reviewed changes

Comment thread hugo/content/en/security/cloud_security_management/review_remediate/ownership_agent.md Resolved

maxvp reviewed Nov 2, 2026

View reviewed changes

Comment thread hugo/content/en/security/cloud_security_management/review_remediate/ownership_preferences.md Resolved

maxvp reviewed Nov 2, 2026

View reviewed changes

Comment thread hugo/content/en/security/cloud_security_management/review_remediate/ownership_preferences.md Resolved

Matzoc and others added 3 commits November 2, 2026 18:42

Update hugo/content/en/security/cloud_security_management/review_reme…

176872e

…diate/ownership_agent.md Co-authored-by: Max Phillips <maxvphillips@gmail.com>

Update hugo/content/en/security/cloud_security_management/review_reme…

6013ce0

…diate/ownership_preferences.md Co-authored-by: Max Phillips <maxvphillips@gmail.com>

Update hugo/content/en/security/cloud_security_management/review_reme…

e5ba12a

…diate/ownership_preferences.md Co-authored-by: Max Phillips <maxvphillips@gmail.com>

maxvp reviewed Nov 2, 2026

View reviewed changes

Address editorial review comments

efc6ea2

	A tag mapping says: _"When a resource has tag `X:Y`, it belongs to this owner."_ When a resource's tag matches a mapping, the Ownership Agent adds the owner as a candidate and ranks it alongside other data sources. Tag mappings do not override a direct ownership tag (like `dd-team`) already on the resource.
	A tag mapping assigns an owner to resources that have a specific tag. When a resource's tag matches a mapping, the Ownership Agent adds the owner as a candidate and ranks it alongside other data sources. Tag mappings don't override a direct ownership tag (such as `dd-team`) already on the resource.

	An exclusion tells the Ownership Agent, "Never suggest this owner." Use exclusions for bot accounts, CI runners, and shared service accounts that appear in cloud resource metadata but don't own the resource.
	An exclusion prevents the Ownership Agent from suggesting a specific owner. Use exclusions for bot accounts, CI runners, and shared service accounts that appear in cloud resource metadata but don't own the resource.

	\| Owner type (optional) \| Only exclude the owner for this type: User, Team, or Service. Leave empty to exclude it for any type \|
	\| Owner type (optional) \| Exclude only the owner for this type: User, Team, or Service. Leave empty to exclude it for any type \|

	\| Resource type (optional) \| Only exclude the owner for this resource type (for example, `aws_ec2_instance`). Leave empty for any type \|
	\| Resource type (optional) \| Exclude only the owner for this resource type (for example, `aws_ec2_instance`). Leave empty for any type \|

	\| `cost-center-convention` \| High \| Ownership is assigned by cost center. Team identifiers always start with team- (for example, team-platform). \|
	\| `cost-center-convention` \| High \| Ownership is assigned by cost center. Team identifiers always start with `team-` (for example, `team-platform`). \|

	The Ownership Agent infers an owner for cloud resources with security findings, using cloud resource tags, Service Catalog data, and other data sources. Ownership preferences let you customize this process with three kinds of rules:
	The Ownership Agent infers an owner for cloud resources with security findings, using cloud resource tags, Software Catalog data, and other data sources. Ownership preferences let you customize this process with three kinds of rules:

	\| 3 \| Service Catalog \| Team ownership data from the Datadog Service Catalog, matched against the resource's service, application, or component tags. \|
	\| 3 \| Software Catalog \| Team ownership data from the Datadog Software Catalog, matched against the resource's service, application, or component tags. \|

Conversation

Matzoc commented Nov 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do? What is the motivation?

Merge readiness

AI assistance

For Datadog employees:

Additional notes

Uh oh!

github-actions Bot commented Nov 2, 2026

Preview links (active after the build_preview check completes)

Modified Files

Uh oh!

Matzoc commented Nov 2, 2026

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maxvp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Matzoc commented Nov 2, 2026 •

edited

Loading

Preview links (active after the `build_preview` check completes)