/

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

Monitor searches for configuration files in your project root directory, in this order:

  1. monitor.config.json
  2. bytehide.monitor.json
  3. bytehide.monitor.config.json
  4. monitor-config.json
  5. bytehide-monitor-config.json

The first file found is used. Place any one of these in your project root directory.

Basic Configuration

Desktop/Mobile Application

JSON
{
  "name": "My Desktop App",
  "enabled": true,
  "projectToken": "${BYTEHIDE_TOKEN}",
  "preset": "desktop",
  "protections": {
    "DebuggerDetection": { "enabled": true, "action": "close" },
    "VirtualMachineDetection": { "enabled": true, "action": "log" }
  }
}

Web Application

JSON
{
  "name": "My Web API",
  "enabled": true,
  "projectToken": "${BYTEHIDE_TOKEN}",
  "preset": "cloud",
  "protections": {
    "SqlInjection": { "enabled": true, "action": "block" },
    "CrossSiteScripting": { "enabled": true, "action": "block" },
    "PathTraversal": { "enabled": true, "action": "block" }
  }
}

Complete Schema Reference

Root Configuration

FieldTypeDefaultDescription
namestring-Configuration name/description
enabledbooleantrueEnable/disable monitoring
projectTokenstring-ByteHide project token (can use env vars)
presetstring-"cloud", "desktop", "mobile", "videogame", "custom"
debugResponsesbooleanfalseInclude threat details in responses (dev only)
autoIntegrationbooleantrueAuto-register middleware (Android web frameworks only)
throwOnConnectionFailurebooleanfalseFail startup if backend unreachable
loggingobject-Logging configuration
protectionsobject-Protection module configurations
cloudobject-Cloud-specific settings (web apps only)

Protection Configuration

Each protection can be configured individually:

JSON
{
  "protections": {
    "SqlInjection": {
      "enabled": true,
      "action": "block",
      "customActionName": "my-action",
      "intervalMs": 30000,
      "config": {}
    }
  }
}
FieldTypeDefaultDescription
enabledbooleantrueEnable this protection
actionstring"block""none", "log", "block", "close", "erase", "custom"
customActionNamestring-Name of custom action (when action="custom")
intervalMsnumber-Check interval in ms (desktop/mobile only)
configobject-Module-specific configuration

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 Fields

FieldTypeDefaultDescription
levelstring"info""trace", "debug", "info", "warning", "error"
consolebooleanfalseEnable console logging (stdout)
debugbooleanfalseEnable debug output
fileobject-File logging configuration
bytehideLogsobject-ByteHide Logs integration

File Logging

FieldTypeDefaultDescription
enabledbooleanfalseEnable file logging
pathstring"logs/bytehide-monitor.log"Log file path
maxSizeMBnumber10Max file size before rotation
maxFilesnumber5Number of backup files

ByteHide Logs Integration

Requires the ByteHide Logger integration.

FieldTypeDefaultDescription
enabledbooleanfalseEnable ByteHide Logs
tokenstring-ByteHide Logs API token
persistbooleantruePersist logs locally when offline
filePathstring-Offline persistence path
maskSensitiveDataarray-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
      }
    ]
  }
}

Rate Limiting

FieldTypeDefaultDescription
enabledbooleanfalseEnable rate limiting
maxRequestsnumber100Max requests per window
windowSizeInMSnumber60000Time window in milliseconds

Anomaly Detection

FieldTypeDefaultDescription
enabledbooleanfalseEnable anomaly detection
detectIpChangesbooleantrueDetect IP address changes
detectUserAgentChangesbooleantrueDetect User-Agent changes
detectSuspiciousPatternsbooleantrueDetect suspicious patterns

Endpoint-Specific Configuration

Override protections for specific routes:

FieldTypeDescription
methodstring"GET", "POST", "PUT", "DELETE", "*" (all)
routestringRoute pattern (e.g., "/api/users/{id}", "/admin/*")
forceProtectionOffbooleanDisable ALL protections for this endpoint
protectionsobjectEndpoint-specific protection overrides
rateLimitobjectEndpoint-specific rate limit

Environment Variables

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

JSON
{
  "projectToken": "${BYTEHIDE_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:

  1. BYTEHIDE_MONITOR_TOKEN environment variable
  2. BYTEHIDE_TOKEN environment variable
  3. projectToken value in the JSON file

Complete Example

Desktop application with comprehensive configuration:

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

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

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

Web application with cloud features:

JSON
{
  "name": "My Web API",
  "enabled": true,
  "projectToken": "${BYTEHIDE_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": {
    "DebuggerDetection": {
      "enabled": true,
      "action": "close",
      "intervalMs": 30000
    },
    "VirtualMachineDetection": {
      "enabled": true,
      "action": "log",
      "intervalMs": 120000
    },
    "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.

Next Steps

Cloud Configuration

Configure protections from the web dashboard with real-time sync

Configuration API

Code-based configuration for custom actions and programmatic control

Protection Modules

Complete reference of all available protection modules

Actions

All action types and when to use each one

Previous
Cloud Configuration
Next
Configuration API