Overview

The Ownership Agent selects a subset of cloud resources with security findings and infers an owner for each one. By default, it uses cloud resource tags, service catalog data, and other data sources to infer ownership.

Ownership preferences let you customize this process by providing your own rules. You store them in a Datadog reference table, and the Ownership Agent reads them automatically to enhance its results.

Create an ownership preference file

1. Create a CSV file following the format described below. Optionally, use the Ownership Agent AI skill with your AI coding assistant to generate the CSV interactively.
2. Upload it as a reference table named k9_ownership_preferences. Preferences take effect within 24 hours.

Preference types

Each row in your reference table is one preference. The preference_type column determines what the row does.

Tag mappings

A tag mapping says: “When a resource has tag X:Y, it belongs to this owner.”

The Ownership Agent checks cloud resource tags against your mappings. When it finds a match, it adds the specified owner as a candidate. Multiple mappings can match the same resource, producing multiple candidates that the Ownership Agent ranks alongside other data sources.

Tag mappings complement existing ownership data sources. They do not override a direct ownership tag (like dd-team) already present on the resource.

Columns

Owner type

The owner_type field tells the Ownership Agent what kind of entity the owner is. This helps the AI engine make better decisions when ranking candidates.

Matching behavior

• Tag key and value matching is case-insensitive. Cost-Center matches cost-center.
• An empty tag_value matches any value for that tag key (wildcard).
• If multiple mappings match, all produce candidates. The Ownership Agent ranks them by confidence.

Confidence levels

Example: Map cost centers to teams

id,preference_type,tag_key,tag_value,owner,owner_type,confidence,handle,exclusion_type,exclusion_resource_type,prompt_text,priority
1,tag_mapping,cost-center,CC-100,team-platform,team,high,,,,,
2,tag_mapping,cost-center,CC-200,team-data-eng,team,high,,,,,
3,tag_mapping,cost-center,CC-300,team-security,team,high,,,,,

Example: Map projects to owners

id,preference_type,tag_key,tag_value,owner,owner_type,confidence,handle,exclusion_type,exclusion_resource_type,prompt_text,priority
1,tag_mapping,project,atlas,team-atlas,team,medium,,,,,
2,tag_mapping,project,hermes,alice@example.com,user,medium,,,,,
3,tag_mapping,project,payments,team-fintech,team,high,,,,,

Example: Wildcard match any resource with a managed-by tag

id,preference_type,tag_key,tag_value,owner,owner_type,confidence,handle,exclusion_type,exclusion_resource_type,prompt_text,priority
1,tag_mapping,managed-by,,team-infra,team,low,,,,,

This matches any value of the managed-by tag and assigns it to team-infra with low confidence. Because the confidence is low, stronger data sources take priority.

Exclusions

An exclusion tells the Ownership Agent, “Never assign this handle as a resource owner.”

Bot accounts, CI runners, and shared service accounts often appear in cloud resource metadata (for example, as the creator or last modifier). Exclusions remove these from ownership results so they only surface real owners.

Columns

Matching behavior

• The handle is matched case-insensitively.
• Optional filters use AND logic. All non-empty fields must match for the exclusion to apply.
• Leave exclusion_type and exclusion_resource_type empty to exclude the handle from all results (most common).

Example: Exclude common bot accounts from all results

id,preference_type,tag_key,tag_value,owner,owner_type,confidence,handle,exclusion_type,exclusion_resource_type,prompt_text,priority
1,exclusion,,,,,,deploy-bot,,,,
2,exclusion,,,,,,ci-runner,,,,
3,exclusion,,,,,,github-actions,,,,
4,exclusion,,,,,,terraform-automation,,,,

Example: Exclude a service account only for specific resource types

id,preference_type,tag_key,tag_value,owner,owner_type,confidence,handle,exclusion_type,exclusion_resource_type,prompt_text,priority
1,exclusion,,,,,,k8s-node-controller,service,aws_ec2_instance,,
2,exclusion,,,,,,autoscaler-svc,service,aws_ec2_instance,,

These exclusions only apply to EC2 instances. The same handles are still eligible as owners for other resource types.

Example: Exclude a team handle for a specific resource type

id,preference_type,tag_key,tag_value,owner,owner_type,confidence,handle,exclusion_type,exclusion_resource_type,prompt_text,priority
1,exclusion,,,,,,legacy-ops,team,aws_ec2_instance,,

This excludes legacy-ops only when it appears as a team candidate for EC2 instances. It is still considered for S3 buckets or other resource types.

Custom prompt text

Custom prompt text provides free-form guidance to the AI inference engine. Use it to share organizational context that helps the AI make better ownership decisions, such as naming conventions, team structures, or which data sources to prioritize.

You can provide up to three prompt text entries, one for each priority level (high, medium, low). Entries with the same priority are concatenated. Use priority to control which guidance the AI engine considers first.

Columns

Tips for writing effective guidance

• Be specific and actionable. “The cost-center tag is our most reliable ownership signal” is better than “Use tags”.
• Explain your organization’s conventions: team naming patterns, how to interpret specific tags, etc.
• Call out accounts that should not be owners (also add these as exclusion rows for enforcement).
• Use one entry per priority level to organize your guidance by importance.

Example: organization-specific context split by priority

id,preference_type,tag_key,tag_value,owner,owner_type,confidence,handle,exclusion_type,exclusion_resource_type,prompt_text,priority
1,prompt_text,,,,,,,,Our organization assigns ownership by cost center. The cost-center tag is the primary ownership signal for all cloud resources. Team identifiers always use the team- prefix followed by the team name (e.g. team-platform team-data-eng).,high
2,prompt_text,,,,,,,,Shared infrastructure accounts (deploy-bot ci-runner github-actions terraform-automation) are automation accounts and should never be assigned as resource owners. Look for the human or team that configured the automation instead.,medium
3,prompt_text,,,,,,,,For container images the repository owner in our GitHub organization is a reliable secondary signal when cost-center tags are missing.,low

Reference table format

Column schema

Your reference table must be named k9_ownership_preferences and contain these 12 columns:

Each row uses a subset of columns depending on preference_type. Leave unused columns empty.

Column usage by preference type

Complete example

A ready-to-use CSV with all three preference types:

id,preference_type,tag_key,tag_value,owner,owner_type,confidence,handle,exclusion_type,exclusion_resource_type,prompt_text,priority
1,tag_mapping,cost-center,CC-100,team-platform,team,high,,,,,
2,tag_mapping,cost-center,CC-200,team-data-eng,team,high,,,,,
3,tag_mapping,cost-center,CC-300,team-security,team,high,,,,,
4,tag_mapping,project,atlas,team-atlas,team,medium,,,,,
5,tag_mapping,project,hermes,alice@example.com,user,medium,,,,,
6,tag_mapping,env,production,sre-team,team,low,,,,,
7,tag_mapping,managed-by,,team-infra,team,low,,,,,
8,exclusion,,,,,,deploy-bot,,,,
9,exclusion,,,,,,ci-runner,service,,,
10,exclusion,,,,,,github-actions,service,,,
11,exclusion,,,,,,legacy-ops,team,aws_ec2_instance,,
12,prompt_text,,,,,,,,Our organization assigns ownership by cost center. The cost-center tag is the primary ownership signal for all cloud resources. Team identifiers always use the team- prefix followed by the team name (e.g. team-platform team-data-eng).,high
13,prompt_text,,,,,,,,Shared infrastructure accounts (deploy-bot ci-runner github-actions) are automation accounts and should never be assigned as resource owners. Look for the human or team that configured the automation instead.,medium
14,prompt_text,,,,,,,,For container images the repository owner in GitHub is a reliable secondary signal when cost-center tags are missing.,low

Validation rules

All preference data is validated when the Ownership Agent reads your reference table. Validation is all-or-nothing: if any row fails validation, the Ownership Agent rejects the entire preference set for that sync cycle. When this happens, the preferences are left empty until a valid set is uploaded.

This strict approach helps ensure you are working with a consistent, fully valid set of preferences.

Allowed characters

Different fields accept different character sets:

Notable restrictions

• Angle brackets (<, >) are not allowed in any field, including prompt text.
• Curly braces ({, }) are not allowed in any field.
• Pipe characters (|) are not allowed in any field.

These restrictions prevent formatting artifacts and help ensure clean processing by the AI engine.

Size limits

Duplicate detection

The Ownership Agent rejects the entire preference set if it contains conflicting or duplicate entries:

• Tag mappings: Two rows with the same tag_key and tag_value but different owner values are a conflict. Two rows with the same tag_key, tag_value, and owner but different confidence levels are also a conflict. Exact duplicates (all fields identical) are allowed.
• Exclusions: Two rows with the same handle, exclusion_type, and exclusion_resource_type are a duplicate. Comparisons are case-insensitive.

If the Ownership Agent detects any conflict or duplicate, it rejects the entire preference set.

Content guidelines for prompt text

The AI engine processes prompt text as organizational context. To help ensure your guidance is effective:

• Use plain, declarative sentences: Describe facts about your organization.
• Avoid special formatting: Markdown headings, HTML tags, and XML-like tags are stripped during processing.
• Focus on ownership data sources: Describe which tags, naming conventions, or team structures indicate ownership.

Examples

• “The cost-center tag is our most reliable ownership signal for all cloud resources.”
• “Team identifiers always use the team- prefix (for example, team-platform, team-data-eng).”
• “Resources in the us-east-1/prod account are managed by team-sre.”

Upload your ownership preferences

Datadog stores your preferences as a reference table. The table must be named k9_ownership_preferences and contain all 12 column headers, even if some rows leave them empty.

There are several ways to create and update the table:

Option 1: Manual CSV upload (Datadog UI)

This approach is best for getting started or making occasional updates.

1. Prepare your CSV file (see Complete example).
2. In Datadog, go to Integrations > Reference Tables.
3. Click New Reference Table.
4. Upload your CSV file.
5. Set the table name to k9_ownership_preferences.
6. Choose id as the primary key.
7. Click Save.

To update your reference table, upload a new CSV to the same table to fully replace its contents.

Manual uploads support files up to 4 MB.

Option 2: Cloud storage sync (S3, Azure Blob, GCS)

This approach is best for automated, recurring updates. Store your CSV in a cloud storage bucket so Datadog can periodically import it.

1. Upload your CSV to an Amazon S3 bucket, Azure Blob Storage container, or Google Cloud Storage bucket.
2. In Datadog, go to Integrations > Reference Tables.
3. Click New Reference Table and select Cloud Storage as the source.
4. Provide the storage path and credentials (IAM role for S3, connection string for Azure, service account for GCS).
5. Set the table name to k9_ownership_preferences.
6. Choose id as the primary key.
7. Click Save.

Datadog periodically re-imports the file, so it automatically picks up updates to the CSV in your bucket.

Cloud storage uploads support files up to 200 MB.

See the Reference Tables documentation for detailed setup instructions per cloud provider.

Option 3: Terraform

This approach is best for managing preferences as infrastructure-as-code alongside your other Datadog resources.

The Datadog Terraform provider supports reference tables. Use it to create and update the table declaratively.

For more information, see datadog_reference_table (Resource) in the Datadog Terraform provider documentation.

API

You can also manage reference tables programmatically through the Reference Tables API. See the API documentation for available endpoints.

Replace api.datadoghq.com with your Datadog site URL if applicable (for example, api.datadoghq.eu, api.us3.datadoghq.com).

When preferences take effect

1. You upload or update your reference table.
2. The Ownership Agent reads the table periodically (approximately once per day per organization).
3. The Ownership Agent validates the preferences in your table. If validation passes, the new preferences replace the previous set.
4. On the next ownership inference run for each resource:
   • Tag mappings add ownership candidates based on your tag rules.
   • 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.

Changes to your reference table take effect within 24 hours.

Troubleshooting

Validation is all-or-nothing. If any row has an issue, the Ownership Agent rejects the entire preference and leaves all preferences empty until you upload a valid set.

Further reading

Additional helpful documentation, links, and articles:

Cloud Security Frontier GroupDOCUMENTATION Reference TablesDOCUMENTATION