Do language-specific steps

Use this workflow for applications that don't run on Kubernetes.

Java

Secure Application integrates runtime security detection into your Java application through a JVM extension (splunk-otel-javaagent-csa) that works with the Splunk Distribution of OpenTelemetry Java.

If your application already uses the standard Splunk OpenTelemetry Java agent, replace that JAR with the Secure Application JVM extension JAR. The Secure Application JVM extension handles both Splunk APM instrumentation and Secure Application library scanning.

  1. Deploy a supported OpenTelemetry Collector.

  2. Download the Secure Application JVM extension version 2.25.1 or higher JAR file:

    SHELL 
    curl -L https://repo1.maven.org/maven2/com/splunk/splunk-otel-javaagent-csa/<version>/splunk-otel-javaagent-csa-<version>.jar -o splunk-otel-javaagent-csa.jar
    Note: The name you give to the downloaded JAR file must contain splunk-otel-javaagent.

  3. Restart your application with the Secure Application JVM extension and its required configuration parameters. You can set these values through system properties or environment variables.

    BASH 
    java -javaagent:./splunk-otel-javaagent-csa.jar \
  -Dotel.service.name=<service-name> \
  -Dotel.resource.attributes=deployment.environment.name=<environment-name>,service.namespace=<namespace-name> \
  -Dotel.exporter.otlp.endpoint=http://<collector-endpoint>:4318 \
  -Dargento.allow.security.events=true \
  -jar <application-name>.jar

    Syntax:

    BASH 
    java -javaagent:./splunk-otel-javaagent-csa.jar \
  -Dotel.service.name=<service-name> \
  -Dotel.resource.attributes=deployment.environment.name=<environment-name>,service.namespace=<namespace-name> \
  -Dotel.exporter.otlp.endpoint=http://<collector-endpoint>:<collector-port> \
  -Dargento.allow.security.events=true \
  -jar <application-name>.jar
    Table 1. Secure Application JVM extension parameters
    System property Environment variable Description
    argento.allow.security.events None Add this flag when you want Secure Application to collect attack events. You must include this flag to populate the Attacks page.
    otel.exporter.otlp.endpoint OTEL_EXPORTER_OTLP_ENDPOINT OTLP endpoint for your OpenTelemetry Collector. Use port 4318 for OTLP/HTTP or port 4317 for OTLP/gRPC, depending on your collector configuration.

    Example: http://otel-collector:4318
    otel.resource.attributes OTEL_RESOURCE_ATTRIBUTES

    Resource attributes to associate with your Java application.

    Recommended:

    If you set otel.service.name or OTEL_SERVICE_NAME, don't also define service.name in otel.resource.attributes.
    otel.service.name OTEL_SERVICE_NAME Service name of your Java application. This value sets the service.name resource attribute.

  4. Verify Secure Application instrumentation:

    1. Confirm that the application starts with splunk-otel-javaagent-csa.jar.

    2. Confirm that your OpenTelemetry Collector receives telemetry from the application and doesn't report export errors for Secure Application data.

  5. Look for security events in APM > Application Security after a few minutes.

    Runtime library and vulnerability data appear on the corresponding tabs. Attack events appear on the Attacks tab only if you start the application with -Dargento.allow.security.events=true.

Tip:

To roll back JVM extension changes, replace splunk-otel-javaagent-csa.jar with your previous Java agent JAR, remove -Dargento.allow.security.events=true if you added it, and restart the application.

Node.js

  1. Deploy a supported OpenTelemetry Collector.

  2. Instrument your application with Splunk OpenTelemetry JS version 4.x.

  3. Activate Secure Application instrumentation for the Node.js agent.

    Set the SPLUNK_SECUREAPP_AGENT_ENABLED environment variable to true.

    CODE 
    export SPLUNK_SECUREAPP_AGENT_ENABLED=true

  4. Configure the OTLP logs endpoint.

    By default, the Node.js agent sends Secure Application logs to http://localhost:4318/v1/logs but you can change this by setting one of these environment variables:

    Environment variable Description Example
    OTEL_EXPORTER_OTLP_ENDPOINT

    Base OTLP endpoint. The Node.js agent appends /v1/logs when it sends Secure Application logs.

    		 http://localhost:4318
    OTEL_EXPORTER_OTLP_LOGS_ENDPOINT

    Full OTLP logs endpoint. The Node.js agent doesn't append /v1/logs.

    		 https://localhost:4318/v1/logs

  5. Set service metadata for your Node.js application.

    Environment variable Description Example
    OTEL_SERVICE_NAME

    Service name for the instrumented Node.js application.

    		 checkout-service
    OTEL_RESOURCE_ATTRIBUTES

    Resource attributes that describe the instrumented service.

    		 deployment.environment=test

  6. Optional: Configure Secure Application runtime reporting.

    Environment variable Description Default
    SPLUNK_SECUREAPP_DEPENDENCY_SCAN_INTERVAL

    Time, in milliseconds, between dependency scans.

    		 86400000 (24 hours)
    SPLUNK_SECUREAPP_RUNTIME_PACKAGES_ONLY

    When set to true, reports only packages loaded at runtime.

    		 true
    SPLUNK_SECUREAPP_NO_SELF_REPORT

    When set to true, excludes dependencies of the Node.js agent from the report.

    		 false

  7. Run your Node.js application:

    SHELL 
    node -r @splunk/otel/instrument <your-application>.js

Your Node.js application launches with Secure Application instrumentation activated. The Node.js agent does the following:

  • Sends vulnerability and library data to the Splunk Observability Cloud back end.

  • Collects potential attack events at runtime.

  • Reports data once at application startup and then every 24 hours thereafter.

Python

Secure Application integrates runtime security detection into your Python application through a Python extension (secureapp-python-agent) that works with the Splunk Distribution of OpenTelemetry Python. This extension sends the OpenTelemetry events and logs that Secure Application needs to Splunk Observability Cloud. Follow these steps to add this extension to your Python application.

Note: The examples in this topic are for a Linux environment.

  1. Confirm that you meet the Python instrumentation requirements.

  2. Deploy a supported OpenTelemetry Collector.

  3. Install the Secure Application Python extension (secureapp-python-agent):

    • If you've already installed the Splunk Distribution of OpenTelemetry Python, you already have the Splunk instrumentation agent (splunk-opentelemetry) installed. Just install the Secure Application Python extension:

      BASH 
      pip install secureapp-python-agent

    • Otherwise, install the Secure Application Python extension together with the Splunk instrumentation agent (splunk-opentelemetry):

      BASH 
      pip install "splunk-opentelemetry[secureapp]"
    Tip: If you're using a requirements.txt or pyproject.toml file, add splunk-opentelemetry to it.

  4. (Optional) Set these environment variables to customize the behavior of the Secure Application Python extension. However, using the default values is strongly recommended:

    Environment variable Default Description
    SPLUNK_SECUREAPP_AGENT_ENABLED true Activate or deactivate the agent.
    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).

    Example:

    BASH 
    export SPLUNK_SECUREAPP_AGENT_ENABLED=true
export SPLUNK_SECUREAPP_DEPENDENCY_INITIAL_DELAY=60
export SPLUNK_SECUREAPP_DEPENDENCY_SCAN_INTERVAL=86400

  5. (Optional) If you haven't already done so, run the opentelemetry-bootstrap tool to scan your current Python environment, detect which libraries you have installed, and automatically install the necessary OpenTelemetry instrumentation packages for them:

    BASH 
    opentelemetry-bootstrap -a install

    Alternatively, run the opentelemetry-bootstrap tool to print the supported packages to the console, and add the output to your requirements.txt or pipfile:

    CODE 
    opentelemetry-bootstrap

  6. Run your Python application with the opentelemetry-instrument wrapper.

    BASH 
    opentelemetry-instrument python3 <application-name>.py

  7. (Optional) Send data directly to Splunk Observability Cloud.

    By default, the extension sends all telemetry to the local instance of the Splunk Distribution of OpenTelemetry Collector. To send data directly to Splunk Observability Cloud, set the SPLUNK_ACCESS_TOKEN and SPLUNK_REALM environment variables:

    BASH 
    export SPLUNK_ACCESS_TOKEN=<access-token>
export SPLUNK_REALM=<realm>

    To obtain a Splunk access token, see Retrieve and manage user API access tokens using Splunk Observability Cloud. To find your Splunk realm, see Configure SSO integrations for Splunk Observability Cloud. For more information on the ingest API endpoints, see Send APM traces.

  8. Set service metadata for your Python application.

    For descriptions of these environment variables, see Configure the Python agent for Splunk Observability Cloud:

    • OTEL_SERVICE_NAME
    • OTEL_RESOURCE_ATTRIBUTES

    Sample minimal configuration for a Kubernetes environment:

    BASH 
    export OTEL_SERVICE_NAME=<application-name>
export OTEL_RESOURCE_ATTRIBUTES="service.name=<application-name>,service.version=<version>"

  9. Look for security events in APM > Application Security after a few minutes.

Your Python application:

  • Sends vulnerability and library data to the Splunk Observability Cloud backend.

  • Collects potential attack events at runtime.

  • Reports data once at application startup and then every 24 hours thereafter.