Concepts
Key notions for reading the console and events: checkpoint, 4 outcomes, catalogue, channels, categories, policies.
This page defines the vocabulary used throughout MaelGard. Each term is stable across screens. A given word always maps to the same notion in the console, the agent and exports.
Checkpoint
The checkpoint is the local TLS proxy embedded in the agent. It receives traffic redirected by the driver, decides whether the flow targets an active AI service, and enforces the policy. It stays on the device.
- It never opens a flow whose domain is not in the catalogue.
- It issues leaf certificates on the fly, signed by a device-local CA.
- It relays responses without buffering or analysis.
- It writes a signed event for every interception.
The 4 outcomes of a request
Any request to an active AI service ends in one of the four outcomes below. The names are fixed in the console, events and exports.
| Outcome | Effect on the request | Window shown |
|---|---|---|
| Allowed | Sent as is, no sensitive data detected above threshold. | No |
| Masked | Detected values are replaced by labels such as [EMAIL_1] or [IBAN_1]. | No, unless policy requires it |
| User decides | The request is held. The user chooses to obfuscate, edit, send without protection, or cancel. | Yes |
| Blocked | The request is rejected. The user receives a notification. | No |
AI service catalogue
The catalogue lists AI services recognised by the agent. Each entry describes the domain, paths, channel and prompt field extraction rule. It is signed by the vendor.
- Vendor catalogue : list published by MaelGard, signed with Ed25519. The agent checks the signature before loading.
- Local catalogue : customer-specific additions for internal AI and private APIs. Signed with the tenant key.
- Merge : both catalogues are merged on the device. In case of conflict on an entry, the local catalogue wins.
- Updates : pushed by the server or a vendor CDN, depending on configuration.
Channels
A channel denotes a usage family. Each channel is activated independently by policy. An inactive channel is not decrypted. A channel in observation mode is analysed but no request is held.
| Channel | Rule | Examples |
|---|---|---|
| Web interface | Signed browser process + web-tagged domain | chatgpt.com, claude.ai, gemini.google.com |
| Desktop application | Process identified by the catalogue | ChatGPT Desktop, Claude Desktop, Copilot |
| Direct API | API-tagged domain, non-browser and non-IDE process | api.openai.com, api.anthropic.com |
| Code assistant | Known IDE process or code-tagged domain | VS Code, Visual Studio, JetBrains, Cursor |
| Internal AI | Domain or IP declared by the customer | Internal LLM gateway, in-house Ollama |
Detection categories
A category groups the entity types that the engine can detect: identifiers, banking data, technical secrets. Each category carries a severity, a threshold and a default action.
| Category | Edition | Severity |
|---|---|---|
| Personal data (PII) | Essential | High |
| Health | Advanced | Critical |
| Finance | Advanced | High |
| HR and legal | Advanced | High |
| Technical secrets | Advanced | Critical |
| Infrastructure | Advanced | Medium |
Policy and actions
Each category carries a default action. The effective action for an interception is the strictest of the categories detected.
| Action | Effect | Window |
|---|---|---|
log | Sent unchanged, event created | No |
auto_obfuscate | Obfuscation applied without user action | No, quiet notification |
ask | Request held, user chooses | Yes |
block | Request rejected without choice | No |
Override priority order
A policy applies to every device by default. Overrides can target a group, a channel or a service. When overrides overlap, the most specific wins: service, channel, user group, device group, default.
Exceptions and memory
- Exceptions : allow list by exact value, pattern, approved AI service, process, user or group.
- Fingerprints : allow-listed values are stored as HMAC fingerprints, never in clear.
- Remember : the user can tick remember this choice. Scope is set by the administrator, from the Windows session to N days.
- Expiry : each exception carries an optional expiry date and an author.