Audience: Developers building coding agents or custom tools who need to understand how BotNexus enforces security boundaries. Prerequisites: C#/.NET, familiarity with agent events and provider system. Source code:
src/gateway/BotNexus.Tools/(the built-in tools andUtils/PathUtils.cs),src/gateway/BotNexus.Gateway/Security/(path policy enforcement),src/agent/BotNexus.Agent.Core/Hooks/(the tool-call hook contracts),examples/BotNexus.CodingAgent/(the sample coding agent:Hooks/SafetyHooks.cs,Hooks/AuditHooks.cs,CodingAgentConfig.cs).
- Path containment (how tools are sandboxed)
- Symlink resolution and escape prevention
- The file access policy (allowed and denied paths)
- The sample coding agent's blocked paths and blocked commands
- File mutation queue (serialized file access)
- Shell command safety
- Audit logging
- How to add safety hooks to a custom agent
BotNexus enforces a defense-in-depth model with three layers:
┌─────────────────────────────────────────────────────┐
│ Layer 1: ToolExecutionPolicy │
│ ● Policy interception before execution │
│ ● Can Block, or return Indeterminate (fails closed)│
├─────────────────────────────────────────────────────┤
│ Layer 2: Tool-level enforcement │
│ ● IPathValidator.ValidateAndResolve in file tools │
│ ● PathUtils.ResolvePath for workspace containment │
│ ● FileMutationQueue for serialized writes │
│ ● Output truncation (2000 lines, 50 KB) │
│ ● Process timeout and tree kill │
├─────────────────────────────────────────────────────┤
│ Layer 3: ToolResultTransformer + IToolAuditSink │
│ ● Result transformation and redaction │
│ ● Durable tool-audit rows in session history │
└─────────────────────────────────────────────────────┘
The hook contracts live in src/agent/BotNexus.Agent.Core/Hooks/ and are invoked by
src/agent/BotNexus.Agent.Core/Loop/ToolExecutor.cs. A hook is a delegate on AgentOptions:
// ToolExecutionContext / ToolExecutionDecision, verbatim shapes:
public record ToolExecutionContext(
AssistantAgentMessage AssistantMessage,
ToolCallContent ToolCallRequest,
IReadOnlyDictionary<string, object?> ValidatedArgs,
AgentContext AgentContext);
public record ToolExecutionDecision(bool Block, string? Reason = null)
{
public bool IsIndeterminate { get; init; }
public bool IsUnambiguousAllow => !Block && !IsIndeterminate;
public static ToolExecutionDecision Indeterminate(string? reason = null);
}Returning null means "no opinion, allow". Block: true is a positive deny. Indeterminate is the
absence of a decision — introduced by issue #2476 so an approval provider whose quorum failed
cannot have its silence coerced into an auto-approve. The executor fails closed on it.
PathUtils.ResolvePath() (src/gateway/BotNexus.Tools/Utils/PathUtils.cs) is the workspace
containment gate. Every file tool calls it before any file operation.
public static string ResolvePath(string relative, string workingDirectory)What it does:
- Validates that neither input is null or empty.
- Normalizes the relative path (collapses
./and..segments). - Resolves to an absolute path using
Path.GetFullPath. - Checks that the resolved path starts with
workingDirectory— if not, throwsInvalidOperationException. - Resolves symlinks — walks each path segment, resolving directory and file symlinks to their final targets via
ResolveFinalTargetPath. - Checks the symlink target is under the root — if the resolved symlink target escapes the working directory, throws
UnauthorizedAccessException.
Example:
// Working directory: /home/user/project
PathUtils.ResolvePath("notes/todo.txt", "/home/user/project");
// → "/home/user/project/notes/todo.txt" ✅
PathUtils.ResolvePath("../../etc/passwd", "/home/user/project");
// → throws InvalidOperationException ❌ (escapes working directory)
PathUtils.ResolvePath("/etc/passwd", "/home/user/project");
// → throws InvalidOperationException ❌ (absolute path outside root)Path containment checks use case-insensitive comparison (OrdinalIgnoreCase) on all platforms. The PathComparer field (used for gitignore path matching) is platform-aware — case-insensitive on Windows and case-sensitive on Unix — but the IsUnderRoot containment check always uses OrdinalIgnoreCase:
// IsUnderRoot always uses:
// StringComparison.OrdinalIgnoreCase (all platforms)
//
// PathComparer (gitignore matching) uses:
// Windows: StringComparer.OrdinalIgnoreCase
// Unix: StringComparer.OrdinalPathUtils.SanitizePath() normalizes paths before resolution:
public static string SanitizePath(string path)- Collapses
./segments - Normalizes directory separators to the OS-native separator (
\on Windows,/on Unix) - Throws
InvalidOperationExceptionif..segments would escape the root
All built-in tools validate paths through ResolvePath before any operation:
| Tool | Path validation |
|---|---|
ReadTool |
ResolvePath(args["path"], workingDir) before reading |
WriteTool |
ResolvePath(args["path"], workingDir) before writing |
EditTool |
ResolvePath(args["path"], workingDir) before editing |
GrepTool |
ResolvePath(args["path"], workingDir) before searching |
GlobTool |
ResolvePath(args["path"], workingDir) before globbing |
ListDirectoryTool |
ResolvePath(args["path"], workingDir) before listing |
ShellTool |
Not path-based, but constrained by the working directory and timeouts |
Every one of those six tools also calls IPathValidator.ValidateAndResolve — that is the policy
gate, described next. ResolvePath answers "is this inside the workspace"; ValidateAndResolve
answers "does the configured policy permit this access".
Path permissions are carried by FileAccessPolicy
(src/domain/BotNexus.Domain/Gateway/Security/FileAccessPolicy.cs), which has exactly three members:
public sealed record FileAccessPolicy
{
public IReadOnlyList<string> AllowedReadPaths { get; init; } = [];
public IReadOnlyList<string> AllowedWritePaths { get; init; } = [];
public IReadOnlyList<string> DeniedPaths { get; init; } = [];
}It is attached to an agent via AgentDescriptor and surfaced through the platform config
(src/gateway/BotNexus.Gateway.Configuration/). Workspace-relative entries are re-anchored onto the
agent's workspace path, so a policy keeps its meaning when copied onto a different agent.
DefaultPathValidator (src/gateway/BotNexus.Gateway/Security/DefaultPathValidator.cs) implements
IPathValidator:
public interface IPathValidator
{
bool CanRead(string absolutePath);
bool CanWrite(string absolutePath);
string? ValidateAndResolve(string rawPath, FileAccessMode mode);
}ValidateAndResolve returns null on refusal — there is no exception to swallow, so a caller that
ignores the result silently loses the check. Its two phases matter:
- Lexical resolution and policy check.
Path.GetFullPathcollapses..segments, thenCanRead/CanWritetests the result against the allow lists andDeniedPaths. - Link-following re-check.
Path.GetFullPathcollapses..lexically, without resolving links, so<symlink>/../<target>can appear to stay inside the root while the OS resolves the link first and lands outside it. The validator re-walks the raw path segment by segment, following links as the OS would, and re-checks containment on the real final target.
When no policy is supplied (or the policy is empty), the validator operates in workspace-only mode: the agent's workspace is the entire permitted surface.
Path comparison is platform-aware here - OrdinalIgnoreCase on Windows, Ordinal on Unix.
The platform gate above is IPathValidator + FileAccessPolicy. The sample coding agent under
examples/BotNexus.CodingAgent/ layers a second, simpler policy of its own on top, driven by
CodingAgentConfig (examples/BotNexus.CodingAgent/CodingAgentConfig.cs) and enforced by
SafetyHooks (examples/BotNexus.CodingAgent/Hooks/SafetyHooks.cs). This is example code, not the
gateway's production path - read it as a worked illustration of a ToolExecutionPolicy delegate.
CodingAgentConfig.BlockedPaths lists paths the write and edit tools may not touch, even inside
the working directory:
// .botnexus-agent/config.json
{
"blockedPaths": [".env", "secrets/", "/etc/passwd"]
}Relative entries are resolved against the working directory; absolute entries are used as-is; a
trailing-slash entry blocks the whole subtree. IsBlockedPath compares the resolved absolute path
against each entry with StartsWith(..., OrdinalIgnoreCase).
SafetyHooks.DefaultBlockedCommands is a hardcoded, case-insensitive substring deny list applied to
the shell command argument.
CodingAgentConfig.AllowedCommands is an optional allowlist. When non-empty, only commands whose
lowercased text starts with one of the entries is permitted; when empty (the default) every command
is allowed except the hardcoded blocked patterns.
// .botnexus-agent/config.json
{
"allowedCommands": ["dotnet", "git", "npm"]
}SafetyHooks warns - it does not block - when a write payload exceeds
LargeWriteThresholdBytes (1 MiB).
FileMutationQueue (src/gateway/BotNexus.Tools/FileMutationQueue.cs) prevents concurrent writes to
the same file. This is critical when ToolExecutionMode.Parallel is enabled.
public sealed class FileMutationQueue
{
public static FileMutationQueue Shared { get; }
public Task<T> WithFileLockAsync<T>(string path, Func<Task<T>> operation);
}How it works:
- Maintains a
ConcurrentDictionary<string, SemaphoreSlim>with per-path semaphores. - Before a file operation, the tool acquires the semaphore for that path.
- The operation runs exclusively — no other tool can modify the same file simultaneously.
- After completion, the semaphore is released.
Usage in WriteTool:
// Simplified from WriteTool.cs
public async Task<AgentToolResult> ExecuteAsync(
string toolCallId, IReadOnlyDictionary<string, object?> arguments, ...)
{
var path = PathUtils.ResolvePath(arguments["path"]!.ToString()!, _workingDirectory);
var content = arguments["content"]!.ToString()!;
return await FileMutationQueue.Shared.WithFileLockAsync(path, async () =>
{
Directory.CreateDirectory(Path.GetDirectoryName(path)!);
await File.WriteAllTextAsync(path, content, cancellationToken);
return new AgentToolResult([new AgentToolContent(AgentToolContentType.Text, $"Wrote {path}")]);
});
}EditTool uses the same queue to prevent race conditions during read-modify-write cycles.
ShellTool (src/gateway/BotNexus.Tools/ShellTool.cs) executes shell commands with multiple safety
layers.
The shell is chosen by a ShellPreference, which also determines the tool's advertised name
(shell for Pwsh, bash otherwise):
ShellPreference |
Behaviour |
|---|---|
Auto (default) |
Tries bash first; falls back to pwsh with a warning |
Pwsh |
Uses PowerShell Core (pwsh) on all platforms |
Bash |
Always bash; falls back to pwsh with a warning if not found |
On Windows the bash probe checks C:\Program Files\Git\bin\bash.exe and the (x86) variant. If
neither is present, it falls back to pwsh and prefixes the output with a warning.
Every command has a configurable timeout (default: 600 seconds), clamped to a ceiling of
ShellTool.DefaultMaxTimeoutSeconds (3600):
// Tool parameters include:
// "timeout" (optional, int) — seconds, default: 600, ceiling: 3600When a command exceeds its timeout:
- The tool captures partial output.
- Appends
"[Output truncated at {timeout} seconds]". - Kills the entire process tree (not just the parent process).
- Marks the result as
IsError = true.
Shell output is capped at MaxOutputLines and MaxOutputBytes:
- 2,000 lines maximum
- 51,200 bytes (50 KB) maximum
If output exceeds these limits, it is truncated with a notification appended.
When a shell command is killed (timeout or abort), the tool kills the entire process tree to prevent orphaned child processes. The result includes a ShellToolDetails record:
public sealed record ShellToolDetails(
int ExitCode,
bool TimedOut,
bool IsError
);This is attached to the AgentToolResult.Details field for inspection by hooks and logging.
A ToolResultTransformer delegate reads the exit code from ShellToolDetails, which is attached to
AgentToolResult.Details:
if (context.Result.Details is ShellToolDetails details)
{
// details.ExitCode, details.TimedOut, details.IsError
}Note the tool's name is shell under ShellPreference.Pwsh and bash otherwise, so a hook that
matches on the name must handle both.
Durable tool auditing is the responsibility of IToolAuditSink
(src/gateway/BotNexus.Gateway/Audit/IToolAuditSink.cs), introduced by issue #2614. It is the
single execution-layer sink both transports write through:
- Streaming callers use the start/result/incomplete renderers as events arrive.
- Blocking
PromptAsynccallers hand the settledToolInvocationRecordtimeline (the #2613 shared record) toProjectBlockingRun.
Both routes emit MessageRole.Tool session-history rows of the same shape, so removing the sink call
from either path removes the audit record entirely — which is exactly what the #2614 mutation tests
assert. Before #2614 the audit guarantee depended on which transport the caller happened to pick.
Write-ahead behaviour (so an interrupted invocation still leaves a record) lives in
ToolAuditWriteAhead.cs alongside it. A tool may be exempted from auditing with
ToolAuditExemptAttribute.
The audit sink is a gateway concern and should not be replaced. To add per-call logging on top,
attach a ToolResultTransformer delegate — it can observe, transform, filter or redact the result before it
reaches the LLM, and returning null leaves the result untouched:
ToolResultTransformer = async (context, ct) =>
{
await myLogger.LogToolCallAsync(
context.ToolCallRequest.Name,
context.IsError,
context.Result);
return null; // do not alter the result
};All file-reading and searching tools enforce consistent output limits:
| Tool | Line limit | Size limit | Per-line limit |
|---|---|---|---|
ReadTool |
2,000 lines | 50 KB | — |
GrepTool |
100 matches (default), 1,000 max | 50 KB | 500 chars |
GlobTool |
1,000 matches | — | — |
ListDirectoryTool |
500 entries | 50 KB | — |
ShellTool |
2,000 lines | 50 KB | — |
These limits prevent the LLM context from being flooded with large tool outputs.
- Supports
offset(1-indexed start line) andlimit(max lines) parameters. - Detects image files (PNG, JPEG, GIF, WebP) via magic bytes and returns base64-encoded data URIs.
- Directory paths trigger recursive listing (max depth 2).
- Excludes
.git/directory. - Filters
.gitignore'd files viaPathUtils.GetGitIgnoredPaths. - Skips binary files (null-byte detection in first 4 KB).
- Continues silently on I/O errors.
- Appends warnings for truncated results.
public sealed class MySecurityPolicy
{
private readonly string _workingDirectory;
private readonly HashSet<string> _blockedPatterns;
public MySecurityPolicy(string workingDirectory, IEnumerable<string> blockedPatterns)
{
_workingDirectory = workingDirectory;
_blockedPatterns = new HashSet<string>(blockedPatterns, StringComparer.OrdinalIgnoreCase);
}
public Task<ToolExecutionDecision?> ValidateAsync(
ToolExecutionContext context, CancellationToken ct)
{
switch (context.ToolCallRequest.Name)
{
case "write" or "edit":
return ValidateFileAccess(context);
case "bash":
return ValidateShellCommand(context);
default:
return Task.FromResult<ToolExecutionDecision?>(null);
}
}
private Task<ToolExecutionDecision?> ValidateFileAccess(ToolExecutionContext context)
{
var path = context.ValidatedArgs["path"]?.ToString();
if (string.IsNullOrEmpty(path))
return Task.FromResult<ToolExecutionDecision?>(
new ToolExecutionDecision(Block: true, Reason: "Path is required"));
try
{
// PathUtils.ResolvePath throws if path escapes working directory
var resolved = PathUtils.ResolvePath(path, _workingDirectory);
// Check custom blocked paths
foreach (var pattern in _blockedPatterns)
{
if (resolved.Contains(pattern, StringComparison.OrdinalIgnoreCase))
return Task.FromResult<ToolExecutionDecision?>(
new ToolExecutionDecision(Block: true, Reason: $"Blocked path: {pattern}"));
}
}
catch (InvalidOperationException ex)
{
return Task.FromResult<ToolExecutionDecision?>(
new ToolExecutionDecision(Block: true, Reason: ex.Message));
}
return Task.FromResult<ToolExecutionDecision?>(null);
}
private Task<ToolExecutionDecision?> ValidateShellCommand(ToolExecutionContext context)
{
var command = context.ValidatedArgs["command"]?.ToString() ?? "";
if (command.Contains("rm -rf", StringComparison.OrdinalIgnoreCase))
return Task.FromResult<ToolExecutionDecision?>(
new ToolExecutionDecision(Block: true, Reason: "Destructive command blocked"));
return Task.FromResult<ToolExecutionDecision?>(null);
}
}public sealed class MyAuditLogger
{
private readonly ConcurrentDictionary<string, DateTimeOffset> _startTimes = new();
public void RecordStart(string toolCallId)
{
_startTimes[toolCallId] = DateTimeOffset.UtcNow;
}
public Task<ToolResultTransformResult?> AuditAsync(ToolResultTransformContext context, CancellationToken ct)
{
var duration = _startTimes.TryRemove(context.ToolCallRequest.Id, out var start)
? (DateTimeOffset.UtcNow - start).TotalMilliseconds
: 0;
Console.WriteLine(
$"[audit] tool={context.ToolCallRequest.Name} " +
$"status={(context.IsError ? "failed" : "ok")} " +
$"duration={duration:F0}ms");
return Task.FromResult<ToolResultTransformResult?>(null);
}
}var securityPolicy = new MySecurityPolicy(workingDirectory, ["secrets/", ".env"]);
var auditLogger = new MyAuditLogger();
var agent = new Agent(new AgentOptions
{
Model = model,
LlmClient = llmClient,
GetApiKey = async (provider, ct) => apiKey,
InitialState = new AgentInitialState
{
SystemPrompt = "You are a coding assistant.",
Tools = [new ReadTool(workingDir), new WriteTool(workingDir), new ShellTool(workingDir)]
},
GenerationSettings = new SimpleStreamOptions { MaxTokens = 8192 },
ToolExecutionPolicy = async (context, ct) =>
{
return await securityPolicy.ValidateAsync(context, ct);
},
ToolResultTransformer = async (context, ct) =>
{
return await auditLogger.AuditAsync(context, ct);
}
});When implementing a custom IAgentTool:
- Call
IPathValidator.ValidateAndResolvefor any file path argument, and treat anullreturn as a refusal — it is the only signal you get - Call
PathUtils.ResolvePathfor workspace containment before using a path - Use
FileMutationQueue.Sharedfor any file write operation - Set process timeouts for any subprocess execution
- Kill the process tree when cancelling subprocesses, not just the parent
- Truncate output to prevent context flooding (aim for ≤50 KB)
- Never trust LLM-provided paths — always validate and resolve them
- Skip binary files when searching file contents
- Filter
.gitignore'd paths to avoid leaking ignored content
- Agent event system — hook system and event lifecycle
- Building your own agent — how an agent wires safety hooks
- Provider system — LLM communication layer
- Glossary — all key terms