pathfence: detect sensitive file paths an agent touched in AI agents

Offline sensitive-path / path-traversal auditor for file paths an AI agent actually touched via tools.

What it detects

Offline sensitive-path / path-traversal auditor for file paths an AI agent actually touched via tools.

When an agent can read_file, write_file, apply_patch, Bash, or use an MCP filesystem server, a prompt injection or confused tool choice can steer it at .env files, SSH keys, cloud credential stores, browser password DBs, /etc/shadow, docker.sock, or paths outside the intended workspace. pathfence extracts those paths from saved transcripts (or a plain path list), classifies each one, and reports findings with tool and turn attribution.

Standard library only. It never runs an agent and never contacts the network.

Rules

Rule	Severity	What it flags
PF01	critical	Secret / credential files (`.env`, `*.pem`, `secrets.json`, tokens, netrc, …). `.env.example` / `.sample` / `.template` / `.placeholder` are not flagged
PF02	critical	SSH / GPG private key paths (`~/.ssh/id_*`, `~/.gnupg/`, …)
PF03	critical	Cloud credential paths (`.aws/credentials`, `.kube/config`, gcloud ADC, `.azure/`, …)
PF04	high	Browser cookie / password / autofill database paths
PF05	critical	OS identity paths (`/etc/shadow`, `/etc/passwd`, host SSH keys, …)
PF06	high	Path traversal segments (`../`, `..\\`)
PF07	high	Absolute / home path outside `--workspace` roots (opt-in)
PF08	medium	Broad home-directory or dotfile reads (`~/`, `$HOME`, `~/.something`)
PF09	high	Write/shell targeting a path already flagged as sensitive
PF10	high	Container / hypervisor escape paths (`docker.sock`, `/proc/self`, `/sys`, …)
PF11	high	Windows sensitive system paths (`…\config\SAM`, `Unattend.xml`, `ntds.dit`, …)
PF12	info	Inventory of every observed path (disable in CI with `--disable PF12`)
PF13	high	UNC / remote share path (forced authentication / NTLM leak)
PF14	high	Cryptocurrency wallet or keystore path (Bitcoin `wallet.dat`, Exodus, Solana `id.json`, MetaMask keystore, …)
PF15	high	Password-manager / credential-store path (`pass`, 1Password, KeePass, GNOME keyring, …)
PF16	critical	Privilege-escalation payload in a write (sudoers `NOPASSWD`, `authorized_keys`, `ld.so.preload`)

Usage

python3 pathfence.py transcript.json [more.jsonl dir/ paths.txt -]
  --as-paths            treat inputs as plain path lists
  --allow-path GLOB     allowlist path (repeatable); still flags traversal + OS identity
  --workspace ROOT      expected workspace root (repeatable); enables PF07
  --disable RULE ...    skip rule ids (e.g. PF08 PF12)
  --json                machine-readable output
  --min-severity S      hide findings below S (default info)
  --fail-on S           exit 1 if any finding >= S (default high; any, none)
  --list-rules

After pip install of the kit, the same options work as agentsec pathfence …. Every tool also accepts --help and almost every tool accepts --json.

Example output

Flags PF03 on .aws/credentials, PF01+PF06 on ../../.env, PF02 on ~/.ssh/id_rsa (via Bash), and PF05+PF09 on the write to /etc/shadow (exit 1). examples/clean_openai.json is clean (exit 0). See also risky_anthropic.json, generic_paths.jsonl and paths.txt. All example secrets are FAKE-EXAMPLE-*.

python3 pathfence.py examples/risky_openai.json --disable PF12

SARIF and CI

agentsec pathfence path/to/input --sarif > pathfence.sarif

# GitHub Actions (composite action ships with the repo)
- uses: dunkleschitz/agentsec@v0
  with:
    tools: pathfence
    paths: path/to/input
    fail-on: high

SARIF 2.1.0 can be uploaded to GitHub code scanning. The composite action writes per-tool reports under agentsec-sarif/ by default.

OWASP mapping

Heuristic mapping of what this tool helps a reviewer look for. Not an official OWASP endorsement, and not complete coverage of any item. Sources: OWASP Top 10 for LLM Applications 2025 and OWASP Top 10 for Agentic Applications 2026.

LLM02 Sensitive Information Disclosure — OWASP LLM Top 10 (2025)
ASI02 Tool Misuse and Exploitation — OWASP Agentic Top 10 (2026)
ASI03 Identity and Privilege Abuse — OWASP Agentic Top 10 (2026)

Known limits

Heuristic tool-name and argument-key detection. A custom tool named get_content

that takes target may be missed unless the value looks like a path; use --as-paths on an extracted list if needed.

Shell-command path mining is regex-based and will miss obfuscated constructions

($(echo /etc)/shadow, base64-decoded paths, variables expanded at runtime).

--workspace compares the *written* path string, not the resolved real path after

symlinks or .. normalization beyond the PF06 flag.

It analyzes what was saved. It cannot block a live read; pair it with an OS

sandbox, MCP fs root allowlist, or toolgate policy in front of the agent.

Full source, tests, and fixtures: tools/pathfence/ in the repository. Install the kit with pip install git+https://github.com/dunkleschitz/agentsec.git.