Referência do moatgator.yml

O moatgator.yml é a sua política de proteção como código. Ele fica no seu repositório, passa por revisão como qualquer outro arquivo e é validado pelo CLI, pelo console, pela API e pelo GitHub App com as mesmas regras.

Suporte no editor

Coloque isto na primeira linha para ter autocompletar e erros no próprio editor, no VS Code (extensão YAML da Red Hat) ou no IntelliJ:

# yaml-language-server: $schema=https://api.moatgator.com/v1/schema/moatgator.json

Uma cópia do schema é publicada junto destas docs em /schema/moatgator.schema.json.

Um exemplo completo

moatgator.yml

version: 1
extends: moatgator:recommended

app:
  android: { package: com.acme.pay }
  ios: { bundleId: com.acme.pay }

shield: { strings: true, assets: true, names: true }

runtime:
  root: block
  hooking: terminate
  overlay: block_sensitive_screens

attest: { enabled: true }

pulse:
  alerts:
    slack: "#security"

network:
  pinning:
    pins:
      - sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=
      - sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=

# Valores que valem só para um ambiente. Eles vencem tudo o que está acima.
env:
  staging:
    runtime: { root: monitor, hooking: warn }

Chaves

Chave	Tipo	O que faz
version	1	Versão do contrato. Hoje é sempre 1.
extends	perfil ou lista de até 3	Perfil(is) de partida. Aplicados em ordem.
app.android.package	string	Nome do pacote Android, por exemplo com.acme.pay.
app.ios.bundleId	string	Bundle id do iOS. Só letras, dígitos, hífens e pontos (sem sublinhado).
shield.strings	booleano	Cifrar strings sensíveis.
shield.assets	booleano	Proteger os assets embutidos.
shield.names	booleano	Ofuscar nomes de classes, métodos e campos.
runtime.<detecção>	resposta	Uma resposta por detecção.
attest.enabled	booleano	Ligar a atestação de integridade do aparelho e do app.
pulse.alerts.slack	string	Canal do Slack (#canal) que recebe os alertas.
network.pinning	booleano ou objeto	true ou false para ligar ou desligar o certificate pinning, ou um objeto com os pins.
network.pinning.pins	lista de sha256/…	Impressões digitais SHA-256 das chaves públicas que você aceita. Inclua um pin de reserva.
env.<production|staging|development>	objeto	Sobrescritas para um ambiente. Aceita shield, runtime, attest, pulse e network.

É obrigatório ter pelo menos um entre app.android.package e app.ios.bundleId. Chaves desconhecidas são erros (um erro de digitação nunca desliga a proteção em silêncio).

Respostas

Resposta	Significado
monitor	Só reporta. O app não toma nenhuma ação.
warn	Reporta o evento como aviso. O usuário não é bloqueado.
block	Recusa a ação sensível.
block_sensitive_screens	Bloqueia só as telas que você marcar como sensíveis (pagamento, login). Pensada para as detecções de telas de pagamento.
terminate	Encerra a sessão. end_session é a mesma resposta com outro nome.

Tudo o que você não listar fica em monitor. Uma detecção ou um recurso novo nunca bloqueia nada até você pedir.

O que o seu plano permite

O plano define quais respostas e detecções você pode usar. O plano gratuito (Hatchling) permite monitor e warn; os planos pagos acrescentam block e terminate. As cinco detecções básicas (root, emulator, debugger, hooking, tamper) estão em todos os planos; as quatro detecções de tela de pagamento começam no Scale. Uma política que pede mais do que o plano permite é recusada, com uma mensagem dizendo qual plano você precisa; monitor é sempre permitido, então um arquivo gerado com todas as chaves em monitor serve em qualquer plano. Se você reduzir o plano, as entradas acima do novo plano voltam para monitor (o console avisa antes de você confirmar). Os limites atuais estão na página de preços.

Perfis

Perfil	root	emulator	debugger	hooking	tamper	overlay, a11y, capture, remote_access
moatgator:recommended	warn	monitor	warn	block	block	monitor
moatgator:strict	block	block	block	terminate	terminate	monitor
moatgator:pix-shield	warn	monitor	warn	block	block	block_sensitive_screens

Ordem de aplicação: os perfis (na ordem do extends), depois o runtime do arquivo e por fim o env pedido.

Ambientes

Para o ambiente que você nomear, os valores de env.<nome> vencem os do nível de cima; qualquer outro ambiente usa o nível de cima. Um padrão comum é afrouxar o staging e manter o production rígido.

Validar

npx moatgator validate                 # moatgator.yml na pasta atual
npx moatgator validate path/to/moatgator.yml --json

Cada erro mostra o arquivo, a linha, a coluna e o caminho da chave. Nos pull requests, o check da Moatgator anota os mesmos erros nas linhas alteradas e lista as mudanças de política em linguagem simples, marcando cada uma como mais rígida ou mais frouxa.

Estado

O motor ainda não aplica esta política a um pacote protegido (prévia). O arquivo é validado, versionado, comparado e guardado hoje. Veja limites e garantias.