Add a validated OS interface for filesystem and subprocess access

[NouemanKHAL]

What does this PR do?

Stack 2 of 3. Adds the OS abstraction layer in datadog_checks_base that integrations use instead of calling open, os, shutil, glob, and subprocess directly, so path-based validation attaches in one place.

No integration is migrated here; that is stack 3. Behavior is unchanged.

• Each method is a thin passthrough preceded by a validator hook. Under the default no-op validator, exception types and timing, permission bits, encodings, laziness, and return values match the call being replaced.
• get_subprocess_output stays its own operation rather than folding into run, preserving its output decoding, empty-output handling, and logging.
• No new configuration. Validation is gated by the existing integration_ignore_untrusted_file_params setting, and never applies to a trusted provider or an excluded check.
• Executable validation covers every program a command launches, not just argv[0]: sudo is unwrapped, and under shell=True the shell is validated, since that is what the OS actually runs. Bare names are resolved through PATH.
• The shared TLS context builder validates the config-derived certificate paths it hands to ssl, via a validate_path operation that validates and returns the value unchanged.
• A mock_os_interface fixture redirects both bindings at once, so tests need not know which one a check uses.

Motivation

Integrations accept inputs that are paths: a file to read, a bin_dir, a path to a binary the check executes. The trusted-provider mechanism already decides whether such an input is acceptable, but applies that decision to config fields at load time. It does not govern the operation performed later, nor paths derived at runtime.

The main operational risk, for reviewers. Because validation reuses the existing setting rather than adding one, it cannot be staged separately from field validation. An operator who already has integration_ignore_untrusted_file_params enabled begins enforcing at every migrated call site as soon as stack 3 ships, and there is no dry-run mode. Rollout depends on the excluded-checks setting and on migrating in batches. This is deliberate, and is the thing most worth a second opinion. See rfc-filesystem-abstraction-layer.md.

This is a mediation layer for direct standard-library I/O, not a containment boundary. A Python wrapper cannot intercept a path opened inside a third-party library, anything a subprocess does once launched, or what a shell string executes. Those limits are documented rather than implied.

Testing

• 185 unit tests in datadog_checks_base; the OS interface suite is 86 tests, 177 counting the test double. The interface module is at 100% line coverage.
• A registry test asserts every public method consults the validator, so a new method cannot be added without enforcement coverage. A second asserts the test double covers the full interface surface, after glob was found missing from it.
• Mutation-tested: dropping a validator hook, dropping shell=True handling, reverting to argv[0]-only validation, or adding an unguarded public method each makes the relevant test fail.
• A fixture points os.path at ntpath so Windows-only path bugs in the double reproduce on any host.
• ddev test --lint clean.

Stack: 1. ddev validate os-interface · 2. this PR · 3. integrations migration

Review checklist (to be filled by reviewers)

• Feature or bugfix MUST have appropriate tests (unit, integration, e2e)
• Add qa/required if this PR needs QA validation, or qa/skip-qa if it does not. Exactly one of the two is required.
• If you need to backport this PR to another branch, you can add the backport/<branch-name> label to the PR and it will automatically open a backport PR once this one is merged

🤖 Generated with Claude Code

[datadog-datadog-prod-us1]

   

⚠️ Warnings

🚦 2 Pipeline jobs failed

PR All | test / jb232c8c / Datadog Checks Base on Linux     

🔧 Fix in code. This looks caused by changes in this PR.

AttributeError: <class 'datadog_checks.base.checks.base.AgentCheck'> does not have the attribute 'unchecked_os' during setup of test_fixture_redirects_check_property and test_fixture_redirects_module_singleton.

PR All Windows | test / jda96080 / Datadog Checks Base on Windows     

🔧 Fix in code. This looks caused by changes in this PR.

2 errors during test setup due to AttributeError: <class 'datadog_checks.base.checks.base.AgentCheck'> does not have the attribute 'unchecked_os'.

📋 Copy prompt for your agent

CI on my pull request is failing. Help me find and fix the root cause of each failing job below — they were flagged as caused by changes in this PR, so focus on the diff. For each job, explain the failure and propose a fix.

Branch: noueman/os-interface-base

PR All | test / jb232c8c / Datadog Checks Base on Linux
Commit: e22f6a2085a78f0678dbf18d8372466061cf5af9
Error (code / test):
AttributeError: <class 'datadog_checks.base.checks.base.AgentCheck'> does not have the attribute 'unchecked_os' during setup of test_fixture_redirects_check_property and test_fixture_redirects_module_singleton.
CI job: https://github.com/DataDog/integrations-core/actions/runs/31197320791/job/92928666775

PR All Windows | test / jda96080 / Datadog Checks Base on Windows
Commit: e22f6a2085a78f0678dbf18d8372466061cf5af9
Error (code / test):
2 errors during test setup due to AttributeError: <class 'datadog_checks.base.checks.base.AgentCheck'> does not have the attribute 'unchecked_os'.
CI job: https://github.com/DataDog/integrations-core/actions/runs/31197322275/job/92928657543

🧪 2 Tests failed in 1 job

PR All Windows | run  

test_fixture_redirects_check_property from test_os_wrapper_fixture.py  

<class 'datadog_checks.base.checks.base.AgentCheck'> does not have the attribute 'unchecked_os'

test_fixture_redirects_module_singleton from test_os_wrapper_fixture.py  

<class 'datadog_checks.base.checks.base.AgentCheck'> does not have the attribute 'unchecked_os'

ℹ️ Info

No other issues found (see more)

❄️ No new flaky tests detected

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 88.91% (+0.42%)

Useful? React with 👍 / 👎

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 012f595 | Docs | Datadog PR Page | Give us feedback!}

[dd-octo-sts]

Validation Report

All 21 validations passed.

Show details

Validation	Description	Status
agent-reqs	Verify check versions match the Agent requirements file	✅
ci	Validate CI configuration and code coverage settings	✅
codeowners	Validate every integration has a CODEOWNERS entry	✅
config	Validate default configuration files against spec.yaml	✅
dep	Verify dependency pins are consistent and Agent-compatible	✅
http	Validate integrations use the HTTP wrapper correctly	✅
imports	Validate check imports do not use deprecated modules	✅
integration-style	Validate check code style conventions	✅
jmx-metrics	Validate JMX metrics definition files and config	✅
labeler	Validate PR labeler config matches integration directories	✅
legacy-signature	Validate no integration uses the legacy Agent check signature	✅
license-headers	Validate Python files have proper license headers	✅
licenses	Validate third-party license attribution list	✅
metadata	Validate metadata.csv metric definitions	✅
models	Validate configuration data models match spec.yaml	✅
openmetrics	Validate OpenMetrics integrations disable the metric limit	✅
package	Validate Python package metadata and naming	✅
qa-label	Validate the pull request declares whether it needs QA for the next Agent release	✅
readmes	Validate README files have required sections	✅
saved-views	Validate saved view JSON file structure and fields	✅
version	Validate version consistency between package and changelog	✅

View full run