feat: add support for attack-protection bot-detection and captcha configurations (#1189)

* feat: enhance attack protection configuration

- src/context/directory/handlers/attackProtection.ts: add botDetection and captcha properties to ParsedAttackProtection
- src/context/directory/handlers/attackProtection.ts: update attackProtectionFiles to include botDetection and captcha file paths
- src/context/directory/handlers/attackProtection.ts: load botDetection and captcha configurations in parse function
- src/context/directory/handlers/attackProtection.ts: dump botDetection and captcha configurations in dump function
- src/context/yaml/handlers/attackProtection.ts: include botDetection and captcha in ParsedAttackProtection
- src/tools/auth0/handlers/attackProtection.ts: add schema definitions for botDetection and captcha
- test/context/directory/attackProtection.test.js: add tests for botDetection and captcha configurations
- test/context/yaml/attackProtection.test.js: add YAML tests for botDetection and captcha
- test/tools/auth0/handlers/attackProtection.tests.js: mock botDetection and captcha in handler tests

* feat: implement attack protection defaults and integration

- src/context/defaults.ts: add attackProtectionDefaults function to mask sensitive captcha secrets.
- src/context/directory/handlers/attackProtection.ts: integrate attackProtectionDefaults for parsing attack protection data.
- src/context/yaml/handlers/attackProtection.ts: utilize attackProtectionDefaults to mask captcha configuration.
- src/tools/auth0/handlers/attackProtection.ts: refactor CAPTCHA providers into a constant and update related logic.

* feat: enhance attack protection types and defaults

- src/context/defaults.ts: add type annotation for attackProtection parameter
- src/context/directory/handlers/attackProtection.ts: update ParsedAttackProtection type to use AttackProtection
- src/context/yaml/handlers/attackProtection.ts: update ParsedAttackProtection type to use AttackProtection
- src/tools/auth0/handlers/attackProtection.ts: define AttackProtection type and update existing property type
- src/types.ts: update attackProtection asset type to use AttackProtection

* feat: refactor attack protection client calls

- src/tools/auth0/handlers/attackProtection.ts: replace direct client reference with this.client for attack protection methods

* feat: update auth0 dependency version

- package.json: bump auth0 from ^4.34.0 to ^4.35.0
- package-lock.json: bump auth0 from 4.34.0 to 4.35.0

* feat: add attack protection configurations
- examples/yaml/tenant.yaml: introduce attackProtection section with botDetection, captcha, breachedPasswordDetection, bruteForceProtection, and suspiciousIpThrottling settings
- examples/directory/attack-protection/bot-detection.json: create bot detection configuration file
- examples/directory/attack-protection/breached-password-detection.json: create breached password detection configuration file
- examples/directory/attack-protection/brute-force-protection.json: create brute force protection configuration file
- examples/directory/attack-protection/captcha.json: create captcha configuration file
- examples/directory/attack-protection/suspicious-ip-throttling.json: create suspicious IP throttling configuration file

* feat(tests): enhance attack protection tests
- test/tools/auth0/handlers/attackProtection.tests.js: add test for handling 403 error when fetching bot detection and captcha configs
- test/tools/auth0/handlers/attackProtection.tests.js: add test to skip updates when attackProtection is null
- test/tools/auth0/handlers/attackProtection.tests.js: add test to skip updates when attackProtection is an empty object
- test/tools/auth0/handlers/attackProtection.tests.js: add test to skip botDetection update when empty object
- test/tools/auth0/handlers/attackProtection.tests.js: add test to skip captcha update when empty object
- test/tools/auth0/handlers/attackProtection.tests.js: add test to clean up empty captcha providers before update
- test/tools/auth0/handlers/attackProtection.tests.js: add test to skip captcha update when updateCaptchaConfig is not a function
- test/tools/auth0/handlers/attackProtection.tests.js: add test to return cached existing data on subsequent calls

* feat: update attack protection handling

- src/context/yaml/handlers/attackProtection.ts: fix maskedAttackProtection assignment to use attackProtectionConfig
- src/tools/auth0/handlers/attackProtection.ts: simplify attackProtectionClient type assertion
- src/tools/auth0/handlers/attackProtection.ts: enhance site_key check for captcha provider configuration

* feat: simplify bot detection and captcha configuration updates

- src/tools/auth0/handlers/attackProtection.ts: streamline bot detection config update logic
- src/tools/auth0/handlers/attackProtection.ts: remove unnecessary checks for captcha config updates
- src/tools/auth0/handlers/attackProtection.ts: optimize captcha provider handling

* feat: clean up CAPTCHA provider configurations and update tests

- src/tools/auth0/handlers/attackProtection.ts: remove empty CAPTCHA provider configurations before updates to prevent API errors
- test/tools/auth0/handlers/attackProtection.tests.js: remove redundant test for skipping captcha update when updateCaptchaConfig is not a function

Author: kushalshit27

examples/directory/attack-protection/bot-detection.json

@@ -0,0 +1,11 @@
+{
+  "bot_detection_level": "medium",
+  "challenge_password_policy": "when_risky",
+  "challenge_passwordless_policy": "when_risky",
+  "challenge_password_reset_policy": "when_risky",
+  "allowlist": [
+    "192.168.1.0/24",
+    "10.0.0.1"
+  ],
+  "monitoring_mode_enabled": false
+}

examples/directory/attack-protection/breached-password-detection.json

@@ -0,0 +1,11 @@
+{
+  "enabled": true,
+  "shields": [
+    "block",
+    "admin_notification"
+  ],
+  "admin_notification_frequency": [
+    "immediately"
+  ],
+  "method": "standard"
+}

examples/directory/attack-protection/brute-force-protection.json

@@ -0,0 +1,10 @@
+{
+  "enabled": true,
+  "shields": [
+    "block",
+    "user_notification"
+  ],
+  "mode": "count_per_identifier_and_ip",
+  "allowlist": [],
+  "max_attempts": 10
+}

examples/directory/attack-protection/captcha.json

@@ -0,0 +1,27 @@
+{
+  "active_provider_id": "friendly_captcha",
+  "friendly_captcha": {
+    "site_key": "##CAPTCHA_FRIENDLY_CAPTCHA_SITE_KEY##",
+    "secret": "##CAPTCHA_FRIENDLY_CAPTCHA_SECRET##"
+  },
+  "recaptcha_v2": {
+    "site_key": "##CAPTCHA_RECAPTCHA_V2_SITE_KEY##",
+    "secret": "##CAPTCHA_RECAPTCHA_V2_SECRET##"
+  },
+  "recaptcha_enterprise": {
+    "site_key": "##CAPTCHA_RECAPTCHA_ENTERPRISE_SITE_KEY##",
+    "api_key": "##CAPTCHA_RECAPTCHA_ENTERPRISE_API_KEY##",
+    "project_id": "##CAPTCHA_RECAPTCHA_ENTERPRISE_PROJECT_ID##"
+  },
+  "hcaptcha": {
+    "site_key": "##CAPTCHA_HCAPTCHA_SITE_KEY##",
+    "secret": "##CAPTCHA_HCAPTCHA_SECRET##"
+  },
+  "arkose": {
+    "site_key": "##CAPTCHA_ARKOSE_SITE_KEY##",
+    "secret": "##CAPTCHA_ARKOSE_SECRET##",
+    "client_subdomain": "my-client-subdomain",
+    "verify_subdomain": "my-verify-subdomain",
+    "fail_open": false
+  }
+}

examples/directory/attack-protection/suspicious-ip-throttling.json

@@ -0,0 +1,20 @@
+{
+  "enabled": true,
+  "shields": [
+    "block",
+    "admin_notification"
+  ],
+  "allowlist": [
+    "127.0.0.1"
+  ],
+  "stage": {
+    "pre-login": {
+      "max_attempts": 100,
+      "rate": 864000
+    },
+    "pre-user-registration": {
+      "max_attempts": 50,
+      "rate": 1200
+    }
+  }
+}

examples/yaml/tenant.yaml

@@ -310,3 +310,65 @@ customDomains:
     domain_metadata:
       myKey: value
 
+attackProtection:
+  botDetection:
+    bot_detection_level: medium
+    challenge_password_policy: when_risky
+    challenge_passwordless_policy: when_risky
+    challenge_password_reset_policy: when_risky
+    allowlist:
+      - 192.168.1.0/24
+      - 10.0.0.1
+    monitoring_mode_enabled: false
+  captcha:
+    active_provider_id: friendly_captcha
+    friendly_captcha:
+      site_key: ##CAPTCHA_FRIENDLY_CAPTCHA_SITE_KEY##
+      secret: ##CAPTCHA_FRIENDLY_CAPTCHA_SECRET##
+    recaptcha_v2:
+      site_key: ##CAPTCHA_RECAPTCHA_V2_SITE_KEY##
+      secret: ##CAPTCHA_RECAPTCHA_V2_SECRET##
+    recaptcha_enterprise:
+      site_key: ##CAPTCHA_RECAPTCHA_ENTERPRISE_SITE_KEY##
+      api_key: ##CAPTCHA_RECAPTCHA_ENTERPRISE_API_KEY##
+      project_id: ##CAPTCHA_RECAPTCHA_ENTERPRISE_PROJECT_ID##
+    hcaptcha:
+      site_key: ##CAPTCHA_HCAPTCHA_SITE_KEY##
+      secret: ##CAPTCHA_HCAPTCHA_SECRET##
+    arkose:
+      site_key: ##CAPTCHA_ARKOSE_SITE_KEY##
+      secret: ##CAPTCHA_ARKOSE_SECRET##
+      client_subdomain: my-client-subdomain
+      verify_subdomain: my-verify-subdomain
+      fail_open: false
+  breachedPasswordDetection:
+    enabled: true
+    shields:
+      - block
+      - admin_notification
+    admin_notification_frequency:
+      - immediately
+    method: standard
+  bruteForceProtection:
+    enabled: true
+    shields:
+      - block
+      - user_notification
+    mode: count_per_identifier_and_ip
+    allowlist: []
+    max_attempts: 10
+  suspiciousIpThrottling:
+    enabled: true
+    shields:
+      - block
+      - admin_notification
+    allowlist:
+      - 127.0.0.1
+    stage:
+      pre-login:
+        max_attempts: 100
+        rate: 864000
+      pre-user-registration:
+        max_attempts: 50
+        rate: 1200
+

src/context/defaults.ts

@@ -1,3 +1,4 @@
+import { AttackProtection } from '../tools/auth0/handlers/attackProtection';
 import { maskSecretAtPath } from '../tools/utils';
 
 // eslint-disable-next-line import/prefer-default-export
@@ -129,3 +130,32 @@ export function logStreamDefaults(logStreams) {
 
   return maskedLogStreams;
 }
+
+export function attackProtectionDefaults(attackProtection: AttackProtection) {
+  const { captcha } = attackProtection;
+
+  if (captcha) {
+    const providersWithSecrets = ['arkose', 'hcaptcha', 'friendly_captcha', 'recaptcha_v2'];
+
+    providersWithSecrets.forEach((provider) => {
+      if (captcha[provider]) {
+        captcha[provider] = {
+          ...captcha[provider],
+          secret: `##CAPTCHA_${provider.toUpperCase()}_SECRET##`,
+        };
+      }
+    });
+
+    if ('recaptcha_enterprise' in captcha) {
+      captcha.recaptcha_enterprise = {
+        ...captcha.recaptcha_enterprise,
+        api_key: '##CAPTCHA_RECAPTCHA_ENTERPRISE_API_KEY##',
+        project_id: '##CAPTCHA_RECAPTCHA_ENTERPRISE_PROJECT_ID##',
+      };
+    }
+
+    attackProtection.captcha = captcha;
+  }
+
+  return attackProtection;
+}

src/context/directory/handlers/attackProtection.ts

@@ -4,29 +4,28 @@ import { constants } from '../../../tools';
 import { dumpJSON, existsMustBeDir, loadJSON } from '../../../utils';
 import { DirectoryHandler } from '.';
 import DirectoryContext from '..';
-import { Asset, ParsedAsset } from '../../../types';
+import { ParsedAsset } from '../../../types';
+import { attackProtectionDefaults } from '../../defaults';
+import { AttackProtection } from '../../../tools/auth0/handlers/attackProtection';
 
-type ParsedAttackProtection = ParsedAsset<
-  'attackProtection',
-  {
-    breachedPasswordDetection: Asset;
-    bruteForceProtection: Asset;
-    suspiciousIpThrottling: Asset;
-  }
->;
+type ParsedAttackProtection = ParsedAsset<'attackProtection', AttackProtection>;
 
 function attackProtectionFiles(filePath: string): {
   directory: string;
+  botDetection: string;
   breachedPasswordDetection: string;
   bruteForceProtection: string;
+  captcha: string;
   suspiciousIpThrottling: string;
 } {
   const directory = path.join(filePath, constants.ATTACK_PROTECTION_DIRECTORY);
 
   return {
     directory: directory,
+    botDetection: path.join(directory, 'bot-detection.json'),
     breachedPasswordDetection: path.join(directory, 'breached-password-detection.json'),
     bruteForceProtection: path.join(directory, 'brute-force-protection.json'),
+    captcha: path.join(directory, 'captcha.json'),
     suspiciousIpThrottling: path.join(directory, 'suspicious-ip-throttling.json'),
   };
 }
@@ -40,6 +39,10 @@ function parse(context: DirectoryContext): ParsedAttackProtection {
     };
   }
 
+  const botDetection = loadJSON(files.botDetection, {
+    mappings: context.mappings,
+    disableKeywordReplacement: context.disableKeywordReplacement,
+  });
   const breachedPasswordDetection = loadJSON(files.breachedPasswordDetection, {
     mappings: context.mappings,
     disableKeywordReplacement: context.disableKeywordReplacement,
@@ -48,17 +51,25 @@ function parse(context: DirectoryContext): ParsedAttackProtection {
     mappings: context.mappings,
     disableKeywordReplacement: context.disableKeywordReplacement,
   });
+  const captcha = loadJSON(files.captcha, {
+    mappings: context.mappings,
+    disableKeywordReplacement: context.disableKeywordReplacement,
+  });
   const suspiciousIpThrottling = loadJSON(files.suspiciousIpThrottling, {
     mappings: context.mappings,
     disableKeywordReplacement: context.disableKeywordReplacement,
   });
 
+  const maskedAttackProtection = attackProtectionDefaults({
+    botDetection,
+    breachedPasswordDetection,
+    bruteForceProtection,
+    captcha,
+    suspiciousIpThrottling,
+  });
+
   return {
-    attackProtection: {
-      breachedPasswordDetection,
-      bruteForceProtection,
-      suspiciousIpThrottling,
-    },
+    attackProtection: maskedAttackProtection,
   };
 }
 
@@ -70,9 +81,21 @@ async function dump(context: DirectoryContext): Promise<void> {
   const files = attackProtectionFiles(context.filePath);
   fs.ensureDirSync(files.directory);
 
-  dumpJSON(files.breachedPasswordDetection, attackProtection.breachedPasswordDetection);
-  dumpJSON(files.bruteForceProtection, attackProtection.bruteForceProtection);
-  dumpJSON(files.suspiciousIpThrottling, attackProtection.suspiciousIpThrottling);
+  if (attackProtection.botDetection) {
+    dumpJSON(files.botDetection, attackProtection.botDetection);
+  }
+  if (attackProtection.breachedPasswordDetection) {
+    dumpJSON(files.breachedPasswordDetection, attackProtection.breachedPasswordDetection);
+  }
+  if (attackProtection.bruteForceProtection) {
+    dumpJSON(files.bruteForceProtection, attackProtection.bruteForceProtection);
+  }
+  if (attackProtection.captcha) {
+    dumpJSON(files.captcha, attackProtection.captcha);
+  }
+  if (attackProtection.suspiciousIpThrottling) {
+    dumpJSON(files.suspiciousIpThrottling, attackProtection.suspiciousIpThrottling);
+  }
 }
 
 const attackProtectionHandler: DirectoryHandler<ParsedAttackProtection> = {

src/context/yaml/handlers/attackProtection.ts

@@ -1,30 +1,42 @@
 import { YAMLHandler } from '.';
 import YAMLContext from '..';
-import { Asset, ParsedAsset } from '../../../types';
-
-type ParsedAttackProtection = ParsedAsset<
-  'attackProtection',
-  {
-    breachedPasswordDetection: Asset;
-    bruteForceProtection: Asset;
-    suspiciousIpThrottling: Asset;
-  }
->;
+import { AttackProtection } from '../../../tools/auth0/handlers/attackProtection';
+import { ParsedAsset } from '../../../types';
+import { attackProtectionDefaults } from '../../defaults';
+
+type ParsedAttackProtection = ParsedAsset<'attackProtection', AttackProtection>;
 
 async function parseAndDump(context: YAMLContext): Promise<ParsedAttackProtection> {
   const { attackProtection } = context.assets;
 
   if (!attackProtection) return { attackProtection: null };
 
-  const { suspiciousIpThrottling, breachedPasswordDetection, bruteForceProtection } =
-    attackProtection;
+  const {
+    botDetection,
+    suspiciousIpThrottling,
+    breachedPasswordDetection,
+    bruteForceProtection,
+    captcha,
+  } = attackProtection;
+
+  const attackProtectionConfig: ParsedAttackProtection['attackProtection'] = {
+    suspiciousIpThrottling,
+    breachedPasswordDetection,
+    bruteForceProtection,
+  };
+
+  if (botDetection) {
+    attackProtectionConfig.botDetection = botDetection;
+  }
+
+  if (captcha) {
+    attackProtectionConfig.captcha = captcha;
+  }
+
+  const maskedAttackProtection = attackProtectionDefaults(attackProtectionConfig);
 
   return {
-    attackProtection: {
-      suspiciousIpThrottling,
-      breachedPasswordDetection,
-      bruteForceProtection,
-    },
+    attackProtection: maskedAttackProtection,
   };
 }