DocumentationPolicy and catalog

Policy and catalog

Policy and catalog

MaelGard policy format, AI service catalog, data categories, detection models, two-eyes review and signed publication.

A MaelGard policy is the configuration applied by device agents. It describes channel states (observe, protect), monitored data categories, obfuscation, blocking and bypass rules, as well as overrides by group, channel or service.

It is produced in the console, reviewed by another person, then published as a signed JSON document (Ed25519 JWS). Agents verify the signature before applying the configuration.

1. Policy format

A policy is a structured JSON document. The main sections are parameters (settings), overrides (overrides), client catalog (catalog_client), categories (categories) and bypass rules (bypass_rules).

{
  "settings": {
    "channels.web.state": "protection",
    "channels.desktop.state": "protection",
    "channels.api.state": "observation",
    "channels.code.state": "protection",
    "policy.bypass.global": false,
    "interception.monitored_ports": [80, 443, 8443],
    "sync.server_url": "https://maelgard.example",
    "sync.tenant_id": "acme",
    "sync.pseudonymization_key": "<base64 Ed25519 key>"
  },
  "overrides": [
    {
      "scope": { "group": "legal" },
      "settings": { "categories.health.threshold": 5000 }
    },
    {
      "scope": { "channel": "api", "service": "azure-openai-corp" },
      "settings": { "policy.bypass.global": true }
    }
  ],
  "catalog_client": [
    {
      "id": "internal-assistant",
      "domains": ["ai.acme.example"],
      "channels": ["web", "api"],
      "min_agent_version": "1.4.0"
    }
  ],
  "categories": [
    {
      "id": "pii",
      "severity": "high",
      "default_action": "ask",
      "threshold": 7000,
      "bypass_allowed": true,
      "placeholder": "PII"
    }
  ]
}

2. Parameters (settings)

Parameters are dotted paths with a typed value. A missing parameter takes the vendor default. The main families:

FamilyParameters
ChannelsState per channel (off, observe, protect); monitored ports; redirection mode; QUIC blocking scope.
CatalogClient entries; policy for pinned applications; CA injection into developer tools.
CategoriesEnablement, severity, default action, threshold, bypass_allowed, placeholder, engine type mapping.
PoliciesGlobal bypass; bypass per group, channel, service; bypass reasons; justification length; choice memorisation.
AnalysisTimeouts; max size; extraction limits; fail-open or fail-closed per cause and per channel.
Device UIDecision timeout; decision without user; value masking; dashboard views.
ReportingServer; mode (real-time, batch, deferred); frequency; pseudonymisation; SIEM destinations.
AdministrationLocal admins group; locally editable parameters; uninstall token.

A parameter marked "locked" in the policy cannot be changed by an override, and no lower-priority source can modify it (central server, local config, vendor defaults).

3. Overrides

Overrides adapt parameters to a subset of the fleet: a device group, a user group, a channel or a service. They apply to the same keys as global parameters.

Resolution: with multiple overrides, the most specific wins, in the order service > channel > user group > device group > default. At equal specificity, the most restrictive wins.

{
  "overrides": [
    { "scope": { "group": "soc" },      "settings": { "policy.bypass.global": true } },
    { "scope": { "channel": "web" },    "settings": { "channels.web.state": "protection" } },
    { "scope": { "service": "chatgpt" }, "settings": { "categories.secrets.default_action": "block" } }
  ]
}

4. Catalog: vendor and client

Vendor catalog

The vendor catalog is provided by MaelGard and updated by signed vendor bundles. It describes recognised public AI services (ChatGPT, Claude, Gemini, Mistral, Copilot), their domains, access paths and body format. It is read-only in the console.

Client catalog

The client catalog adds your own services: internal tool, client Azure OpenAI instance, unreferenced service. Each entry declares:

  • identifier (stable technical key);
  • channels (web, desktop app, API, code tool);
  • domains (hosts and optional access paths);
  • JSONPath extraction paths to isolate request fields to analyse;
  • minimum agent version required to apply the rule.

The client catalog goes through the same review cycle as the policy. It is published alongside, signed, then distributed to agents.

5. Data categories

Categories group the entity types returned by the engine. When a request contains several categories, the decision applies the most restrictive rule, and bypass is only offered if all detected categories allow it.

Category attributes.
AttributeTypeDescription
idstable stringTechnical key, e.g. pii, health, finance.
parentid or emptyEnables sub-categories (pii.national_id).
enabledbooleanCategory active or not.
severitylow / medium / high / criticalDisplay order and entity merging.
default_actionask, auto_obfuscate, block, logDefault decision applied on the device.
thresholdinteger 0 to 10,000Minimum score to keep an entity.
bypass_allowedbooleanBypass allowed for this category.
placeholderstringObfuscation label root, e.g. EMAIL produces [EMAIL_1].
engine_typeslistEngine entity types attached.
modelslistRequired detection models.
Default actions.
ActionEffectDialog shown
blockRequest rejected with no choice.No — notification only.
askRequest held, obfuscation preselected.Yes.
auto_obfuscateObfuscation applied without interaction.No — discreet notification.
logRequest sent as is, event created.No.

A channel in observe mode forces action log regardless of category. The effective action is the most restrictive of detected categories, in the order block > ask > auto_obfuscate > log.

6. Detection models

Detection models are signed libraries, loaded by agents based on configuration. A model listed in the catalog is not necessarily loaded by every device: selection depends on active categories and language.

Available models.
ModelLanguagesCovered categoriesState
pii-baselinefr, enPII (name, address, phone, email, national IDs), IBAN, payment cards.Available.
secrets-baselineagnosticAPI keys, tokens, passwords, private keys, connection strings.Available.
pii-advancedfr, enHealth, HR, legal, confidential business, internal infrastructure.Coming soon.

7. Bypass rules

Bypass is offered to the user only if the following four conditions are met: global bypass allowed, allowed for every detected category, allowed for the user or their group, allowed for the channel and the AI service.

{
  "bypass_rules": {
    "global": false,
    "require_justification": true,
    "min_justification_length": 20,
    "allowed_reasons": [
      "public_data",
      "test_without_real_data",
      "business_agreement"
    ],
    "memory": { "scope": "session", "allow_bypass_memory": false }
  }
}

Memorising an obfuscation choice targets the pair (value fingerprint, AI service). Memorising a bypass is a separate setting, disabled by default.

8. Draft to Publish cycle

Every policy change follows a four-step cycle: Draft · In review · Approved · Published. A draft may also be Rejected; the reason is sent to the author.

  1. Draft: the security admin (or DPO for privacy settings) edits parameters, overrides and client catalog. Saving applies nothing.
  2. Simulation (optional): count of devices and people affected, preview of the resulting configuration, test on fictional text.
  3. Submit for review: the draft is no longer editable. Another person is notified for review.
  4. Approve or Reject: by someone other than the author, holding the role required by the draft content.
  5. Publish: the configuration is signed with the client key, then notified to relevant agents.

9. Two-eyes review

Two-eyes review requires a person distinct from the author to approve publication. The reviewer must hold the role matching the draft content.

Draft contentRequired reviewer role
Privacy settings onlyDPO
Other parameters, client catalogSecurity admin
Draft mixing bothA single person holding both roles

10. Signature and agent-side verification

The published policy is signed with the client key (Ed25519) in a compact JWS envelope. The agent verifies it on receipt with the ConfigPublicKey public key provided at install (MSI property, Windows policy, or Linux installer parameter).

  • Signing key rotation is done through a document signed with the previous key (chained rotation).
  • A mis-signed or invalid policy is rejected as a whole. The agent keeps the previous configuration and creates a configuration event.
  • Each applied configuration is versioned by fingerprint. The agent reports this fingerprint to the server, which displays it on the device page.
  • Changes apply without restarting the service or the session, except for the driver redirection mode, which takes effect at the next sign-in.

11. Common errors and diagnostics

SituationDiagnostic
Agent refusing the policyCheck the signature with the ConfigPublicKey key and the configuration events on the device page.
Override with no effectA parameter locked by the global policy cannot be overridden. Unlock it or reach out to the lock author.
Bypass refused for the userAt least one detected category forbids bypass, or the channel / service / group does not allow it. Check the event detail.
Pseudonymisation key missingApproving a re-identification requires sync.pseudonymization_key in the published policy.
Model not loaded by a deviceA model is loaded only if the matching category is active and the language declared. Check the device page.