Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update docs for AppSec on Ruby 1.1.0 #13941

Merged
merged 3 commits into from
May 26, 2022
Merged

Update docs for AppSec on Ruby 1.1.0 #13941

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f9c1273
Update docs for AppSec on Ruby 1.1.0
lloeki May 5, 2022
379573c
Update content/en/security_platform/application_security/getting_star…
lloeki May 6, 2022
e68c7df
fix breaking build, edit pass
kayayarai May 6, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 50 additions & 13 deletions content/en/security_platform/application_security/getting_started/ruby.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ further_reading:
text: "Troubleshooting Application Security Monitoring"
---

You can monitor application security for Ruby apps running in Docker, Kubernetes, AWS ECS, and AWS Fargate.
You can monitor application security for Ruby apps running in Docker, Kubernetes, AWS ECS, and AWS Fargate.

{{% appsec-getstarted %}}

Expand All @@ -25,61 +25,97 @@ You can monitor application security for Ruby apps running in Docker, Kubernetes
1. **Update your Gemfile to include the Datadog library**:

```ruby
gem 'ddtrace', '~> 1.0'
gem 'ddtrace', '~> 1.1'
```

For information about which language and framework versions are supported by the library, see [Compatibility][1].

For more information about upgrading from a `dd-trace` 0.x version, see [the Ruby tracer upgrade guide][2].

2. **Enable ASM**, either in your code:

Note: ASM currently requires the APM tracer to be enabled; a quick setup covering the most common cases is described below, see [the Ruby tracer documentation][3] for more details.

{{< tabs >}}

{{% tab "Rails" %}}
Either enable the tracer through auto-instrumentation by updating your Gemfile:
Enable the APM tracer manually by adding an initializer in your application code:
lloeki marked this conversation as resolved.
Show resolved Hide resolved

```ruby
# config/initializers/datadog.rb

require 'datadog/appsec'

Datadog.configure do |c|
# enable the APM tracer
c.tracing.instrument :rails

# enable ASM
c.appsec.enabled = true
c.appsec.instrument :rails
end
```

Or enable the APM tracer through auto-instrumentation by updating your Gemfile to auto-instrument:

```ruby
gem 'ddtrace', '~> 1.0', require: 'ddtrace/auto_instrument'
gem 'ddtrace', '~> 1.1', require: 'ddtrace/auto_instrument'
```

Or enable the tracer by adding an initializer in your application code:
And also enable AppSec:

```ruby
# config/initializers/datadog.rb

require 'datadog/appsec'

Datadog.configure do |c|
# enable the APM tracer
# not needed if `gem 'ddtrace', require: 'ddtrace/auto_instrument' is used
c.tracing.instrument :rails
# the APM tracer is enabled by auto-instrumentation

# enable ASM
c.appsec.enabled = true
c.appsec.instrument :rails
end
```

{{% /tab %}}

{{% tab "Sinatra" %}}
Enable the tracer by adding the following to your application's startup:
Enable the APM tracer by adding the following to your application's startup:

```ruby
require 'sinatra'
require 'ddtrace'
require 'datadog/appsec'

Datadog.configure do |c|
# enable the APM tracer
c.tracing.instrument :sinatra

# enable appsec for Sinatra
# enable ASM for Sinatra
c.appsec.enabled = true
c.appsec.instrument :sinatra
end
```

Or enable the APM tracer through auto-instrumentation:

```ruby
require 'sinatra'
require 'ddtrace/auto_instrument'

Datadog.configure do |c|
# the APM tracer is enabled by auto-instrumentation

# enable ASM for Sinatra
c.appsec.enabled = true
c.appsec.instrument :sinatra
end
```
{{% /tab %}}

{{% tab "Rack" %}}
Enable the tracer by adding the following to your `config.ru` file:
Enable the APM tracer by adding the following to your `config.ru` file:

```ruby
require 'ddtrace'
Expand All @@ -89,7 +125,7 @@ You can monitor application security for Ruby apps running in Docker, Kubernetes
# enable the APM tracer
c.tracing.instrument :rack

# enable appsec for Rack
# enable ASM for Rack
c.appsec.enabled = true
c.appsec.instrument :rack
end
Expand Down Expand Up @@ -141,7 +177,7 @@ spec:
{{% /tab %}}
{{% tab "AWS ECS" %}}

Update your ECS task definition JSON file, by adding this in the environment section:
Update your ECS task definition JSON file, by adding this in the environment section:

```json
"environment": [
Expand Down Expand Up @@ -175,3 +211,4 @@ env DD_APPSEC_ENABLED=true rails server

[1]: /security_platform/application_security/setup_and_configure/?code-lang=ruby#compatibility
[2]: https://github.com/DataDog/dd-trace-rb/blob/master/docs/UpgradeGuide.md#from-0x-to-10
[3]: /tracing/setup_overview/setup/ruby/
80 changes: 75 additions & 5 deletions content/en/security_platform/application_security/setup_and_configure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -292,11 +292,51 @@ if span, ok := tracer.SpanFromContext(request.Context()); ok {

{{< programming-lang lang="ruby" >}}

Use either API to add user information to a trace so that you can monitor authenticated requests in the application.

{{< tabs >}}

{{% tab "Using `Datadog::Kit::Identity.set_user` %}}

Starting with `ddtrace` 1.1.0, a convenience `set_user` method is available:

```ruby
# Get the active trace
trace = Datadog::Tracing.active_trace

# Set mandatory user id tag
Datadog::Kit::Identity.set_user(trace, id: 'd131dd02c56eeec4')
lloeki marked this conversation as resolved.
Show resolved Hide resolved

# 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:, '[email protected]',
session_id:, '987654321',
role: 'admin',
scope: 'read:message, write:files',

# optional free-form tags
another_tag: 'another_value',
)
```

{{% /tab %}}

{{% tab "Using trace `set_tag`" %}}
lloeki marked this conversation as resolved.
Show resolved Hide resolved

Note: `Datadog::Kit::Identity.set_user` is the recommended way to set user information.

Use the the Ruby tracer's API for adding custom tags to a trace, and add user information so that you can monitor authenticated requests in the application.

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.
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 root span and add relevant user monitoring tags:
The example below shows how to obtain the active trace and add relevant user monitoring tags:

**Notes**:
- Tag values must be strings.
Expand All @@ -309,14 +349,21 @@ trace = Datadog::Tracing.active_trace
# Set mandatory user id tag
trace.set_tag('usr.id', 'd131dd02c56eeec4')

# Set optional user monitoring tags
# Set optional user monitoring tags with known sematics
trace.set_tag('usr.name', 'Jean Example')
trace.set_tag('usr.email', '[email protected]')
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')
```

{{% /tab %}}

{{< /tabs >}}

{{< /programming-lang >}}

{{< programming-lang lang="php" >}}
Expand Down Expand Up @@ -386,11 +433,34 @@ The data that you collect with Datadog can contain sensitive information that yo

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][2], so to customize scanning, set the value of these environment variables to a valid RE2 patten:
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][2], 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 key, all corresponding values, and any child nodes are redacted.
* `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.

{{< programming-lang-wrapper langs="ruby" >}}

{{< programming-lang lang="ruby" >}}

It is also possible to configure these patterns from code:

```ruby
Datadog.configure do |c|
# ...

# Set custom RE2 regexes
c.appsec.obfuscator_key_regex = '...'
c.appsec.obfuscator_value_regex = '...'
end
```

Note: this feature is available starting with `ddtrace` 1.1.0.

{{< /programming-lang >}}

{{< /programming-lang-wrapper >}}


The following are examples of data that are flagged as sensitive by default:

* `pwd`, `password`, `ipassword`, `pass_phrase`
Expand Down