Language Specific Agents (LSA)

Deepfactor is added to your application in a language agnostic manner. It collects telemetry from your running application and generates security insights. In order to enhance insights, we also provide programming language specific agents which can be injected when you run your application with Deepfactor. 

The LSA provides the following additional capabilities:

Language specific stack trace frame information

Deepfactor by default shows the native stack trace frames. LSA is used to collect interpreted language stack trace frames.

This capability is enabled by default. If you want to disable this functionality, you can perform the following steps.

1. dfctl run
   If you are running your application using Deepfactor command line utility (dfctl), then you can pass the option --disable-stack-traces (optional).
2. docker build
   If you are building Deepfactor enabled container images (to be used in container orchestration platforms), then you need to pass the following additional build arg
   --build-arg "DF_STACK_TRACES=disable"
3. Kubernetes admission webhook
   If you are using the K8s admission webhook, then you can set the following annotation to your podspec. Read more here.
   df.k8-app.stack-traces: disable
   
   If you would like to disable stack trace collection for the entire namespace, you can set the following option in the webhook config. Read more here.
   webhookconfig.namespaces[x].stackTraces: false

Method tracing

Deepfactor can keep track of all the methods invoked by your application at runtime and give you a consolidated list per dependency. This information will help you understand the extent of usage of your dependencies and help you prioritize which vulnerable dependencies to update/replace. 

Note: Since this operation intercepts every method invoked, it can add a non-trivial amount of overhead, particularly at startup depending upon the complexity of your application.

 This capability can be enabled for different deployment modes by using the following instructions

1. dfctl run
   If you are running your application using the Deepfactor command line utility (dfctl), then you can pass the option --enable-method-tracing.
   
   
2. docker build
   If you are building Deepfactor enabled container images (to be used in container orchestration platforms), then you need to pass the following additional build arg
   --build-arg "DF_METHOD_TRACING=enable"
   
   
3. Kubernetes admission webhook
   This capability can be enabled for the entire namespace by setting webhookconfig.namespaces[x].methodTracing to true. Read more here.
   This capability can also be enabled per pod by setting the annotation df.k8-app.method-tracing to true in your pod spec. Read more here.

Deepfactor automatically detects the programming language per process and injects the appropriate language specific agent. You can however override this behavior by

• Specifying the --build-arg "DF_LSA=<>" option for docker build
• Specifying webhookconfig.namespaces.lsa in the webhook config
• Specifying df.k8-app.lsa pod annotation

The possible values for the above option are

• java-nativeagent: Enable stack traces for java applications

• java-agent: Enables method tracing for java applications

• java: Enables both stack traces and method tracing for java applications

• python: Enables stack traces for python applications.

Note: In most cases, you do not need to specify the language or LSA options. There maybe some special cases where you may want to do that. For example, you only want to enable stack traces only for java applications in your namespace. In this case, you can specify webhookconfig.namespaces[x].lsa=java-nativeagent

LSA Internals

As of today, Deepfactor provides LSA modules for applications written in either Java or Python.

• Java Language Specific Agents
• Python Language Specific Agents

Java Language Specific Agents

Deepfactor provides the following two java language specific agents

1. Java Virtual Machine Tools (JVM TI) Library: This is a lightweight JVM TI library that is used to collect java stack traces. This stack trace information is shown for the alerts raised by Deepfactor. Stack traces can be helpful for developers to pinpoint where the issue is within their code.

JVMTI agent is automatically injected by default since stack traces are enabled by default.

Ex.

dfctl run -a "my application" -c "my component" --version "111" -v  --cmd /usr/bin/java -jar mycomponent.jar

2. Java Agent: This is a java agent which uses the Java Instrumentation API to gather runtime usage of dependencies. This information is shown under the usage section of the dependency. This information will help you understand the extent of usage of your dependencies and help you prioritize which vulnerable dependencies to update/replace.

If enabled, there will be a startup performance impact on your application comparable with other Java code coverage agents like JaCoCo. Please be aware that the Deepfactor java-agent incurs most performance degradation on startup, whereas JaCoCo incurs the overhead on the intercept of SIGINT to generate a report.

At this time, the Deepfactor java-agent does not support a Java application that includes:
- non-JDK, or custom, ClassLoader(s) that do not use the default system ClassLoader ClassPool
- bytecode transformation/instrumentation
- operation with other java-agents

This agent is automatically injected when you enable method tracing for your component. 

Ex: 

dfctl run -a "my application" -c "my component" --version "111" -v --enable-method-tracing --cmd /usr/bin/java -jar mycomponent.jar

Note: Since this agent intercepts every method invoked, it can add a non-trivial amount of overhead, particularly at startup depending upon the complexity of your application.

When method tracing is enabled, both agents are automatically enabled.

Ex: 

dfctl run -a "my application" -c "my component" --version "111" -v --enable-method-tracing --cmd /usr/bin/java -jar mycomponent.jar

Python Language Specific Agents

Deepfactor provides a Python language specific agent that can be used to provide stack trace information for many alerts displayed in the Deepfactor management portal. 

This agent is automatically injected when you enable stack traces.

Eg:

dfctl run -a "my application" -c "my component" --version "111" -v --cmd python3 myapp.py