DocumentationConcepts

Concepts

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.

The four possible outcomes of a request.
OutcomeEffect on the requestWindow shown
AllowedSent as is, no sensitive data detected above threshold.No
MaskedDetected values are replaced by labels such as [EMAIL_1] or [IBAN_1].No, unless policy requires it
User decidesThe request is held. The user chooses to obfuscate, edit, send without protection, or cancel.Yes
BlockedThe 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.

The five supported channels and their classification rule.
ChannelRuleExamples
Web interfaceSigned browser process + web-tagged domainchatgpt.com, claude.ai, gemini.google.com
Desktop applicationProcess identified by the catalogueChatGPT Desktop, Claude Desktop, Copilot
Direct APIAPI-tagged domain, non-browser and non-IDE processapi.openai.com, api.anthropic.com
Code assistantKnown IDE process or code-tagged domainVS Code, Visual Studio, JetBrains, Cursor
Internal AIDomain or IP declared by the customerInternal 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.

Shipped categories and proposed default severity.
CategoryEditionSeverity
Personal data (PII)EssentialHigh
HealthAdvancedCritical
FinanceAdvancedHigh
HR and legalAdvancedHigh
Technical secretsAdvancedCritical
InfrastructureAdvancedMedium

Policy and actions

Each category carries a default action. The effective action for an interception is the strictest of the categories detected.

Possible actions for a category.
ActionEffectWindow
logSent unchanged, event createdNo
auto_obfuscateObfuscation applied without user actionNo, quiet notification
askRequest held, user choosesYes
blockRequest rejected without choiceNo

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.