[AppSec] Api to allow user data to be associated with the local root span (DataDog#2546)

robertpi · web-flow · commit b292273f3415 · 2022-04-11T17:51:29.000+02:00
This PR adds a convenient method to the tracer to link an actor to a trace. You have to pass a UserDetails object with at least its Id property set to a non-null value.

To correlate users to web requests, you would need to use the following code snippet within each web request, after user authorization has been performed:

```csharp
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);
```
diff --git a/docs/Datadog.Trace/README.md b/docs/Datadog.Trace/README.md
@@ -277,6 +277,35 @@ Note: Call-target instrumentation does not support instrumenting custom implemen
 
 The `integrations.json` file is no longer required for instrumentation. You can remove references to this file, for example by deleting the `DD_INTEGRATIONS` environment variable.
 
+### User Identification
+
+The tracer provides a convenient method to link an actor to a trace. You have to pass a `UserDetails` object with at least its Id property set to a non-null value.
+
+To correlate users to web requests, you would need to use the following code snippet within each web request, after user authorization has been performed:
+
+```csharp
+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);
+
+```
+
 ## Get in touch
 
 If you have questions, feedback, or feature requests, reach our [support](https://docs.datadoghq.com/help).
+
diff --git a/tracer/src/Datadog.Trace/SpanExtensions.cs b/tracer/src/Datadog.Trace/SpanExtensions.cs
@@ -0,0 +1,69 @@
+// <copyright file="SpanExtensions.cs" company="Datadog">
+// Unless explicitly stated otherwise all files in this repository are licensed under the Apache 2 License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2017 Datadog, Inc.
+// </copyright>
+
+using Datadog.Trace.Util;
+
+namespace Datadog.Trace
+{
+    /// <summary>
+    /// Extension methods for the <see cref="ISpan"/> interface
+    /// </summary>
+    public static class SpanExtensions
+    {
+        /// <summary>
+        /// Sets the details of the user on the local root span
+        /// </summary>
+        /// <param name="span">The span to be tagged</param>
+        /// <param name="userDetails">The details of the current logged on user</param>
+        public static void SetUser(this ISpan span, UserDetails userDetails)
+        {
+            if (span is null)
+            {
+                ThrowHelper.ThrowArgumentNullException(nameof(span));
+            }
+
+            if (userDetails is null)
+            {
+                ThrowHelper.ThrowArgumentNullException(nameof(userDetails));
+            }
+
+            if (userDetails.Id is null)
+            {
+                ThrowHelper.ThrowArgumentException(nameof(userDetails) + ".Id must be set to a value other than null", nameof(userDetails));
+            }
+
+            var localRootSpan = span;
+            if (span is Span spanClass)
+            {
+                localRootSpan = spanClass.Context.TraceContext?.RootSpan ?? span;
+            }
+
+            if (userDetails.Id is not null)
+            {
+                localRootSpan.SetTag(Tags.User.Id, userDetails.Id);
+            }
+
+            if (userDetails.Email is not null)
+            {
+                localRootSpan.SetTag(Tags.User.Email, userDetails.Email);
+            }
+
+            if (userDetails.Name is not null)
+            {
+                localRootSpan.SetTag(Tags.User.Name, userDetails.Name);
+            }
+
+            if (userDetails.SessionId is not null)
+            {
+                localRootSpan.SetTag(Tags.User.SessionId, userDetails.SessionId);
+            }
+
+            if (userDetails.Role is not null)
+            {
+                localRootSpan.SetTag(Tags.User.Role, userDetails.Role);
+            }
+        }
+    }
+}
diff --git a/tracer/src/Datadog.Trace/Tags.cs b/tracer/src/Datadog.Trace/Tags.cs
@@ -478,5 +478,14 @@ public static class Tags
         internal const string GrpcMethodService = "grpc.method.service";
         internal const string GrpcMethodName = "grpc.method.name";
         internal const string GrpcStatusCode = "grpc.status.code";
+
+        internal static class User
+        {
+            internal const string Email = "usr.email";
+            internal const string Name = "usr.name";
+            internal const string Id = "usr.id";
+            internal const string SessionId = "usr.session_id";
+            internal const string Role = "usr.role";
+        }
     }
 }
diff --git a/tracer/src/Datadog.Trace/UserDetails.cs b/tracer/src/Datadog.Trace/UserDetails.cs
@@ -0,0 +1,38 @@
+// <copyright file="UserDetails.cs" company="Datadog">
+// Unless explicitly stated otherwise all files in this repository are licensed under the Apache 2 License.
+// This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2017 Datadog, Inc.
+// </copyright>
+
+namespace Datadog.Trace
+{
+    /// <summary>
+    /// A data container class for the users details
+    /// </summary>
+    public class UserDetails
+    {
+        /// <summary>
+        /// Gets or sets the user's email address
+        /// </summary>
+        public string Email { get; set; }
+
+        /// <summary>
+        /// Gets or sets the user's name as displayed in the UI
+        /// </summary>
+        public string Name { get; set; }
+
+        /// <summary>
+        /// Gets or sets the unique identifier assoicated with the users
+        /// </summary>
+        public string Id { get; set; }
+
+        /// <summary>
+        /// Gets or sets the user's session unique identifier
+        /// </summary>
+        public string SessionId { get; set; }
+
+        /// <summary>
+        /// Gets or sets the role associated with the user
+        /// </summary>
+        public string Role { get; set; }
+    }
+}
diff --git a/tracer/test/Datadog.Trace.Tests/Snapshots/PublicApiTests.PublicApiHasNotChanged.verified.txt b/tracer/test/Datadog.Trace.Tests/Snapshots/PublicApiTests.PublicApiHasNotChanged.verified.txt
@@ -250,6 +250,10 @@ namespace Datadog.Trace
         public Datadog.Trace.ISpanContext Parent { get; set; }
         public System.DateTimeOffset? StartTime { get; set; }
     }
+    public static class SpanExtensions
+    {
+        public static void SetUser(this Datadog.Trace.ISpan span, Datadog.Trace.UserDetails userDetails) { }
+    }
     public static class SpanKinds
     {
         public const string Client = "client";
@@ -315,6 +319,15 @@ namespace Datadog.Trace
         public Datadog.Trace.IScope StartActive(string operationName, Datadog.Trace.SpanCreationSettings settings) { }
         public static void Configure(Datadog.Trace.Configuration.TracerSettings settings) { }
     }
+    public class UserDetails
+    {
+        public UserDetails() { }
+        public string Email { get; set; }
+        public string Id { get; set; }
+        public string Name { get; set; }
+        public string Role { get; set; }
+        public string SessionId { get; set; }
+    }
 }
 namespace Datadog.Trace.ExtensionMethods
 {
diff --git a/tracer/test/Datadog.Trace.Tests/TracerTests.cs b/tracer/test/Datadog.Trace.Tests/TracerTests.cs
@@ -4,6 +4,7 @@
 // </copyright>
 
 using System;
+using System.Collections.Generic;
 using System.Linq;
 using System.Net;
 using System.Threading.Tasks;
@@ -524,5 +525,175 @@ public async Task ForceFlush()
 
             agent.Verify(a => a.FlushTracesAsync(), Times.Once);
         }
+
+        [Fact]
+        public void SetUserOnRootSpanDirectly()
+        {
+            var scopeManager = new AsyncLocalScopeManager();
+
+            var settings = new TracerSettings
+            {
+                StartupDiagnosticLogEnabled = false
+            };
+            var tracer = new Tracer(settings, Mock.Of<IAgentWriter>(), Mock.Of<ISampler>(), scopeManager, Mock.Of<IDogStatsd>());
+
+            var rootTestScope = tracer.StartActive("test.trace");
+            var childTestScope = tracer.StartActive("test.trace.child");
+            childTestScope.Dispose();
+
+            var email = "test@adventure-works.com";
+            var name = "Jane Doh";
+            var id = Guid.NewGuid().ToString();
+            var sessionId = Guid.NewGuid().ToString();
+            var role = "admin";
+
+            var userDetails = new UserDetails()
+            {
+                Email = email,
+                Name = name,
+                Id = id,
+                SessionId = sessionId,
+                Role = role,
+            };
+            tracer.ActiveScope?.Span.SetUser(userDetails);
+
+            Assert.Equal(email, rootTestScope.Span.GetTag(Tags.User.Email));
+            Assert.Equal(name, rootTestScope.Span.GetTag(Tags.User.Name));
+            Assert.Equal(id, rootTestScope.Span.GetTag(Tags.User.Id));
+            Assert.Equal(sessionId, rootTestScope.Span.GetTag(Tags.User.SessionId));
+            Assert.Equal(role, rootTestScope.Span.GetTag(Tags.User.Role));
+        }
+
+        [Fact]
+        public void SetUserOnChildChildSpan_ShouldAttachToRoot()
+        {
+            var scopeManager = new AsyncLocalScopeManager();
+
+            var settings = new TracerSettings
+            {
+                StartupDiagnosticLogEnabled = false
+            };
+            var tracer = new Tracer(settings, Mock.Of<IAgentWriter>(), Mock.Of<ISampler>(), scopeManager, Mock.Of<IDogStatsd>());
+
+            var rootTestScope = tracer.StartActive("test.trace");
+            var childTestScope = tracer.StartActive("test.trace.child");
+
+            var email = "test@adventure-works.com";
+            var name = "Jane Doh";
+            var id = Guid.NewGuid().ToString();
+            var sessionId = Guid.NewGuid().ToString();
+            var role = "admin";
+
+            var userDetails = new UserDetails()
+            {
+                Email = email,
+                Name = name,
+                Id = id,
+                SessionId = sessionId,
+                Role = role,
+            };
+            tracer.ActiveScope?.Span.SetUser(userDetails);
+
+            childTestScope.Dispose();
+
+            Assert.Equal(email, rootTestScope.Span.GetTag(Tags.User.Email));
+            Assert.Equal(name, rootTestScope.Span.GetTag(Tags.User.Name));
+            Assert.Equal(id, rootTestScope.Span.GetTag(Tags.User.Id));
+            Assert.Equal(sessionId, rootTestScope.Span.GetTag(Tags.User.SessionId));
+            Assert.Equal(role, rootTestScope.Span.GetTag(Tags.User.Role));
+        }
+
+        [Fact]
+        public void SetUser_ShouldWorkOnAnythingImplementingISpan()
+        {
+            var testSpan = new SpanStub();
+
+            var email = "test@adventure-works.com";
+            var name = "Jane Doh";
+            var id = Guid.NewGuid().ToString();
+            var sessionId = Guid.NewGuid().ToString();
+            var role = "admin";
+
+            var userDetails = new UserDetails()
+            {
+                Email = email,
+                Name = name,
+                Id = id,
+                SessionId = sessionId,
+                Role = role,
+            };
+            testSpan.SetUser(userDetails);
+
+            Assert.Equal(email, testSpan.GetTag(Tags.User.Email));
+            Assert.Equal(name, testSpan.GetTag(Tags.User.Name));
+            Assert.Equal(id, testSpan.GetTag(Tags.User.Id));
+            Assert.Equal(sessionId, testSpan.GetTag(Tags.User.SessionId));
+            Assert.Equal(role, testSpan.GetTag(Tags.User.Role));
+        }
+
+        [Fact]
+        public void SetUser_ShouldThrowAnExceptionIfNoIdIsProvided()
+        {
+            var testSpan = new SpanStub();
+
+            var email = "test@adventure-works.com";
+
+            var userDetails = new UserDetails()
+            {
+                Email = email,
+            };
+
+            Assert.ThrowsAny<ArgumentException>(() =>
+                testSpan.SetUser(userDetails));
+        }
+
+        private class SpanStub : ISpan
+        {
+            private Dictionary<string, string> _tags = new Dictionary<string, string>();
+
+            public string OperationName { get; set; }
+
+            public string ResourceName { get; set; }
+
+            public string Type { get; set; }
+
+            public bool Error { get; set; }
+
+            public string ServiceName { get; set; }
+
+            public ulong TraceId => 1ul;
+
+            public ulong SpanId => 1ul;
+
+            public ISpanContext Context => null;
+
+            public void Dispose()
+            {
+            }
+
+            public void Finish()
+            {
+            }
+
+            public void Finish(DateTimeOffset finishTimestamp)
+            {
+            }
+
+            public string GetTag(string key)
+            {
+                _tags.TryGetValue(key, out var value);
+                return value;
+            }
+
+            public void SetException(Exception exception)
+            {
+            }
+
+            public ISpan SetTag(string key, string value)
+            {
+                _tags[key] = value;
+                return this;
+            }
+        }
     }
 }

Original file line number	Diff line number	Diff line change
`@@ -250,6 +250,10 @@ namespace Datadog.Trace`
`250`	`250`	`public Datadog.Trace.ISpanContext Parent { get; set; }`
`251`	`251`	`public System.DateTimeOffset? StartTime { get; set; }`
`252`	`252`	`}`
	`253`	`+ public static class SpanExtensions`
	`254`	`+ {`
	`255`	`+ public static void SetUser(this Datadog.Trace.ISpan span, Datadog.Trace.UserDetails userDetails) { }`
	`256`	`+ }`
`253`	`257`	`public static class SpanKinds`
`254`	`258`	`{`
`255`	`259`	`public const string Client = "client";`
`@@ -315,6 +319,15 @@ namespace Datadog.Trace`
`315`	`319`	`public Datadog.Trace.IScope StartActive(string operationName, Datadog.Trace.SpanCreationSettings settings) { }`
`316`	`320`	`public static void Configure(Datadog.Trace.Configuration.TracerSettings settings) { }`
`317`	`321`	`}`
	`322`	`+ public class UserDetails`
	`323`	`+ {`
	`324`	`+ public UserDetails() { }`
	`325`	`+ public string Email { get; set; }`
	`326`	`+ public string Id { get; set; }`
	`327`	`+ public string Name { get; set; }`
	`328`	`+ public string Role { get; set; }`
	`329`	`+ public string SessionId { get; set; }`
	`330`	`+ }`
`318`	`331`	`}`
`319`	`332`	`namespace Datadog.Trace.ExtensionMethods`
`320`	`333`	`{`