docs: docs :3

DisCatSharp.Docs/articles/misc/sentry.md

@@ -0,0 +1,189 @@
+---
+uid: misc_sentry
+title: Sentry
+author: DisCatSharp Team
+---
+
+# Sentry Integration in DisCatSharp
+
+## Overview
+
+Sentry is an error tracking tool that helps developers monitor and fix crashes in real-time. In DisCatSharp, Sentry integration is utilized to report and analyze errors and missing fields, ensuring a more robust and reliable library.
+
+## How Sentry is Used in DisCatSharp
+
+The Sentry integration in DisCatSharp is configured to capture and report exceptions, missing fields, and other critical information. This data helps developers identify and fix issues promptly. The integration is controlled by several configuration options within the `DiscordConfiguration` class.
+
+## Configuration Options
+
+The following configuration options are available for Sentry integration, and they are all **disabled** or set to **null** by default:
+
+- **ReportMissingFields**: Determines whether to report missing fields for Discord objects. This is useful for library development.
+  ```csharp
+  public bool ReportMissingFields { internal get; set; } = false;
+  ```
+
+- **EnableSentry**: Enables the Sentry integration.
+  ```csharp
+  public bool EnableSentry { internal get; set; } = false;
+  ```
+
+- **AttachUserInfo**: If enabled, attaches the bot's username and ID to Sentry reports to help pinpoint problems.
+  ```csharp
+  public bool AttachUserInfo { internal get; set; } = false;
+  ```
+
+- **FeedbackEmail**: An email address that can be used to reach out when the bot encounters library bugs. It is only transmitted if `AttachUserInfo` is enabled.
+  ```csharp
+  public string? FeedbackEmail { internal get; set; } = null;
+  ```
+
+- **DeveloperUserId**: The Discord user ID for contacting the developer when the bot encounters library bugs. It is only transmitted if `AttachUserInfo` is enabled.
+  ```csharp
+  public ulong? DeveloperUserId { internal get; set; } = null;
+  ```
+
+- **TrackExceptions**: Specifies which exceptions to track with Sentry. This setting is internal and should only be modified by library developers.
+  ```csharp
+  internal List<Type> TrackExceptions { get; set; } = [typeof(ServerErrorException), typeof(BadRequestException)];
+  ```
+
+- **EnableLibraryDeveloperMode**: Enables developer mode for the library. This is intended for internal use.
+  ```csharp
+  internal bool EnableLibraryDeveloperMode { get; set; } = false;
+  ```
+
+- **SentryDebug**: Enables Sentry's debug mode for additional logging.
+  ```csharp
+  internal bool SentryDebug { get; set; } = false;
+  ```
+
+- **DisableExceptionFilter**: Disables the exception filter.
+  ```csharp
+  internal bool DisableExceptionFilter { get; set; } = false;
+  ```
+
+- **CustomSentryDsn**: Custom Sentry DSN for configuring the Sentry client.
+  ```csharp
+  internal string? CustomSentryDsn { get; set; } = null;
+  ```
+
+All internal fields can only be modified if whitelisted and only locally.
+
+## Data Transmitted to Sentry
+
+When an error or missing field is detected, the following data is transmitted to Sentry:
+
+1. **Event Metadata**: Includes SDK information, event ID, and timestamps.
+   ```json
+   {
+      "sdk": {
+         "name": "sentry.dotnet",
+         "version": "4.5.0"
+      },
+      "event_id": "d9d303e3d75d400e992e1b1d7aef6641",
+      "timestamp": "2024-05-16T19:58:31.6006568+00:00"
+   }
+   ```
+
+2. **Exception Details**: Information about the exception, including the type, value, module, and stack trace.
+   ```json
+   {
+      "exception": {
+         "values": [
+            {
+               "type": "DisCatSharp.Exceptions.BadRequestException",
+               "value": "Bad request: BadRequest",
+               "module": "DisCatSharp, Version=10.6.3.0, Culture=neutral, PublicKeyToken=null",
+               "stacktrace": {
+                  "frames": [
+                     {
+                        "filename": "Entities\\Command.cs",
+                        "function": "async Task<CommandResult> Command.ExecuteAsync(CommandContext ctx)",
+                        "lineno": 100
+                     }
+                  ]
+               }
+            }
+         ]
+      }
+   }
+   ```
+
+3. **Breadcrumbs**: Log entries leading up to the error, providing context for the issue.
+   ```json
+   {
+      "breadcrumbs": [
+         {
+            "timestamp": "2024-05-16T19:58:09.814Z",
+            "message": "Release notes disabled by config",
+            "category": "DisCatSharp.BaseDiscordClient"
+         }
+      ]
+   }
+   ```
+
+4. **User Information**: If `AttachUserInfo` is enabled, the bot's username, ID, and developer contact details.
+   ```json
+   {
+      "user": {
+         "id": "822242444070092860",
+         "username": "nyuw#7780",
+         "ip_address": "{{auto}}",
+         "other": {
+            "developer": "856780995629154305",
+            "email": "[email protected]"
+         }
+      }
+   }
+   ```
+
+## Ensuring User Privacy
+
+No sensitive data, such as tokens or user messages, is logged or transmitted to Sentry. The only potentially sensitive data included are the bot's username and ID, which are only sent if explicitly enabled in the configuration. Additionally, steps have been taken to ensure that log lines sent with bad request reports do not contain sensitive information.
+
+Furthermore, while the JSON payload includes the field `"ip_address": "{{auto}}"`, no actual IP addresses are transmitted.
+
+## Client-Side Filters
+
+To enhance safety and ensure no sensitive information is leaked, various filters have been implemented on the client side:
+
+1. **StripTokens Utility**: This utility function removes any Discord-based tokens from strings before they are sent to Sentry.
+   ```csharp
+   public static string? StripTokens(string? str)
+   {
+      if (string.IsNullOrWhiteSpace(str))
+         return str;
+
+      str = Regex.Replace(str, @"([a-zA-Z0-9]{68,})", "{WEBHOOK_OR_INTERACTION_TOKEN}"); // Any alphanumeric string this long is likely to be sensitive information anyways
+      str = Regex.Replace(str, @"(mfa\\.[a-z0-9_-]{20,})|((?<botid>[a-z0-9_-]{23,28})\\.(?<creation>[a-z0-9_-]{6,7})\\.(?<enc>[a-z0-9_-]{27,}))", "{BOT_OR_USER_TOKEN}");
+
+      return str;
+   }
+   ```
+
+2. **Breadcrumb Filter**: Filters out sensitive information from breadcrumb logs before sending them to Sentry.
+   ```csharp
+   options.SetBeforeBreadcrumb(b
+      => new Breadcrumb(Utilities.StripTokens(b.Message),
+         b.Type,
+         b.Data?.Select(x => new KeyValuePair<string, string>(x.Key, Utilities.StripTokens(x.Value)))
+         .ToDictionary(x => x.Key, x => x.Value),
+         b.Category,
+         b.Level));
+   ```
+
+3. **Transaction Filter**: Ensures that sensitive information is not included in transaction data sent to Sentry.
+   ```csharp
+   options.SetBeforeSendTransaction(tr =>
+   {
+      if (tr.Request.Data is string str)
+         tr.Request.Data = Utilities.StripTokens(str);
+
+      return tr;
+   });
+   ```
+
+By maintaining these practices, DisCatSharp ensures user privacy while leveraging Sentry to improve the library's reliability and performance.
+
+For more information on configuring and using Sentry in DisCatSharp, refer to the official [announcement](https://docs.dcs.aitsys.dev/changelogs/v10/10_6_0#sentry-integration).

DisCatSharp.Docs/articles/sec_comp/sentry.md

@@ -0,0 +1,72 @@
+---
+uid: sec_comp_sentry
+title: Sentry Vulnerability Report
+author: DisCatSharp Team
+---
+
+# Disclaimer on Recent Claims and Sentry Integration Measures
+
+## Overview
+
+Recently, claims were made regarding the logging of tokens within our Sentry integration in the DisCatSharp library. These claims were taken seriously and thoroughly investigated. This document outlines our findings and the steps taken to further ensure the security and privacy of our users.
+
+## Claims and Investigation
+
+The claims suggested that our Sentry integration was logging sensitive information, including tokens. After a comprehensive review, including chasing the logs through a proxy, it was confirmed that no sensitive information such as tokens was being transmitted.
+
+### Validation Process
+
+1. **Proxy Analysis**: Logs sent to Sentry were inspected using a proxy to ensure no sensitive data was being transmitted.
+2. **Code Review**: The relevant sections of the code were reviewed to verify that no tokens or sensitive information were included in the logs.
+
+## Measures Taken
+
+Despite the validation that no sensitive data was being logged, additional measures have been implemented to further enhance security:
+
+1. **StripTokens Utility**: A utility function to remove any Discord-based tokens from strings before they are sent to Sentry.
+   ```csharp
+   public static string? StripTokens(string? str)
+   {
+      if (string.IsNullOrWhiteSpace(str))
+         return str;
+
+      str = Regex.Replace(str, @"([a-zA-Z0-9]{68,})", "{WEBHOOK_OR_INTERACTION_TOKEN}"); // Any alphanumeric string this long is likely to be sensitive information anyways
+      str = Regex.Replace(str, @"(mfa\\.[a-z0-9_-]{20,})|((?<botid>[a-z0-9_-]{23,28})\\.(?<creation>[a-z0-9_-]{6,7})\\.(?<enc>[a-z0-9_-]{27,}))", "{BOT_OR_USER_TOKEN}");
+
+      return str;
+   }
+   ```
+
+2. **Breadcrumb Filter**: Filters out sensitive information from breadcrumb logs before sending them to Sentry.
+   ```csharp
+   options.SetBeforeBreadcrumb(b
+      => new Breadcrumb(Utilities.StripTokens(b.Message),
+         b.Type,
+         b.Data?.Select(x => new KeyValuePair<string, string>(x.Key, Utilities.StripTokens(x.Value)))
+         .ToDictionary(x => x.Key, x => x.Value),
+         b.Category,
+         b.Level));
+   ```
+
+3. **Transaction Filter**: Ensures that sensitive information is not included in transaction data sent to Sentry.
+   ```csharp
+   options.SetBeforeSendTransaction(tr =>
+   {
+      if (tr.Request.Data is string str)
+         tr.Request.Data = Utilities.StripTokens(str);
+
+      return tr;
+   });
+   ```
+
+## Conclusion
+
+The initial claims were found to be unsubstantiated. However, we have taken this opportunity to enhance our security measures further to ensure the utmost safety and privacy for our users. We appreciate the community's vigilance and remain committed to maintaining a secure and reliable library.
+
+For more details on the specific pull requests and discussions related to these measures, please refer to the following:
+- [Pull Request 494](https://github.com/Aiko-IT-Systems/DisCatSharp/pull/494)
+- [Pull Request 493](https://github.com/Aiko-IT-Systems/DisCatSharp/pull/493)
+- [Pull Request 495](https://github.com/Aiko-IT-Systems/DisCatSharp/pull/495)
+- [Pull Request 501](https://github.com/Aiko-IT-Systems/DisCatSharp/pull/501)
+
+Thank you for your continued support and understanding.

DisCatSharp.Docs/articles/toc.yml

@@ -119,3 +119,9 @@ items:
             href: misc/hosting.md
           - name: Voice Activities
             href: misc/voice_activities.md
+          - name: Sentry
+            href: misc/sentry.md
+    - name: Security & Compliance
+      items:
+          - name: Sentry Vulnerability Report
+            href: sec_comp/sentry.md