Security Considerations¶

Overview¶

Ralph Orchestrator executes AI agents with significant system access. This document outlines security considerations and best practices for safe operation.

Threat Model¶

Potential Risks¶

Unintended Code Execution
AI agents may generate and execute harmful code
File system modifications beyond project scope
System command execution
Data Exposure
API keys in prompts or code
Sensitive data in Git history
Credentials in state files
Resource Exhaustion
Infinite loops in generated code
Excessive API calls
Disk space consumption
Supply Chain
Compromised AI CLI tools
Malicious prompt injection
Dependency vulnerabilities

Security Controls¶

Ralph implements multiple security layers to protect against threats:

 🔒 Security Defense Layers

   ╭───────────────────╮
   │    User Input     │
   ╰───────────────────╯
     │
     │
     ∨
   ┌───────────────────┐
   │ Input Validation  │
   └───────────────────┘
     │
     │
     ∨
   ┌───────────────────┐
   │ Process Isolation │
   └───────────────────┘
     │
     │
     ∨
   ┌───────────────────┐
   │  File Boundaries  │
   └───────────────────┘
     │
     │
     ∨
   ┌───────────────────┐
   │    Git Safety     │
   └───────────────────┘
     │
     │
     ∨
   ┌───────────────────┐
   │ Env Sanitization  │
   └───────────────────┘
     │
     │
     ∨
   ╭───────────────────╮
   │     AI Agent      │
   ╰───────────────────╯

graph-easy source

graph { label: "🔒 Security Defense Layers"; flow: south; }
[ User Input ] { shape: rounded; } -> [ Input Validation ]
[ Input Validation ] -> [ Process Isolation ]
[ Process Isolation ] -> [ File Boundaries ]
[ File Boundaries ] -> [ Git Safety ]
[ Git Safety ] -> [ Env Sanitization ]
[ Env Sanitization ] -> [ AI Agent ] { shape: rounded; }

Process Isolation¶

Ralph runs AI agents in subprocesses with:

Timeout protection (5 minutes default)
Output size limits
Error boundaries

result = subprocess.run(
    cmd,
    capture_output=True,
    text=True,
    timeout=300,  # 5-minute timeout
    env=filtered_env  # Sanitized environment
)

File System Boundaries¶

Restricted Paths¶

Work within project directory
No access to system files
Preserve .git integrity

Safe Defaults¶

# Validate paths stay within project
def validate_path(path):
    abs_path = os.path.abspath(path)
    project_path = os.path.abspath('.')
    return abs_path.startswith(project_path)

Git Safety¶

Protected Operations¶

No force pushes
No branch deletion
No history rewriting

Checkpoint-Only Commits¶

# Ralph only creates checkpoint commits
git add .
git commit -m "Ralph checkpoint: iteration N"

Environment Sanitization¶

Filtered Variables¶

SAFE_ENV_VARS = [
    'PATH', 'HOME', 'USER',
    'LANG', 'LC_ALL', 'TERM'
]

def get_safe_env():
    return {k: v for k, v in os.environ.items()
            if k in SAFE_ENV_VARS}

No Credential Exposure¶

Never pass API keys through environment
Agents should use their own credential stores
No secrets in prompts or logs

Best Practices¶

1. Prompt Security¶

DO¶

Review prompts before execution
Use specific, bounded instructions
Include safety constraints

DON'T¶

Include credentials in prompts
Request system-level changes
Use unbounded iterations

2. Agent Configuration¶

Claude¶

# Use restricted mode if available
claude --safe-mode PROMPT.md

Gemini¶

# Limit context and capabilities
gemini --no-web --no-exec PROMPT.md

3. Repository Setup¶

.gitignore¶

# Security-sensitive files
*.key
*.pem
.env
.env.*
secrets/
credentials/

# Ralph workspace
.agent/metrics/
.agent/logs/

Pre-commit Hooks¶

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/Yelp/detect-secrets
    hooks:
      - id: detect-secrets
        args: ["--baseline", ".secrets.baseline"]

4. Runtime Monitoring¶

Resource Limits¶

# Set resource limits
import resource

# Limit memory usage to 1GB
resource.setrlimit(
    resource.RLIMIT_AS,
    (1024 * 1024 * 1024, -1)
)

# Limit CPU time to 1 hour
resource.setrlimit(
    resource.RLIMIT_CPU,
    (3600, -1)
)

Audit Logging¶

import logging
import json

# Log all agent executions
logging.info(json.dumps({
    'event': 'agent_execution',
    'agent': agent_name,
    'timestamp': time.time(),
    'user': os.getenv('USER'),
    'prompt_hash': hashlib.sha256(prompt.encode()).hexdigest()
}))

Security Checklist¶

Before Running Ralph¶

Review PROMPT.md for unsafe instructions
Check no credentials in prompt
Verify working directory is correct
Ensure Git repository is backed up
Confirm agent tools are up-to-date

During Execution¶

Monitor resource usage
Watch for unexpected file changes
Check agent output for anomalies
Verify checkpoints are created
Ensure no sensitive data in logs

After Completion¶

Review generated code for security issues
Check Git history for exposed secrets
Verify no system files were modified
Clean up temporary files
Rotate any potentially exposed credentials

Incident Response¶

If Compromise Suspected¶

Immediate Actions

# Stop Ralph
pkill -f ralph_orchestrator

# Preserve evidence
cp -r .agent /tmp/ralph-incident-$(date +%s)

# Check for modifications
git status
git diff

Investigation
Review .agent/metrics/state_*.json
Check system logs
Examine Git history
Analyze agent outputs
Recovery

# Reset to last known good state
git reset --hard <last-good-commit>

# Clean workspace
rm -rf .agent

# Rotate credentials if needed
# Update API keys for affected services

Sandboxing Options¶

Docker Container¶

FROM python:3.11-slim
RUN useradd -m -s /bin/bash ralph
USER ralph
WORKDIR /home/ralph/project
COPY --chown=ralph:ralph . .
CMD ["./ralph", "run"]

Virtual Machine¶

# Run in VM with snapshot
vagrant up
vagrant ssh -c "cd /project && ./ralph run"
vagrant snapshot restore clean

Restricted User¶

# Create restricted user
sudo useradd -m -s /bin/bash ralph-runner
sudo usermod -L ralph-runner  # No password login

# Run as restricted user
sudo -u ralph-runner ./ralph run

API Key Management¶

Secure Storage¶

Never Store Keys In¶

PROMPT.md files
Git repositories
Environment variables in scripts
Log files

Recommended Approaches¶

Agent-specific credential stores
System keychain/keyring
Encrypted vault (e.g., HashiCorp Vault)
Cloud secret managers

Key Rotation¶

# Regular rotation schedule
# 1. Generate new keys
# 2. Update agent configurations
# 3. Test with new keys
# 4. Revoke old keys

Compliance Considerations¶

Data Privacy¶

Don't process PII in prompts
Sanitize outputs before sharing
Comply with data residency requirements

Audit Trail¶

Maintain execution logs
Track prompt modifications
Document agent interactions

Access Control¶

Limit who can run Ralph
Restrict agent permissions
Control repository access

Security Updates¶

Stay current with:

AI CLI tool updates
Python security patches
Git security advisories
Dependency vulnerabilities

# Check for updates
npm update -g @anthropic-ai/claude-code
pip install --upgrade subprocess
git --version

Reporting Security Issues¶

If you discover a security vulnerability:

Do NOT open a public issue
Email security report to: security@ralph-orchestrator.org
Include:
Description of vulnerability
Steps to reproduce
Potential impact
Suggested fix (if any)

We aim to respond within 48 hours and provide fixes promptly.