moatgator.yml reference

moatgator.yml is your protection policy as code. It lives in your repository, goes through review like any other file, and is validated by the CLI, the console, the API and the GitHub App with the same rules.

Editor support

Put this on the first line to get autocomplete and inline errors in VS Code (Red Hat YAML extension) or IntelliJ:

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

A copy of the schema is published with these docs at /schema/moatgator.schema.json.

A complete example

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=

# Values that apply to one environment only. They win over everything above.
env:
  staging:
    runtime: { root: monitor, hooking: warn }

Keys

Key	Type	What it does
version	1	Contract version. Always 1 today.
extends	profile or list of up to 3	Starting profile(s). Applied in order.
app.android.package	string	Android package name, for example com.acme.pay.
app.ios.bundleId	string	iOS bundle id. Letters, digits, hyphens and dots only (no underscore).
shield.strings	boolean	Encrypt sensitive strings.
shield.assets	boolean	Protect bundled assets.
shield.names	boolean	Obfuscate class, method and field names.
runtime.<detection>	response	One response per detection.
attest.enabled	boolean	Turn on device and app integrity attestation.
pulse.alerts.slack	string	Slack channel (#channel) that receives alerts.
network.pinning	boolean or object	true or false to turn certificate pinning on or off, or an object with the pins.
network.pinning.pins	list of sha256/…	SHA-256 fingerprints of the public keys you accept. Include a backup pin.
env.<production|staging|development>	object	Overrides for one environment. Accepts shield, runtime, attest, pulse and network.

At least one of app.android.package or app.ios.bundleId is required. Unknown keys are errors (a typo never silently disables protection).

Responses

Response	Meaning
monitor	Report only. The app takes no action.
warn	Report the event as a warning. The user is not blocked.
block	Refuse the sensitive action.
block_sensitive_screens	Block only the screens you mark as sensitive (payment, login). Meant for the payment-screen detections.
terminate	End the session. end_session is the same response under another name.

Anything you do not list stays in monitor. A new detection or feature never blocks anything until you ask.

What your plan allows

The plan sets which responses and detections you can use. The free plan (Hatchling) allows monitor and warn; paid plans add block and terminate. The five core detections (root, emulator, debugger, hooking, tamper) are in every plan; the four payment-screen detections start at Scale. A policy that asks for more than the plan allows is refused with a message saying which plan you need; monitor is always allowed, so a generated file with every key in monitor fits any plan. If you downgrade, entries above the new plan go back to monitor (the console warns you before you confirm). Current limits are on the pricing page.

Profiles

Profile	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

Order of application: the profiles (in extends order), then the file's runtime, then the requested env.

Environments

For the environment you name, env.<name> values win over the top level; any other environment uses the top level. A common pattern is to loosen staging and keep production strict.

Validate

npx moatgator validate                 # moatgator.yml in the current folder
npx moatgator validate path/to/moatgator.yml --json

Each error shows the file, line, column and key path. In pull requests, the Moatgator check annotates the same errors on the changed lines and lists policy changes in plain language, marking each as stricter or looser.

Status

The engine does not apply this policy to a protected package yet (preview). The file is validated, versioned, diffed and stored today. See limits and guarantees.