secureapp-python-agent 26.5.0__py3-none-any.whl

secureapp_python_agent-26.5.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: secureapp-python-agent
+Version: 26.5.0
+Summary: Splunk SecureApp OpenTelemetry Extension for Python applications
+Author-email: Splunk <support@splunk.com>
+License-Expression: LicenseRef-Proprietary
+Keywords: observability,opentelemetry,security,monitoring,splunk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opentelemetry-api<1.40,>=1.27.0
+Requires-Dist: opentelemetry-sdk<1.40,>=1.27.0
+Requires-Dist: opentelemetry-exporter-otlp<1.40,>=1.27.0
+Requires-Dist: protobuf>=5.0; python_version >= "3.14"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.4.1; extra == "dev"
+Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
+Requires-Dist: pytest-testmon>=2.1.3; extra == "dev"
+Requires-Dist: mypy>=1.16.1; extra == "dev"
+Requires-Dist: ruff>=0.12.1; extra == "dev"
+Requires-Dist: coverage[toml]>=7.0.0; extra == "dev"
+Requires-Dist: tox>=4.27.0; extra == "dev"
+Requires-Dist: build>=1.2.2.post1; extra == "dev"
+Requires-Dist: pip-tools>=7.4.1; extra == "dev"
+Requires-Dist: setuptools-scm[toml]>=8.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Provides-Extra: benchmark
+Requires-Dist: pytest-benchmark>=4.0.0; extra == "benchmark"
+Requires-Dist: memory-profiler>=0.61.0; extra == "benchmark"
+Requires-Dist: psutil>=5.9.0; extra == "benchmark"
+Requires-Dist: memray>=1.10.0; extra == "benchmark"
+Provides-Extra: all
+Requires-Dist: secureapp-python-agent[benchmark,dev]; extra == "all"
+Dynamic: license-file
+
+# Splunk SecureApp OpenTelemetry Extension
+
+OpenTelemetry Python extension for integrating Splunk SecureApp with OpenTelemetry.
+This extension monitors runtime dependencies and reports them via OpenTelemetry logs.
+
+
+## Installation
+
+```bash
+# Install from PyPI
+pip install secureapp-python-agent
+
+# Install with OpenTelemetry instrumentation
+pip install secureapp-python-agent splunk-opentelemetry
+
+# Run your application with automatic instrumentation
+opentelemetry-instrument python your_app.py
+
+## Configuration
+
+The extension can be configured using environment variables:
+
+| Environment Variable                        | Default | Description                                               |
+|---------------------------------------------|---------|-----------------------------------------------------------|
+| `SPLUNK_SECUREAPP_AGENT_ENABLED`            | `true`  | Enable or disable the agent completely                    |
+| `OTEL_LOGS_EXPORTER`                        | `otlp`  | Log exporter type: `otlp`, `console`, or `none`           |
+| `SPLUNK_SECUREAPP_DEPENDENCY_INITIAL_DELAY` | `60.0`  | Initial delay (seconds) before dependency tracking starts |
+| `SPLUNK_SECUREAPP_DEPENDENCY_SCAN_INTERVAL` | `86400` | Interval (seconds) between dependency scans (24 hours)    |
+| `SPLUNK_SECUREAPP_LOG_LEVEL_INFO            |  NOTSET | Standard Python Log Levels                                |
+
+## Features
+
+### Runtime Dependency Monitoring
+
+The extension monitors third-party Python packages loaded at runtime and reports
+them through OpenTelemetry logs with:
+- Package name and version
+- Import timestamp
+- Standard library exclusion for performance optimization
+- Low overhead (<10MB memory, <100ms startup impact)
+
+### OpenTelemetry Integration
+
+- Sends dependency data as structured logs via configurable exporters
+- Compatible with the OpenTelemetry Collector and Splunk Observability backends
+- Lightweight implementation with optimized performance
+
+## Compatibility
+
+### OpenTelemetry Versions
+
+The extension is compatible with OpenTelemetry versions 1.39.x plus
+
+### Python Versions
+
+Supported Python versions:
+- Python 3.10
+- Python 3.11
+- Python 3.12
+- Python 3.13
+- Python 3.14
+
+## Performance Considerations
+
+The SecureApp agent is designed with minimal performance impact:
+- Startup overhead: <100ms
+- Memory overhead: <10MB
+- Optimizations:
+  - Lazy imports for better startup performance
+  - Standard library detection to avoid unnecessary scanning
+  - Configurable scan intervals
+  - Efficient batch processing for telemetry data
+

secureapp_python_agent-26.5.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+secureapp_python_agent-26.5.0.dist-info/licenses/LICENSE,sha256=oOJ-AemxdpKyhlaKimR1M0xZAX0c83qdhf-JEZPx_VM,114
+splunk_secureapp_opentelemetry_extension/__init__.py,sha256=-f2AjRN0PY1iU-6AWQC9K3IytpXD4D6dUYcPLGfdmIQ,975
+splunk_secureapp_opentelemetry_extension/agent.py,sha256=8qk7HqM6RPz_gp8T7_s3bMk6UdbQlyO6epfR161XCew,11492
+splunk_secureapp_opentelemetry_extension/dependency_analyzer.py,sha256=1L7w4kNZh-dWHAM3kJcscPyXTijexRDSrBwvEBv-sl0,19853
+splunk_secureapp_opentelemetry_extension/environment_variables.py,sha256=3OWPjQZvTmOWE-rqnfJxx6i0GDyr2FuRbr9wNOAlYh4,1707
+splunk_secureapp_opentelemetry_extension/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+splunk_secureapp_opentelemetry_extension/utils.py,sha256=GdVF6NkjIGn4CpQLDjh6Tfmq9hvf7s8sli9gXQKSFow,2730
+secureapp_python_agent-26.5.0.dist-info/METADATA,sha256=gjmSgQII1k5ULgnaVAVt2sksg_hbcHj6zGn7VzX5zuw,4609
+secureapp_python_agent-26.5.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+secureapp_python_agent-26.5.0.dist-info/entry_points.txt,sha256=4jjmIjyx4CM0dFRCha8SjG8wPcPhPM-yMunARk_FAMc,215
+secureapp_python_agent-26.5.0.dist-info/top_level.txt,sha256=v4_vqQoYxJHbcukkfaEXrUfcesHkGm-6G18lxXrruyI,41
+secureapp_python_agent-26.5.0.dist-info/RECORD,,

secureapp_python_agent-26.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

secureapp_python_agent-26.5.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[opentelemetry_post_instrument]
+splunk_secureapp = splunk_secureapp_opentelemetry_extension:post_instrument
+
+[opentelemetry_pre_instrument]
+splunk_secureapp = splunk_secureapp_opentelemetry_extension:pre_instrument

secureapp_python_agent-26.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,2 @@
+
+The terms governing use of the code is at this site: https://www.splunk.com/en_us/legal/splunk-general-terms.html

secureapp_python_agent-26.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+splunk_secureapp_opentelemetry_extension

splunk_secureapp_opentelemetry_extension/__init__.py

@@ -0,0 +1,38 @@
+# Copyright (c) 2026 Splunk Inc.
+# All rights reserved.
+# This software is the proprietary information of Splunk Inc.
+
+
+"""Splunk SecureApp OpenTelemetry Extension for Python."""
+
+from splunk_secureapp_opentelemetry_extension.agent import (
+    start_monitoring,
+    stop_monitoring,
+)
+
+
+def pre_instrument() -> None:
+    """OpenTelemetry pre-instrumentation hook.
+
+    Called by OpenTelemetry auto-instrumentation before instrumenting libraries.
+    This initializes the SecureApp agent early in the process lifecycle.
+    """
+    start_monitoring()
+
+
+def post_instrument() -> None:
+    """OpenTelemetry post-instrumentation hook.
+
+    Called by OpenTelemetry auto-instrumentation after instrumenting libraries.
+    Currently a no-op since dependency monitoring is started in pre_instrument.
+    """
+    # No additional actions needed after instrumentation
+    pass
+
+
+__all__ = [
+    "start_monitoring",
+    "stop_monitoring",
+    "pre_instrument",
+    "post_instrument",
+]

splunk_secureapp_opentelemetry_extension/agent.py

@@ -0,0 +1,304 @@
+# Copyright (c) 2026 Splunk Inc.
+# All rights reserved.
+# This software is the proprietary information of Splunk Inc.
+
+
+"""Main agent module for Splunk SecureApp OpenTelemetry Extension."""
+
+import os
+import threading
+from typing import TYPE_CHECKING
+
+from opentelemetry.environment_variables import OTEL_LOGS_EXPORTER
+
+from splunk_secureapp_opentelemetry_extension.utils import log_package_info
+
+# Lazy imports for better startup performance - only import when needed
+if TYPE_CHECKING:
+    from opentelemetry.sdk._logs import LoggerProvider
+
+    from splunk_secureapp_opentelemetry_extension.dependency_analyzer import (
+        RuntimeDependencyAnalyzer,
+    )
+
+from splunk_secureapp_opentelemetry_extension import environment_variables, utils
+
+# Performance constants for startup optimization
+_SHUTDOWN_TIMEOUT_SECONDS = 5.0
+_DEFAULT_EXPORTER_TYPE = "otlp"
+
+_PROJECT_NAME = "secureapp-python-agent"
+
+logger = utils.set_logging_for_module(__name__)
+
+
+class SecureAppAgent:
+    """Main agent class for Splunk SecureApp OpenTelemetry Extension."""
+
+    def __init__(self) -> None:
+        """Initialize the SecureApp agent."""
+        self._initialized = False
+        self._dependency_thread: threading.Thread | None = None
+        self._stop_event: threading.Event = threading.Event()
+        self._logger_provider: LoggerProvider | None = None
+        self._dependency_analyzer: RuntimeDependencyAnalyzer | None = None
+
+    def _create_logger_provider(self) -> "LoggerProvider":
+        """Create and configure the OpenTelemetry logger provider.
+
+        Returns:
+            Configured LoggerProvider with appropriate exporter.
+
+        Raises:
+            ImportError: If required OpenTelemetry components are not available.
+            RuntimeError: If logger provider configuration fails.
+        """
+        # Lazy imports for better startup performance - only import when actually starting
+        from opentelemetry.sdk._logs import LoggerProvider
+        from opentelemetry.sdk._logs.export import BatchLogRecordProcessor, LogExporter
+
+        # Initialize SecureApp's logger provider
+        logger_provider = LoggerProvider()
+
+        exporter_type = os.getenv(OTEL_LOGS_EXPORTER, _DEFAULT_EXPORTER_TYPE).lower()
+        log_exporter: LogExporter
+        # Create appropriate exporter based on configuration
+        if exporter_type == "otlp":
+            from opentelemetry.exporter.otlp.proto.http._log_exporter import (
+                OTLPLogExporter,
+            )
+
+            log_exporter = OTLPLogExporter()  # type: ignore[assignment]
+        elif exporter_type == "console":
+            from opentelemetry.sdk._logs.export import ConsoleLogExporter
+
+            log_exporter = ConsoleLogExporter()  # type: ignore[assignment]
+        else:
+            logger.warning(
+                f"Unknown {OTEL_LOGS_EXPORTER} value: {exporter_type}, defaulting to OTLP"
+            )
+            from opentelemetry.exporter.otlp.proto.http._log_exporter import (
+                OTLPLogExporter,
+            )
+
+            log_exporter = OTLPLogExporter()  # type: ignore[assignment]
+
+        logger_provider.add_log_record_processor(BatchLogRecordProcessor(log_exporter))
+
+        return logger_provider
+
+    def start(self) -> None:
+        """Start the SecureApp agent.
+
+        Uses the following environment variables for configuration:
+        - OTEL_LOGS_EXPORTER to specify the log exporter type (otlp, console, none)
+        - SPLUNK_SECUREAPP_DEPENDENCY_INITIAL_DELAY for initial delay before dependency tracking starts
+        - SPLUNK_SECUREAPP_DEPENDENCY_SCAN_INTERVAL for how often to scan dependencies
+
+        Note: SPLUNK_SECUREAPP_AGENT_ENABLED is checked at the start_monitoring() level.
+        """
+        if self._initialized:
+            logger.warning("Agent already initialized, skipping configuration")
+            return
+
+        logger.info("Starting SecureApp agent")
+
+        log_package_info(_PROJECT_NAME, logger)
+
+        try:
+            from splunk_secureapp_opentelemetry_extension.dependency_analyzer import (
+                RuntimeDependencyAnalyzer,
+            )
+
+            # Create and configure logger provider
+            self._logger_provider = self._create_logger_provider()
+
+            # Initialize dependency analyzer with our logger provider
+            self._dependency_analyzer = RuntimeDependencyAnalyzer(
+                logger_provider=self._logger_provider
+            )
+
+            # Start dependency tracking (always enabled when agent is enabled)
+            self._begin_monitoring()
+
+            self._initialized = True
+            logger.info("SecureApp agent started successfully")
+
+        except Exception as e:
+            logger.error(f"Failed to start SecureApp agent: {e}")
+            raise
+
+    def _begin_monitoring(self) -> None:
+        """Begin background dependency monitoring."""
+        if self._dependency_thread and self._dependency_thread.is_alive():
+            logger.debug("Dependency monitoring already running")
+            return
+
+        logger.info("Beginning dependency monitoring")
+        self._dependency_thread = threading.Thread(
+            target=self._dependency_tracking_loop,
+            daemon=True,
+            name="SecureApp-DependencyTracker",
+        )
+        self._dependency_thread.start()
+
+    def _dependency_tracking_loop(self) -> None:
+        """Background loop for dependency tracking with initial delay."""
+        if self._dependency_analyzer is None:
+            logger.error("Dependency analyzer not initialized")
+            return
+
+        initial_delay = environment_variables.SPLUNK_SECUREAPP_DEPENDENCY_INITIAL_DELAY
+        scan_interval = environment_variables.SPLUNK_SECUREAPP_DEPENDENCY_SCAN_INTERVAL
+
+        # Wait for initial delay to allow application initialization
+        logger.info(
+            f"Dependency tracking starting after {initial_delay}s initial delay"
+        )
+        if self._stop_event.wait(initial_delay):
+            # Stop event was set during initial delay
+            logger.info("Dependency tracking stopped during initial delay")
+            return
+
+        logger.info("Starting regular dependency scans")
+
+        while not self._stop_event.is_set():
+            try:
+                # Emit runtime package events using our specific analyzer
+                self._dependency_analyzer.emit_package_events()
+
+            except Exception as e:
+                logger.error(f"Error during dependency tracking: {e}")
+                # Add exponential backoff on errors to prevent rapid retry loops
+                error_backoff = min(
+                    60.0, scan_interval * 0.1
+                )  # Max 1 minute, min 10% of interval
+                if self._stop_event.wait(error_backoff):
+                    break
+                continue
+
+            # Wait for next scan or stop event
+            if self._stop_event.wait(scan_interval):
+                # Stop event was set, exit the loop
+                break
+
+        logger.info("Dependency tracking stopped")
+
+    def shutdown(self) -> None:
+        """Shutdown the SecureApp agent and all monitoring activities.
+
+        This method follows OpenTelemetry shutdown conventions and:
+        - Signals the dependency tracking thread to stop
+        - Waits for the thread to finish gracefully
+        - Shuts down the logger provider and processors
+        - Marks the agent as uninitialized for potential restart
+
+        This method is idempotent - calling it multiple times is safe.
+
+        Raises:
+            Exception: Re-raises any critical errors during shutdown that prevent cleanup.
+        """
+        if not self._initialized:
+            logger.debug("Agent not initialized, nothing to shutdown")
+            return
+
+        logger.info("Shutting down SecureApp agent")
+
+        try:
+            # Signal stop to dependency tracking thread
+            self._stop_event.set()
+
+            # Wait for dependency thread to finish gracefully
+            if (
+                self._dependency_thread is not None
+                and self._dependency_thread.is_alive()
+            ):
+                logger.debug("Waiting for dependency tracking thread to stop")
+                self._dependency_thread.join(
+                    timeout=_SHUTDOWN_TIMEOUT_SECONDS
+                )  # 5 second timeout
+                if (
+                    self._dependency_thread is not None
+                    and self._dependency_thread.is_alive()
+                ):
+                    logger.warning("Dependency tracking thread did not stop gracefully")
+                    # Thread is still alive, but we'll continue cleanup anyway
+
+            # Shutdown logger provider and processors
+            if self._logger_provider is not None:
+                try:
+                    # Type check: Ensure shutdown method exists and is callable
+                    shutdown_method = getattr(self._logger_provider, "shutdown", None)
+                    if shutdown_method is not None and callable(shutdown_method):
+                        shutdown_method()
+                    else:
+                        logger.warning("LoggerProvider does not have a shutdown method")
+                except Exception as e:
+                    logger.warning(f"Error shutting down logger provider: {e}")
+
+            logger.info("SecureApp agent shutdown complete")
+
+        finally:
+            # Always reset state for potential restart, even if shutdown had errors
+            # Type safety: Explicitly set each attribute to None with correct types
+            self._initialized = False
+            self._dependency_thread = None
+            self._logger_provider = None
+            self._dependency_analyzer = None
+            self._stop_event.clear()  # CRITICAL: Reset for potential restart
+
+
+# Global agent instance
+_agent: SecureAppAgent | None = None
+
+
+def start_monitoring() -> None:
+    """Start the SecureApp agent.
+
+    This is the main public API function for starting dependency monitoring.
+    Can be called multiple times safely (subsequent calls are ignored).
+
+    Respects the SPLUNK_SECUREAPP_AGENT_ENABLED environment variable.
+    If disabled, this function returns early without creating an agent.
+    """
+    global _agent
+
+    # Check if agent should be enabled before creating it
+    if not environment_variables.SPLUNK_SECUREAPP_AGENT_ENABLED:
+        logger.info("SecureApp agent is disabled via SPLUNK_SECUREAPP_AGENT_ENABLED")
+        return
+
+    # Check exporter configuration first before creating any resources
+    exporter_type = os.getenv(OTEL_LOGS_EXPORTER, _DEFAULT_EXPORTER_TYPE).lower()
+    if exporter_type == "none":
+        # No exporter - agent will be essentially disabled for logs
+        logger.info(
+            f"SecureApp agent is disabled because Logs exporter disabled via {OTEL_LOGS_EXPORTER}=none"
+        )
+        return
+
+    if _agent is None:
+        _agent = SecureAppAgent()
+
+    _agent.start()
+
+
+def get_agent() -> SecureAppAgent | None:
+    """Get the global agent instance.
+
+    Returns:
+        SecureApp agent instance or None if not configured or disabled.
+    """
+    return _agent
+
+
+def stop_monitoring() -> None:
+    """Stop the SecureApp monitoring agent.
+
+    This gracefully shuts down all monitoring activities and cleans up resources.
+    Can be called multiple times safely (subsequent calls are ignored).
+    """
+    global _agent
+    if _agent is not None:
+        _agent.shutdown()
+        _agent = None

splunk_secureapp_opentelemetry_extension/dependency_analyzer.py

@@ -0,0 +1,528 @@
+# Copyright (c) 2026 Splunk Inc.
+# All rights reserved.
+# This software is the proprietary information of Splunk Inc.
+
+
+"""Dependency analysis module for tracking Python package dependencies."""
+
+import base64
+import gzip
+import json
+import logging
+import sys
+import time
+import uuid
+from dataclasses import dataclass
+from importlib.metadata import (
+    Distribution,
+    PackageNotFoundError,
+    distribution,
+    packages_distributions,
+)
+from typing import TYPE_CHECKING, Any, Optional
+
+from opentelemetry._logs.severity import SeverityNumber
+from opentelemetry.sdk._logs._internal import LogRecord  # type: ignore[attr-defined]
+from opentelemetry.trace.span import TraceFlags
+
+from splunk_secureapp_opentelemetry_extension import environment_variables, utils
+
+if TYPE_CHECKING:
+    from opentelemetry.sdk._logs import LoggerProvider
+
+logger = utils.set_logging_for_module(__name__)
+
+# SecureApp event name constants
+SECUREAPP_DEPENDENCY_REPORT_EVENT_NAME = "com.cisco.secureapp.report.v1"
+
+# Configuration constants
+MAX_PACKAGES_PER_FRAGMENT = 1000
+PKG_DISTRIBUTIONS_CACHE_TTL = 300.0  # 5 minutes TTL
+
+
+@dataclass
+class PackageInfo:
+    """Package information for dependency reports and runtime analysis.
+
+    Represents a single package entry with all required fields for
+    security analysis and internal processing.
+    """
+
+    name: str
+    version: str
+    ecosystem: str = "python"
+    path: str = ""
+
+
+@dataclass
+class SecureAppEventBody:
+    """Event body structure for SecureApp dependency reports.
+
+    Represents the complete structure of a dependency report event,
+    including fragmentation support for large package lists.
+    """
+
+    id: str
+    fragment_index: int
+    max_fragments: int
+    is_done: bool
+    packages: list[PackageInfo]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert event body to dictionary format for JSON serialization."""
+        # Pre-allocate dict with known size for better performance
+        result = {
+            "id": self.id,
+            "fragment_index": self.fragment_index,
+            "max_fragments": self.max_fragments,
+            "is_done": self.is_done,
+            "packages": [],
+        }
+
+        # Use list comprehension for better performance
+        result["packages"] = [
+            {
+                "name": pkg.name,
+                "version": pkg.version,
+                "ecosystem": pkg.ecosystem,
+                "path": pkg.path,
+            }
+            for pkg in self.packages
+        ]
+
+        return result
+
+
+class RuntimeDependencyAnalyzer:
+    """Analyzes Python packages loaded into runtime.
+
+    This analyzer identifies third-party packages while ignoring stdlib modules.
+    It uses importlib.metadata for accurate package resolution and supports
+    namespace packages correctly.
+    """
+
+    def __init__(self, logger_provider: Optional["LoggerProvider"] = None) -> None:
+        """Initialize the runtime dependency analyzer.
+
+        Args:
+            logger_provider: OpenTelemetry LoggerProvider to use for event emission.
+                           If None, events will not be emitted.
+        """
+        self._runtime_packages: dict[str, PackageInfo] = {}
+        self._last_scan_time: float = 0.0
+        self._scan_interval = (
+            environment_variables.SPLUNK_SECUREAPP_DEPENDENCY_SCAN_INTERVAL
+        )
+        self._logger_provider = logger_provider
+        # Cache packages_distributions() result - expensive call with TTL
+        self._pkg_distributions_cache: dict[str, list[str]] | None = None
+        self._pkg_distributions_cache_time: float = 0.0
+
+        # Cache for stdlib module detection
+        self._stdlib_module_cache: dict[str, bool] = {}
+
+        # Pre-cache stdlib module names for faster lookups (Python 3.10+)
+        self._stdlib_module_names: frozenset[str] = getattr(
+            sys, "stdlib_module_names", frozenset()
+        )
+
+    def _should_ignore_module(self, module_name: str, module_path: str | None) -> bool:
+        """Determine if a module should be ignored during dependency scanning.
+
+        Uses Python 3.10+ native detection with optimized lookups.
+        Pre-caches stdlib_module_names to avoid repeated hasattr() calls.
+
+        Args:
+            module_name: The module name
+            module_path: The __file__ attribute of the module, or None
+
+        Returns:
+            True if module should be ignored (stdlib/system), False if it's a third-party package
+        """
+        if not module_path:
+            return True
+
+        # Use cache for repeated lookups
+        if module_name in self._stdlib_module_cache:
+            return self._stdlib_module_cache[module_name]
+
+        # Extract top-level module name once
+        top_level_name = module_name.split(".", 1)[0]
+
+        # Fast path: Check pre-cached stdlib module names
+        if top_level_name in self._stdlib_module_names:
+            self._stdlib_module_cache[module_name] = True
+            return True
+
+        # Check built-in modules (C extensions in stdlib)
+        if top_level_name in sys.builtin_module_names:
+            self._stdlib_module_cache[module_name] = True
+            return True
+
+        # Cache and return False (third-party)
+        self._stdlib_module_cache[module_name] = False
+        return False
+
+    def _get_packages_distributions(self) -> dict[str, list[str]]:
+        """Get cached packages_distributions() result.
+
+        Returns:
+            Dictionary mapping top-level package names to distribution names.
+        """
+        current_time = time.time()
+
+        if (
+            self._pkg_distributions_cache is None
+            or current_time - self._pkg_distributions_cache_time
+            > PKG_DISTRIBUTIONS_CACHE_TTL
+        ):
+            # Convert Mapping to dict to match type annotation
+            self._pkg_distributions_cache = dict(packages_distributions())
+            self._pkg_distributions_cache_time = current_time
+
+        return self._pkg_distributions_cache
+
+    def _find_distribution_for_module(
+        self, module_name: str, module_path: str
+    ) -> PackageInfo | None:
+        """Find the correct distribution for a module.
+
+        Args:
+            module_name: Full module name (e.g., "google.protobuf")
+            module_path: Path to the module file
+
+        Returns:
+            PackageInfo with correct distribution name and version, or None if not found
+        """
+        # Extract top-level package name
+        top_level_name = module_name.split(".", 1)[0]
+
+        # Only log debug messages if debug logging is enabled
+        debug_enabled = logger.isEnabledFor(logging.DEBUG)
+        if debug_enabled:
+            logger.debug(
+                f"Finding distribution for module: {module_name} (top-level: {top_level_name}) at {module_path}"
+            )
+
+        try:
+            # Use cached packages_distributions to get the mapping
+            pkg_to_dists = self._get_packages_distributions()
+            distributions_for_module = pkg_to_dists.get(top_level_name, [])
+
+            if debug_enabled:
+                logger.debug(
+                    f"packages_distributions() found: {distributions_for_module} for {top_level_name}"
+                )
+
+            if not distributions_for_module:
+                # Try direct lookup if not in packages_distributions
+                if debug_enabled:
+                    logger.debug(
+                        f"No distributions found in packages_distributions, trying direct lookup for {top_level_name}"
+                    )
+                try:
+                    dist = distribution(top_level_name)
+                    result = PackageInfo(
+                        name=dist.metadata["Name"],
+                        version=dist.version,
+                        path=module_path,
+                    )
+                    if debug_enabled:
+                        logger.debug(
+                            f"Direct lookup successful: {result.name} v{result.version}"
+                        )
+                    return result
+                except PackageNotFoundError:
+                    if debug_enabled:
+                        logger.debug(f"Direct lookup failed for {top_level_name}")
+                    return None
+
+            # If only one distribution provides this module, use it
+            if len(distributions_for_module) == 1:
+                dist_name = distributions_for_module[0]
+                if debug_enabled:
+                    logger.debug(f"Single distribution found: {dist_name}")
+                dist = distribution(dist_name)
+                result = PackageInfo(
+                    name=dist.metadata["Name"],
+                    version=dist.version,
+                    path=module_path,
+                )
+                if debug_enabled:
+                    logger.debug(
+                        f"Using single distribution: {result.name} v{result.version}"
+                    )
+                return result
+
+            # Multiple distributions provide this module - determine which one
+            # based on which distribution actually contains the specific module file
+            if debug_enabled:
+                logger.debug(
+                    f"Multiple distributions found: {distributions_for_module}"
+                )
+                logger.debug(
+                    "Checking which distribution contains the specific module file..."
+                )
+
+            for dist_name in distributions_for_module:
+                try:
+                    dist = distribution(dist_name)
+                    if debug_enabled:
+                        logger.debug(f"Checking distribution: {dist_name}")
+
+                    # Check if this distribution contains the specific module file
+                    if self._distribution_contains_module_file(dist, module_path):
+                        result = PackageInfo(
+                            name=dist.metadata["Name"],
+                            version=dist.version,
+                            path=module_path,
+                        )
+                        if debug_enabled:
+                            logger.debug(
+                                f"File match found! Using distribution: {result.name} v{result.version}"
+                            )
+                        return result
+                    if debug_enabled:
+                        logger.debug(
+                            f"Distribution {dist_name} does not contain the module file"
+                        )
+
+                except Exception as e:
+                    if debug_enabled:
+                        logger.debug(f"Error checking distribution {dist_name}: {e}")
+                    continue
+
+            # If no distribution matched by file, use first as fallback
+            dist_name = distributions_for_module[0]
+            if debug_enabled:
+                logger.debug(
+                    f"No file match found, using first distribution as fallback: {dist_name}"
+                )
+            dist = distribution(dist_name)
+            result = PackageInfo(
+                name=dist.metadata["Name"],
+                version=dist.version,
+                path=module_path,
+            )
+            if debug_enabled:
+                logger.debug(f"Fallback distribution: {result.name} v{result.version}")
+            return result
+
+        except Exception as e:
+            if debug_enabled:
+                logger.debug(f"Error finding distribution for {module_name}: {e}")
+            return None
+
+    def _distribution_contains_module_file(
+        self, dist: Distribution, module_path: str
+    ) -> bool:
+        """Check if a distribution contains the specific module file.
+
+        Args:
+            dist: Distribution object from importlib.metadata
+            module_path: Full path to the module file
+
+        Returns:
+            True if this distribution contains the module file, False otherwise
+        """
+        try:
+            # Fast path: Check if this distribution has files
+            if not hasattr(dist, "files") or not dist.files:
+                return False
+
+            # Extract relative path once with optimized logic
+            if "site-packages/" in module_path:
+                relative_path = module_path.split("site-packages/", 1)[1]
+            elif "dist-packages/" in module_path:
+                relative_path = module_path.split("dist-packages/", 1)[1]
+            else:
+                return False
+
+            # Use any() with generator for memory efficiency
+            return any(str(file_obj) == relative_path for file_obj in dist.files)
+
+        except Exception as e:
+            logger.debug(f"Error checking if distribution contains module file: {e}")
+            return False
+
+    def get_runtime_packages(self) -> dict[str, PackageInfo]:
+        """Get information about packages currently loaded in Python runtime.
+
+        Returns:
+            Dictionary mapping distribution names to PackageInfo objects.
+            Only includes third-party packages from site-packages/dist-packages.
+        """
+        current_time = time.time()
+
+        # Use cached data if within scan interval and cache exists
+        if (
+            current_time - self._last_scan_time < self._scan_interval
+            and self._runtime_packages
+        ):
+            if logger.isEnabledFor(logging.DEBUG):
+                logger.debug(
+                    f"Using cached runtime packages ({len(self._runtime_packages)} packages)"
+                )
+            return self._runtime_packages.copy()
+
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug("Performing fresh scan of runtime packages...")
+
+        # Create a snapshot of sys.modules to avoid "dictionary changed size during iteration"
+        modules_snapshot = dict(sys.modules)
+        found_packages: dict[str, PackageInfo] = {}
+        processed_count = 0
+        skipped_count = 0
+
+        for module_name, module_obj in modules_snapshot.items():
+            try:
+                # Skip modules without __file__ or with None __file__
+                module_path = getattr(module_obj, "__file__", None)
+                if not module_path:
+                    skipped_count += 1
+                    continue
+
+                # Skip stdlib and system modules
+                if self._should_ignore_module(module_name, module_path):
+                    skipped_count += 1
+                    continue
+
+                # Find the distribution for this module
+                package_info = self._find_distribution_for_module(
+                    module_name, module_path
+                )
+                if package_info:
+                    # Use distribution name as key to avoid duplicates
+                    found_packages[package_info.name] = package_info
+                    processed_count += 1
+
+            except Exception as e:
+                if logger.isEnabledFor(logging.DEBUG):
+                    logger.debug(f"Error processing module {module_name}: {e}")
+                continue
+
+        # Update cache
+        self._runtime_packages = found_packages
+        self._last_scan_time = current_time
+
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug(
+                f"Scan complete - found {len(found_packages)} packages, "
+                f"processed {processed_count}, skipped {skipped_count}"
+            )
+        return found_packages.copy()
+
+    def create_runtime_package_events(self) -> list[LogRecord]:
+        """Create OpenTelemetry log events for runtime package dependencies.
+
+        Returns:
+            List of LogRecord objects containing package dependency data.
+        """
+        packages = self.get_runtime_packages()
+
+        # No conversion needed - packages are already PackageInfo objects
+        package_infos = list(packages.values())
+
+        # Create event fragments
+        events = []
+        total_packages = len(package_infos)
+        max_fragments = max(
+            1,
+            (total_packages + MAX_PACKAGES_PER_FRAGMENT - 1)
+            // MAX_PACKAGES_PER_FRAGMENT,
+        )
+        event_id = str(uuid.uuid4())
+
+        for fragment_index in range(max_fragments):
+            start_idx = fragment_index * MAX_PACKAGES_PER_FRAGMENT
+            end_idx = min(start_idx + MAX_PACKAGES_PER_FRAGMENT, total_packages)
+            fragment_packages = package_infos[start_idx:end_idx]
+
+            event_body = SecureAppEventBody(
+                id=event_id,
+                fragment_index=fragment_index,
+                max_fragments=max_fragments,
+                is_done=(fragment_index == max_fragments - 1),
+                packages=fragment_packages,
+            )
+
+            # Encode the event body
+            encoded_body = self._encode_event_body(event_body)
+            if encoded_body is None:
+                logger.error("Failed to encode event body")
+                continue
+
+            # Create log record with hardcoded trace/span IDs for OTLP compatibility
+            # Note: resource parameter removed in OpenTelemetry 1.39.0+
+            log_record_kwargs = {
+                "timestamp": int(time.time() * 1_000_000_000),  # nanoseconds
+                "trace_id": 0,  # Use simple hardcoded trace/span IDs for OpenTelemetry compatibility
+                "span_id": 0,  # Use simple hardcoded trace/span IDs for OpenTelemetry compatibility
+                "trace_flags": TraceFlags.get_default(),
+                "severity_text": "",
+                "severity_number": SeverityNumber.UNSPECIFIED,
+                "body": encoded_body,
+                "attributes": {
+                    "event.name": SECUREAPP_DEPENDENCY_REPORT_EVENT_NAME,
+                },
+            }
+
+            # Try with resource parameter for OTel <1.39.0 compatibility
+            try:
+                log_record = LogRecord(**log_record_kwargs, resource=None)  # type: ignore[call-overload]
+            except TypeError:
+                # OTel 1.39.0+ removed resource parameter
+                log_record = LogRecord(**log_record_kwargs)  # type: ignore[call-overload]
+
+            events.append(log_record)
+
+        logger.debug(
+            f"Created {len(events)} package events with {total_packages} total packages"
+        )
+        return events
+
+    def emit_package_events(self) -> None:
+        """Emit package dependency events using the configured logger provider."""
+        if not self._logger_provider:
+            logger.debug("No logger provider configured - skipping event emission")
+            return
+
+        try:
+            events = self.create_runtime_package_events()
+            if not events:
+                logger.debug("No events to emit")
+                return
+
+            otel_logger = self._logger_provider.get_logger("secureapp")
+
+            for event in events:
+                otel_logger.emit(event)
+
+            logger.debug(f"Successfully emitted {len(events)} package events")
+
+        except Exception as e:
+            logger.error(f"Failed to emit package events: {e}")
+
+    def _encode_event_body(self, event_body: SecureAppEventBody) -> str | None:
+        """Encode event body as compressed base64 JSON.
+
+        Args:
+            event_body: SecureAppEventBody object to encode
+
+        Returns:
+            Base64-encoded compressed JSON string, or None if encoding fails
+        """
+        try:
+            # Convert to JSON
+            json_data = json.dumps(event_body.to_dict(), separators=(",", ":"))
+
+            # Compress with gzip
+            compressed_data: bytes = gzip.compress(json_data.encode("utf-8"))
+
+            # Encode as base64 (bytes is valid input for b64encode)
+            encoded_data = base64.b64encode(compressed_data)
+            return encoded_data.decode("ascii")
+
+        except Exception as e:
+            logger.error(f"Failed to encode event body: {e}")
+            return None

splunk_secureapp_opentelemetry_extension/environment_variables.py

@@ -0,0 +1,59 @@
+# Copyright (c) 2026 Splunk Inc.
+# All rights reserved.
+# This software is the proprietary information of Splunk Inc.
+
+
+"""Environment variable definitions for Splunk SecureApp OpenTelemetry Extension."""
+
+import os
+
+
+def get_env_bool(name: str, default: bool = False) -> bool:
+    """Get boolean environment variable value.
+
+    Args:
+        name: Environment variable name.
+        default: Default value if variable is not set.
+
+    Returns:
+        Boolean value of the environment variable.
+    """
+    value = os.getenv(name, "").lower()
+    return value in ("true", "1", "yes", "on") if value else default
+
+
+def get_env_str(name: str, default: str = "") -> str:
+    """Get string environment variable value.
+
+    Args:
+        name: Environment variable name.
+        default: Default value if variable is not set.
+
+    Returns:
+        String value of the environment variable.
+    """
+    return os.getenv(name, default)
+
+
+# OTLP configuration
+# Use standard OpenTelemetry environment variables instead:
+# - OTEL_EXPORTER_OTLP_ENDPOINT
+# - OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
+
+# Feature toggles
+SPLUNK_SECUREAPP_AGENT_ENABLED = get_env_bool("SPLUNK_SECUREAPP_AGENT_ENABLED", True)
+
+# Dependency analysis configuration
+SPLUNK_SECUREAPP_DEPENDENCY_SCAN_INTERVAL = int(
+    get_env_str(
+        "SPLUNK_SECUREAPP_DEPENDENCY_SCAN_INTERVAL", "86400"
+    )  # 1 day (24 * 60 * 60)
+)
+SPLUNK_SECUREAPP_DEPENDENCY_INITIAL_DELAY = int(
+    get_env_str("SPLUNK_SECUREAPP_DEPENDENCY_INITIAL_DELAY", "60")  # 1 minute
+)
+
+# Logging
+SPLUNK_SECUREAPP_LOG_LEVEL = get_env_str("SPLUNK_SECUREAPP_LOG_LEVEL")
+if SPLUNK_SECUREAPP_LOG_LEVEL is not None:
+    SPLUNK_SECUREAPP_LOG_LEVEL = SPLUNK_SECUREAPP_LOG_LEVEL.upper()

splunk_secureapp_opentelemetry_extension/utils.py

@@ -0,0 +1,86 @@
+# Copyright (c) 2026 Splunk Inc.
+# All rights reserved.
+# This software is the proprietary information of Splunk Inc.
+
+
+"""Utilities for Splunk SecureApp OpenTelemetry Extension."""
+
+import logging
+from importlib.metadata import (
+    PackageNotFoundError,
+    distribution,
+    metadata,
+    requires,
+)
+
+from splunk_secureapp_opentelemetry_extension import environment_variables
+
+
+def set_logging_for_module(name: str) -> logging.Logger:
+    """Configures and returns a logging.Logger instance for a specific module.
+
+    Args:
+        name (str): The name of the module, typically passed as __name__.
+
+    Returns:
+        logging.Logger: A configured logger instance.
+    """
+    logger = logging.getLogger(name)
+
+    # If Log Level not set for SecureApp - just use whatever root logger has set
+    if not environment_variables.SPLUNK_SECUREAPP_LOG_LEVEL:
+        return logger
+
+    # Set the logger level - if error - print it and return logger with root level
+    try:
+        logger.setLevel(environment_variables.SPLUNK_SECUREAPP_LOG_LEVEL)
+    except ValueError as e:
+        print(f"Error: {e}")
+        return logger
+
+    # Prevent duplicate handlers if the function is called multiple times
+    if not logger.handlers:
+        console_handler = logging.StreamHandler()
+        console_handler.setLevel(environment_variables.SPLUNK_SECUREAPP_LOG_LEVEL)
+
+        formatter = logging.Formatter(
+            "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+        )
+        console_handler.setFormatter(formatter)
+        logger.addHandler(console_handler)
+
+        logger.propagate = False
+
+    # Explicitly return the logger
+    return logger
+
+
+def log_package_info(package_name: str, logger: logging.Logger) -> None:
+    """Logs the name, version, and installation location of a specified Python package.
+
+    Args:
+        package_name (str): The name of the package to retrieve information for.
+        logger (logging.Logger): The logger instance used to output the package information.
+
+    Returns:
+        None
+    """
+    try:
+        # Get the distribution information for the package
+        dist = distribution(package_name)
+
+        # Get all metadata
+        pkg_metadata = metadata(package_name)
+
+        # Get dependencies
+        pkg_dependencies = requires(package_name)
+
+        # Log the package details
+        logger.info(f"Package: {package_name}")
+        logger.info(f"Version: {dist.version}")
+        logger.info(f"Location: {dist.locate_file('')}")
+        logger.info(f"Summary: {pkg_metadata['Summary']}")
+        logger.info(f"Dependencies: {pkg_dependencies}")
+
+    except PackageNotFoundError:
+        logger.info(f"Package '{package_name}' is not installed in this environment.")