🔧 Sandboxing
Visão Geral#
O sistema de Sandboxing do Caffeine Studio garante que os scripts de jogo operem num ambiente seguro e controlado. Ao contrário de uma aplicação Lua padrão, os scripts dentro do motor não devem ter acesso direto ao sistema de ficheiros do sistema operativo, execução de comandos externos ou manipulação de recursos críticos que possam comprometer a estabilidade do IDE ou a segurança do utilizador.
Este módulo redefine o ambiente global do Lua, removendo funções perigosas e substituindo-as por alternativas seguras fornecidas pela API caffeine.*. Isto permite que o motor corra scripts de terceiros (como plugins ou assets da comunidade) com um risco reduzido.
Implementação#
Políticas de Acesso#
A LuaVM configura o estado inicial restringindo as bibliotecas padrão.
| Categoria | Permitido | Bloqueado / Removido |
|---|---|---|
| Core API | caffeine.* |
os.*, io.* (exceto em modo editor) |
| Utilitários | math.*, string.*, table.* |
load, loadstring |
| Módulos | require (apenas módulos do projeto) |
package.loadlib |
| Debug | Nenhuma | debug.* |
Implementação do Restritor (C++)#
void LuaVM::applySandbox() {
// 1. Limpar bibliotecas perigosas
m_lua["os"] = sol::nil;
m_lua["io"] = sol::nil;
m_lua["package"] = sol::nil;
m_lua["load"] = sol::nil;
m_lua["loadfile"] = sol::nil;
m_lua["dofile"] = sol::nil;
// 2. Criar alternativa segura para 'os.clock' se necessário
auto os_safe = m_lua["os"].get_or_create<sol::table>();
os_safe["clock"] = []() { return Timer::GetTotalSeconds(); };
// 3. Redefinir 'require' para procurar apenas dentro da pasta 'scripts/' do projeto
m_lua.set_function("require", [this](std::string moduleName) {
return loadProjectModule(moduleName);
});
}
Diagrama de Isolamento#
[ SCRIPT LUA ]
|
v
+---------------------------+
| Environment Wrapper |
+-------------+-------------+
| SAFE API | BLOCKED API |
| (caffeine.*)| (os.exit) | ----> [ ERRO DE EXECUÇÃO ]
+-------------+-------------+
|
v
[ ENGINE CORE ]
Decisões de Design#
| Decisão | Justificativa |
|---|---|
| Whitelist approach | É mais seguro definir explicitamente o que é permitido do que tentar bloquear o que é proibido. |
Remoção total de io |
Garante que scripts não podem ler dados sensíveis do utilizador ou escrever ficheiros maliciosos fora da sandbox. |
Custom require |
Impede que scripts carreguem bibliotecas dinâmicas (.dll / .so) externas ao ecossistema do motor. |
Critério de Aceitação#
- [ ] Tentativas de chamar
os.execute()resultam num erro de script. - [ ] A biblioteca
ionão está acessível no ambiente global. - [ ] O acesso a
mathestringpermanece funcional. - [ ] O motor não crasha ao tentar executar uma função bloqueada.
Dependências#
- Upstream:
LuaVM - Downstream:
AssetManager(para o carregamento seguro de módulos)
🔗 Tópicos Relacionados#
| Tópico | Description |
|---|---|
docs/scripting/scripting.md |
Lista de APIs permitidas para programadores. |
docs/assets/asset-manager.md |
Como os scripts são resolvidos no sistema de ficheiros. |