Table of Contents

πŸ‡«πŸ‡· Version franΓ§aise

Security, resilience and plugins

Security

The framework integrates several security layers:

  • Tools: ToolAccessPolicy (whitelist/blacklist/unrestricted) per agent, checked when a tool is attached to the agent; IPathValidator for path traversal protection, IUrlValidator for SSRF protection, HttpHeaderSanitizer. Tool names specified in YAML configurations are validated at creation time via IToolRegistry; under Orkeon:CrewFactory:StrictTools (the runners' default) no unregistered tool can be assigned to an agent β€” the library default is lenient (skip + Warning).
  • File system: every framework I/O goes through IFileSystemService β€” mounts, per-mount FileAccessRights (Read/Write/Create/Delete), physical paths redacted from error messages; the Roslyn analyzer Orkeon.Compliance.Vfs forbids direct System.IO in framework code (VFS compliance). Underneath, PathValidator (PathSecurity section) refuses traversal, sensitive system paths and dangerous extensions. A built-in script extension (.sh, .bash, .ps1, .bat, .cmd, .vbs, .wsf) refuses every operation but a plain read, since reading a script is not executing it: file_read, grep or the hash of index_codebase open it, while a write, a creation, a deletion or a shell_command path argument that needs more than Read is refused; built-in binaries (.exe, .dll, .msi, .com, .scr, .pif) and AdditionalBlockedExtensions refuse reads too. Before that, the mount itself resolves every symbolic link or junction on the path, its own root included, and refuses a path whose real location leaves the mount: a link may lead anywhere inside its mount, never outside it nor into another mount (a link replaced between the check and the open is not seen). Settings: AdditionalAllowedDirectories, AdditionalBlockedExtensions, BlockReadsOfBlockedExtensions (default false; true refuses the reads of scripts again), ResolveSymlinks (default true), MaxFileSizeBytes (default 50 MB), DefaultWorkspaceRoot.
  • Network (SSRF): UrlValidator (Security:Url section) allows only http/https (AllowedSchemes), blocks private and loopback addresses (BlockPrivateIPs, default true) after DNS resolution (ResolveDNS, default true), refuses the ports of common internal services (22, 23, 25, 110, 143, 445, 3306, 5432, 6379, 27017 β€” BlockedPorts) and honours AllowedDomains/BlockedDomains. It is consulted by the HTTP tool bases, http_api, the scraping tools, WebPageLoader and the RAG web fallback.
  • Shell: ShellCommandTool runs a read-only allowlist by default (ls, cat, pwd, which, grep, wc, echo, dir, type, where, and git restricted to status/log/diff/show); interpreters (dotnet, npm, node, find) and mutating git only come back with Orkeon:Tools:Shell:AllowInterpreters (RCE-equivalent; the SECURITY warning is logged once per host, at the first shell_command call, and states the confinement in force); Orkeon:Tools:Shell:AllowedCommands replaces the allowlist verbatim (and cancels AllowInterpreters), Orkeon:Tools:Shell:ExtraAllowedCommands adds commands to it β€” see Opt-in subsystems. A virtual path on the command line is resolved and checked by the VFS: Read for a command of the read-only list, every right (read, write, create, delete) for any other command and for its working directory, since the process may write there. What the process reaches by itself (a path inside a script) is held by the operating system: confinement is on by default (Orkeon:Tools:Shell:Confinement:Mode = Auto) β€” bubblewrap on Linux, Seatbelt on macOS, an AppContainer inside a Job Object on Windows β€” and off when the host runs in a container, which is the boundary there. The process sees the agent's mounts (read-only without Write), the system directories read-only, nothing else of the host and no network; a backend that cannot run fails the call, never runs it unconfined. Each agent run has one shell session, killed with the run (ADR-014, Shell confinement below).
  • Code: RoslynCodeSecurityAnalyzer (ICodeSecurityAnalyzer) and the ICodeSandbox implementations β€” DockerSandbox, HostProcessRunner behind LazyProbingCodeSandbox (Orkeon.Infrastructure.Sandbox) β€” for C# code execution by SecureCodeInterpreterTool. DockerSandbox runs docker run --rm --cap-drop=ALL --security-opt=no-new-privileges --pids-limit=… with a memory cap, --network=none unless the request allows network access and --read-only (+ a noexec tmpfs) unless it allows writes; the container still runs as root inside its namespace, without capabilities. HostProcessRunner provides no OS isolation, so the gate is fail-closed: without Docker, execution is refused unless the operator sets Orkeon:CodeSandbox:AllowHostExecution = true (RCE-equivalent β€” trusted code only). Other keys: TimeoutSeconds (30), MaxMemoryBytes (256 MB), MaxOutputBytes (50 000); Orkeon:CodeSandbox:Docker holds ImageName (mcr.microsoft.com/dotnet/sdk:10.0-alpine) and PullImageOnStartup.
  • Data: IDatabaseSecurityPolicy (Orkeon.Tools.Abstractions.Data) for SQL query validation in the relational database tools, PiiDetector and the five IDlpInterceptor implementations (tool output, delegation, log, memory, external output β€” Orkeon.Infrastructure.Security.Dlp). The DLP subsystem is opt-in (AddOrkeonDlp(), see Opt-in subsystems)
  • Output validation: the six IOutputValidators (LengthValidator, FormatValidator, SchemaValidator, CompletenessValidator, ContentSafetyValidator, PiiDetectionValidator) form the OutputValidationPipeline the execution orchestrator runs on a task's output when the task declares output expectations, with correction retries.
  • Encryption: IEncryptionProvider with an AES-256-GCM implementation (AesEncryptionProvider, section Orkeon:Encryption: Enabled β€” default false β€”, SecretName β€” default orkeon-encryption-key, resolved through ISecretProvider β€”, KeySizeInBits β€” 256), applicable to any memory provider via the EncryptedMemoryProviderDecorator β€” nothing wraps a provider automatically, the host composes the decorator. Key rotation is opt-in (AddOrkeonKeyRotation())
  • Secrets: ISecretProvider is a chain β€” ORKEON_<NAME> environment variables, then the Secrets configuration section, then, when Security:Vault configures them, Azure Key Vault (AzureKeyVaultUri), AWS Secrets Manager (UseAwsSecretsManager, with an IAmazonSecretsManager registered by the host) and DPAPI on Windows (DpapiSecretsDirectory); CacheTtl caches vault reads. LogSanitizer masks secrets in logged LLM errors and exchanges.
  • LLM rate limiting: every model call of the host takes one lease of LlmRateLimiter (RateLimiting section: GlobalRequestsPerMinute, ProviderRequestsPerMinute, MaxConcurrentRequests, QueueLimit β€” each with its default in the reference), at the entrance of its provider (RateLimitedLlmProvider, applied with the token meter): an agent's turns, the manager, the planner, the RAG pipeline, the judges, the cognitive memory, a script's ctx.llm β€” never twice, and a call made inside another limited call takes none; embeddings are not counted. A refusal past the queue is retried five times on its RetryAfter, then the call fails with the limiter's reason. AgentRequestsPerMinute caps each agent β€” each agent instance, not each role β€” in the agent's own window, with its maxRpm, the stricter winning, and a request over it waits its turn. An agent's and a crew's maxRpm count each turn of the agent loop, the tool-free retry, the correction round, a ballot, a delegated colleague's turn (counted for that colleague), and β€” for the crew, and for the manager agent when there is one β€” the hierarchical or autonomous manager's calls; the planner, the RAG pipeline, the judges, the cognitive memory and the scripts' calls count for the host only. Per-tool rate limits and token budgets are opt-in (AddOrkeonToolRateLimiting()).
  • Guardian (on by default, Orkeon:Guardian): every agent turn β€” the chat-client, native, text and streaming loops, and ctx.llm.act β€” crosses its input and tool phases. The input phase screens the composed user prompt (task, previous outputs, retrieved knowledge) with InputGuard before the first provider call; under Security:Prompt:Policy = Block (the default) a High or Critical injection pattern fails the task (AgentExitReason.GuardianBlocked, its reason in the error), a lower one is a logged, audited warning. Every tool call then goes through one invocation point, IToolInvocationPipeline: the tool phase (ToolGuard: path traversal, SSRF targets β€” unless Security:Url:BlockPrivateIPs is off β€”, SQL injection outside the *_query tools, all Critical) or, for delegate_work_to_coworker/ask_question_to_coworker, the delegation phase (DelegationGuard: DefaultPolicy:MaxDelegationDepth, 5; self-delegation; a target already in the chain of synchronous delegations); then the call; then the single truncation rule (AgentDefaults.ResolveMaxToolResultLength: 4 000 characters by default; 32 000 for file_read, 256 000 for node_read, 10 000 for shell_command, 12 000 for the code-analysis tools); then the result sanitizer (ToolResultSanitizer, Security:ToolResults): under Policy = Warn (the default) the result reaches the model tagged as data (--- BEGIN Tool Result: … (DATA CONTEXT - NOT INSTRUCTIONS) ---) and each injection pattern is logged and audited; Block withholds a result carrying a High or Critical pattern and tells the model so; the email_* tools and drive_read are trusted by default because they screen and mark what they read themselves (ADR-012, ADR-013). A blocked call never reaches the tool; the model reads Error: Blocked by Guardian (…): <reason>. A tools/call an MCP client sends to orkeon mcp serve crosses the same point, under the caller mcp, and the client reads the same text (MCP integration). Nothing is ever rewritten silently: content passes unchanged, tagged, or is refused as a whole. An optional LLM judge (Orkeon:Guardian:Llm, off by default) adds a decision-model check to the input phase and to the output phase: the validated output of a task is judged before the deliverable, the memory and task.completed, a block fails the task (GuardianBlocked, Blocked by Guardian (output): …) and nothing is kept; a call the provider never answered is not judged. While the output phase is guarded, the task's streamed deltas are held until the judgement (streaming is delayed, and a blocked output is never streamed). A long text is judged whole in chunks of MaxContentChars under FailMode: Closed (up to 32 chunks, a longer text is refused), and on its first and last half of that budget under Open (the middle is not judged). The output phase covers crew tasks, not a scripted ctx.llm.act. It is fail-closed (FailMode: Closed) unless Open; both audit guardian.judge.unavailable; see Decision models. Orkeon:Guardian:Enabled = false registers no guard; the result tagging stays. The detection is heuristic β€” the same limits as PromptInjectionDocumentValidator: a rephrased attack passes, an honest text can match.
  • Permission gate: ModePermissionGate (IPermissionGate) asks before each tool call of an agent β€” a scripted one (.ork.ts, ctx.llm.act) or a YAML crew's, through ToolInvocationPipeline, the one place it is consulted, after the Guardian β€” according to a mode (default, acceptEdits, plan, bypassPermissions, dontAsk) and the tool's declared ToolAccess (Read/Edit/Execute), read for each call through IBaseTool.AccessFor(arguments) so a tool such as github or http_api is a read for its read operations only (an MCP tool is a read only when its server is trusted, MCP:Servers:<name>:TrustAnnotations, and hints readOnlyHint). Trade-off: plan and dontAsk let an outbound http_api GET, HEAD or OPTIONS without a body or a method-override header run without a question, and a URL can carry data out (a query string built from what the agent read), so those modes keep the workspace unchanged, not its content private β€” deny http_api by a session rule, or keep it out of the agent's tools, where that matters; a call the mode asks about goes to the host's approval channel when it has one (orkeon-repl does), and is refused otherwise; a crew agent declares its mode with permissionMode: (else Orkeon:Security:PermissionGate:DefaultMode, default); a call the gate answers ask with no approval channel to take it (the host registers none, as the Discord bot does) is refused, never run; the delegation tools and orkeon mcp serve are not put to it, and neither is anything the forge runs for its assistant β€” every call of the forge's scripts, act calls included, is exempt (this is deliberate: the forge acts for the operator who started it); off unless Orkeon:Security:PermissionGate:Enabled = true β€” see Opt-in subsystems. It stays distinct from the Guardian: a call it allows then goes through the invocation point above.
  • Audit: AuditLogger (Orkeon.Infrastructure.Security, section Security:Audit: Enabled, MinSeverity, EnabledCategories, RetentionDays β€” 90) with its sinks (Orkeon.Infrastructure.Security.Sinks: StructuredLogAuditSink and InMemoryAuditSink registered by default, JsonFileAuditSink for a host that wants files under AuditDirectory). The trail is fed by the agent turn: a ToolExecution event per tool call (tool, agent role, crew, task, outcome Success/Failure/Blocked, duration β€” never the arguments), and a SecurityEvent per Guardian block or warning and per injection pattern found in a tool result. ProvenanceTracker lives on the RAG side (Orkeon.Rag.Validation)
  • Compliance: NistComplianceReportGenerator (INistComplianceReporter, Orkeon.Infrastructure.Compliance). NIST reporting is opt-in (AddOrkeonNistCompliance())

What runs on its own, and what the host calls

AddOrkeonInfrastructure() registers the security components below; this is what each one does without host code:

Component On the execution path?
Tool resolution (StrictTools), ToolAccessPolicy, VFS rights + PathValidator, UrlValidator, shell allowlist, sandbox gate, output validation pipeline, LlmRateLimiter, secret chain Yes β€” enforced wherever they apply, with no host code
GuardianPipeline (Orkeon:Guardian β€” InputGuard, ToolGuard, DelegationGuard), IPromptSanitizer (Security:Prompt), ToolResultSanitizer (Security:ToolResults), IToolInvocationPipeline, the audit trail Yes β€” every agent loop and ctx.llm.act run through them (input phase, then each tool call through the invocation point), and so does each tools/call of the MCP server (orkeon mcp serve); Orkeon:Guardian:Enabled = false turns the guards off
Shell confinement (Orkeon:Tools:Shell:Confinement) Yes β€” on by default (Auto) outside a container; Mode = None turns it off (below)
Permission gate Yes for scripts and YAML crews once enabled (an ask with no approval channel is a refusal)
DLP interceptors, NIST reporting, key rotation, tool rate limiting Opt-in, and host-invoked once registered β€” see Opt-in subsystems

The Azure AD and OIDC providers validate A2A bearer tokens (below); no other inbound authentication guard exists.

Tool resolution in YAML

When a Crew is created from YAML, each tool name in agents[].tools[] is resolved via IToolRegistry.GetToolByNameAsync(toolName). What happens when a tool does not exist depends on CrewFactoryOptions.StrictTools:

  • Strict mode (Orkeon:CrewFactory:StrictTools=true β€” the default for orkeon run and the runners): CrewFactory throws, naming the missing tools and listing the registry's available names. No agent can operate with non-existent capabilities.
  • Lenient mode (the library default, false): the tool is skipped with a Warning log and the crew loads without it β€” a host embedding the library that wants the guarantee must turn strict mode on.

Shell confinement

shell_command checks each command line against its allowlist and the VFS, then hands it to the agent's shell session, which the operating system confines (ADR-014).

Backends. Orkeon:Tools:Shell:Confinement:Mode is Auto by default:

Platform Backend What the process sees
Linux bubblewrap (bwrap --unshare-all --die-with-parent) the virtual paths: each agent-facing mount bound at its virtual path, read-only without Write, a sub path without rights covered; /usr, /bin, /sbin, /lib*, /etc read-only; its own /proc, /dev and /tmp (HOME and TMPDIR)
macOS Seatbelt (/usr/bin/sandbox-exec -p <profile>) the physical paths, filtered by a (deny default) profile: the mounts read-only or read-write after their rights, the system directories read-only, the listing of / (the dynamic loader reads it), a scratch folder of the session as HOME and TMPDIR
Windows 10 and later an AppContainer (one profile per session) inside a Job Object the physical paths: the mounts granted to the container's SID by ACE (read and execute, or modify), a sub path without rights (or read-only inside a writable mount) cut off from the grant its parent passes down (its DACL protected for the session, then written back: the container's access check skips a deny ACE), what ALL APPLICATION PACKAGES reads (the Windows and Program Files trees); TEMP, TMP and HOME in the profile's own folder
  • Off in a container. Auto resolves to None when the host runs in a container (/.dockerenv, /run/.containerenv, DOTNET_RUNNING_IN_CONTAINER=true) and logs it once; the images also set Orkeon__Tools__Shell__Confinement__Mode=None. An explicit mode is never overridden.

  • Fail closed. A backend that cannot run (bwrap missing, user namespaces refused, Windows older than 10, a mode for another platform) fails the call with the reason and the way out (Mode = None); the command never falls back to running unconfined.

  • The SECURITY line. When the interpreters (node, dotnet, npm, find) are enabled, the tool logs one SECURITY line, once per host, at the first shell_command call validated, whatever the command: constructing or listing the tool logs nothing. The line states the confinement in force: the backend and what it shows the process; or none and why (the host runs in a container, or Mode = None, where commands run on the host unconfined); or unavailable with the reason, when every call will fail rather than run unconfined. A confining backend also states the network, network on or network off (from Confinement:AllowNetwork), and bubblewrap adds system directories are read-only. Under Mode = None, or unconfined inside a container, the line always says network on (the unconfined shell never cuts the network) and makes no read-only claim.

  • No network unless Confinement:AllowNetwork = true: a network namespace with loopback only under bubblewrap, (deny network*) under Seatbelt, no network capability under AppContainer.

  • Session sockets. The shell's environment allow-list carries XDG_RUNTIME_DIR and SSH_AUTH_SOCK when the host has them, and DBUS_SESSION_BUS_ADDRESS under the condition below. Each holds an address rather than a secret, but what it leads to is powerful: the ssh agent signs with every key it holds, and the session bus reaches every service of the operator's session. Under bubblewrap they follow only with AllowNetwork = true, and then only the socket files are bound read-write at their own path β€” the SSH_AUTH_SOCK path and a unix:path= bus β€” when they exist and are no directory; XDG_RUNTIME_DIR itself is never bound. Without the network neither the variables nor the binds are given. Every other variable, the LLM API keys first, stays dropped.

  • The session bus is opt-in. Through the bus a command runs systemd-run --user sh -c … (or calls org.freedesktop.systemd1 with gdbus) and so executes outside the sandbox, and secret-tool search --all reads every secret of the keyring. A confined session (bubblewrap, Seatbelt, AppContainer) therefore receives neither DBUS_SESSION_BUS_ADDRESS nor, under bubblewrap, the bus socket unless Orkeon:Tools:Shell:Environment:SessionBus = true, which the host logs as a warning when it starts. Turn it on only for a trusted agent that needs a keyring-backed credential helper (gh auth git-credential, git-credential-libsecret); an ssh remote or a credential the operator hands over another way needs no bus. A unix:abstract= bus is the exception bubblewrap cannot close: an abstract socket belongs to the network namespace, which AllowNetwork shares, so it stays reachable to a command that finds its name, variable or not. An unconfined session (Mode = None, a container) and the code sandbox always receive the bus: no jail holds them, and they reach its socket in XDG_RUNTIME_DIR without the variable.

  • Added variables. Orkeon:Tools:Shell:Environment:Propagate adds host variables to the allow-list, for the shell session and the code sandbox alike. The code sandbox reads the key from configuration only: a list set in code with Configure<ShellToolOptions> reaches the shell alone, since Orkeon.Infrastructure does not reference the shell's project. The secret filter wins over it: a name starting with ORKEON_, containing KEY, TOKEN, SECRET, PASSWORD, PASSWD, PASS, CREDENTIAL or AUTH, or holding the word PAT on its own (GITHUB_PAT, not PATH), without case, blank, or holding = or a NUL is dropped with a warning, and so is one whose value carries URL credentials (http://user:password@proxy:3128, https://<token>@host, or schemeless user:password@proxy:3128, a / in the password included), the warning naming the variable and never its value; a built-in name is ignored. Names compare with case (http_proxy and HTTP_PROXY are two variables), except on Windows. The filter reads names and URL userinfo only: a value carrying a credential in another shape passes, so list only variables whose value is no secret. Under bubblewrap an added variable passes with or without the network, since only a socket needs it, and no path it names is bound: the view stays what the mounts and ReadOnlyPaths make it, so a variable naming a host directory points at nothing inside unless that directory is lent another way.

  • Paths. Under bubblewrap the arguments are checked and passed virtual. Under Seatbelt, AppContainer and None they are translated virtualβ†’physical, and physical paths in the output come back virtual.

  • Agent file-system scope. An agent that declares a file-system scope sees its entries alone: a mount no entry selects is not bound, and each entry is bound with the rights in force there (the mount's, narrowed by the entry), its sub-path overrides beneath it. Under a working root as well, the entries are clipped to the root. Unconfined (Mode = None, or inside a container), the shell holds the scope only for the paths its command line names and its working directory, as it holds the mounts. A denial under a scope names the scope and no other mount; a listing gives only what a read would allow; the semantic-graph tools leave out the nodes of files outside it.

  • Agent working root. An agent that declares a working root sees, of the mount that holds it, the root alone. When the root is a linked git worktree (its .git is a file, gitdir: <path>, written by git worktree add), git commits through two directories outside it, which are bound after every other path of the mount so that git status, git add and git commit work there and commit on the worktree's branch:

    • the repository's common dir (<main>/.git) read-only as a whole: its config, hooks, info, modules, the other worktrees' git dirs, and anything created there later, are read by the user's own git in the main checkout, so the agent can neither change nor add them;
    • over it, read-write (capped by the root's rights and the rights in force there): <common>/objects, <common>/refs, <common>/logs (each only when it is a directory, not a symlink; a repository without logs/ cannot record reflogs from the agent) and the worktree's own git dir (<common>/worktrees/<name>), which was already the agent's in effect since git in the worktree trusts the .git file of the root;
    • then the mount's overrides under these directories, each narrowed to the lesser of what it grants and what the git rule grants there: an override narrows a git dir (a read-only refs/heads stays read-only) but never widens one (a read-write override on the common dir leaves its hooks and config read-only).

    Nothing is bound unless every check holds: the gitdir sits in a worktrees directory and the common dir is its grandparent; its commondir names exactly that common dir; its back-link gitdir names exactly this root's .git (an agent cannot point its .git at another worktree's git dir); both have the git layout; both lie on the mount outside the root and do not hold it; and no component of their path below the mount's root is a symlink, read through the VFS without following the last link (the VFS resolves paths lexically, while the kernel follows links when it binds a source). A gitdir, commondir or back-link may be relative (to the directory that holds the file; git worktree add --relative-paths, git 2.48 and later), a virtual path, or a host path under the mount's physical root (plain git worktree add), bound at that host path. Anything else binds nothing and is logged at Debug. The checks run when the command starts; what a job of the same agent may write meanwhile lies in objects, refs, logs or the gitdir, none of which is a component of the checked paths. Nothing else of the main checkout is bound: its working tree stays out of reach. The three backends take these paths from the same list and give a read-only parent with read-write children the same rights: bubblewrap binds deeper paths last, Seatbelt writes them last (its last matching rule wins), AppContainer grants Modify on the children over an inherited read-and-execute.

  • Jobs. action = start_job runs an allowlisted command detached, with the same confinement as a blocking call, and returns a job_id and the virtual path of its output file, /output/jobs/<id>.log (the first mount with Write rights when /output is not writable; refused when none is). job_status reports running or the exit_code; job_tail returns the last tail_lines lines (a bounded read from the end of the file). A run holds 16 live jobs at most, a job id is valid for the run that started it, and the run's end kills the jobs still running. The >, >>, <, |, ; and & operators stay refused in the command: the redirection to the log is the session's, by stream, never a shell operator.

  • Windows commands. A program is looked up on PATH only (never the working directory, a mount the agent writes to), .exe then .com. A cmd.exe built-in (echo, dir, type) runs as cmd.exe /d /v:off /s /c "<built-in> <arguments>", every argument that is not a plain word between double quotes, % refused. This holds with Mode = None too. A batch file (.bat, .cmd) is refused in an AppContainer session, since cmd.exe would parse its arguments again; with Mode = None it runs (npm finds npm.cmd after .exe and .com) as cmd.exe /d /v:off /s /c "<path> <arguments>", escaped as a built-in, % refused.

The session's life. The session is opened at the agent run's first command and bound to its AgentRunScope; the run's later commands reuse it (each in a subshell, so cd or a variable does not carry over), and it is reopened when the mounts change. Agents running side by side have their own. It is killed with everything it started when the run ends, fails or is cancelled. A command that times out, or a caller's cancellation, kills the session: the result says so and the next command opens a new one. A command outside any agent run gets a session of its own, closed after it. When the host itself dies:

Backend What takes the session down
bubblewrap the kernel: --die-with-parent and the PID namespace, of which bwrap is the init β€” every process of the session, detached or not
AppContainer, and None on Windows the kernel: the Job Object is KILL_ON_JOB_CLOSE and the host holds its only handle; ACEs a crash left are recorded in %LOCALAPPDATA%\Orkeon\shell-sessions\ and taken back by the next host's first session
Seatbelt, and None on Linux and macOS a watchdog shell (outside the sandbox under Seatbelt) that checks every second that the host still exists, then stops and kills the session's process tree and removes its scratch folder; a process that left the tree (a double fork) is not reached, and the watchdog itself is a process that a SIGKILL of its own ends

Common settings (environment variables shown; the same keys go in appsettings.json):

  • Turn it off: Orkeon__Tools__Shell__Confinement__Mode=None. The process then runs on the host as the host's user, the VFS checking only the paths its command line names.
  • Install bubblewrap (Linux): sudo apt-get install bubblewrap on Debian and Ubuntu (the Orkeon .deb depends on it). Ubuntu 24.04 and later restrict unprivileged user namespaces through AppArmor: an AppArmor profile for /usr/bin/bwrap that grants userns lifts the restriction for bubblewrap alone; without one the call fails with bwrap's reason, and the machine-wide way out is sysctl kernel.apparmor_restrict_unprivileged_userns=0 (what the nightly runner does). Check with bwrap --unshare-all --die-with-parent --ro-bind / / /bin/true.
  • Give it a toolchain outside the system directories: Orkeon__Tools__Shell__Confinement__ReadOnlyPaths__0=/opt/node, Orkeon__Tools__Shell__Confinement__ReadOnlyPaths__1=/home/me/.dotnet (bound read-only at their own path; on Windows, fully qualified host directories the container may read and execute).
  • Allow the network (a package manager, git fetch): Orkeon__Tools__Shell__Confinement__AllowNetwork=true.

Limits: Known limitations.

A2A mutual TLS

The opt-in A2A subsystem (AddOrkeonA2A()) enforces the security posture declared in A2ASecurityOptions:

  • Server (RequireMutualTls = true): an incoming client certificate is authenticated, not merely required β€” it must chain to one of the configured TrustedCertificateAuthorities (X509 chain built with CustomRootTrust, which also covers the validity window) or match a pinned TrustedClientCertificateThumbprints entry. Self-signed certificates that are not pinned are rejected (403). Starting the server with RequireMutualTls and no trust anchor throws (fail-closed): presence and date validity alone are not authentication. Revocation is not checked β€” the trust anchors are assumed to be private CAs without CRL/OCSP endpoints.
  • Client: full TLS validation always applies β€” there is deliberately no accept-any-certificate opt-out. Configuring TrustedCertificateAuthorities pins trust to private CAs (a self-signed or local-dev server must pin its CA this way); the pinning only vouches for an unknown chain (RemoteCertificateChainErrors) β€” a host-name mismatch or a missing certificate is never bypassed.
  • Credentials (AllowedAuthSchemes): a declared scheme is validated, not just matched. Bearer tokens are offered to the registered IAuthenticationProviders β€” AzureAdAuthProvider (A2A:Security:AzureAD: TenantId, ClientId, optional Authority, ValidIssuers, ValidAudiences; signing keys from the tenant's OpenID configuration) and OidcAuthProvider (A2A:Security:Oidc: Authority, ClientId, ValidAudiences, RequireHttpsMetadata), registered by AddOrkeonA2A(configuration) for each filled section, or the host's own. ApiKey keys (Authorization: ApiKey <key>) are read through ISecretProvider from the names in ApiKeySecretNames on every request β€” never written in configuration β€” and compared in constant time. A rejected credential gets 401. Starting a server that declares a scheme without a validator throws (fail-closed, like RequireMutualTls without a trust anchor); any scheme other than Bearer and ApiKey has none. Client side, ClientAuthScheme (Bearer or ApiKey) and ClientCredentialSecretName make A2AClient send Authorization: <scheme> <secret> on every task call, the secret read through ISecretProvider each time; a credential that cannot be read fails the call before anything is sent.
  • Real mutual TLS termination requires an OS-level HTTPS binding for HttpListener β€” see Known limitations.

RAG web fallback & prompt injection

The corrective RAG pipeline can optionally fall back to a web search (WebSearchDocumentRetriever, Orkeon.Rag.WebFallback) when local retrieval fails. Web content is the textbook vector for indirect prompt injection: a page crafted so that, once retrieved and inserted into an LLM prompt, its text is interpreted as instructions β€” hijacking the agent, leaking the conversation, or triggering tool calls.

The defense is layered; no single layer is trusted on its own:

  • Strict opt-in: the fallback is off by default behind two independent switches β€” the transport (Orkeon:Rag:WebFallback:Enabled + an Endpoint, registered by AddOrkeonRag(configuration)) and the corrective-graph policy (Orkeon:Rag:Corrective:WebFallback:Enabled); both must be on for a web document to ever reach the graph. Enabling it without configuring an endpoint keeps it inert and logs a warning β€” there is no silent egress. The API key is read from an environment variable (ApiKeyEnvVar), never from configuration files.
  • Deterministic validation: every downloaded page passes through PromptInjectionDocumentValidator (Orkeon.Rag.Validation) β€” pure heuristics, no LLM, testable offline. Detected signals: model-addressed directives (EN + FR: "ignore previous instructions", "you are now…", "system:", Β« nouvelles instructions : »…), chat-template control tokens (<|im_start|>, <<SYS>>, [INST]…) with per-occurrence accumulation, hidden HTML markup (display:none, visibility:hidden, near-zero opacity/font-size, aria-hidden), massive HTML comments, exfiltration vectors (auto-loading markdown images with encoded query payloads, percent-encoded link payloads, base64 data URIs) and long base64 blobs. The per-document verdict is Clean | Suspicious | Rejected with reasons and incriminated spans.
  • Traceability, no silent cleaning: Rejected documents never leave the retriever and are logged with their reasons and URL. Suspicious documents are β€” per SuspiciousAction β€” either discarded (logged) or kept flagged in metadata (injection_verdict, injection_reasons, injection_risk_score). Content is never rewritten: the validator detects, it does not sanitize. On the ingestion path the same validator sits in the DataValidationPipeline (IDataValidator chain) with quarantine and provenance tracking.
  • Fail-quiet on the network, fail-loud on security: search HTTP errors and timeouts degrade to an empty result list with a warning (the corrective graph simply proceeds without web context); rejections are always warnings with full reasons.

Honest limits: these heuristics are pattern-based and can be evaded β€” paraphrased directives, languages other than English/French, novel encodings or split payloads will pass. Conversely, legitimate technical documents about prompts or CSS may score Suspicious (they are flagged, never silently dropped). A content validator is a filter, not a privilege boundary: the real containment is architectural β€” retrieved text must stay data (never executed as instructions), agents consuming web content should run with least-privilege tools, and sensitive actions must not be triggerable by retrieved content alone.

E-mail tools

The e-mail family (Orkeon.Tools.Email β€” guide) reads mail written by strangers and acts on a real mailbox, so its defense does not rest on the model's judgment:

  • The model only picks an account name. Servers, credentials and rights are the operator's configuration (Orkeon:Tools:Email). A secret is the name of an environment variable, never a value in that configuration, and never a tool argument β€” tool arguments are logged.
  • Rights are declared per account, and mandatory. Read, Organize, Draft, Send, Delete, Purge: an account that declares none is refused, and every call is checked against the right its operation needs. Each tool also declares its ToolAccess (Read, Edit, Execute β€” email_send and email_delete are Execute), which is what the permission gate reads.
  • Sending fails closed. email_send reaches only the addresses Send:AllowedRecipients allows (an address, *@domain or *; an empty list allows nobody), checked on To, Cc and Bcc by address, never by display name. The SMTP envelope is passed explicitly β€” the checked list, never derived from headers, so no Resent-* header can widen it β€” From is forced to the account, and Send:MaxRecipients / Send:MaxPerHour cap the volume. Over Graph, which reads the envelope from the headers, a message naming anyone outside the checked list is refused. email_draft is the human-review path: the agent writes, a person sends.
  • Received content is untrusted. Every search page and read result opens with a notice that it is data, never instructions. email_read and email_parser carry the verdict of the same PromptInjectionDocumentValidator as the web fallback above, run on the rendered text β€” what the agent sees, not the raw HTML or MIME. Text the HTML hides from a human reader through the inline declarations the renderer knows (display:none, font-size:0…) or the hidden attribute is left out and flagged hidden_content; a CSS class, a 1-pixel font or white on white is not detected, and a plain-text part β€” what the agent reads when there is one β€” is not compared with the HTML. The default policy flags; Screening:WithholdRejected withholds the body of a rejected message.
  • MCP OAuth tokens never reach the disk or the log. An MCP server in oauth2-client-credentials or oauth2-device is signed in by OAuthMcpAuthenticator: the client secret is read from an environment variable on every token request, the access and refresh tokens are held in memory only, and the token endpoint is reached through the orkeon-mcp-oauth client, which is kept out of the LLM exchange log. The secret and the tokens are scrubbed from every error and log line, even when the identity provider echoes them; a token endpoint must be https (loopback http excepted). orkeon-host has no terminal and refuses the device flow (MCP integration).
  • Tokens stay out of the agents' reach. OAuth tokens are written by orkeon email login into the internal root /credentials, mounted only when an OAuth account is declared and reached through PrivilegedFileSystemAccess, which no agent-facing tool resolves (VFS compliance). The tools never start an interactive sign-in, and a Graph paging link is followed only while it still points at graph.microsoft.com over HTTPS, so the bearer token never leaves for another host. Transport is TLS (SslOnConnect or StartTls) β€” None is accepted towards a loopback test server only, and no option accepts an invalid certificate.
  • Forged crews are tried on a fictitious mailbox. orkeon forge offers the twelve mailbox tools, and its bench runs every try inside a mail trial: the tools read and change a trial mailbox, a send is recorded and never leaves, and the configured account's rights, allow-list and caps already judge each simulated action.

Honest limits. The screen is the pattern-based detector described above: it flags, and a paraphrased injection passes it. The boundary is the account's rights, the fail-closed allow-list and drafts. Every account is visible to every crew and every .ork.ts script that resolves the same settings file β€” scripts call tools.email* directly, and the crews hosted by orkeon-host share the host's settings β€” so declare accounts in the crew's own appsettings.json (a run resolves one settings file; keep accounts out of an appsettings.json in the directory runs start from and out of Orkeon__Tools__Email__… environment variables, which the .NET host reads for every run), grant the fewest rights, prefer email_draft, and do not give an untrusted crew both e-mail Read and an outbound channel (http_api, the web tools): a message could ask the agent to carry the mailbox out. The token files are plain JSON: shielded from the VFS tools, not from a shell or code tool running as the same operating-system user.

Drive tools

The drive family (Orkeon.Tools.Drive β€” guide) reads and changes a real Google Drive or OneDrive, whose files anyone the owner works with may have written or shared. Its defense follows the e-mail family's:

  • The model only picks an account name. The client, the secret's variable name, the tenant, the rights and the root folder are the operator's configuration (Orkeon:Tools:Drive); no credential is ever a tool argument.
  • Rights are declared per account, and mandatory β€” Read, Write, Organize, Share, Delete, Purge β€” and each tool declares its ToolAccess (drive_delete and drive_share are Execute). An account that only reads asks the provider for a read-only scope.
  • A root folder an agent cannot leave. With Root, every item a call touches must descend from that folder β€” checked by its parent path on OneDrive, by climbing its parents on Google Drive β€” and an item outside is reported as not found, so the tools never confirm what lies beyond it. Search results outside the root are dropped.
  • Sharing fails closed. drive_share reaches only the addresses Share:AllowedRecipients allows (an address, *@domain or *; an empty list allows nobody), sends no notification unless asked, and creates a link anyone can open only when Share:AllowPublicLinks is set.
  • The trash first. drive_delete moves to the trash; a deletion for good needs Purge.
  • Read content is untrusted. drive_read opens with a notice that the text is data, and carries the verdict of the same PromptInjectionDocumentValidator; Screening:WithholdRejected withholds the text of a rejected file. drive_read bypasses the result sanitizer because it marks its text itself; the names and metadata the other drive tools return go through it.
  • The token never leaves the API host. It is sent over HTTPS to www.googleapis.com or graph.microsoft.com only: a OneDrive download goes through the pre-authenticated downloadUrl without it, an upload session receives the bytes without it, and a paging cursor that does not point at Graph is refused. Tokens are written by orkeon drive login into the drive subdirectory of the internal root /credentials (VFS compliance).
  • Forged crews never touch a drive. orkeon forge removes the eleven drive tools from the catalogue: there is no trial drive yet.

Honest limits. The screen flags, and a paraphrased injection passes it; the boundary is the rights, the root folder and the closed share allow-list. Every account is visible to every crew and script that resolves the same settings file β€” declare accounts in the crew's own settings, grant the fewest rights, set a Root, and do not give an untrusted crew both drive Read and an outbound channel (http_api, the web tools, drive_share). The token files are plain JSON: shielded from the VFS tools, not from a shell or code tool running as the same user.

LLM keys: the settings file names the variable

A settings file never has to hold an API key: ApiKeyEnvVar, in Llm and in each Llm:Profiles:<name>, names the environment variable that does, and the runner host reads it when the configuration resolves no ApiKey β€” in the process environment, then, on Windows, in the user scope (HKCU\Environment), read and never copied into the run's process, so what a run starts (a shell tool, a stdio MCP server, the code sandbox) inherits no key it did not have (configuration).

The reference may name any variable. A settings file is trusted configuration already: it declares the stdio MCP servers whose command the runner starts, and it directs the key to its own BaseUrl. A hostile file placed beside a crew could name another variable and send it to its endpoint β€” and it could already do worse. Restricting the reference to the provider's conventional names would refuse a variable an operator chose, against a risk the file opens otherwise. What the reference does guarantee is discretion: no message, log line or orkeon doctor row repeats its value β€” a key pasted into ApiKeyEnvVar by mistake must not reach a log β€”, they name its configuration path (Llm:Profiles:z-ai:ApiKeyEnvVar). A value that cannot be a variable's name (an =, a space, a line break) refuses the start, by its path; an ApiKey written as a ${NAME} placeholder β€” which nothing ever expanded, so the text went out as the key β€” refuses it too. More generally Orkeon never expands a variable in a setting: a ${NAME} or %NAME% reference in any setting it passes as written refuses the start, naming the path and never the value β€” run exits 1, orkeon-host 78 (the list).

Resilience

ResiliencePolicies (Orkeon.Infrastructure.Resilience) holds the two Polly policies on the execution path:

  • GetLlmApiPolicy β€” built by HttpLlmProviderBase for every LLM provider: retries transient HTTP failures (5xx, 408, network errors) and 429. A rate-limit window the provider announces (Retry-After, retry-after-ms or a reset header) is waited out in full when it is at most Llm:MaxRateLimitWait (default 00:05:00); a longer one fails the call at once. The retry budget is Llm:MaxRetries (default 10) on a ladder that is linear for the first two retries then Γ—3, every wait of that ladder capped at 30 s. A call that hits the HTTP timeout is retried once, then fails naming the setting.
  • GetRedisRetryPolicy β€” exponential backoff (2^n s, 3 retries) on Redis errors (connection and timeout included), used by RedisMemoryProvider.

The LLM budget and timeout are set by Llm:MaxRetries and Llm:TimeoutSeconds; the Redis budget is fixed.

Checkpointing

A tool approval that outlives the process. With Orkeon:Checkpointing:Enabled, DurableToolApprovalChannel stands in front of the host's IToolApprovalChannel (or alone, when it has none): what the permission gate asks about a tool call becomes a persisted question of kind ToolApproval (ToolName, ArgsHash - a digest of the arguments, never their values -, choices allow, allow_for_session, deny) under the id <TaskKey>#<n>.<q>. A run with nobody to answer stops on it (waiting_for_input, exit 75) instead of having the call refused, and the answer given to --resume --input (or POST /runs/{id}/input) decides the call when the task is replayed; anything but allow and allow_for_session is a denial. A call made outside a task of a checkpointed run is asked of the host's channel, or denied: the gate still fails closed. The answer is matched by the id alone. POST /runs/{id}/input goes through the authorization of the other /runs routes.

CheckpointManager and ResumeEngine (Orkeon.Application.Services.Checkpointing) enable saving and resuming the state of crew executions. Useful for long workflows that must survive restarts.

What the state store holds. The state store (in memory, JSON files, SQLite, PostgreSQL) keeps the outputs of the tasks and the answers given to a human in plaintext: protect it as you protect the data the run handles (file permissions, database access). The error message of a failed run passes through the log sanitizer before it is persisted, so a quoted secret is masked; task outputs and answers are not, because they are the data the resumed run reads back. A checkpoint rebuilds a structured output only as the type the task declares (or a plain JSON type): any other type name found in the store is refused and the task runs again.

The execution states themselves (ICrewExecutionStateManager: status, progress, output) can also be persisted in the same state stores (IStateStore β€” in-memory, SQLite via AddOrkeonSqliteCheckpointing, PostgreSQL) for recovery after a crash. Opt-in via AddCrewExecutionStatePersistence(...) β€” or the Orkeon:ExecutionState:Persistence section, which only takes effect through the AddOrkeonInfrastructure(IConfiguration) overload (the shipped runners use the parameterless one, so for them the explicit call is the route); default: in-memory only. See Opt-in subsystems.

Plugin system

IOrkeonPlugin, PluginAssemblyDiscovery, PluginLoader/PluginLoadContext and IPluginRegistry (Orkeon.Plugins) provide a plugin system for extending the framework with custom tools and providers: directory-based discovery through the VFS, isolated loading via a collectible AssemblyLoadContext, opt-in DI activation AddOrkeonPlugins(...).

⚠️ Trust boundary: loading a plugin executes arbitrary code with the host process privileges β€” no sandbox, and the AssemblyLoadContext is not a security boundary. Only load trusted plugins. Details and operating rules: Plugin system.


See also: LLM providers Β· Events and CQRS Β· Back to index