How the Egonex Dashboard Code Viewer Enforces Path Allowlisting from the Knowledge Graph

The Egonex dashboard code viewer enforces strict path allowlisting by validating every file request against a Set of paths extracted directly from the knowledge graph, rejecting any access attempts outside the defined project scope.

The Egonex Understand-Anything dashboard provides a secure code viewer that only exposes source files explicitly referenced in the project's knowledge graph. This implementation prevents directory traversal attacks and ensures sensitive files outside the analysis scope remain inaccessible, all while delivering syntax-highlighted source code through a React-based interface.

Building the Allowlist from the Knowledge Graph

The security model begins with a pre-computed allowlist derived from the graph data generated during the project analysis phase.

Extracting File Paths with graphFilePathSet

When the development server starts, it invokes graphFilePathSet to parse the knowledge-graph.json file and extract every node's filePath property. This function creates an in-memory Set<string> containing all permissible paths, ensuring O(1) lookup time during request validation.

In understand-anything-plugin/packages/dashboard/vite.config.ts, the implementation reads the graph structure and filters for nodes with valid string paths:

// vite.config.ts (excerpt)
function graphFilePathSet(graphFile: string, projectRoot: string): Set<string> {
  const allowed = new Set<string>();
  const raw = JSON.parse(fs.readFileSync(graphFile, "utf-8")) as {
    nodes?: Array<Record<string, unknown>>;
  };
  for (const node of raw.nodes ?? []) {
    if (typeof node.filePath !== "string") continue;
    const normalized = normalizeGraphPath(node.filePath, projectRoot);
    if (normalized) allowed.add(normalized);
  }
  return allowed;
}

Normalizing Paths for Cross-Platform Compatibility

Before paths enter the allowlist, normalizeGraphPath converts them to a canonical form. This process makes paths relative to the project root and standardizes backslashes to forward slashes, eliminating platform-specific discrepancies that could bypass security checks.

The normalization ensures that paths like src\components\App.tsx and src/components/App.tsx resolve to identical entries in the allowlist Set.

Validating File Requests in the Development Server

The development server exposes a single endpoint for file retrieval, implementing multiple layers of validation before serving content.

The /file-content.json Endpoint

The server middleware in vite.config.ts handles requests to /file-content.json by delegating to readSourceFile, which orchestrates the security checks:

// vite.config.ts (excerpt)
if (pathname === "/file-content.json") {
  const result = readSourceFile(url);
  sendJson(res, result.statusCode, result.payload);
  return;
}

Token and Path Sanitization

The readSourceFile function first validates the presence of a one-time token parameter, then sanitizes the path query parameter. It rejects requests containing null bytes, absolute paths, or traversal sequences that attempt to escape the project root.

This sanitization produces a safeRelativePath that is guaranteed to reside within the project directory structure, neutralizing .. traversal attempts before they reach the allowlist check.

Allowlist Enforcement Logic

After sanitization, the server performs the critical allowlist validation. It checks whether the safeRelativePath exists in the graphFilePathSet. If the path is absent, the server returns an HTTP 404 with the message "File is not in the knowledge graph", preventing access to any file not explicitly modeled in the graph.

// vite.config.ts (excerpt)
const graphFile = findGraphFile("knowledge-graph.json");
if (!graphFile) return rejectFileRequest("No knowledge graph found. Run /understand first.", 404);

const projectRoot = projectRootFromGraphFile(graphFile);
// ... sanitization logic ...
const safeRelativePath = relativeToRoot.split(path.sep).join("/");
if (!graphFilePathSet(graphFile, projectRoot).has(safeRelativePath)) {
  return rejectFileRequest("File is not in the knowledge graph", 404);
}

Only after passing this check does the server verify the file is not binary and enforce the MAX_SOURCE_FILE_BYTES limit (1 MiB).

Client-Side Implementation

The React component responsible for displaying source code constructs requests URLs that include the required security token and file path.

Constructing Secure Requests in CodeViewer.tsx

The CodeViewer.tsx component uses fileContentUrl to build the request URL, encoding the path and token as query parameters:

// CodeViewer.tsx (excerpt)
function fileContentUrl(filePath: string, token: string): string {
  const params = new URLSearchParams({ token, path: filePath });
  return `/file-content.json?${params.toString()}`;
}

After fetching the JSON response, the component renders the source with syntax highlighting. Because the server strictly validates every request against the graph-derived allowlist, the UI cannot inadvertently expose files outside the project's analyzed scope, even if the client-side code is compromised.

Summary

The Egonex dashboard code viewer implements defense-in-depth for source file access:

• Graph-derived allowlist: The graphFilePathSet function builds a Set of permissible paths exclusively from nodes in knowledge-graph.json
• Path normalization: All paths are converted to relative, forward-slash format to ensure consistent matching across platforms
• Traversal prevention: The readSourceFile function sanitizes inputs and resolves safe relative paths before allowlist checking
• Strict enforcement: Requests for paths not present in the allowlist receive HTTP 404 errors with explicit messaging
• Size and type limits: Additional checks prevent binary file exposure and enforce a 1 MiB size cap

Frequently Asked Questions

How does the code viewer prevent access to files outside the project directory?

The server rejects any request containing absolute paths or directory traversal sequences (..) during the initial sanitization phase in readSourceFile. Even if these checks were bypassed, the path must still exist in the graphFilePathSet derived from the knowledge graph, which only contains references to files within the analyzed project root.

What happens if a file is not listed in the knowledge graph?

The server returns an HTTP 404 status code with the message "File is not in the knowledge graph". This occurs in vite.config.ts when the safeRelativePath lookup against the allowlist Set returns false, preventing the file system from being accessed for unlisted paths.

Why is the allowlist implemented as a Set rather than an array?

The graphFilePathSet function returns a Set<string> to provide O(1) average-time complexity for membership tests. This is critical for performance when the knowledge graph contains thousands of files, ensuring that request validation remains instantaneous regardless of project size.

How does the token validation work alongside path allowlisting?

Before checking the path allowlist, readSourceFile verifies the presence of a valid one-time token in the request URL. This token acts as a short-lived credential that prevents unauthorized external requests from even reaching the path validation logic, creating a two-layer security barrier for source code access.

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