SovGuard Integration in Jailbox

SovGuard integrates with jailbox to scan files before and during workspace sessions. While SovGuard's primary role is message-level prompt injection defense, its file scanning capabilities (Layer 6) extend to the jailbox to detect dangerous files before a sovagent ever sees them.

Why Scan Files?

When a buyer opens a jailbox workspace, the sovagent gains read access to the project directory. This introduces two risks:

Risk	Description	Example
Sensitive file exposure	Files containing secrets are readable by the sovagent	`.env`, `credentials.json`, `id_rsa`
Malicious file injection	A compromised sovagent writes files designed to exploit the buyer's system	Scripts with crypto miners, shell command injection

SovGuard's file scanning addresses both risks -- pre-session scanning catches sensitive files before the sovagent connects, and real-time scanning catches malicious writes during the session.

Configuration

Enabling SovGuard for jailbox

SovGuard file scanning is enabled when a SOVGUARD_API_KEY is available. There are two ways to provide it:

1. Platform default

If the Junction41 platform is configured with a SovGuard instance, file scanning is enabled automatically for all jailbox sessions. No buyer action needed.

2. Buyer-provided key

Buyers can provide their own SovGuard API key for custom scanning configuration:

bash

j41-jailbox ./project --uid TOKEN --sovguard-key sg_live_abc123...

This overrides the platform default and uses the buyer's SovGuard instance, which may have different threshold settings.

When no key is available

If no SovGuard key is configured (platform or buyer), file scanning is skipped. The jailbox still enforces all three isolation walls, session limits, and the audit log -- SovGuard adds an additional defense layer but is not required for basic sandbox operation.

Pre-Session Scanning

When the jailbox CLI starts, it performs a full directory scan before connecting to the relay and allowing the sovagent to access files.

What happens during pre-scan

Directory walk -- the jailbox recursively enumerates all files in the project directory
Metadata scan -- each file's name and path are checked against SovGuard's filename rules
Content scan -- files matching sensitive patterns are content-scanned
Exclusion list -- dangerous files are added to the exclusion list
Directory hash -- a SHA-256 hash of the directory structure is computed for attestation
Report to platform -- the exclusion list and directory hash are sent to the relay

Metadata scanning

SovGuard's metadata scanner checks filenames and paths for known sensitive patterns:

Pattern	Category	Action
`.env`, `.env.*`	Secrets	Auto-exclude
`.pem`, `.key`, `*.p12`	Certificates / keys	Auto-exclude
`credentials.json`, `secrets.json`	Secrets	Auto-exclude
`id_rsa`, `id_ed25519`, `*.pub`	SSH keys	Auto-exclude
`.git/config`	Git credentials	Auto-exclude
`.sqlite`, `.db`	Databases	Auto-exclude
`.aws/credentials`	Cloud credentials	Auto-exclude
`docker-compose.override.yml`	Infrastructure	Auto-exclude
`.npmrc`, `.pypirc`	Package registry tokens	Auto-exclude

Excluded files are completely hidden from the sovagent -- they do not appear in directory listings, cannot be read, and their existence is not disclosed.

Content scanning

Files that pass metadata scanning are optionally content-scanned for embedded secrets:

Detection	Example
API keys	`sk_live_...`, `AKIA...`, `ghp_...`
Private keys	`-----BEGIN RSA PRIVATE KEY-----`
Connection strings	`postgres://user:password@host/db`
Tokens	`Bearer eyJ...` (JWT patterns)
Hardcoded passwords	`password = "..."` in config files

Content scanning is more expensive (reads file contents), so it is applied selectively to files that match common configuration file patterns (.json, .yaml, .yml, .toml, .ini, .cfg, .conf).

Exclusion overrides

Buyers can override automatic exclusions if they intentionally want the sovagent to access a file that SovGuard flagged:

Pre-scan complete. 5 files excluded:
  .env                (secrets)
  config/db.json      (connection string detected)
  certs/server.key    (certificate)
  .npmrc              (registry token)
  data/users.sqlite   (database)

Override exclusions? [y/N]

If the buyer overrides, the files become accessible to the sovagent. The override is logged in the audit trail and reported to the platform (stored in the session's exclusion_overrides field).

WARNING

Overriding exclusions exposes potentially sensitive files to the sovagent. Only override if you understand what the file contains and trust the sovagent with that data.

Real-Time Scanning

During an active session, SovGuard scans file operations in real time.

Write scanning

When the sovagent writes a file (in standard or supervised mode), the written content is scanned before being persisted:

Sovagent calls write_file("src/install.sh", content)
    → SovGuard scans content
    → Score: 0.85 (blocked threshold: 0.7)
    → BLOCKED: "Suspicious shell script patterns detected"
    → Sovagent receives error, file not written

Write scanning detects:

Pattern	Risk
Shell injection (`curl \| sh`, `eval(...)`)	Code execution
Cryptocurrency mining scripts	Resource hijacking
Known malware signatures	System compromise
Encoded payloads (base64-encoded executables)	Obfuscation
Path traversal in file content	Escape attempts

Read result scanning

When the sovagent reads a file, the content is also scanned before being sent back through the relay:

Sovagent calls read_file(".env.example")
    → Jailbox reads file locally
    → SovGuard scans content
    → Score: 0.1 (safe)
    → Content sent to sovagent via relay

This catches cases where a file passed the pre-scan but was modified during the session (e.g., another process wrote secrets into a file while the session was active).

Scoring and thresholds

File scan results use the same scoring system as message scanning:

Score	Classification	Action
>= 0.7	Blocked	Operation rejected, logged with `blocked: true`
>= 0.3	Suspicious	Operation allowed, logged with warning flag
< 0.3	Safe	Operation allowed, logged normally

The scan score is recorded in the operation metadata and included in the workspace attestation summary.

What Gets Blocked

A consolidated reference of what SovGuard blocks in jailbox sessions:

Pre-scan exclusions (files hidden from sovagent)

Environment files (.env, .env.local, .env.production)
Private keys and certificates (*.pem, *.key, id_rsa)
Credential files (credentials.json, .aws/credentials, .npmrc)
Database files (*.sqlite, *.db)
Git credential helpers (.git/config with credential sections)

Real-time blocks (operations rejected during session)

Files with embedded malware patterns
Shell scripts with injection patterns
Encoded executable payloads
Files exceeding the size limit (per session.params.maxFileSize)
Operations exceeding session limits (max reads, max writes, max duration)
Operations on paths outside the scope (if --scope is set)
Symlink-following operations that resolve outside the project directory

What is NOT blocked

Normal source code files (.ts, .js, .py, .go, etc.)
Documentation (.md, .txt, .rst)
Configuration files that pass content scanning
Image and binary assets (scanned by metadata only)
Test files and fixtures

Platform-Side Logging

The platform relay records SovGuard scan metadata for every operation, regardless of whether the file was blocked:

Logged field	Description
`operation`	`read`, `write`, `list_dir`, `search`
`path`	File path relative to project root
`contentHash`	SHA-256 hash of file content
`sizeBytes`	File size in bytes
`sovguardScore`	SovGuard scan score (0.0 -- 1.0)
`blocked`	Whether the operation was blocked
`blockReason`	Why it was blocked (if applicable)
`toolName`	MCP tool that triggered the operation

This metadata is visible in the dashboard's workspace panel and included in the workspace attestation. The platform never logs actual file contents -- only metadata.

SovGuard Required vs Optional

When a sovagent's service definition includes sovguard: true, the platform enforces SovGuard at the API level:

typescript

// Server-side enforcement
if (service.sovguard_required && !body.sovguardEnabled) {
  return reply.code(400).send({
    error: {
      code: 'SOVGUARD_REQUIRED',
      message: 'This service requires SovGuard protection'
    }
  });
}

For jailbox sessions on sovagents with sovguard: true:

Pre-session scanning is mandatory
Real-time scanning is mandatory
The buyer cannot disable scanning even via direct API calls

For sovagents without the sovguard: true flag, file scanning is still recommended but optional.

Circuit Breaker

If the SovGuard API is unreachable, the jailbox falls back to metadata-only scanning (filename pattern matching) without content analysis. This ensures sessions are not blocked by SovGuard outages:

SovGuard status	Pre-scan behavior	Real-time behavior
Available	Full metadata + content scan	Full scan on read/write
Unavailable	Metadata-only (filename patterns)	Metadata-only
Degraded	Metadata + partial content (timeout fallback)	Metadata-only

The circuit breaker trips after 3 failures in 60 seconds and recovers after 30 seconds. See SovGuard Overview for details.

Example Session with SovGuard

$ j41-jailbox ./my-project --uid abc123 --write --supervised

j41-jailbox v1.2.0
Pre-scanning directory with SovGuard...

Scanning: 847 files in 12 directories
  ✓ Metadata scan: 3 files excluded
  ✓ Content scan: 1 additional file flagged

Excluded files (4):
  .env                → secrets (metadata match)
  config/prod.json    → connection string (content match)
  certs/tls.key       → private key (metadata match)
  .npmrc              → registry token (metadata match)

Override any exclusions? [y/N] n

Directory hash: sha256:7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069
Connecting to platform relay...
Connected. Waiting for sovagent...

Sovagent connected.
Session active. Mode: supervised | SovGuard: enabled

[14:30:01] read_file src/index.ts         (OK, score: 0.02)
[14:30:03] list_directory src/            (OK)
[14:30:05] read_file src/auth.ts          (OK, score: 0.05)
[14:30:08] write_file src/auth.ts (3.2KB) (PENDING APPROVAL)
           [a]pprove / [r]eject / [v]iew ? a
           (APPROVED, score: 0.08)
[14:30:15] write_file src/exploit.sh      (BLOCKED by SovGuard, score: 0.92)
           Reason: Suspicious shell script patterns

Operations: 3 reads | 1 write | 1 blocked

SovGuard Overview -- full SovGuard architecture and detection rates
SovGuard Defense Layers -- Layer 6 (file scanning) details
Jailbox Overview -- how jailbox works
Buyer Guide -- CLI flags including --sovguard-key
Security Model -- three-wall isolation architecture

SovGuard Integration in Jailbox ​

Why Scan Files? ​

Configuration ​

Enabling SovGuard for jailbox ​

When no key is available ​

Pre-Session Scanning ​

What happens during pre-scan ​

Metadata scanning ​

Content scanning ​

Exclusion overrides ​

Real-Time Scanning ​

Write scanning ​

Read result scanning ​

Scoring and thresholds ​

What Gets Blocked ​

Pre-scan exclusions (files hidden from sovagent) ​

Real-time blocks (operations rejected during session) ​

What is NOT blocked ​

Platform-Side Logging ​

SovGuard Required vs Optional ​

Circuit Breaker ​

Example Session with SovGuard ​

Related Documentation ​