Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pecta.ai/llms.txt

Use this file to discover all available pages before exploring further.

The filesystem gate walks every string value in ctx.output — including nested strings inside objects and arrays — and blocks the evaluation if it finds patterns that indicate a destructive or unauthorized filesystem operation. It is designed for agents that can generate or suggest shell commands: coding assistants, DevOps automation bots, CI/CD orchestrators, and similar tools where a single bad output could wipe data or expose credentials. All three checks are enabled by default. You can disable any of them individually through the options if your use case requires it.

​
Usage

import { createEngine, gates } from "@pecta/core";

const engine = createEngine({
  gates: [
    gates.filesystem(),
  ],
});

const result = await engine.evaluate({
  agent_id: "devops-bot",
  tool: "shell.suggest",
  output: { command: "rm -rf /var/app/data" },
});
// result.passed === false

​
What it detects

​
Destructive rm commands

The gate matches any of the following patterns:
PatternExample
rm -rf, rm -frrm -rf /tmp/old
rm -Rf, rm -fRrm -Rf ./build
Flags with other letters mixed inrm -rfv /data
Long-form flagsrm --recursive --force /mnt
Reversed long-form flagsrm --force --recursive /mnt

​
Path traversal

Any occurrence of .. used as a directory component — whether delimited by /, \, whitespace, or quotes — is flagged. This blocks attempts to escape a working directory such as ../../etc/passwd.

​
Sensitive directories

The gate flags references to the following paths:
PathWhat it protects
/etcSystem configuration files
/usrSystem binaries and libraries
/varVariable data including logs and databases
~/.ssh or /home/<user>/.sshSSH private keys
~/.aws or /home/<user>/.awsAWS credentials
~/.gnupg or /home/<user>/.gnupgGPG keys

​
What a failure looks like

{
  "name": "filesystem",
  "passed": false,
  "reason": "destructive rm command detected",
  "latency_ms": 0.19
}

{
  "name": "filesystem",
  "passed": false,
  "reason": "path traversal (..) detected",
  "latency_ms": 0.11
}

{
  "name": "filesystem",
  "passed": false,
  "reason": "sensitive path detected: ~/.ssh",
  "latency_ms": 0.14
}

​
Configuration

​
detectRmRf
boolean
Enable destructive rm command detection. Defaults to true.
​
detectTraversal
boolean
Enable path traversal (..) detection. Defaults to true.
​
detectSensitive
boolean
Enable sensitive directory detection. Defaults to true.
​
name
string
Override the gate name recorded in results. Defaults to "filesystem".

​
Disabling individual checks

Turn off specific checks while keeping the others: 
import { createEngine, gates } from "@pecta/core";

const engine = createEngine({
  gates: [
    gates.filesystem({
      detectRmRf: true,
      detectTraversal: true,
      detectSensitive: false, // your agent legitimately references /etc
    }),
  ],
});
The gate scans strings recursively through the entire output value, including deeply nested objects and arrays. Very large or deeply nested outputs are capped at 10,000 visited nodes to prevent pathological runtime. Outputs beyond that cap are not fully scanned.