JSON Configuration

Configure Monitor using local JSON configuration files. Ideal for version-controlled setups, offline environments, and CI/CD pipelines.

Overview

JSON configuration lets you define protections, logging, rate limiting, and other Monitor settings in a file that lives alongside your application code. This is useful for:

Version control: Track configuration changes in git alongside your codebase
Environment-specific configs: Different files per environment (dev, staging, production)
Offline deployments: No dependency on the ByteHide Cloud API
CI/CD pipelines: Automate configuration as part of your build and deploy process

Configuration Priority

When multiple configuration sources are present, they are applied in this priority order: Cloud Dashboard (highest) > JSON File > Code (Configuration API) (lowest). Cloud configuration overrides JSON settings. See Cloud Configuration for details.

Export from Cloud Dashboard

If you already have rules configured in the Cloud Dashboard, click Export config in the Workflow tab to download them as a JSON file. This gives you a ready-to-use configuration file that matches your current cloud setup.

Configuration Files

The SDK searches for configuration files in this order:

Encrypted embedded config (injected automatically by the Gradle plugin at build time)
Plain JSON files (fallback for development / desktop):
- monitor-config.json
- bytehide-monitor-config.json
- bytehide.monitor.json
- monitor.config.json

Android: Place the file in src/main/assets/. Desktop/Server: Place it in src/main/resources/ (classpath).

Android with Gradle plugin

On Android with the Gradle plugin, the plugin generates and embeds an encrypted config automatically from the monitor {} DSL. You only need a manual JSON file if you're not using the plugin or want to override the embedded config during development.

Basic Configuration

Mobile Application

JSON

{
  "enabled": true,
  "projectToken": "${BYTEHIDE_API_TOKEN}",
  "protections": [
    { "type": "DebuggerDetection", "enabled": true, "action": "close" },
    { "type": "JailbreakDetection", "enabled": true, "action": "close" },
    { "type": "ClockTampering", "enabled": true, "action": "log" }
  ]
}

{
  "enabled": true,
  "projectToken": "${BYTEHIDE_API_TOKEN}",
  "protections": [
    { "type": "DebuggerDetection", "enabled": true, "action": "close" },
    { "type": "JailbreakDetection", "enabled": true, "action": "close" },
    { "type": "ClockTampering", "enabled": true, "action": "log" }
  ]
}

Desktop Application

JSON

{
  "enabled": true,
  "projectToken": "${BYTEHIDE_API_TOKEN}",
  "protections": [
    { "type": "DebuggerDetection", "enabled": true, "action": "close" },
    { "type": "VirtualMachineDetection", "enabled": true, "action": "log" },
    { "type": "ProcessInjection", "enabled": true, "action": "log" },
    { "type": "ContainerDetection", "enabled": true, "action": "log" },
    { "type": "CloudMetadata", "enabled": true, "action": "log" }
  ]
}

{
  "enabled": true,
  "projectToken": "${BYTEHIDE_API_TOKEN}",
  "protections": [
    { "type": "DebuggerDetection", "enabled": true, "action": "close" },
    { "type": "VirtualMachineDetection", "enabled": true, "action": "log" },
    { "type": "ProcessInjection", "enabled": true, "action": "log" },
    { "type": "ContainerDetection", "enabled": true, "action": "log" },
    { "type": "CloudMetadata", "enabled": true, "action": "log" }
  ]
}

Complete Schema Reference

Root Configuration

Field	Type	Default	Description
`name`	string	-	Configuration name/description
`enabled`	boolean	`true`	Enable/disable monitoring
`projectToken`	string	-	ByteHide project token (can use env vars)
`preset`	string	-	`"cloud"`, `"desktop"`, `"mobile"`, `"videogame"`, `"custom"`
`debugResponses`	boolean	`false`	Include threat details in responses (dev only)
`autoIntegration`	boolean	`true`	Auto-register middleware (Android web frameworks only)
`throwOnConnectionFailure`	boolean	`false`	Fail startup if backend unreachable
`logging`	object	-	Logging configuration
`protections`	object	-	Protection module configurations
`cloud`	object	-	Cloud-specific settings (web apps only)

Protection Configuration

Each protection is an object in the protections array:

JSON

{
  "protections": [
    {
      "type": "DebuggerDetection",
      "enabled": true,
      "action": "close",
      "customActionName": "my-action"
    }
  ]
}

{
  "protections": [
    {
      "type": "DebuggerDetection",
      "enabled": true,
      "action": "close",
      "customActionName": "my-action"
    }
  ]
}

Field	Type	Default	Description
`type`	string	(required)	Module name (see values below)
`enabled`	boolean	`true`	Enable this protection
`action`	string	`"log"`	`"none"`, `"log"`, `"close"`, `"erase"`, `"custom"`
`intervalMs`	integer	varies	Check interval in milliseconds
`customActionName`	string	-	Name of custom handler (when `action` is `"custom"`)

Protection `type` Values

Use the PascalCase name (case-insensitive):

Value	Description
`"DebuggerDetection"`	Attached debuggers (ADB, JDWP, ptrace)
`"ClockTampering"`	System clock manipulation
`"JailbreakDetection"`	Root / jailbreak
`"VirtualMachineDetection"`	VM environments (VMware, VirtualBox, QEMU)
`"EmulatorDetection"`	Android emulators (Genymotion, AVD, BlueStacks)
`"MemoryDumpDetection"`	Memory dumping tools (Frida, Objection)
`"TamperingDetection"`	File/code integrity violations
`"ProcessInjection"`	Process injection attacks
`"NetworkTampering"`	MITM / proxy / VPN
`"LicenseBinding"`	License-to-device binding
`"ContainerDetection"`	Docker / Kubernetes / LXC
`"RemoteDesktop"`	Remote desktop sessions
`"CloudMetadata"`	Cloud metadata endpoints (AWS, Azure, GCP)

Interval Configuration

intervalMs only applies to desktop/mobile protections (DebuggerDetection, VirtualMachineDetection, etc.). Web protections run per-request.

Available Presets

Presets enable a predefined group of protections. See Protection Modules for the full reference of all available modules.

`"cloud"` - Web Applications

Enables web-focused protections:

SqlInjection
CrossSiteScripting
PathTraversal
CommandInjection
SSRF
LdapInjection
XxeInjection
NoSqlInjection
LlmPromptInjection

`"desktop"` - Desktop Applications

Enables desktop-focused protections:

DebuggerDetection
VirtualMachineDetection
EmulatorDetection
ClockTampering
MemoryDumpDetection
ProcessInjection

`"mobile"` - Mobile Applications

Enables mobile-focused protections:

JailbreakDetection (iOS/Android root)
DebuggerDetection
EmulatorDetection
ClockTampering
MemoryDumpDetection
HookingDetection

`"videogame"` - Game Applications

Enables game-focused protections:

DebuggerDetection
MemoryDumpDetection
SpeedHackDetection
CheatEngineDetection

`"custom"` - Manual Configuration

No default protections. Specify all protections manually.

Logging Configuration

JSON

{
  "logging": {
    "level": "warning",
    "console": true,
    "debug": false,
    "file": {
      "enabled": true,
      "path": "logs/monitor.log",
      "maxSizeMB": 10,
      "maxFiles": 5
    },
    "bytehideLogs": {
      "enabled": false,
      "token": "${BYTEHIDE_LOGS_TOKEN}",
      "persist": true,
      "filePath": "logs/bytehide-logs-offline.json",
      "maskSensitiveData": ["password", "token", "apiKey"]
    }
  }
}

{
  "logging": {
    "level": "warning",
    "console": true,
    "debug": false,
    "file": {
      "enabled": true,
      "path": "logs/monitor.log",
      "maxSizeMB": 10,
      "maxFiles": 5
    },
    "bytehideLogs": {
      "enabled": false,
      "token": "${BYTEHIDE_LOGS_TOKEN}",
      "persist": true,
      "filePath": "logs/bytehide-logs-offline.json",
      "maskSensitiveData": ["password", "token", "apiKey"]
    }
  }
}

Logging Fields

Field	Type	Default	Description
`level`	string	`"info"`	`"trace"`, `"debug"`, `"info"`, `"warning"`, `"error"`
`console`	boolean	`false`	Enable console logging (stdout)
`debug`	boolean	`false`	Enable debug output
`file`	object	-	File logging configuration
`bytehideLogs`	object	-	ByteHide Logs integration

File Logging

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable file logging
`path`	string	`"logs/bytehide-monitor.log"`	Log file path
`maxSizeMB`	number	`10`	Max file size before rotation
`maxFiles`	number	`5`	Number of backup files

ByteHide Logs Integration

Requires the ByteHide Logger integration.

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable ByteHide Logs
`token`	string	-	ByteHide Logs API token
`persist`	boolean	`true`	Persist logs locally when offline
`filePath`	string	-	Offline persistence path
`maskSensitiveData`	array	-	Patterns to mask (e.g., `["password"]`)

Cloud Configuration (Web Applications)

Advanced settings for web/API applications:

JSON

{
  "cloud": {
    "rateLimit": {
      "enabled": true,
      "maxRequests": 100,
      "windowSizeInMS": 60000
    },
    "anomalyDetection": {
      "enabled": true,
      "detectIpChanges": true,
      "detectUserAgentChanges": true,
      "detectSuspiciousPatterns": true
    },
    "endpoints": [
      {
        "method": "POST",
        "route": "/api/admin/*",
        "protections": {
          "SqlInjection": { "enabled": true, "action": "block" }
        }
      },
      {
        "method": "*",
        "route": "/health",
        "forceProtectionOff": true
      }
    ]
  }
}

{
  "cloud": {
    "rateLimit": {
      "enabled": true,
      "maxRequests": 100,
      "windowSizeInMS": 60000
    },
    "anomalyDetection": {
      "enabled": true,
      "detectIpChanges": true,
      "detectUserAgentChanges": true,
      "detectSuspiciousPatterns": true
    },
    "endpoints": [
      {
        "method": "POST",
        "route": "/api/admin/*",
        "protections": {
          "SqlInjection": { "enabled": true, "action": "block" }
        }
      },
      {
        "method": "*",
        "route": "/health",
        "forceProtectionOff": true
      }
    ]
  }
}

Rate Limiting

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable rate limiting
`maxRequests`	number	`100`	Max requests per window
`windowSizeInMS`	number	`60000`	Time window in milliseconds

Anomaly Detection

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable anomaly detection
`detectIpChanges`	boolean	`true`	Detect IP address changes
`detectUserAgentChanges`	boolean	`true`	Detect User-Agent changes
`detectSuspiciousPatterns`	boolean	`true`	Detect suspicious patterns

Endpoint-Specific Configuration

Override protections for specific routes:

Field	Type	Description
`method`	string	`"GET"`, `"POST"`, `"PUT"`, `"DELETE"`, `"*"` (all)
`route`	string	Route pattern (e.g., `"/api/users/{id}"`, `"/admin/*"`)
`forceProtectionOff`	boolean	Disable ALL protections for this endpoint
`protections`	object	Endpoint-specific protection overrides
`rateLimit`	object	Endpoint-specific rate limit

Environment Variables

You can reference environment variables in any string value using ${VARIABLE_NAME} syntax:

JSON

{
  "projectToken": "${BYTEHIDE_API_TOKEN}",
  "logging": {
    "bytehideLogs": {
      "token": "${BYTEHIDE_LOGS_TOKEN}"
    }
  }
}

{
  "projectToken": "${BYTEHIDE_API_TOKEN}",
  "logging": {
    "bytehideLogs": {
      "token": "${BYTEHIDE_LOGS_TOKEN}"
    }
  }
}

This avoids hardcoding sensitive values in configuration files.

Token Resolution Order

The project token is resolved in this order:

BYTEHIDE_API_TOKEN environment variable
BYTEHIDE_MONITOR_TOKEN environment variable
projectToken value in the JSON file

Complete Example

Desktop application with comprehensive configuration:

JSON

{
  "name": "My Production App",
  "enabled": true,
  "projectToken": "${BYTEHIDE_API_TOKEN}",
  "preset": "desktop",
  "debugResponses": false,
  "throwOnConnectionFailure": false,

  "logging": {
    "level": "warning",
    "console": false,
    "file": {
      "enabled": true,
      "path": "logs/monitor.log",
      "maxSizeMB": 50,
      "maxFiles": 10
    }
  },

  "protections": [
    { "type": "DebuggerDetection", "enabled": true, "action": "close" },
    { "type": "VirtualMachineDetection", "enabled": true, "action": "log" },
    { "type": "ClockTampering", "enabled": true, "action": "close" },
    { "type": "MemoryDumpDetection", "enabled": true, "action": "erase" },
    { "type": "ProcessInjection", "enabled": true, "action": "close" }
  ]
}

{
  "name": "My Production App",
  "enabled": true,
  "projectToken": "${BYTEHIDE_API_TOKEN}",
  "preset": "desktop",
  "debugResponses": false,
  "throwOnConnectionFailure": false,

  "logging": {
    "level": "warning",
    "console": false,
    "file": {
      "enabled": true,
      "path": "logs/monitor.log",
      "maxSizeMB": 50,
      "maxFiles": 10
    }
  },

  "protections": [
    { "type": "DebuggerDetection", "enabled": true, "action": "close" },
    { "type": "VirtualMachineDetection", "enabled": true, "action": "log" },
    { "type": "ClockTampering", "enabled": true, "action": "close" },
    { "type": "MemoryDumpDetection", "enabled": true, "action": "erase" },
    { "type": "ProcessInjection", "enabled": true, "action": "close" }
  ]
}

Web application with cloud features:

JSON

{
  "name": "My Web API",
  "enabled": true,
  "projectToken": "${BYTEHIDE_API_TOKEN}",
  "preset": "cloud",
  "autoIntegration": true,
  "debugResponses": false,

  "logging": {
    "level": "info",
    "console": true,
    "bytehideLogs": {
      "enabled": true,
      "token": "${BYTEHIDE_LOGS_TOKEN}",
      "persist": true,
      "maskSensitiveData": ["password", "token", "apiKey", "secret"]
    }
  },

  "protections": {
    "SqlInjection": { "enabled": true, "action": "block" },
    "CrossSiteScripting": { "enabled": true, "action": "block" },
    "PathTraversal": { "enabled": true, "action": "block" },
    "CommandInjection": { "enabled": true, "action": "block" },
    "SSRF": { "enabled": true, "action": "block" },
    "LlmPromptInjection": { "enabled": true, "action": "log" }
  },

  "cloud": {
    "rateLimit": {
      "enabled": true,
      "maxRequests": 1000,
      "windowSizeInMS": 60000
    },
    "anomalyDetection": {
      "enabled": true,
      "detectIpChanges": true,
      "detectUserAgentChanges": true,
      "detectSuspiciousPatterns": true
    },
    "endpoints": [
      {
        "method": "*",
        "route": "/health",
        "forceProtectionOff": true
      },
      {
        "method": "POST",
        "route": "/api/admin/*",
        "rateLimit": {
          "enabled": true,
          "maxRequests": 10,
          "windowSizeInMS": 60000
        }
      },
      {
        "method": "POST",
        "route": "/api/public/search",
        "protections": {
          "SqlInjection": { "enabled": true, "action": "block" },
          "NoSqlInjection": { "enabled": true, "action": "block" }
        }
      }
    ]
  }
}

{
  "name": "My Web API",
  "enabled": true,
  "projectToken": "${BYTEHIDE_API_TOKEN}",
  "preset": "cloud",
  "autoIntegration": true,
  "debugResponses": false,

  "logging": {
    "level": "info",
    "console": true,
    "bytehideLogs": {
      "enabled": true,
      "token": "${BYTEHIDE_LOGS_TOKEN}",
      "persist": true,
      "maskSensitiveData": ["password", "token", "apiKey", "secret"]
    }
  },

  "protections": {
    "SqlInjection": { "enabled": true, "action": "block" },
    "CrossSiteScripting": { "enabled": true, "action": "block" },
    "PathTraversal": { "enabled": true, "action": "block" },
    "CommandInjection": { "enabled": true, "action": "block" },
    "SSRF": { "enabled": true, "action": "block" },
    "LlmPromptInjection": { "enabled": true, "action": "log" }
  },

  "cloud": {
    "rateLimit": {
      "enabled": true,
      "maxRequests": 1000,
      "windowSizeInMS": 60000
    },
    "anomalyDetection": {
      "enabled": true,
      "detectIpChanges": true,
      "detectUserAgentChanges": true,
      "detectSuspiciousPatterns": true
    },
    "endpoints": [
      {
        "method": "*",
        "route": "/health",
        "forceProtectionOff": true
      },
      {
        "method": "POST",
        "route": "/api/admin/*",
        "rateLimit": {
          "enabled": true,
          "maxRequests": 10,
          "windowSizeInMS": 60000
        }
      },
      {
        "method": "POST",
        "route": "/api/public/search",
        "protections": {
          "SqlInjection": { "enabled": true, "action": "block" },
          "NoSqlInjection": { "enabled": true, "action": "block" }
        }
      }
    ]
  }
}

Advanced Interval Configuration

For desktop/mobile protections, you can specify check intervals:

JSON

{
  "protections": [
    { "type": "DebuggerDetection", "enabled": true, "action": "close", "intervalMs": 30000 },
    { "type": "VirtualMachineDetection", "enabled": true, "action": "log", "intervalMs": 120000 },
    { "type": "ClockTampering", "enabled": true, "action": "close", "intervalMs": 300000 }
  ]
}

{
  "protections": [
    { "type": "DebuggerDetection", "enabled": true, "action": "close", "intervalMs": 30000 },
    { "type": "VirtualMachineDetection", "enabled": true, "action": "log", "intervalMs": 120000 },
    { "type": "ClockTampering", "enabled": true, "action": "close", "intervalMs": 300000 }
  ]
}

Recommended intervals:

DebuggerDetection: 30000ms (30 seconds)
VirtualMachineDetection: 120000ms (2 minutes, runs once typically)
ClockTampering: 300000ms (5 minutes)
MemoryDumpDetection: 60000ms (1 minute)
JailbreakDetection: 120000ms (2 minutes, runs once typically)

Performance Impact

Lower intervals mean more frequent checks but higher CPU usage. Balance security needs with performance requirements.

JSON Configuration

Overview

Configuration Files

Basic Configuration

Mobile Application

Desktop Application

Complete Schema Reference

Root Configuration

Protection Configuration

Protection `type` Values

Available Presets

`"cloud"` - Web Applications

`"desktop"` - Desktop Applications

`"mobile"` - Mobile Applications

`"videogame"` - Game Applications

`"custom"` - Manual Configuration

Logging Configuration

Logging Fields

File Logging

ByteHide Logs Integration

Cloud Configuration (Web Applications)

Rate Limiting

Anomaly Detection

Endpoint-Specific Configuration

Environment Variables

Token Resolution Order

Complete Example

Advanced Interval Configuration

Next Steps

Cloud Configuration

Configuration API

Protection Modules

Actions

Overview

Configuration Files

Basic Configuration

Mobile Application

Desktop Application

Complete Schema Reference

Root Configuration

Protection Configuration

Protection type Values

Available Presets

"cloud" - Web Applications

"desktop" - Desktop Applications

"mobile" - Mobile Applications

"videogame" - Game Applications

"custom" - Manual Configuration

Logging Configuration

Logging Fields

File Logging

ByteHide Logs Integration

Cloud Configuration (Web Applications)

Rate Limiting

Anomaly Detection

Endpoint-Specific Configuration

Environment Variables

Token Resolution Order

Complete Example

Advanced Interval Configuration

Next Steps

Protection `type` Values

`"cloud"` - Web Applications

`"desktop"` - Desktop Applications

`"mobile"` - Mobile Applications

`"videogame"` - Game Applications

`"custom"` - Manual Configuration