How CBM_ALLOWED_ROOT Sandboxing Protects Against Untrusted Callers in Codebase-Memory-MCP

CBM_ALLOWED_ROOT is an optional environment variable that restricts the index_repository operation to a configurable root directory, preventing untrusted callers from accessing files outside the allowed path.

The Codebase-Memory-MCP (CBM) server provides semantic code search capabilities through the Model Context Protocol (MCP). When deployed in agentic or multi-tenant environments where callers may not be fully trusted, the CBM_ALLOWED_ROOT sandboxing mechanism ensures that indexing operations cannot escape a designated directory boundary, protecting the host file system from unauthorized access.

How CBM_ALLOWED_ROOT Sandboxing Works

The sandbox operates as a prefix-based access control system enforced early in the indexing pipeline. Before any file system operations occur, the server validates that the requested repository path lies within the allowed boundary.

Environment Variable Configuration

Administrators define the sandbox boundary by setting the CBM_ALLOWED_ROOT environment variable to an absolute path. When this variable is present, every index_repository request undergoes mandatory path validation regardless of the caller's origin.

Path Canonicalization and Validation

The validation process in src/mcp/mcp.c follows three strict steps:

1. Canonicalization – Both the requested repo_path and the CBM_ALLOWED_ROOT value are resolved using realpath() to eliminate symbolic links and normalize parent-directory references ("..").
2. Prefix Verification – The server performs a string comparison using strncmp() to verify that the resolved repository path starts with the resolved allowed root.
3. Early Rejection – If the path fails verification, the function returns ERR_FORBIDDEN immediately, preventing any file system access outside the sandbox.

Implementation Details in src/mcp/mcp.c

The sandbox check is implemented in src/mcp/mcp.c (approximately lines 6870-6890), where the index_repository handler validates paths before processing file contents. The following simplified excerpt demonstrates the core logic:

/* Simplified excerpt from src/mcp/mcp.c */
const char *allowed_root = getenv("CBM_ALLOWED_ROOT");
if (allowed_root) {
    char resolved_repo[PATH_MAX];
    char resolved_root[PATH_MAX];

    realpath(repo_path, resolved_repo);   // canonicalise target
    realpath(allowed_root, resolved_root); // canonicalise sandbox root

    if (strncmp(resolved_repo, resolved_root, strlen(resolved_root)) != 0) {
        fprintf(stderr, "error: repository path outside CBM_ALLOWED_ROOT\n");
        return ERR_FORBIDDEN;
    }
}

This implementation ensures that path traversal attacks via symbolic links or parent-directory references are neutralized before the server attempts to read any repository files.

Security Benefits for Untrusted Callers

Deploying CBM with CBM_ALLOWED_ROOT provides several critical security advantages:

• Attack Surface Reduction – Callers cannot induce the server to read sensitive files like /etc/passwd or write to system directories.
• Multi-tenant Isolation – In shared environments, each MCP instance can be restricted to its designated data volume without risking cross-tenant data access.
• Zero Side-effects – Because validation occurs before file operations, failed requests leave no traces on the host system and consume minimal resources.
• Symbolic Link Safety – The realpath() resolution prevents attackers from using symlinks to bypass directory restrictions.

Configuration Examples

Basic Sandboxing Setup

To restrict indexing to a dedicated data directory:

export CBM_ALLOWED_ROOT="/home/user/mcp-data"
codebase-memory-mcp  # start the MCP server

# Any index_repository request outside /home/user/mcp-data returns ERR_FORBIDDEN

CI/CD and Temporary Sandboxes

For ephemeral environments like CI pipelines:

CBM_ALLOWED_ROOT=$(mktemp -d)  # Create temporary sandbox

codebase-memory-mcp index_repository /path/to/project

# Requests are rejected unless the project path is within the temp directory

Summary

• CBM_ALLOWED_ROOT sandboxing restricts index_repository operations to a configurable directory boundary using environment-based configuration.
• The validation in src/mcp/mcp.c uses realpath() canonicalization and prefix matching to prevent path traversal attacks.
• Requests targeting paths outside the allowed root are rejected with ERR_FORBIDDEN before any file system access occurs.
• This mechanism is essential for securing agentic and multi-tenant deployments of the Codebase-Memory-MCP server.

Frequently Asked Questions

What happens if CBM_ALLOWED_ROOT is not set?

When the environment variable is undefined, the sandboxing check is skipped and the MCP server attempts to index the requested path without restrictions. While this allows maximum flexibility, it should only be used in trusted, single-user environments.

Does this protect against all path traversal attacks?

Yes, the implementation is designed to prevent directory traversal via both dot-dot sequences ("..") and symbolic links because realpath() resolves the canonical absolute path before the prefix comparison occurs in src/mcp/mcp.c.

Can I use multiple allowed roots?

The current implementation supports only a single root directory per process. To sandbox multiple distinct directories, you must run separate MCP server instances with different CBM_ALLOWED_ROOT values, or structure your file system with a common parent directory containing all allowed repositories.

Is there a performance impact?

The overhead is negligible for typical operations. The realpath() calls add minimal latency during the initial request validation, but this occurs only once per index_repository invocation and prevents expensive file operations on unauthorized paths.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}