Sandbox Environment

For security reasons, the Lua scripting environment in CoCoCo runs in a sandboxed mode with certain potentially dangerous modules and functions disabled. This ensures scripts cannot access the file system, execute system commands, or load arbitrary code.

Disabled Modules and Functions

The following Lua standard library modules and functions have been removed from the sandbox:

File System Access

• io module: Complete I/O library disabled
  • Cannot read/write files directly
  • Cannot open file handles
  • Cannot manipulate file pointers
• file module: All file operations disabled

Operating System Access

• os.execute: Cannot run system commands
• os.exit: Cannot terminate the process
• os.getenv: Cannot read environment variables
• os.remove: Cannot delete files
• os.rename: Cannot rename/move files
• os.tmpname: Cannot create temporary files

Code Loading

• package module: Cannot load external Lua packages
• require: Cannot import modules
• dofile: Cannot execute Lua files
• load: Cannot compile Lua code strings
• loadfile: Cannot load and compile Lua files
• loadstring: Cannot compile strings as code (deprecated)

Available Alternatives

While these restrictions are in place, CoCoCo provides safe alternatives through its API modules:

Instead of File I/O

-- ❌ DISABLED: Direct file access
-- local file = io.open("data.txt", "r")
-- local content = file:read("*all")

-- ✅ USE: Database or cache storage
local success, data = database.query("storage-db",
    "SELECT content FROM files WHERE name = ?", {"data.txt"})

-- ✅ USE: Cache for temporary storage
cache.put("temp_data", content)
local content = cache.get("temp_data")

Instead of System Commands

-- ❌ DISABLED: System command execution
-- os.execute("rm -rf /tmp/old_files")

-- ✅ USE: API calls or database operations
database.query("maintenance-db",
    "DELETE FROM temporary_files WHERE created_at < ?",
    {cutoff_date})

Instead of Environment Variables

-- ❌ DISABLED: Reading environment variables
-- local api_key = os.getenv("API_KEY")

-- ✅ USE: Configuration passed through template data
local api_key = config.api_key  -- Passed from application

-- ✅ USE: Secure storage in database
local success, result = database.query("config-db",
    "SELECT value FROM settings WHERE key = ?", {"api_key"})

Instead of Dynamic Code Loading

-- ❌ DISABLED: Loading external code
-- require("custom_module")
-- dofile("scripts/helper.lua")

-- ✅ USE: Functions provided by the API
local result = template.render("helper-template", data)

-- ✅ USE: Pre-approved functions in templates
-- Functions can be associated with templates and executed safely

Working Within the Sandbox

Safe Data Persistence

-- Use cache for temporary data
function save_session(session_id, data)
    cache.put_ttl("session:" .. session_id, data, 3600)
end

-- Use database for permanent storage
function save_user_data(user_id, data)
    database.query("main-db",
        "INSERT INTO user_data (user_id, data_json) VALUES (?, ?)",
        {user_id, encoding.json(data)})
end

Safe External Communication

-- Use HTTP module for external APIs
local response = http.request({
    url = "https://api.example.com/data",
    method = "get",
    headers = {["Authorization"] = "Bearer " .. token}
})

-- Use GraphQL for internal data access
local success, data = graphql.query([[
    query { getSystemStatus { status uptime } }
]])

Safe Template Processing

-- Generate dynamic content safely
local html = template.render_raw([[
    <h1>{{ title | escape }}</h1>
    <p>{{ content | strip_html }}</p>
]], {
    title = user_input_title,
    content = user_input_content
})

Security Benefits

The sandbox provides several security benefits:

1. No File System Access: Scripts cannot read sensitive files or write malicious files
2. No Command Injection: Scripts cannot execute system commands
3. No Code Injection: Scripts cannot dynamically load or execute arbitrary code
4. Resource Isolation: Scripts operate within defined resource limits
5. Data Validation: All external data access goes through validated API channels

Best Practices in the Sandbox

1. Use API modules for all I/O operations

   -- Good: Use provided APIs
   local data = cache.get("key")
   local result = database.query(...)
   
   -- Bad: Trying to bypass restrictions (will fail)
   -- local file = io.open(...)  -- Not available

2. Store configuration in the database

   -- Store settings safely
   database.query("config-db",
       "INSERT INTO settings (key, value) VALUES (?, ?)",
       {"feature_enabled", "true"})

3. Use templates for dynamic content generation

   -- Safe template rendering with automatic escaping
   local output = template.render("email-template", {
       user_name = name,
       content = message
   })

4. Handle errors gracefully

   -- Always check for disabled functions
   local success, result = pcall(function()
       -- Your code here
   end)
   
   if not success then
       print("Operation failed: " .. result)
   end

The sandbox ensures that while scripts have powerful capabilities through the provided API modules, they cannot compromise system security or stability through direct system access.