File-system-based routing maps executable tool endpoints directly from files in a directory structure. It speeds development, but it also creates a governance challenge because the act of adding a file can effectively add a new permissioned capability without a separate review step.
Expanded Definition
File-system-based routing is a routing pattern in which executable tool endpoints are discovered from a directory tree, so the path, filename, or folder structure determines the callable capability. In agentic systems and NHI-heavy platforms, this can simplify onboarding because developers add a file and the tool becomes routable without touching a central registry.
That convenience also changes the control model. Instead of treating each endpoint as an explicit change request, the file system becomes an implicit policy surface. In practice, teams must decide whether the directory structure is merely a deployment convenience or a governance boundary, because a new file may introduce a new permissioned action. No single standard governs this yet; usage in the industry is still evolving across agent frameworks and internal platform conventions. For a broader NHI governance context, see Ultimate Guide to NHIs and the NIST Cybersecurity Framework 2.0.
The most common misapplication is treating file placement as a low-risk implementation detail, which occurs when code review does not include permission review for newly routable files.
Examples and Use Cases
Implementing file-system-based routing rigorously often introduces a governance overhead, requiring organisations to weigh development speed against the cost of tighter change control and entitlement review.
- A support agent framework scans a tools directory at startup, exposing every new file as a callable action for an AI agent.
- A platform team uses nested folders to separate admin-only tools from standard workflows, but still requires an approval step before deployment.
- A CI pipeline generates route files automatically, which accelerates release cadence but demands extra checks for secrets access and execution scope.
- An internal NHI service loads per-tenant endpoints from disk, making directory permissions part of the security boundary rather than a purely operational choice.
- Teams using agent patterns often compare this approach to broader identity and runtime guidance in Ultimate Guide to NHIs, while the general risk-management lens aligns with NIST Cybersecurity Framework 2.0.
Because the routing map is derived from files, operational teams must also define who can create, rename, or delete those files and how that activity is logged for auditability.
Why It Matters in NHI Security
File-system-based routing matters because it can turn ordinary code changes into security-relevant changes. In NHI environments, that means a developer, build system, or compromised pipeline may unintentionally grant an AI agent or service account access to a new capability simply by adding a file. This is especially dangerous when routed tools can read secrets, call external APIs, or perform privileged actions without a separate entitlement review. NHIMG reports that 97% of NHIs carry excessive privileges, and 96% of organisations store secrets outside of secrets managers in vulnerable locations including code, config files, and CI/CD tools, which makes implicit capability growth a serious concern. See the Ultimate Guide to NHIs for the wider governance context.
The security issue is not routing itself, but the absence of compensating controls around discovery, review, and runtime restriction. When file creation equals capability creation, teams need stronger change management, least privilege, and detection for unexpected route additions. Organisations typically encounter the impact only after a new file exposes a tool or a breach reveals that a path-based endpoint was reachable long before anyone intended to approve it.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP Agentic AI Top 10 and OWASP Non-Human Identity Top 10 address the attack and risk surface, while NIST CSF 2.0 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| OWASP Agentic AI Top 10 | Agentic frameworks warn that tool exposure must be explicitly governed, not implied by code layout. | |
| OWASP Non-Human Identity Top 10 | NHI-01 | File-driven endpoints can expand NHI attack surface through unmanaged capability creation. |
| NIST CSF 2.0 | PR.AC-4 | Least-privilege access control applies when file changes can expose new permissions. |
Treat routed tool files as privileged capabilities and require approval before exposure.
Related resources from NHI Mgmt Group
- Why are identity-based attacks growing faster than traditional network attacks?
- What is the difference between a rules-based secret scanner and a hybrid scanner?
- What is the difference between role-based access and API key governance for NHI security?
- When should organisations treat an AI agent as a privileged system?
Deepen Your Knowledge
Reviewed and updated by the NHIMG editorial team on June 8, 2026.
NHI Mgmt Group — the #1 independent authority on Non-Human Identity, IAM, and Agentic AI security. nhimg.org
