From 9ed218c161536adb7cb39c696e20a9adbd5d6a9a Mon Sep 17 00:00:00 2001 From: Joshua Delgado Date: Fri, 10 Apr 2026 13:36:25 -0400 Subject: [PATCH 1/7] Added documentation for new repo datadog-custom-rules-template --- .../static_analysis/custom_rules/_index.md | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/content/en/security/code_security/static_analysis/custom_rules/_index.md b/content/en/security/code_security/static_analysis/custom_rules/_index.md index 8e805a1238b..b1ba53850bf 100644 --- a/content/en/security/code_security/static_analysis/custom_rules/_index.md +++ b/content/en/security/code_security/static_analysis/custom_rules/_index.md @@ -25,6 +25,64 @@ on how rules are organized within a ruleset. For example, some users might want A ruleset must have a unique name with only letters, numbers, and hyphens (`-`). Examples of valid ruleset names are `python-security`, `cobra-team-checks`, or `my-company-security-checks`. +## Manage rules with the template repository + +The [datadog-custom-rules-template][5] GitHub repository provides a Git-based workflow for managing custom rules. On every push to `main`, a GitHub Action automatically creates, updates, or deletes rulesets and rules to match what's on disk. + +### Get started + +1. Click **Use this template** on the [datadog-custom-rules-template][5] repository to create your own copy. +2. Add your Datadog credentials as GitHub secrets. See [Authentication](#authentication). +3. Rename `rulesets/my-custom-rules/` or add new ruleset directories under `rulesets/`. +4. Push to `main`. The GitHub Action uploads your rules automatically. + +### Authentication + +1. In your GitHub repository, go to **Settings → Secrets and variables → Actions**. +2. Add three secrets: + - `DD_API_KEY` — your Datadog API key + - `DD_APP_KEY` — your Datadog Application key + - `DD_SITE` — your Datadog site hostname (for example, `datadoghq.com`, `datadoghq.eu`, or `us3.datadoghq.com`) + +### How sync works + +On every push to `main`, the GitHub Action runs `upload.py`, which: +- **Creates** rulesets and rules that are new on disk +- **Updates** rulesets and rules whose content has changed +- **Deletes** rulesets and rules that have been removed from disk + +Only changed rules trigger API calls — unchanged rules are skipped. + +To trigger a sync without pushing a commit, go to the **Actions** tab and click **Upload Custom Rules → Run workflow**. + +### Rule file format + +Each ruleset directory contains a `ruleset.yaml` and a separate `.yaml` file for each rule. + +**`ruleset.yaml`** + +```yaml +name: my-org-custom-rules +short_description: One-line summary +description: Longer description of what this ruleset covers. +``` + +**Rule file** + +```yaml +name: your-rule-name +short_description: One-line summary +description: Detailed description. +category: BEST_PRACTICES # SECURITY | BEST_PRACTICES | CODE_STYLE | ERROR_PRONE | PERFORMANCE +severity: ERROR # ERROR | WARNING | NOTICE | INFO +language: JAVASCRIPT +tree_sitter_query: ... # See Anatomy of a custom rule +code: |- # See Anatomy of a custom rule + function visit(node, filename, code) { ... } +tests: [] +is_published: false # Set to true when the rule is ready for scans +``` + ## Anatomy of a custom rule A custom rule is composed of three main components: @@ -85,3 +143,4 @@ All Datadog default rules are available in [Code Security][4]. You can easily an [2]: https://tree-sitter.github.io/ [3]: https://tree-sitter.github.io/tree-sitter/using-parsers/queries/index.html [4]: https://app.datadoghq.com/ci/code-analysis/static-analysis/default-rulesets +[5]: https://github.com/DataDog/datadog-custom-rules-template From 22636fc01acf3d9565a4d857d22180a812917857 Mon Sep 17 00:00:00 2001 From: Joshua Delgado Date: Fri, 10 Apr 2026 13:48:38 -0400 Subject: [PATCH 2/7] Adjusted page for CONTRIBUTING guidelines --- .../code_security/static_analysis/custom_rules/_index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/en/security/code_security/static_analysis/custom_rules/_index.md b/content/en/security/code_security/static_analysis/custom_rules/_index.md index b1ba53850bf..0782ed54e96 100644 --- a/content/en/security/code_security/static_analysis/custom_rules/_index.md +++ b/content/en/security/code_security/static_analysis/custom_rules/_index.md @@ -51,7 +51,7 @@ On every push to `main`, the GitHub Action runs `upload.py`, which: - **Updates** rulesets and rules whose content has changed - **Deletes** rulesets and rules that have been removed from disk -Only changed rules trigger API calls — unchanged rules are skipped. +Only changed rules trigger API calls—unchanged rules are skipped. To trigger a sync without pushing a commit, go to the **Actions** tab and click **Upload Custom Rules → Run workflow**. @@ -76,9 +76,9 @@ description: Detailed description. category: BEST_PRACTICES # SECURITY | BEST_PRACTICES | CODE_STYLE | ERROR_PRONE | PERFORMANCE severity: ERROR # ERROR | WARNING | NOTICE | INFO language: JAVASCRIPT -tree_sitter_query: ... # See Anatomy of a custom rule -code: |- # See Anatomy of a custom rule - function visit(node, filename, code) { ... } +tree_sitter_query: # See Anatomy of a custom rule +code: |- # See Anatomy of a custom rule + function visit(node, filename, code) { } tests: [] is_published: false # Set to true when the rule is ready for scans ``` From 259dede9bebf30f6e196f3899bea60ec998830aa Mon Sep 17 00:00:00 2001 From: Joshua Delgado Date: Fri, 10 Apr 2026 13:51:20 -0400 Subject: [PATCH 3/7] Include that this template is optional and not mandatory --- .../code_security/static_analysis/custom_rules/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/security/code_security/static_analysis/custom_rules/_index.md b/content/en/security/code_security/static_analysis/custom_rules/_index.md index 0782ed54e96..57c402662e8 100644 --- a/content/en/security/code_security/static_analysis/custom_rules/_index.md +++ b/content/en/security/code_security/static_analysis/custom_rules/_index.md @@ -27,7 +27,7 @@ ruleset names are `python-security`, `cobra-team-checks`, or `my-company-securit ## Manage rules with the template repository -The [datadog-custom-rules-template][5] GitHub repository provides a Git-based workflow for managing custom rules. On every push to `main`, a GitHub Action automatically creates, updates, or deletes rulesets and rules to match what's on disk. +As an alternative to managing custom rules in Datadog, the [datadog-custom-rules-template][5] GitHub repository provides a Git-based workflow for managing custom rules as code. On every push to `main`, a GitHub Action automatically creates, updates, or deletes rulesets and rules to match what's on disk. ### Get started From 8c3542346f0b32c3dba055837fdeb886483a8896 Mon Sep 17 00:00:00 2001 From: Joshua Delgado <100707532+jdelgo@users.noreply.github.com> Date: Fri, 10 Apr 2026 16:37:40 -0400 Subject: [PATCH 4/7] Update content/en/security/code_security/static_analysis/custom_rules/_index.md Co-authored-by: Rosa Trieu <107086888+rtrieu@users.noreply.github.com> --- .../code_security/static_analysis/custom_rules/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/security/code_security/static_analysis/custom_rules/_index.md b/content/en/security/code_security/static_analysis/custom_rules/_index.md index 57c402662e8..98e0661c438 100644 --- a/content/en/security/code_security/static_analysis/custom_rules/_index.md +++ b/content/en/security/code_security/static_analysis/custom_rules/_index.md @@ -27,7 +27,7 @@ ruleset names are `python-security`, `cobra-team-checks`, or `my-company-securit ## Manage rules with the template repository -As an alternative to managing custom rules in Datadog, the [datadog-custom-rules-template][5] GitHub repository provides a Git-based workflow for managing custom rules as code. On every push to `main`, a GitHub Action automatically creates, updates, or deletes rulesets and rules to match what's on disk. +As an alternative to managing custom rules in Datadog, the [datadog-custom-rules-template][5] GitHub repository provides a Git-based workflow for managing custom rules as code. On every push to `main`, a GitHub Action automatically creates, updates, or deletes rulesets and rules to match what's in the repository. ### Get started From 26e22931cb62d76d3ea2bacbae1c7d5aec985943 Mon Sep 17 00:00:00 2001 From: Joshua Delgado <100707532+jdelgo@users.noreply.github.com> Date: Fri, 10 Apr 2026 16:37:47 -0400 Subject: [PATCH 5/7] Update content/en/security/code_security/static_analysis/custom_rules/_index.md Co-authored-by: Rosa Trieu <107086888+rtrieu@users.noreply.github.com> --- .../code_security/static_analysis/custom_rules/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/security/code_security/static_analysis/custom_rules/_index.md b/content/en/security/code_security/static_analysis/custom_rules/_index.md index 98e0661c438..910a144d8d4 100644 --- a/content/en/security/code_security/static_analysis/custom_rules/_index.md +++ b/content/en/security/code_security/static_analysis/custom_rules/_index.md @@ -49,7 +49,7 @@ As an alternative to managing custom rules in Datadog, the [datadog-custom-rules On every push to `main`, the GitHub Action runs `upload.py`, which: - **Creates** rulesets and rules that are new on disk - **Updates** rulesets and rules whose content has changed -- **Deletes** rulesets and rules that have been removed from disk +- **Deletes** rulesets and rules that have been removed the repository Only changed rules trigger API calls—unchanged rules are skipped. From e56e66d8f29d3fc7321a36424813c4244a360965 Mon Sep 17 00:00:00 2001 From: Joshua Delgado <100707532+jdelgo@users.noreply.github.com> Date: Fri, 10 Apr 2026 16:38:04 -0400 Subject: [PATCH 6/7] Update content/en/security/code_security/static_analysis/custom_rules/_index.md Co-authored-by: Rosa Trieu <107086888+rtrieu@users.noreply.github.com> --- .../code_security/static_analysis/custom_rules/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/security/code_security/static_analysis/custom_rules/_index.md b/content/en/security/code_security/static_analysis/custom_rules/_index.md index 910a144d8d4..cefbb62091f 100644 --- a/content/en/security/code_security/static_analysis/custom_rules/_index.md +++ b/content/en/security/code_security/static_analysis/custom_rules/_index.md @@ -47,7 +47,7 @@ As an alternative to managing custom rules in Datadog, the [datadog-custom-rules ### How sync works On every push to `main`, the GitHub Action runs `upload.py`, which: -- **Creates** rulesets and rules that are new on disk +- **Creates** rulesets and rules that are new in the repository - **Updates** rulesets and rules whose content has changed - **Deletes** rulesets and rules that have been removed the repository From 535af5741313d2bfff0d1c65d9def1df25fa3b54 Mon Sep 17 00:00:00 2001 From: Joshua Delgado <100707532+jdelgo@users.noreply.github.com> Date: Fri, 10 Apr 2026 16:38:12 -0400 Subject: [PATCH 7/7] Update content/en/security/code_security/static_analysis/custom_rules/_index.md Co-authored-by: Rosa Trieu <107086888+rtrieu@users.noreply.github.com> --- .../code_security/static_analysis/custom_rules/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/security/code_security/static_analysis/custom_rules/_index.md b/content/en/security/code_security/static_analysis/custom_rules/_index.md index cefbb62091f..2816765ae51 100644 --- a/content/en/security/code_security/static_analysis/custom_rules/_index.md +++ b/content/en/security/code_security/static_analysis/custom_rules/_index.md @@ -53,7 +53,7 @@ On every push to `main`, the GitHub Action runs `upload.py`, which: Only changed rules trigger API calls—unchanged rules are skipped. -To trigger a sync without pushing a commit, go to the **Actions** tab and click **Upload Custom Rules → Run workflow**. +To run a sync manually, in to your GitHub repository, go to the **Actions** tab, select **Upload Custom Rules**, and click **Run workflow**. ### Rule file format