From ccf823a2d56d3cb1441e8291c5b75ce50efae69e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADctor=20Mayoral=20Vilches?= Date: Fri, 14 Nov 2025 12:40:58 +0100 Subject: [PATCH] Document --continue mode MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: VΓ­ctor Mayoral Vilches --- docs/cai_quickstart.md | 22 ++ docs/continue_mode.md | 332 +++++++++++++++++++++++ examples/continue_mode_jokes.py | 77 ++++++ examples/continue_mode_security_audit.py | 137 ++++++++++ mkdocs.yml | 1 + 5 files changed, 569 insertions(+) create mode 100644 docs/continue_mode.md create mode 100644 examples/continue_mode_jokes.py create mode 100644 examples/continue_mode_security_audit.py diff --git a/docs/cai_quickstart.md b/docs/cai_quickstart.md index 6b65eb58..ecdef2ea 100644 --- a/docs/cai_quickstart.md +++ b/docs/cai_quickstart.md @@ -36,6 +36,28 @@ That should initialize CAI and provide a prompt to execute any security task you Here's a quick [demo video](https://asciinema.org/a/zm7wS5DA2o0S9pu1Tb44pnlvy) to help you get started with CAI. We'll walk through the basic steps β€” from launching the tool to running your first AI-powered task in the terminal. Whether you're a beginner or just curious, this guide will show you how easy it is to begin using CAI. +### Autonomous Mode with --continue + +CAI can run autonomously using the `--continue` flag, which makes agents automatically continue their work without waiting for user input: + +```bash +# Have CAI tell security jokes continuously +cai --continue --prompt "tell me a joke about security" + +# Run autonomous security audit +cai --continue --prompt "perform security audit of authentication system" + +# Hunt for vulnerabilities automatically +cai --continue --prompt "find SQL injection vulnerabilities" +``` + +With `--continue`, CAI will: +- Analyze the conversation context after each turn +- Generate intelligent continuation prompts +- Keep working until the task is complete or interrupted + +See the [Continue Mode Guide](continue_mode.md) for detailed information. + From here on, type on `CAI` and start your security exercise. Best way to learn is by example: ### Environment Variables diff --git a/docs/continue_mode.md b/docs/continue_mode.md new file mode 100644 index 00000000..36493359 --- /dev/null +++ b/docs/continue_mode.md @@ -0,0 +1,332 @@ +# CAI Continue Mode + +## Overview + +The `--continue` flag enables CAI agents to operate autonomously by automatically generating intelligent continuation prompts when they would normally stop and wait for user input. This feature uses AI-powered analysis to provide contextual advice based on the conversation history, allowing agents to work on complex tasks without manual intervention. + +## Quick Start + +```bash +# Tell jokes continuously +cai --continue --prompt "tell me a joke about security" + +# Analyze code autonomously +cai --continue --prompt "find all SQL injection vulnerabilities in this codebase" + +# Run security audit +cai --continue --prompt "perform a comprehensive security audit" +``` + +## Example: Security Jokes with Continue Mode + +Here's what happens when you run `cai --continue --prompt "tell me a joke about security"`: + +```bash +$ cai --continue --prompt "tell me a joke about security" + +πŸ€– Processing initial prompt: tell me a joke about security + +Agent: Why did the hacker break up with their password? + Because it wasn't strong enough! πŸ’”πŸ” + +πŸ€– Auto-continuing with: Tell another cybersecurity joke or pun. + +Agent: Why don't cybersecurity experts tell secrets at parties? + Because they're afraid of social engineering! πŸŽ‰πŸ•΅οΈ + +πŸ€– Auto-continuing with: Tell another cybersecurity joke or pun. + +Agent: What's a hacker's favorite season? + Phishing season! πŸŽ£πŸ’» + +[Continues until interrupted with Ctrl+C] +``` + +## How It Works + +### 1. Intelligent Context Analysis + +When an agent completes a turn, the continuation system analyzes: +- **Original request**: The initial task or prompt from the user +- **Conversation history**: Recent messages and responses +- **Tool usage**: Which tools were used and their outputs +- **Error states**: Any errors encountered and their types +- **Task progress**: Current state of task completion + +### 2. AI-Powered Continuation Generation + +The system uses the configured AI model (default: alias1) to generate contextual continuation prompts: + +```python +# The system creates a detailed context summary +context_summary = """ +ORIGINAL TASK: Tell me a joke about security +CONVERSATION FLOW: +User: Tell me a joke about security +Agent: Why did the hacker break up with their password? Because it wasn't strong enough! + +CURRENT STATUS: +- Last action: Told a cybersecurity joke +- Tools used: None +- Errors: No + +Generate a specific continuation prompt... +""" +``` + +### 3. Smart Fallback System + +When the AI model is unavailable, the system provides intelligent fallbacks based on context: + +| Scenario | Fallback Continuation | +|----------|----------------------| +| Security joke told | "Tell another cybersecurity joke or pun." | +| File not found | "Search for the correct file path or create the missing resource." | +| Search completed | "Examine the search results in detail and investigate the most relevant findings." | +| Security analysis | "Analyze the code for security vulnerabilities like injection flaws or authentication issues." | +| Permission denied | "Check permissions and try accessing the resource with appropriate credentials." | + +## Common Use Cases + +### 1. Automated Security Audits +```bash +cai --continue --prompt "perform a security audit of the authentication system" +``` +The agent will: +- Search for authentication-related files +- Analyze code for vulnerabilities +- Check for common security issues +- Generate a comprehensive report + +### 2. Continuous Bug Hunting +```bash +cai --continue --prompt "find and document all XSS vulnerabilities" +``` +The agent will: +- Search for user input handling code +- Identify potential XSS vectors +- Document findings +- Suggest fixes + +### 3. Extended Code Analysis +```bash +cai --continue --prompt "analyze this codebase for OWASP Top 10 vulnerabilities" +``` +The agent will: +- Systematically check for each vulnerability type +- Provide detailed findings +- Continue until all categories are covered + +### 4. Entertainment Mode +```bash +cai --continue --prompt "tell me cybersecurity jokes and fun facts" +``` +The agent will: +- Tell jokes about security topics +- Share interesting security facts +- Continue entertaining until stopped + +## Configuration + +### Environment Variables + +```bash +# Use a different model for continuation generation +export CAI_MODEL=gpt-4 +cai --continue --prompt "analyze this code" + +# Set a fallback model if primary fails +export CAI_CONTINUATION_FALLBACK_MODEL=gpt-3.5-turbo +cai --continue --prompt "test application security" + +# Configure API keys for custom models +export ALIAS_API_KEY=your-api-key +cai --continue --prompt "perform penetration testing" +``` + +### Combining with Other CAI Features + +```bash +# Use specific agent with continue mode +CAI_AGENT_TYPE=bug_bounter_agent cai --continue --prompt "test example.com" + +# Set workspace for file operations +CAI_WORKSPACE=project1 cai --continue --prompt "audit all Python files" + +# Enable streaming for real-time output +CAI_STREAM=true cai --continue --prompt "monitor security events" +``` + +## Advanced Features + +### Continuation Decision Logic + +The system decides whether to continue based on: +1. **Completion indicators**: Stops if agent says "completed", "finished", "done" +2. **Active work detection**: Continues if tools are being used +3. **Error recovery**: Attempts to resolve errors automatically +4. **Task progress**: Evaluates if the original goal is achieved + +### Context-Aware Prompts + +The continuation prompts adapt based on: +- **Task type**: Security analysis, testing, code review, etc. +- **Current state**: Errors, findings, progress +- **Tool usage**: Different prompts for different tools +- **Conversation flow**: Maintains coherent task progression + +## Best Practices + +### 1. Clear Initial Prompts +```bash +# Good - Specific and actionable +cai --continue --prompt "find SQL injection vulnerabilities in user.py" + +# Less effective - Too vague +cai --continue --prompt "check security" +``` + +### 2. Monitor Progress +- Check output periodically to ensure correct direction +- Use Ctrl+C to stop if needed +- Review logs for detailed execution history + +### 3. Set Appropriate Limits +```python +# In code integration, use max_turns +run_cai_cli( + starting_agent=agent, + initial_prompt="analyze security", + continue_mode=True, + max_turns=10 # Limit to 10 turns +) +``` + +### 4. Error Handling +The system automatically: +- Retries failed operations with different approaches +- Searches for alternatives when files are missing +- Adjusts strategies based on error types + +## Troubleshooting + +### Issue: Generic Continuation Messages +**Symptom**: Always see "Continue working on the task based on your previous findings" + +**Solution**: +- Check model configuration is correct +- Ensure API keys are valid +- Review debug logs for API errors + +### Issue: Continuation Not Triggering +**Symptom**: Agent stops after completing a task + +**Possible causes**: +- Agent explicitly said task is "completed" or "done" +- No recent tool usage detected +- Error in continuation module + +**Solution**: +- Use more open-ended initial prompts +- Check logs for completion indicators +- Verify --continue flag is properly set + +### Issue: Infinite Loops +**Symptom**: Agent keeps doing the same thing + +**Solution**: +- Set max_turns limit +- Use more specific initial prompts +- Interrupt with Ctrl+C and refine the task + +## Technical Implementation + +### Core Components + +1. **`src/cai/continuation.py`**: Main continuation logic + - `generate_continuation_advice()`: Creates AI-powered prompts + - `should_continue_automatically()`: Decides when to continue + +2. **`src/cai/cli.py`**: Integration point + - `--continue` flag handling + - Continuation loop implementation + +3. **Context Analysis**: + - Extracts conversation history + - Identifies tool usage patterns + - Detects error conditions + +### API Integration + +The continuation system uses LiteLLM for model calls: +```python +response = await litellm.acompletion( + model=model_name, + messages=[{"role": "user", "content": context_summary}], + temperature=0.3, # Low temperature for focused responses + max_tokens=150 +) +``` + +## Examples Gallery + +### Security Audit Continuation +``` +Original: "Audit the login system" +β†’ "Search for authentication-related files in the codebase." +β†’ "Analyze the login function for SQL injection vulnerabilities." +β†’ "Check password hashing implementation for security best practices." +β†’ "Review session management for potential security issues." +``` + +### Bug Bounty Continuation +``` +Original: "Test example.com for vulnerabilities" +β†’ "Perform initial reconnaissance to gather information about the target." +β†’ "Scan for exposed endpoints and services." +β†’ "Test authentication endpoints for common vulnerabilities." +β†’ "Check for information disclosure in error messages." +``` + +### Code Review Continuation +``` +Original: "Review api.py for security issues" +β†’ "Analyze input validation in API endpoints." +β†’ "Check for proper authentication and authorization." +β†’ "Review error handling for information leakage." +β†’ "Examine data serialization for injection vulnerabilities." +``` + +## Example Scripts + +Explore working examples in the `examples/` directory: + +### Security Jokes Example +```python +# examples/continue_mode_jokes.py +# Demonstrates continuous joke telling with --continue flag +python examples/continue_mode_jokes.py +``` + +### Security Audit Example +```python +# examples/continue_mode_security_audit.py +# Shows autonomous vulnerability scanning with --continue +python examples/continue_mode_security_audit.py +``` + +These examples demonstrate: +- How to use --continue flag programmatically +- Handling continuous output +- Graceful interruption with Ctrl+C +- Practical security use cases + +## Summary + +The `--continue` flag transforms CAI into an autonomous cybersecurity assistant capable of: +- Working independently on complex tasks +- Recovering from errors intelligently +- Maintaining context across multiple operations +- Providing entertainment with continuous jokes + +Whether you're conducting security audits, hunting for bugs, or just want some cybersecurity humor, continue mode keeps your agent working until the job is done. \ No newline at end of file diff --git a/examples/continue_mode_jokes.py b/examples/continue_mode_jokes.py new file mode 100644 index 00000000..2e0e57ca --- /dev/null +++ b/examples/continue_mode_jokes.py @@ -0,0 +1,77 @@ +#!/usr/bin/env python3 +""" +Example: Using CAI Continue Mode for Security Jokes + +This example demonstrates how to use CAI's --continue flag to have an agent +continuously tell cybersecurity jokes without manual intervention. + +Usage: + python examples/continue_mode_jokes.py + +Or directly from command line: + cai --continue --prompt "tell me a joke about security" +""" + +import subprocess +import sys +import os +import signal + +def run_joke_session(): + """Run CAI with continue mode to tell security jokes""" + + print("🎭 CAI Security Joke Session") + print("=" * 60) + print("Starting CAI in continue mode to tell cybersecurity jokes...") + print("Press Ctrl+C to stop when you've had enough laughs!") + print("=" * 60) + + # Command to run CAI with continue flag + cmd = [ + sys.executable, + "src/cai/cli.py", + "--continue", + "--prompt", "tell me a joke about cybersecurity" + ] + + try: + # Run CAI + proc = subprocess.Popen( + cmd, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + stdin=subprocess.PIPE, + text=True, + bufsize=1 + ) + + # Close stdin to prevent hanging + proc.stdin.close() + + # Read and display output + for line in proc.stdout: + print(line, end='') + + # Highlight continuation messages + if "Auto-continuing with:" in line: + print("πŸ”„ " + "=" * 56) + + except KeyboardInterrupt: + print("\n\nβœ‹ Joke session interrupted by user") + if proc.poll() is None: + proc.terminate() + print(" Gracefully stopping CAI...") + + except Exception as e: + print(f"\n❌ Error: {e}") + + print("\n" + "=" * 60) + print("Thanks for using CAI joke mode! πŸŽ‰") + +if __name__ == "__main__": + # Change to project root directory + script_dir = os.path.dirname(os.path.abspath(__file__)) + project_root = os.path.dirname(script_dir) + os.chdir(project_root) + + run_joke_session() \ No newline at end of file diff --git a/examples/continue_mode_security_audit.py b/examples/continue_mode_security_audit.py new file mode 100644 index 00000000..ea686ac3 --- /dev/null +++ b/examples/continue_mode_security_audit.py @@ -0,0 +1,137 @@ +#!/usr/bin/env python3 +""" +Example: Autonomous Security Audit with CAI Continue Mode + +This example shows how to use CAI's --continue flag to perform an autonomous +security audit that continues analyzing files and finding vulnerabilities +without manual intervention. + +Usage: + python examples/continue_mode_security_audit.py + +Or directly from command line: + cai --continue --prompt "perform a security audit of all Python files" +""" + +import subprocess +import sys +import os +import time +import signal + +def run_security_audit(): + """Run CAI with continue mode for autonomous security auditing""" + + print("πŸ”’ CAI Autonomous Security Audit") + print("=" * 60) + print("Starting autonomous security audit...") + print("CAI will continuously analyze code for vulnerabilities.") + print("Press Ctrl+C to stop the audit.") + print("=" * 60) + + # Create a sample vulnerable file for demonstration + sample_file = "sample_vulnerable.py" + with open(sample_file, "w") as f: + f.write(''' +# Sample file with security vulnerabilities for CAI to find + +import os +import sqlite3 + +def login(username, password): + # SQL Injection vulnerability + conn = sqlite3.connect('users.db') + query = f"SELECT * FROM users WHERE name='{username}' AND pass='{password}'" + cursor = conn.execute(query) + return cursor.fetchone() + +def execute_command(user_input): + # Command Injection vulnerability + os.system(f"echo {user_input}") + +def read_file(filename): + # Path Traversal vulnerability + with open(f"/app/data/{filename}", "r") as f: + return f.read() + +# Hardcoded credentials +API_KEY = "sk-1234567890abcdef" +DB_PASSWORD = "admin123" +''') + + # Command to run CAI audit + cmd = [ + sys.executable, + "src/cai/cli.py", + "--continue", + "--prompt", f"Perform a comprehensive security audit of {sample_file}, " + f"identify all vulnerabilities, and suggest fixes" + ] + + try: + # Run CAI + proc = subprocess.Popen( + cmd, + stdout=subprocess.PIPE, + stderr=subprocess.STDOUT, + stdin=subprocess.PIPE, + text=True, + bufsize=1 + ) + + # Close stdin + proc.stdin.close() + + # Track findings + vulnerabilities_found = [] + continuation_count = 0 + + # Read output + for line in proc.stdout: + print(line, end='') + + # Track vulnerabilities + vuln_keywords = ["injection", "vulnerability", "security issue", + "hardcoded", "insecure", "exposed"] + if any(keyword in line.lower() for keyword in vuln_keywords): + vulnerabilities_found.append(line.strip()) + + # Track continuations + if "Auto-continuing with:" in line: + continuation_count += 1 + print(f"πŸ”„ Continuation #{continuation_count} " + "=" * 40) + + # Stop after finding multiple issues + if continuation_count >= 5: + print("\nπŸ“‹ Audit Summary: Found multiple security issues.") + print(" Stopping audit after thorough analysis.") + proc.terminate() + break + + except KeyboardInterrupt: + print("\n\nβœ‹ Security audit interrupted by user") + if proc and proc.poll() is None: + proc.terminate() + + except Exception as e: + print(f"\n❌ Error: {e}") + + finally: + # Cleanup + if os.path.exists(sample_file): + os.remove(sample_file) + print(f"\nπŸ—‘οΈ Cleaned up {sample_file}") + + print("\n" + "=" * 60) + print("πŸ”’ Security Audit Complete") + if vulnerabilities_found: + print(f" Found {len(set(vulnerabilities_found))} potential security issues") + print("=" * 60) + +if __name__ == "__main__": + # Change to project root directory + script_dir = os.path.dirname(os.path.abspath(__file__)) + project_root = os.path.dirname(script_dir) + os.chdir(project_root) + + run_security_audit() \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index b5d24d14..feb9f1c4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -93,6 +93,7 @@ nav: # ======================================== - Guides: - Running Agents: running_agents.md + - Continue Mode: continue_mode.md - Working with Results: results.md - Streaming: streaming.md - Tracing & Debugging: tracing.md