GitHub - agairola/securing-ralph-loop: Security checks for the Ralph Loop - scan before commit, fix iteratively, escalate when stuck

Adding security practices to the Ralph Loop - scan, fix, repeat.

Ralph is an autonomous AI agent loop that runs Claude Code repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. Memory persists via git history, progress.txt, and prd.json. Based on Geoffrey Huntley's Ralph pattern.

When I saw the Ralph pattern going viral, my security paranoia got the best of me. After wasting way too many tokens, I came up with a simple approach: put security checks in the path for each generation, independent of any external tooling, using open-source scanners. Is it bulletproof? Definitely not. But it's a thought exercise in how we can take traditional DevSecOps practices and let AI follow them while still being functional.

PRD → Claude Code → Implement → Security Scan → PASS? → Commit → Next Story
                                      ↓
                                     FAIL → Fix → Retry (3x) → Escalate

"AFK (Away From Keyboard) movement" - run this, walk away, come back to secure code.

The name "Ralph Wiggum Loop" is a nod to The Simpsons character who's famously oblivious to danger. This system is the opposite: it catches security issues automatically, so you don't have to.

Traditional AI-assisted development:

• AI writes code → human hopes it's secure → CI finds issues → human fixes

Securing Ralph Loop:

• AI writes code → scans immediately → AI fixes issues → repeats until secure → escalates if stuck

The security loop runs inside Claude's session, giving it full context to fix problems iteratively. You can step away knowing that vulnerable code won't reach your branch.

Security Tenets

This project is built on 10 security principles:

How Security Is Enforced

Security scanning is mandatory through Claude Code's skills system:

How scanning is enforced

1. Workflow Instructions (CLAUDE.md)

   • Requires /security-scan before every commit
   • Documents the scan-fix-retry loop

2. Claude Code Skills (.claude/skills/)

   • /security-scan - Runs ASH with 5 scanners, enforces PASS/FAIL
   • /fix-security - Applies secure coding patterns
   • /self-check - Pre-commit validation
   • /code-review - Security-focused review checklist

3. Pre-Execution Hooks (.claude/hooks/)

   • Validates every Bash command before execution
   • Blocks: network commands, privilege escalation, dangerous deletions

4. Permission Controls (.claude/settings.local.json)

   • Whitelist of allowed tools
   • Explicit deny list for dangerous operations
   • No curl, wget, sudo, ssh

The Mandatory Loop

Code changes → /self-check → /security-scan → Compare baseline
                                    ↓
                        NEW findings? → FAIL (block commit)
                                    ↓
                        No NEW? → PASS (allow commit)
                                    ↓
                        3 failures? → Escalate to human

Acknowledgments

The Ralph Loop

Built on the Ralph Loop methodology created by Geoffrey Huntley. His original work on autonomous AI development loops (ghuntley.com/ralph, ghuntley.com/loop) introduced the concept of "AFK movement" - letting AI agents work autonomously while humans step away. This adds security practices to that loop: scan before commit, fix iteratively, escalate when stuck.

Open Source Tools

• ASH - AWS Labs' security scanner orchestrator
• claude-code-transcripts - Simon Willison's transcript extractor
• Semgrep - Multi-language static analysis
• Grype - Vulnerability scanner for containers and filesystems
• Checkov - Infrastructure-as-Code security scanner
• detect-secrets - Credential detection by Yelp

Quick Start

# 1. Clone this repo
git clone https://github.com/yourorg/securing-ralph-loop.git
cd securing-ralph-loop

# 2. Install prerequisites
npm install -g @anthropic-ai/claude-code
curl -LsSf https://astral.sh/uv/install.sh | sh
brew install jq

# 3. Run on your project
./ralph-secure.sh /path/to/your-project

# 4. Edit the PRD with your user stories
nano state/your-project/prd.json

Prerequisites

Usage

# Basic - run on a project directory
./ralph-secure.sh /path/to/project

# With options
./ralph-secure.sh --max-iterations 5 --target /path/to/project

# All options
./ralph-secure.sh \
  --project my-app \
  --target /path/to/project \
  --max-iterations 10 \
  --slack-webhook https://hooks.slack.com/... \
  --no-create-issues

Options

PRD Format

User stories go in state/{project}/prd.json:

{
  "projectName": "My App",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add login page",
      "description": "As a user, I want to log in with email/password",
      "acceptanceCriteria": ["Form validates email", "Shows error on failure"],
      "passes": false
    }
  ]
}

Set passes: false for stories you want Claude to implement.

What It Does

1. Spawns Claude Code on your project
2. Claude implements user stories from the PRD
3. Before each commit, runs security scan (ASH/Semgrep/Grype)
4. If scan fails, Claude fixes issues (up to 3 retries)
5. If still failing, escalates to human review
6. Repeats until all stories pass or max iterations reached

Documentation

• How It Works - Architecture and flow
• Security Model - Threat mitigations
• Customization - Custom rules and thresholds
• Troubleshooting - Common issues

License

MIT