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:
| Family | Parameters |
|---|---|
| Channels | State per channel (off, observe, protect); monitored ports; redirection mode; QUIC blocking scope. |
| Catalog | Client entries; policy for pinned applications; CA injection into developer tools. |
| Categories | Enablement, severity, default action, threshold, bypass_allowed, placeholder, engine type mapping. |
| Policies | Global bypass; bypass per group, channel, service; bypass reasons; justification length; choice memorisation. |
| Analysis | Timeouts; max size; extraction limits; fail-open or fail-closed per cause and per channel. |
| Device UI | Decision timeout; decision without user; value masking; dashboard views. |
| Reporting | Server; mode (real-time, batch, deferred); frequency; pseudonymisation; SIEM destinations. |
| Administration | Local 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.
| Attribute | Type | Description |
|---|---|---|
id | stable string | Technical key, e.g. pii, health, finance. |
parent | id or empty | Enables sub-categories (pii.national_id). |
enabled | boolean | Category active or not. |
severity | low / medium / high / critical | Display order and entity merging. |
default_action | ask, auto_obfuscate, block, log | Default decision applied on the device. |
threshold | integer 0 to 10,000 | Minimum score to keep an entity. |
bypass_allowed | boolean | Bypass allowed for this category. |
placeholder | string | Obfuscation label root, e.g. EMAIL produces [EMAIL_1]. |
engine_types | list | Engine entity types attached. |
models | list | Required detection models. |
| Action | Effect | Dialog shown |
|---|---|---|
block | Request rejected with no choice. | No — notification only. |
ask | Request held, obfuscation preselected. | Yes. |
auto_obfuscate | Obfuscation applied without interaction. | No — discreet notification. |
log | Request 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.
| Model | Languages | Covered categories | State |
|---|---|---|---|
pii-baseline | fr, en | PII (name, address, phone, email, national IDs), IBAN, payment cards. | Available. |
secrets-baseline | agnostic | API keys, tokens, passwords, private keys, connection strings. | Available. |
pii-advanced | fr, en | Health, 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.
- Draft: the security admin (or DPO for privacy settings) edits parameters, overrides and client catalog. Saving applies nothing.
- Simulation (optional): count of devices and people affected, preview of the resulting configuration, test on fictional text.
- Submit for review: the draft is no longer editable. Another person is notified for review.
- Approve or Reject: by someone other than the author, holding the role required by the draft content.
- 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 content | Required reviewer role |
|---|---|
| Privacy settings only | DPO |
| Other parameters, client catalog | Security admin |
| Draft mixing both | A 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
| Situation | Diagnostic |
|---|---|
| Agent refusing the policy | Check the signature with the ConfigPublicKey key and the configuration events on the device page. |
| Override with no effect | A parameter locked by the global policy cannot be overridden. Unlock it or reach out to the lock author. |
| Bypass refused for the user | At least one detected category forbids bypass, or the channel / service / group does not allow it. Check the event detail. |
| Pseudonymisation key missing | Approving a re-identification requires sync.pseudonymization_key in the published policy. |
| Model not loaded by a device | A model is loaded only if the matching category is active and the language declared. Check the device page. |