feat(iast): security controls

[avara1986]

Handle IAST security controls custom validation and sanitization methods

Overview

The DD_IAST_SECURITY_CONTROLS_CONFIGURATION environment variable allows you to specify custom sanitizers and validators that IAST should recognize when analyzing your application for security vulnerabilities.

Format

The configuration uses the following format:

CONTROL_TYPE:VULNERABILITY_TYPES:MODULE:METHOD[:PARAMETER_POSITIONS]

Multiple security controls are separated by semicolons (;).

Fields

1. CONTROL_TYPE: Either INPUT_VALIDATOR or SANITIZER
2. VULNERABILITY_TYPES: Comma-separated list of vulnerability types or * for all types
3. MODULE: Python module path (e.g., shlex, django.utils.http)
4. METHOD: Method name to instrument
5. PARAMETER_POSITIONS (Optional): Zero-based parameter positions to validate (INPUT_VALIDATOR only)

Vulnerability Types

Supported vulnerability types:

• COMMAND_INJECTION / CMDI
• CODE_INJECTION
• SQL_INJECTION / SQLI
• XSS
• HEADER_INJECTION
• PATH_TRAVERSAL
• SSRF
• UNVALIDATED_REDIRECT
• INSECURE_COOKIE
• NO_HTTPONLY_COOKIE
• NO_SAMESITE_COOKIE
• WEAK_CIPHER
• WEAK_HASH
• WEAK_RANDOMNESS
• STACKTRACE_LEAK

Use * to apply to all vulnerability types.

Examples

Basic Examples

Input Validator for Command Injection

export DD_IAST_SECURITY_CONTROLS_CONFIGURATION="INPUT_VALIDATOR:COMMAND_INJECTION:shlex:quote"

Sanitizer for XSS

export DD_IAST_SECURITY_CONTROLS_CONFIGURATION="SANITIZER:XSS:html:escape"

Multiple Vulnerability Types

export DD_IAST_SECURITY_CONTROLS_CONFIGURATION="INPUT_VALIDATOR:COMMAND_INJECTION,XSS:custom.validator:validate_input"

All Vulnerability Types

export DD_IAST_SECURITY_CONTROLS_CONFIGURATION="SANITIZER:*:custom.sanitizer:sanitize_all"

Advanced Examples

Multiple Security Controls

export DD_IAST_SECURITY_CONTROLS_CONFIGURATION="INPUT_VALIDATOR:COMMAND_INJECTION:shlex:quote;SANITIZER:XSS:html:escape;SANITIZER:SQLI:custom.db:escape_sql"

Validator with Specific Parameter Positions

export DD_IAST_SECURITY_CONTROLS_CONFIGURATION="INPUT_VALIDATOR:COMMAND_INJECTION:custom.validator:validate:0,2"

This validates only the 1st and 3rd parameters (0-based indexing).

Complex Configuration

export DD_IAST_SECURITY_CONTROLS_CONFIGURATION="INPUT_VALIDATOR:COMMAND_INJECTION,XSS:security.validators:validate_user_input:0,1;SANITIZER:SQLI:database.utils:escape_sql_string;SANITIZER:*:security.sanitizers:clean_all_inputs"

How It Works

Input Validators

• Purpose: Mark input parameters as safe after validation
• When to use: When your function validates input and returns a boolean or throws an exception
• Effect: Parameters are marked as secure for the specified vulnerability types
• Parameter positions: Optionally specify which parameters to mark (0-based index)

Sanitizers

• Purpose: Mark return values as safe after sanitization
• When to use: When your function cleans/escapes input and returns the sanitized value
• Effect: Return value is marked as secure for the specified vulnerability types

Integration with Existing Controls

Your custom security controls work alongside the built-in IAST security controls:

• shlex.quote (Command injection sanitizer)
• html.escape (XSS sanitizer)
• Database escape functions (SQL injection sanitizers)
• Django validators (Various validators)
• And more...

Checklist

• PR author has checked that all the criteria below are met
• The PR description includes an overview of the change
• The PR description articulates the motivation for the change
• The change includes tests OR the PR description describes a testing strategy
• The PR description notes risks associated with the change, if any
• Newly-added code is easy to change
• The change follows the library release note guidelines
• The change includes or references documentation updates if necessary
• Backport labels are set (if applicable)

Reviewer Checklist

• Reviewer has checked that all the criteria below are met
• Title is accurate
• All changes are related to the pull request's stated goal
• Avoids breaking API changes
• Testing strategy adequately addresses listed risks
• Newly-added code is easy to change
• Release note makes sense to a user of the library
• If necessary, author has acknowledged and discussed the performance implications of this PR as reported in the benchmarks PR comment
• Backport labels are set in a manner that is consistent with the release branch maintenance policy

[github-actions]

CODEOWNERS have been resolved as:

ddtrace/appsec/_iast/secure_marks/README_CONFIGURATION.md               @DataDog/asm-python
ddtrace/appsec/_iast/secure_marks/configuration.py                      @DataDog/asm-python
releasenotes/notes/iast-security-controls-9cb913d485cd5e4b.yaml         @DataDog/apm-python
tests/appsec/iast/secure_marks/__init__.py                              @DataDog/asm-python
tests/appsec/iast/secure_marks/test_security_controls_configuration.py  @DataDog/asm-python
ddtrace/appsec/_iast/_patch_modules.py                                  @DataDog/asm-python
ddtrace/appsec/_iast/main.py                                            @DataDog/asm-python
ddtrace/appsec/_iast/secure_marks/__init__.py                           @DataDog/asm-python
ddtrace/appsec/_iast/secure_marks/sanitizers.py                         @DataDog/asm-python
ddtrace/appsec/_iast/secure_marks/validators.py                         @DataDog/asm-python
ddtrace/settings/asm.py                                                 @DataDog/asm-python
docs/configuration.rst                                                  @DataDog/python-guild
tests/appsec/integrations/django_tests/django_app/urls.py               @DataDog/asm-python
tests/appsec/integrations/django_tests/django_app/views.py              @DataDog/asm-python
tests/appsec/integrations/django_tests/test_iast_django.py              @DataDog/asm-python
tests/telemetry/test_writer.py                                          @DataDog/apm-python

[github-actions]

Bootstrap import analysis

Comparison of import times between this PR and base.

Summary

The average import time from this PR is: 276 ± 4 ms.

The average import time from base is: 278 ± 2 ms.

The import time difference between this PR and base is: -2.1 ± 0.1 ms.

Import time breakdown

The following import paths have shrunk:

ddtrace.auto 2.008 ms (0.73%)

ddtrace.bootstrap.sitecustomize 1.332 ms (0.48%)

ddtrace.bootstrap.preload 1.332 ms (0.48%)

ddtrace.internal.remoteconfig.client 0.639 ms (0.23%)

ddtrace 0.676 ms (0.25%)

ddtrace.internal._unpatched 0.031 ms (0.01%)

json 0.031 ms (0.01%)

json.decoder 0.031 ms (0.01%)

re 0.031 ms (0.01%)

enum 0.031 ms (0.01%)

types 0.031 ms (0.01%)

[pr-commenter]

Benchmarks

Benchmark execution time: 2025-06-17 13:04:12

Comparing candidate commit 808b772 in PR branch avara1986/APPSEC-56901-iast_security_controls with baseline commit b9d71bf in branch main.

Found 1 performance improvements and 5 performance regressions! Performance is the same for 492 metrics, 6 unstable metrics.

scenario:iastaspects-format_map_aspect

• 🟥 execution_time [+402.250ns; +473.958ns] or [+12.373%; +14.579%]

scenario:iastaspectsospath-ospathnormcase_aspect

• 🟥 execution_time [+283.903ns; +373.257ns] or [+8.206%; +10.788%]

scenario:iastaspectsospath-ospathsplitext_aspect

• 🟥 execution_time [+575.157ns; +639.079ns] or [+12.730%; +14.145%]

scenario:iastaspectssplit-splitlines_aspect

• 🟥 execution_time [+137.436ns; +160.898ns] or [+9.427%; +11.036%]

scenario:iastdjangostartup-tracer

• 🟩 execution_time [-1.890s; -1.689s] or [-90.501%; -80.881%]

scenario:telemetryaddmetric-1-distribution-metric-1-times

• 🟥 execution_time [+351.306ns; +386.785ns] or [+12.121%; +13.345%]