Setup and Configure
Cette page n'est pas encore disponible en français, sa traduction est en cours.
Si vous avez des questions ou des retours sur notre projet de traduction actuel,
n'hésitez pas à nous contacter.
Compatibility
Supported Java versions
The Datadog library supports Java JRE 1.8 and higher of both Oracle JDK and OpenJDK, on the following architectures:
- Linux (GNU) x86, x86-64
- Alpine Linux (musl) x86, x86-64
- macOS (Darwin) x86, x86-64
- Windows (msvc) x86, x86-64
Datadog does not officially support any early-access versions of Java.
You can monitor application security for Java apps running in Docker, Kubernetes, AWS ECS, and AWS Fargate.
Supported frameworks
Framework Web Server | Minimum Framework Version |
---|
Servlet Compatible | 2.3+, 3.0+ |
Spring | 3.1 |
Note: Many application servers are Servlet compatible and are supported by ASM, such as WebSphere, WebLogic, and JBoss. Also, frameworks like Spring Boot are supported by virtue of using a supported embedded application server (such as Tomcat, Jetty, or Netty).
Supported .NET versions
The following .NET versions are supported:
- .NET Core 6
- .NET Core 5
- .NET Framework 4.8
- .NET Framework 4.7.2
- .NET Framework 4.7
- .NET Framework 4.6.2
- .NET Framework 4.6.1
These are supported on the following architectures:
- Linux (GNU) x86, x86-64
- Alpine Linux (musl) x86, x86-64
- macOS (Darwin) x86, x86-64
- Windows (msvc) x86, x86-64
You can monitor application security for .NET apps running in Docker, Kubernetes, AWS ECS, and AWS Fargate.
Supported frameworks
The .NET Tracer supports all .NET-based languages (for example, C#, F#, Visual Basic).
Framework Web Server | Minimum Framework Version |
---|
ASP.NET | 4.6 |
ASP.NET Core | 2.1 |
Supported Go versions
The Datadog Go tracing library supports Go version 1.14 and greater, on the following architectures:
- Linux (GNU) x86-64
- Alpine Linux (musl) x86-64
- macOS (Darwin) x86-64
You can monitor application security for Go apps running in Docker, Kubernetes, and AWS ECS.
Supported frameworks
Integrate the Go tracer with the following list of web frameworks using one of the corresponding APM tracer integration. Click to see the integrations documentation, which provides a detailed overview of the supported packages and their APIs, along with usage examples.
Enabling CGO
Compiling your code with ASM enabled involves CGO and therefore requires:
- The
gcc
compiler for the target GOOS
and GOARCH
. - The C library headers.
- The CGO bindings enabled. This is controlled by the
CGO_ENABLED
environment variable which is enabled by default when compiling natively.
To install the above requirements:
Operating system | Console command |
---|
Debian, Ubuntu | $ apt install gcc libc6-dev |
Alpine | $ apk add gcc musl-dev |
RHEL, CentOS, Fedora | $ yum install gcc glibc-devel |
macOS | $ xcode-select --install |
Note: The Go toolchain disables CGO when cross-compiling and so, CGO needs to be explicitly enabled.
Supported Ruby versions
The Datadog Ruby library supports the latest gem for the following Ruby interpreters:
These are supported on the following architectures:
- Linux (GNU) x86-64, aarch64
- Alpine Linux (musl) x86-64, aarch64
- macOS (Darwin) x86-64, arm64
You can monitor application security for Ruby apps running in Docker, Kubernetes, AWS ECS, and AWS Fargate.
Supported frameworks
Framework Web Server | Minimum Framework Version |
---|
Rack | 1.1 |
Rails | 3.2 (also depends on Ruby version) |
Sinatra | 1.4 |
The Datadog PHP library supports PHP version 7.0 and above on the following architectures:
- Linux (GNU) x86-64
- Alpine Linux (musl) x86-64
You can monitor application security for PHP apps running in Docker, Kubernetes, and AWS ECS.
It supports the use of all PHP frameworks, and also the use no framework.
Supported NodeJS versions
The Datadog NodeJS library supports the following NodeJS versions:
- NodeJS 13.10.0 and higher
- NodeJS 12.17.0 and higher
These are supported on the following architectures:
- Linux (GNU) x86-64
- Alpine Linux (musl) x86-64
- macOS (Darwin) x86-64
- Windows (msvc) x86, x86-64
You can monitor application security for NodeJS apps running in Docker, Kubernetes, AWS ECS, and AWS Fargate.
Supported frameworks
Framework Web Server | Minimum Framework Version |
---|
Express | 4.0 |
Instrument your services with the standardized user tags to track authenticated user activity, whether you’re tracking application performance or application security.
This way, you can identify bad actors that are generating suspicious security activity, review all their activity around this time frame, and prioritize handling the most advanced attacks and signals targeting your authenticated attack surface.
You can add custom tags to your root span, or use the instrumentation functions described below.
Use the the Java tracer’s API for adding custom tags to a root span and add user information so that you can monitor authenticated requests in the application.
User monitoring tags are applied on the root span and start with the prefix usr
followed by the name of the field. For example, usr.name
is a user monitoring tag that tracks the user’s name.
Note: Check that you have added necessary dependencies to your application.
The example below shows how to obtain the root span and add the relevant user monitoring tags:
// Get the active span
final Span span = GlobalTracer.get().activeSpan();
if ((span instanceof MutableSpan)) {
MutableSpan localRootSpan = ((MutableSpan) span).getLocalRootSpan();
// Setting the mandatory user id tag
localRootSpan.setTag("usr.id", "d131dd02c56eec4");
// Setting optional user monitoring tags
localRootSpan.setTag("usr.name", "Jean Example");
localRootSpan.setTag("usr.email", "jean.example@example.com");
localRootSpan.setTag("usr.session_id", "987654321");
localRootSpan.setTag("usr.role", "admin");
localRootSpan.setTag("usr.scope", "read:message, write:files");
}
The .NET tracer package provides the SetUser()
function, which allows you to monitor authenticated requests by adding user information to the trace.
The example below shows how to add the relevant user monitoring tags:
using Datadog.Trace;
// ...
var userDetails = new UserDetails()
{
// the systems internal identifier for the users
Id = "d41452f2-483d-4082-8728-171a3570e930",
// the email address of the user
Email = "test@adventure-works.com",
// the user's name, as displayed by the system
Name = "Jane Doh",
// the user's session id
SessionId = "d0632156-132b-4baa-95b2-a492c5f9cb16",
// the role the user is making the request under
Role = "standard",
};
Tracer.Instance.ActiveScope?.Span.SetUser(userDetails);
For information and options, read the .NET tracer documentation.
The Go tracer package provides the SetUser()
function, which allows you to monitor authenticated requests by adding user information to the trace. For more options, see the Go tracer documentation.
This example shows how to retrieve the current tracer span and use it to set user monitoring tags:
// Retrieve the current tracer span from an HTTP request's context
if span, ok := tracer.SpanFromContext(request.Context()); ok {
// Record user information in the trace the span belongs to
tracer.SetUser(span, usr.id, tracer.WithUserEmail(usr.email), tracer.WithUserName(usr.name))
Use one of the following APIs to add user information to a trace so that you can monitor authenticated requests in the application:
Starting with ddtrace
1.1.0, the Datadog::Kit::Identity.set_user
method is available. This is the recommended API for adding user information to traces:
# Get the active trace
trace = Datadog::Tracing.active_trace
# Set mandatory user id tag
Datadog::Kit::Identity.set_user(trace, id: 'd131dd02c56eeec4')
# Or set any of these optional user monitoring tags
Datadog::Kit::Identity.set_user(
trace,
# mandatory id
id: 'd131dd02c56eeec4',
# optional tags with known semantics
name: 'Jean Example',
email:, 'jean.example@example.com',
session_id:, '987654321',
role: 'admin',
scope: 'read:message, write:files',
# optional free-form tags
another_tag: 'another_value',
)
If Datadog::Kit::Identity.set_user
does not meet your needs, you can use set_tag
instead.
User monitoring tags are applied on the trace and start with the prefix usr.
followed by the name of the field. For example, usr.name
is a user monitoring tag that tracks the user’s name.
The example below shows how to obtain the active trace and add relevant user monitoring tags:
Notes:
- Tag values must be strings.
- The
usr.id
tag is mandatory.
# Get the active trace
trace = Datadog::Tracing.active_trace
# Set mandatory user id tag
trace.set_tag('usr.id', 'd131dd02c56eeec4')
# Set optional user monitoring tags with known sematics
trace.set_tag('usr.name', 'Jean Example')
trace.set_tag('usr.email', 'jean.example@example.com')
trace.set_tag('usr.session_id', '987654321')
trace.set_tag('usr.role', 'admin')
trace.set_tag('usr.scope', 'read:message, write:files')
# Set free-form tags:
trace.set_tag('usr.another_tag', 'another_value')
Use the the PHP tracer’s API for adding custom tags to a root span, and add user information so that you can monitor authenticated requests in the application.
User monitoring tags are applied to the meta
section of the root span and start with the prefix usr
followed by the name of the field. For example, usr.name
is a user monitoring tag that tracks the user’s name.
The example below shows how to obtain the root span and add the relevant user monitoring tags:
<?php
$rootSpan = \DDTrace\root_span();
// Required unique identifier of the user.
$rootSpan->meta['usr.id'] = ‘123456789’;
// All other fields are optional.
$rootSpan->meta['usr.name'] = ‘Jean Example’;
$rootSpan->meta['usr.email'] = ‘jean.example@example.com’;
$rootSpan->meta['usr.session_id'] = ‘987654321’;
$rootSpan->meta['usr.role'] = ‘admin’;
$rootSpan->meta['usr.scope'] = ‘read:message, write:files’;
?>
The Node tracer package provides the tracer.setUser(user)
function, which allows you to monitor authenticated requests by adding user information to the trace.
The example below shows how to add relevant user monitoring tags:
const tracer = require('dd-trace').init()
function handle () {
tracer.setUser({
id: '123456789', // *REQUIRED* Unique identifier of the user.
// All other fields are optional.
email: 'jane.doe@example.com', // Email of the user.
name: 'Jane Doe', // User-friendly name of the user.
session_id: '987654321', // Session ID of the user.
role: 'admin', // Role the user is making the request under.
scope: 'read:message, write:files', // Scopes or granted authorizations the user currently possesses.
// Arbitrary fields are also accepted to attach custom data to the user (RBAC, Oauth, etc…)
custom_tag: 'custom data'
})
}
For information and options, read the NodeJS tracer documentation.
Data security considerations
The data that you collect with Datadog can contain sensitive information that you want to filter out, obfuscate, scrub, filter, modify, or just not collect. Additionally, it may contain synthetic traffic that might cause your threat detection be inaccurate, or cause Datadog to not accurately indicate the security of your services.
By default, ASM collects information from suspicious requests to help you understand why the request was flagged as suspicious. Before sending the data, ASM scans it for patterns and keywords that indicate that the data is sensitive. If the data is deemed sensitive, it is replaced with a <redacted>
flag, so you observe that although the request was suspicious, the request data could not be collected because of data security concerns.
To protect users’ data, sensitive data scanning is activated by default in ASM. You can customize the configuration by using the following environment variables. The scanning is based on the RE2 syntax, so to customize scanning, set the value of these environment variables to a valid RE2 pattern:
DD_APPSEC_OBFUSCATION_PARAMETER_KEY_REGEXP
- Pattern for scanning for keys whose values commonly contain sensitive data. If found, the values and any child nodes associated with the key are redacted.DD_APPSEC_OBFUSCATION_PARAMETER_VALUE_REGEXP
- Pattern for scanning for values that could indicate sensitive data. If found, the value and all its child nodes are redacted.
For Ruby only, starting in ddtrace
version 1.1.0You can also configure scanning patterns in code:
Datadog.configure do |c|
# ...
# Set custom RE2 regexes
c.appsec.obfuscator_key_regex = '...'
c.appsec.obfuscator_value_regex = '...'
end
The following are examples of data that are flagged as sensitive by default:
pwd
, password
, ipassword
, pass_phrase
secret
key
, api_key
, private_key
, public_key
token
consumer_id
, consumer_key
, consumer_secret
sign
, signed
, signature
bearer
authorization
BEGIN PRIVATE KEY
ssh-rsa
See APM Data Security for information about other mechanisms in the Datadog Agent and libraries that can also be used to remove sensitive data.
Exclusion filters
There may be a time when an ASM signal, or a suspicious request, is a false positive. For example, ASM repeatedly detects
the same suspicious request and a signal is generated, but the signal has been reviewed and is not a threat.
You can set an exclusion filter, which ignore events from a rule, to eliminate these noisy signal patterns and focus on legitimate suspicious requests.
To create an exclusion filter, do one of the following:
- Click on a signal in ASM Signals and click the Create Exclusion Filter button in the top left corner. This method automatically generates a filter query for the targeted service.
- Navigate to Exclusion Filters Configuration and manually configure a new exclusion filter based on your own filter query.
Note: Requests (traces) matching an exclusion filter are not billed.
Disabling Application Security Monitoring
To disable ASM, remove the DD_APPSEC_ENABLED=true
environment variable from your application configuration. Once it’s removed, restart your service.
If you need additional help, contact Datadog support.
Further Reading
Documentation, liens et articles supplémentaires utiles: