Path & SSRF Hardening

Agents that accept paths or URLs from the LLM (which got them from a user) are a classic source of security holes:

Path traversal: the LLM helpfully passes ../../etc/passwd to your read_file tool.
SSRF (Server-Side Request Forgery): the LLM fetches http://localhost:9200/_search and exfiltrates your internal Elasticsearch index.
Null byte injection: legit.txt\0/etc/shadow — some filesystems still trim at the null.
Control character injection: ANSI escape sequences or carriage returns in paths.

v2.0 ships hardened defaults plus building blocks for your own tools.

`safeJoin(base, rel)`

import { safeJoin, PathSecurityError } from "@agentium/core";

const full = safeJoin("/var/data", "users/2024.json");
// → "/var/data/users/2024.json"

safeJoin("/var/data", "../../etc/passwd");
// throws PathSecurityError("Path traversal blocked: ../../etc/passwd resolves outside /var/data")

What it blocks

Attack	Example input	Behavior
Parent traversal	`"../../etc/passwd"`	throws PathSecurityError
Absolute path	`"/etc/passwd"`	throws PathSecurityError
Null byte	`"ok\0.txt"`	throws PathSecurityError
Control characters	`"x\u0001.txt"`	throws PathSecurityError
Prefix-matching escape	`safeJoin("/etc", "passwd")` from base `/etcfoo`	distinct directories enforced via PATH_SEP

What it does NOT do

Does not follow symlinks. If users/2024.json is a symlink to /etc/passwd, safeJoin returns the symlink path; reading it will still escape. Use fs.realpath() after safeJoin if you need symlink-aware safety.
Does not check existence. Pure path math.
Does not normalize Unicode. Use path.normalize() upstream if you need NFC normalization.

`PathSecurityError`

class PathSecurityError extends Error {
  name = "PathSecurityError";
}

Pattern-match on err instanceof PathSecurityError for fine-grained error handling.

Where it’s used by default

The FileSystemToolkit is now hardened automatically:

import { FileSystemToolkit } from "@agentium/core";

const fs = new FileSystemToolkit({
  basePath: "./agent-workspace", // any LLM-supplied path is safeJoin'd into this
  allowWrite: true,
});

const agent = new Agent({ tools: fs.getTools(), ... });

Any tool call with a traversal-y path (../../etc/passwd) raises PathSecurityError, which the tool executor catches and surfaces to the model as a clean error string. The model can self-correct. For tools you write yourself, route every LLM-supplied path through safeJoin:

import { safeJoin } from "@agentium/core";

const readNote = defineTool({
  name: "read_note",
  parameters: z.object({ path: z.string() }),
  execute: async ({ path }, ctx) => {
    const safe = safeJoin("./notes", path);  // ← hard fence
    return await fs.readFile(safe, "utf8");
  },
});

SSRF protection — `allowedHosts`

URL-fetching toolkits accept an allowedHosts option that whitelists exactly which hosts the toolkit is permitted to reach.

Built-in coverage

ScraperToolkit is the canonical example; it accepts an LLM-supplied URL:

import { ScraperToolkit } from "@agentium/core";

const scraper = new ScraperToolkit({
  allowedHosts: ["wikipedia.org", "nodejs.org", "github.com"],
});

const agent = new Agent({ tools: scraper.getTools(), ... });

The model can now only successfully fetch from those three domains. Anything else throws PathSecurityError("Host blocked by allowedHosts policy: ...") before any network round-trip.

Matching rules

Allowlist entry	Matches
`"example.com"`	`example.com` (exact) AND `api.example.com`, `cdn.example.com` (any sub-domain)
`"sub.example.com"`	only `sub.example.com` and its sub-domains

Sub-domain matching uses suffix comparison after a . boundary, so "example.com" does not accidentally allow notexample.com.

`isHostAllowed` / `assertHostAllowed`

Use these directly in your own URL-accepting tools:

import { assertHostAllowed, isHostAllowed } from "@agentium/core";

const allowList = ["api.example.com"];

const callApi = defineTool({
  name: "call_api",
  parameters: z.object({ url: z.string() }),
  execute: async ({ url }) => {
    assertHostAllowed(url, allowList); // throws PathSecurityError if denied
    return fetch(url).then((r) => r.text());
  },
});

// Or do a boolean check for soft enforcement:
if (isHostAllowed(url, allowList)) await fetch(url);

isHostAllowed(url, undefined) and isHostAllowed(url, []) always return true (no restriction). Pass an explicit array to enforce.

Defense-in-depth recommendations

Even with safeJoin and allowedHosts, multiple layers help:

Run the agent as an unprivileged OS user — even if pathing escapes, the user can’t read sensitive files.
Restrict outbound network at the firewall — allowedHosts is a soft fence; iptables / VPC egress rules are the hard fence.
Audit tool.result events — the EventBus emits every tool call; alert on suspicious patterns (many denied requests in a short window).
Use the SandboxAgent for any agent that runs arbitrary code or shell.

​Path & SSRF Hardening

​safeJoin(base, rel)

​What it blocks

​What it does NOT do

​PathSecurityError

​Where it’s used by default

​SSRF protection — allowedHosts

​Built-in coverage

​Matching rules

​isHostAllowed / assertHostAllowed

​Defense-in-depth recommendations

​See also