Kokeshi Beanstalk 🌱

Runtime security guardian for Clawdbot installations.

A Darby Tool from PIP Projects Inc.

"Kokeshi Beanstalk never changes system state without explaining what will happen, asking permission, and confirming success."

The Problem

Clawdbot is amazing, but the default configuration often exposes your API keys and chat history to the public internet.

Kokeshi Beanstalk is a runtime sentinel that runs alongside your bot to:

1. Lock the doors (Enforce localhost binding & auth tokens)
2. Watch the windows (Detect exposure & port scans)
3. Encrypt the secrets (Protect MEMORY.md at rest)

Quick Start

# 1. Run the hardening script (One-time setup)
npx kokeshi-beanstalk harden

# 2. Start the monitor
npx kokeshi-beanstalk monitor

Features

🛡️ Defense in Depth

• Network: Monitors port 18789 for 0.0.0.0 binding
• Config: Validates clawdbot.json against security best practices
• Storage: AES-256 encryption for sensitive memory files

🎲 Prime-Fibonacci Jitter

Most security monitors check at fixed intervals (e.g., every 10s). Attackers can time their probes to slip in between checks.

Kokeshi Beanstalk uses a hybrid timing algorithm:

Interval = (Prime × Multiplier) + (Fibonacci × Variation) + CSPRNG noise

This creates a non-harmonic monitoring pattern with genuine cryptographic randomness added at each cycle. The jitter is scheduling noise — it makes monitoring intervals unpredictable, but it is not a security primitive on its own. Your primary defenses are localhost binding, auth tokens, and proper firewalling. Jitter is an additional layer that makes probe timing harder to predict.

🌸 Fibonacci Bloom Filter

Tracks suspicious connection attempts using a space-efficient probabilistic data structure. It remembers repeat probes without needing a heavy database.

🧠 Timing Model: Anti-Pattern Scheduling

Kokeshi Beanstalk uses a two-layer timing approach to make monitoring intervals unpredictable.

Important: Jitter is a scheduling technique, not a security boundary. Your real security comes from localhost binding, auth tokens, file encryption, and OS-level firewalling. Jitter makes it harder for an attacker to time probes between checks, but it does not compensate for weak network binding, missing auth, or absent firewalling.

Layer 1: The Weave (Coverage)

The Prime-Fibonacci slapback algorithm distributes monitoring intervals non-linearly across the time spectrum. This avoids the predictable gaps that occur with fixed-interval monitoring (e.g., checking every 10 seconds creates a known safe window at second 11).

• Prime numbers distribute check windows across the time spectrum.
• Fibonacci variation adds amplitude diversity.
• Figure-8 slapback prevents linear sequence prediction.

Layer 2: The Noise (Unpredictability)

Each interval includes genuine cryptographic randomness:

| Source | Range | Notes | | :--- | :--- | :--- | | crypto.randomBytes(2) | 0–500ms | CSPRNG — the real entropy source | | process.hrtime()[1] | 0–100ns | CPU nanosecond noise | | Temporal Drift | ×17 daily variants | Minor daily variation |

The CSPRNG component provides the meaningful unpredictability. The prime-fibonacci weave determines the general scheduling window; the random noise determines the exact moment within that window.

What This Means

The weave pattern is deterministic and public (visible in source code). The CSPRNG noise is private and genuinely random. An attacker who reads this source code knows the scheduling pattern but cannot predict the exact check time due to the random component. This makes timing attacks harder but is not a substitute for proper network security.

Usage

🔍 Security Scan

Check your installation for security issues without making changes. Shows a security score and tells you exactly how to fix each issue.

npx kokeshi-beanstalk scan

Example output:

╔═══════════════════════════════════════════════════════════════════════╗
║              KOKESHI BEANSTALK - SECURITY SCAN                        ║
╠═══════════════════════════════════════════════════════════════════════╣
║  ❌ Security Score: 35/100  Grade: F                                  ║
║  [███████░░░░░░░░░░░░░]                                               ║
╚═══════════════════════════════════════════════════════════════════════╝

🔴 [CRITICAL] Your bot is visible to the entire internet
   Technical: Gateway bound to 0.0.0.0 instead of 127.0.0.1
   Fix: Edit ~/.clawdbot/clawdbot.json: set "gateway.bind": "127.0.0.1"

🟠 [HIGH] Your memories are stored in plain text
   Technical: MEMORY.md exists unencrypted
   Fix: npx kokeshi-beanstalk protect --secure --file ~/clawd/MEMORY.md

🟡 [MEDIUM] Your bot accepts messages from anyone
   Technical: DM policy is "open" instead of "pairing"
   Fix: Edit config: set "channels.dmPolicy": "pairing"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔴 CRITICAL = You could be hacked right now
🟠 HIGH     = Fix this today
🟡 MEDIUM   = Recommended improvement
🔵 LOW      = Nice to have

───────────────────────────────────────────────────────────────────────
Don't want to fix manually? Run: npx kokeshi-beanstalk harden
───────────────────────────────────────────────────────────────────────

Harden Configuration (Guided Wizard)

Interactive 4-step wizard that explains changes, asks permission, applies them, and verifies success.

npx kokeshi-beanstalk harden

The wizard flow:

1. Step 1 (Explain) - Shows exactly what will change
2. Step 2 (Confirm) - Asks "Ready to apply these changes?"
3. Step 3 (Execute) - Applies changes, shows token, confirms you saved it
4. Step 4 (Verify) - Re-validates config to confirm success

For automation (CI/CD, scripts):

npx kokeshi-beanstalk harden --yes    # Skip prompts, but still shows explanations

Note: The --yes flag skips prompts but NOT explanations. This ensures auditable logs even in CI/CD pipelines.

🔐 File Protection (Guided Wizard)

Interactive 3-step wizard that walks you through protecting your sensitive files.

npx kokeshi-beanstalk protect           # Interactive mode selection
npx kokeshi-beanstalk protect --secure  # Keychain mode (machine-bound)
npx kokeshi-beanstalk protect --max     # Passphrase mode (prompts for password)

The wizard flow:

1. Step 1 (Explain) - Shows files found, explains protection levels
2. Step 2 (Confirm) - You pick mode; passphrase requires double-entry + "I UNDERSTAND"
3. Step 3 (Execute) - Protects files, offers to test unprotect immediately

Safety net: After protecting files, the wizard offers "Test unprotect now? [Y/n]" to verify you can recover your data before deleting originals.

Protection Levels:

| Mode | Security | Recovery | Best For | |------|----------|----------|----------| | obfuscate | Low | Always (no key needed) | Casual privacy, stops shoulder surfers | | keychain | High | Via system login | Most users - secure but can't lose key | | passphrase | Maximum | User responsible | High security needs, compliance |

For automation:

npx kokeshi-beanstalk protect --secure --yes                    # Keychain, no prompts
npx kokeshi-beanstalk protect --max --secret "pass" --yes       # Passphrase, no prompts
npx kokeshi-beanstalk unprotect --file MEMORY.md.aes --secret "pass" --yes

File extensions by mode:

• .obf = obfuscated (reversible, no key)
• .enc = keychain encrypted (key in system keychain)
• .aes = passphrase encrypted (user manages key)

Recommendation: Use --secure (keychain) for most cases. Only use --max if you have specific compliance requirements and a password manager.

Monitor

Runs the continuous sentinel process.

npx kokeshi-beanstalk monitor --jitter-min 1000 --jitter-max 30000

Install Globally (Optional)

npm install -g kokeshi-beanstalk

Design Principles

Guided Wizard UX

Principle (testable):

"Any command that mutates system state MUST execute an explicit Explain → Confirm → Execute flow, unless --yes is provided."

Why this rule exists:

1. Prevent silent failure - Explanations ensure you know what should happen, so you can detect when something goes wrong
2. Prevent accidental lockout - Confirmations catch typos and misunderstandings before they become irreversible
3. Prevent irreversible mistakes - Dangerous actions require typing "I UNDERSTAND" to prove intent

STATE CHANGE includes: file writes, permission changes, key generation, service registration, network rule changes, background processes, or deletion.

The --yes flag:

• Skips prompts (confirmations, mode selection)
• Does NOT skip explanations (Step 1 is always shown)
• Ensures auditable logs even in CI/CD pipelines

Security Coverage

| Vulnerability | Status | |---------------|--------| | Unauth Admin UI | ✅ SOLVED | | Public Exposure | ✅ SOLVED | | RCE via Skills | ✅ MITIGATED | | Plaintext Memory | ✅ SOLVED |

Keychain Threat Model

Keychain mode (--secure) stores the encryption key in your OS keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service).

What keychain protects against:

• Disk theft (encrypted at rest by OS)
• Casual file access by another user on the same machine
• Key extraction without your OS login credentials

What keychain does NOT protect against:

• A compromised OS user session (malware running as your user, an attacker logged into your account)
• Root/admin-level access to the machine
• Physical access to an unlocked, logged-in session

Recommended OS hardening:

• Enable full-disk encryption (FileVault, BitLocker, LUKS)
• Use a screen lock with short timeout
• Practice least-privilege (don't run as admin daily)
• Keep your OS and keychain software updated

If your threat model includes a compromised OS session, use --max (passphrase mode) with a strong passphrase stored in a separate password manager.

Security Guarantees and Non-Guarantees

What Kokeshi Beanstalk guarantees:

• Config hardening enforces localhost binding, token auth, and restrictive file permissions
• AES-256-GCM (AEAD) encryption provides confidentiality and tamper detection for protected files
• Symlink, hardlink, and path traversal attacks are blocked on all file write paths
• The --secret CLI flag is blocked by default (requires --force) to prevent process-list leakage
• Obfuscate mode is clearly labeled as NOT encryption throughout the UI
• All state-changing commands follow Explain -> Confirm -> Execute flow

What Kokeshi Beanstalk does NOT guarantee:

• Jitter timing is scheduling noise, not a security boundary — it does not replace firewalls or auth
• Keychain security depends on your OS keychain — a compromised session compromises the key
• Obfuscate mode provides zero cryptographic security (it's reversible without a key)
• This tool hardens Clawdbot's config — it cannot protect against vulnerabilities in Clawdbot itself
• Bloom filter tracking is probabilistic (false positives are possible by design)

Author

Darby Bailey McDonough, Ph.D. GitHub: @darbybailey

Acknowledgments

Built with assistance from Claude (Anthropic), Gemini (Google), and Grok (xAI).

License

MIT © PIP Projects Inc.