CODLAB / Blog · AI & integration

Command Gate, Fail-Closed Grants and Consent-Bound BYOK AI Diagnostics in CardinalHost

15 Nov 2026 CODLAB Team 11 min

As of November 2026: CardinalHost (currently pre-launch and documented at cardinalhost.org) strictly separates AI-assisted diagnostics from command execution. Deterministic code classifies command risk and gates AI tool calls beforehand, enforces mandatory data previews plus explicit consent on file-read and command calls (with a 16 KiB source cap in leggi_file), and validates signed authorisation envelopes and input grants with mutation testing.

Why a Language Model Must Never Be the Security Boundary of Systems Administration

Whenever an AI diagnostic assistant inspects remote system logs, process tables or service configurations, its context window ingests untrusted external input. A crafted HTTP user-agent string inside an access log, a malicious container label or an unexpected filename can attempt indirect prompt injection against the model. If that model were wired directly to an interactive shell or unrestricted file-reading tool, two unacceptable failure modes would immediately arise: silent exfiltration of secrets and destructive or persistent host modification.

Probabilistic guardrails—asking a language model in its system prompt to “be careful and avoid dangerous commands”—cannot form a security boundary. In systems engineering, a security boundary exists only where deterministic, auditable code outside the model decides what may execute and what is rejected. That principle guides our work on CardinalHost in our projects research overview, complementing the native Linux Wayland and hybrid video transport architecture examined in our first article.

The Command Gate: Risk Classifier, AI Tool Gate and Envelope Verifier with 18 Rejection Reasons

On the client side in Swift, CardinalHost separates three distinct mechanisms: conservative risk classification of a shell command string (ClassificatoreRischioComando), the AI tool gate layered on top of it (StrumentiAIAgente and GateAIAgente), and cryptographic verification of signed capability envelopes (VerificatoreEnvelope).

First, ClassificatoreRischioComando evaluates each command string deterministically and conservatively (best-effort, highest matching risk wins) into three risk tiers: lettura is granted solely to whitelisted read-only commands in leading position with zero shell metacharacters, redirections or control characters; state-changing commands as well as any unknown command default conservatively to modifica (never lettura); irreversible patterns—such as rm -rf, dd of=, mkfs, shutdown/reboot, writes targeting system prefixes like /etc, /dev, /boot, /usr or /root, direct shell/eval invocations and inline interpreter flags (-c, -e, -r)—are classified as distruttivo. When a user API key is present (without a key, the gate stays spento), StrumentiAIAgente maps AI requests into three operational outcomes:

  • Automatic Execution (automatico): Strictly limited to three bounded metadata tools (leggi_salute, elenca_cartella, indice_cartella). Even read-only shell commands requested via esegui_comando never receive automatico, preventing silent exfiltration of file contents through cat or grep.
  • Explicit Human Consent (chiediConsenso): File content reads (leggi_file) plus esegui_comando requests classified as lettura or modifica—explicitly including unknown shell commands, which default to modifica and pause until a human operator reviews and approves them.
  • Hard Refusal (rifiuta): Any unknown AI tool absent from the registered tool catalogue and any command classified as distruttivo. Within the AI gate, rifiuta is terminal; by contrast, a closed binary allowlist rejecting every unlisted command belongs to the separate node-side PonteAI foundation brick below.

Separately from command risk classification, VerificatoreEnvelope validates signed capability envelopes (EnvelopeFirmato) immediately before execution at the sink on a fail-closed basis and distinguishes exactly 18 typed rejection reasons (MotivoNegazioneEnvelope): malformed token structure (malformato), unknown issuer (emittenteSconosciuto), invalid signature (firmaNonValida), invalid field format (campoNonValido), revoked epoch (revocato), mismatched tenant, host or sessione (tenantErrato, hostErrato, sessioneErrata), mismatched action verb or canonical argument hash (azioneErrata, argomentiDiversi), unauthorised subject (soggettoNonAutorizzato), malformed policy or policy insufficient for the real risk (policyMalformata, policyInsufficiente), excessive TTL, not-yet-valid or expired window (ttlEccessivo, nonAncoraValido, scaduto), and nonce replay or full nonce registry (replay, registroNoncePieno).

Subsystem Verified State Today (November 2026) Explicitly Declared Scope Boundary / Next Milestone
Client Risk Classifier & AI Tool Gate Risk tiers (lettura / modifica / distruttivo; unknown commands → modifica) and AI gate (automatico metadata only, chiediConsenso incl. unknown commands, rifiuta for unknown tools or distruttivo) tested Best-effort risk classification for the AI and command gate; no closed binary allowlist in the client, and the interactive SSH terminal remains a separate explicit path for administrators
Envelope Verifier & Input Grants VerificatoreEnvelope with 18 typed rejection reasons; fail-closed input grants with expiry and instant revocation Offline third-party verifiable cryptographically signed effect receipts across the full product chain are under construction
Node-Side Enforcement (PonteAI) First shell-free foundation brick verified on the test bench with closed catalogue (uname -sr, uptime) and mutation testing Wiring to the remote dispatcher, consent UI and full product execution paths on the remote node is in active construction

Stating these boundaries plainly is essential to engineering honesty: we do not claim to restrict what a human administrator types into an unrestricted SSH terminal, and we distinguish clearly between the client-side gate running today and the node-side enforcement and signed receipt layers currently being expanded.

Fail-Closed Grants and Why Passing Unit Tests Alone Are Not Enough

Both remote desktop input permissions and approved actions in CardinalHost are represented as explicit capability grants carrying scope, an expiration timestamp (expiry) and immediate revocation state. Whenever a field is missing, a clock check fails or revocation has been triggered, the verifier defaults strictly to fail-closed rejection.

In security-critical code, however, ordinary unit tests can achieve high line coverage while missing subtle boundary bugs—such as a < comparison accidentally written as <=, or an expiry check inadvertently skipped when an optional field is null. We therefore verify CardinalHost’s grant and authorisation logic using mutation testing: automated test harnesses deliberately inject code-level sabotage mutants into the verifier and assert that the test suite detects and kills every mutant. If a sabotaged verifier passes the tests, we treat the test suite itself as defective.

Lessons from Our Adversarial Review of BYOK AI Diagnostics and Write Guards

For optional AI-assisted troubleshooting, CardinalHost follows a strict Bring Your Own Key (BYOK) architecture: users store their own provider API key in the operating system’s native credential vault (macOS Keychain or GNOME Keyring on Linux). CodLab charges zero markup (€0 margin on token usage) and operates no central AI proxy inspecting customer prompts. For host health diagnostics (DiagnosiAI), CardinalHost requires explicit diagnostic opt-in and displays a mandatory data preview (anteprimaLeggibile) derived directly from the serialised status fields before anything leaves the machine.

During our internal adversarial security review in August 2026, we examined both the AI diagnostic boundary (GateAIAgente and DiagnosiAI) and the separate agent file-management write surface, establishing three distinct controls with explicit boundaries:

  1. Per-Action Consent, 16 KiB Source Cap in leggi_file and Post-Read Output Truncation: So that indirect prompt injection inside a log entry cannot silently exfiltrate arbitrary files in an autonomous loop, both leggi_file and read-only commands via esegui_comando are excluded from automatico and require explicit per-action human consent (chiediConsenso) whenever a user API key is configured. Only leggi_file single-quotes the approved path with option termination (--) and runs head -c 16384, capping the read at 16 KiB at the source, whereas an approved esegui_comando call executes the confirmed command without that source cap; when the returned tool output (across elenca_cartella, leggi_file or esegui_comando) exceeds 8,192 characters, limita retains the first 8,192 characters and appends the 11-character marker …[troncato] (8,203 characters returned in total for pure ASCII text; because limita counts Swift characters rather than bytes, UTF-8 text with multibyte characters from leggi_file can still reach the full 16 KiB read at the source). Notably, leggi_file does not enforce an automatic path blocklist on reads—protection rests on human approval of the requested path or command.
  2. Preview Line Sanitisation: To prevent untrusted host strings (such as a newline embedded in an OS string or failed-service name) from forging phantom lines in the mandatory diagnostic preview, senzaACapo strips newlines and control characters specifically in the rendered field values of anteprimaLeggibile—preserving preview fidelity rather than acting as a universal prompt filter over arbitrary file contents.
  3. Separate realpath Anti-Persistence Guards on Agent Writes: Independently of AI file reads, a canonical path guard (_percorso_avvio_vietato) hardens the agent’s file-write and rename operations (file-carica, file-rinomina, file-crea-cartella). It resolves symlinks via realpath and deterministically blocks writes targeting persistence vectors such as ~/.ssh, login-shell startup files (.bashrc, .zshrc, .profile, .bash_aliases, .pam_environment, .netrc), systemd --user and user autostart directories.

We apply the same separation between trusted control logic and untrusted retrieved text in our enterprise AI systems—detailed in our Engineering Note on RAG source boundaries and indirect prompt injection defences and across our AI engineering and systems integration practice.

The First PonteAI Node Brick: Shell-Free Execution and Atomic Consumption

So that safety guarantees do not rely solely on client integrity, the Cardinal infrastructure repository develops PonteAI, the node-side execution verifier. Its first completed foundation brick (September 2026) demonstrates how tightly a remote diagnostic execution surface can be constrained:

  • 16 KiB Request Ceiling and Strict JSON Schema: Oversized or malformed payloads are rejected before command resolution begins.
  • Direct argv[] Execution Without a Shell: Commands execute as explicit argument arrays without invoking /bin/sh -c, neutralising shell metacharacters, command chaining and subshell expansion by construction.
  • Closed Command Catalogue: In this initial brick, only explicitly enumerated diagnostic commands (uname -sr and uptime) are valid; any unlisted binary or flag combination is refused.
  • SHA-256 Action Fingerprint, 60-Second Expiry and Single-Shot Consumption: Each authorisation binds action and arguments into a SHA-256 fingerprint, expires after 60 seconds, and is consumed atomically once to prevent replay within the validity window.
  • Non-Root Isolation and Hardened Local Audit Trail: Execution requires an unprivileged user (UID != 0), closes stdin, enforces a hard 5-second timeout, and appends structured JSONL audit records using 0600 permissions, O_NOFOLLOW symlink protection and explicit fsync durability.

In the recorded test-bench evidence of 14 September 2026 (macOS harness compiling the real classifier and AutoritaPermessi alongside mock model/channel adapters and a local uname -sr execution), this foundation brick passed 41 out of 41 behavioural tests and caught 6 out of 6 sabotage mutants. Equally important are the explicit limits of this first slice: the remote SSH/CLI verb --esegui-proposta, channel dispatcher, live consent UI dialog, Linux packaging and real AI provider adapter are not yet wired in this deliverable, and the local JSONL audit file—while filesystem-hardened—is not yet cryptographically signed.

Which Six Sabotage Mutants prove-sabotaggi.py Actually Executes

Whereas boundary properties such as the 60-second expiry window, SHA-256 binding, atomic single-shot removal, UID != 0 and 0600 file permissions are exercised by the 41 behavioural tests, prove-sabotaggi.py mutates temporary copies of PonteAI.swift across six specific sabotage cases, requiring each mutant to fail its designated behavioural assertion rather than merely failing to compile:

  • automatico-diventa-clic (Session Auto Treated as Click): Weakens origine == .clic so an automatic session grant masquerades as an explicit per-action click.
  • consenso-ampio (Overly Broad Capability Scope): Replaces the exact power check poteri == [a.potere] with true, testing whether a wide capability could authorise a specific action.
  • classificazione-saltata (Risk Classifier Bypassed): Forces ClassificatoreRischioComando.rischio to return .lettura, verifying that destructive or disguised inputs still fail downstream checks.
  • catalogo-aperto (Closed Catalogue Disabled): Bypasses CatalogoPonteAI.eseguibile(proposta.argv) != nil, testing whether unlisted binaries, scripts or root calls are caught even under a low risk label.
  • registro-inizio-saltato (Initial Audit Record Omitted): Deletes the pre-execution annota(.inizio, ...) call to confirm that an audit-log failure closes the gate before any process starts.
  • consenso-assente-esegue (Execution Without Valid Consent): Executes the command inside the .consensoNonValido error branch, proving that even read-only queries never run without valid consent.

Additional mutants—such as perturbing the 60-second clock comparison or JSONL file-mode bits directly—remain candidates for future expansion rather than part of this six-mutant log. Across the documented authorisation and PonteAI modules, pairing behavioural tests with explicit sabotage counter-proofs keeps the test suite honest.

“The Voice”: Local On-Device Spoken Warnings Without Cloud Transfer

Practical operator ergonomics do not always require cloud models. When supervising multiple hosts or watching for risk transitions during maintenance, CardinalHost provides spoken health and risk alerts (“The voice”) in the application’s active language. Speech synthesis runs entirely on the local device: it requires no AI API key, works offline, and transmits zero diagnostic text to external cloud speech services.

Frequently Asked Questions (FAQ)

Can the AI assistant in CardinalHost execute arbitrary shell commands on my servers on its own?

No. Language models in CardinalHost never receive direct shell access. In the AI tool gate, only three bounded metadata tools run automatically; file content reads as well as read-only, state-changing or unknown shell commands (conservatively classified as modifica) require explicit human consent, while unknown AI tools and commands classified as destructive are refused. Separately, VerificatoreEnvelope checks signed capability tokens with 18 typed rejection reasons.

Does CodLab route or store my server diagnostics when I use AI troubleshooting?

No. CardinalHost uses a Bring Your Own Key (BYOK) design: your API key stays in your operating system keychain with zero CodLab markup, no central CodLab AI proxy sits in the middle, and a mandatory data preview shows the exact payload before anything is sent to your chosen AI provider.

How does CardinalHost defend against indirect prompt injection reading sensitive files?

In the AI tool gate, neither leggi_file nor read-only shell commands via esegui_comando run automatically: both paths require explicit per-action human consent (chiediConsenso). Only leggi_file single-quotes the target path with -- and caps reads at the source at 16 KiB via head -c 16384, whereas an approved esegui_comando call executes the confirmed command without that source cap; when the returned tool output (across elenca_cartella, leggi_file or esegui_comando) exceeds 8,192 characters, limita retains the first 8,192 characters and appends the 11-character marker …[troncato] (8,203 characters returned in total for pure ASCII text; because limita counts Swift characters rather than bytes, UTF-8 text with multibyte characters from leggi_file can still reach the full 16 KiB read at the source). The leggi_file path does not enforce a read blocklist on file paths; canonical realpath blocks on ~/.ssh, shell startup files and autostart folders apply separately to agent file-write, rename and folder-creation operations.

Does the spoken warning feature (“The voice”) require an AI API key or internet connection?

No. Spoken status summaries and risk warnings are synthesised locally on the user device in the active application language, requiring no AI key and sending zero text to external cloud services.

Share this article

Comments

No comments yet. Be the first to comment!

Leave a comment

Will not be published

Related Articles

Project on your mind?

We develop tailored software and AI solutions. Let's start your next project together.

Free initial consultation