Adds scan resumption capability to Strix, allowing users to resume interrupted scans from automatic checkpoints. Fixes #29

[ahmedk20]

Summary

Adds scan resumption capability to Strix, allowing users to resume interrupted scans from automatic checkpoints.

Key Features

• Automatic checkpointing after each agent iteration
• --resume flag to continue from saved state
• TUI resume indicator showing progress on splash screen
• Auto-cleanup of checkpoints after successful completion
• Graceful fallback when checkpoints are missing/invalid

Screenshots

Interrupt Scan:

Resume Indicator:

Continued Execution:

Implementation

Core Changes

New Checkpoint Module (strix/telemetry/checkpoint.py, 186 lines)

• Handles save/load/validation with atomic file operations
• JSON format with versioning for future schema migrations
• Stores full agent state, scan config, and tracer data

Agent State Persistence (strix/agents/base_agent.py:208)

• Saves checkpoint after each successful iteration
• Captures complete conversation history, sandbox info, and execution context
• Non-blocking error handling to prevent checkpoint failures from crashing scans

Resume Logic (strix/interface/cli.py:88-144, tui.py:304-347)

• Loads checkpoint when --resume flag detected
• Validates target compatibility before resuming
• Restores agent state and continues from saved iteration

TUI Enhancements (strix/interface/tui.py:153-161)

• Displays "✓ Resuming from iteration X/Y" on splash screen
• Amber/green styling for visual feedback
• Shows checkpoint validation status

Automatic Cleanup (strix/telemetry/tracer.py:211-219)

• Deletes checkpoint only on successful scan completion
• Preserves checkpoints for interrupted/failed scans

Technical Details

Checkpoint File Structure:

{
  "version": 1,
  "created_at": "2026-01-01T03:34:40+00:00",
  "scan_config": {
    "targets": [...],
    "run_name": "...",
    ...
  },
  "agent_state": {
    "iteration": 33,
    "max_iterations": 300,
    "messages": [...],
    "sandbox_id": "...",
    ...
  }
}

State Preservation:

• Full LLM conversation history (messages)
• Sandbox connection info (sandbox_id, sandbox_token)
• Agent context and execution metadata
• Action/observation logs with timestamps

Validation & Safety:

• Target count validation prevents resuming different scans
• Version checking enables future schema migrations
• Atomic writes (temp file + rename) prevent corruption
• Pydantic deserialization ensures type safety

Error Handling:

• All checkpoint operations wrapped in exception handlers
• Failures log warnings but never crash scans
• Invalid/missing checkpoints trigger fresh scan with feedback
• Graceful degradation philosophy throughout

Usage

# Start a scan
strix --target https://example.com --run-name my-scan

# If interrupted (Ctrl+C, crash, timeout), resume
strix --target https://example.com --run-name my-scan --resume

Edge Cases Handled

✓ Corrupted checkpoint files → starts fresh with warning
✓ Schema version mismatch → starts fresh
✓ Target mismatch → refuses resume with error
✓ Already completed scan → starts fresh
✓ Missing checkpoint → starts fresh with warning
✓ Checkpoint save failure → continues without checkpointing
✓ Pydantic validation errors → starts fresh with warning

[greptile-apps]

Greptile Summary

• Adds scan resumption functionality to Strix penetration testing framework with automatic checkpointing after each agent iteration and a --resume CLI flag
• Implements checkpoint management system with JSON-based state persistence, target validation, atomic file operations, and automatic cleanup after successful scan completion
• Enhances TUI to display resumption status on splash screen with visual indicators showing current iteration progress when resuming from checkpoint

Important Files Changed

Filename	Overview
strix/telemetry/checkpoint.py	New module providing checkpoint save/load operations with atomic writes, version management, and validation logic
strix/agents/base_agent.py	Added checkpoint saving after each successful iteration with error handling to prevent failures from crashing scans
strix/interface/cli.py	Integrated resume logic with checkpoint loading, state validation, and user feedback for resume operations
strix/interface/tui.py	Enhanced splash screen to show resumption status and added checkpoint loading logic to TUI app initialization

Confidence score: 4/5

• This PR appears well-implemented with comprehensive error handling and graceful fallbacks for checkpoint operations
• Score reflects solid implementation but complexity of state management and multiple file integrations requires careful review
• Pay close attention to strix/telemetry/checkpoint.py for atomic operations and strix/agents/base_agent.py for checkpoint timing logic

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as "CLI/TUI"
    participant Checkpoint as "Checkpoint"
    participant StrixAgent as "StrixAgent"
    participant BaseAgent as "BaseAgent"
    participant LLM as "LLM"
    participant Tools as "Tools"
    participant Tracer as "Tracer"

    User->>CLI: "strix --target example.com --resume"
    CLI->>Checkpoint: "can_resume(run_dir, scan_config)"
    Checkpoint-->>CLI: "true"
    CLI->>Checkpoint: "load_checkpoint(run_dir)"
    Checkpoint-->>CLI: "checkpoint_data"
    CLI->>StrixAgent: "new StrixAgent(config + restored_state)"
    CLI->>StrixAgent: "execute_scan(scan_config)"
    StrixAgent->>BaseAgent: "agent_loop(task)"
    
    loop Each Iteration
        BaseAgent->>LLM: "generate(conversation_history)"
        LLM-->>BaseAgent: "response"
        BaseAgent->>Tools: "process_tool_invocations(actions)"
        Tools-->>BaseAgent: "should_agent_finish"
        BaseAgent->>Tracer: "update agent status"
        BaseAgent->>Checkpoint: "save_checkpoint(run_dir, state, config)"
        Checkpoint-->>BaseAgent: "checkpoint saved"
    end
    
    BaseAgent-->>StrixAgent: "final_result"
    StrixAgent-->>CLI: "scan_result"
    CLI->>Tracer: "cleanup()"
    Tracer->>Checkpoint: "delete_checkpoint(run_dir)"
    CLI-->>User: "scan complete"

Loading

[greptile-apps]

Additional Comments (5)

1. strix/agents/base_agent.py, line 210-212 (link)

   style: imports are inside the try block, potentially causing performance overhead on every iteration

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

2. strix/agents/base_agent.py, line 215 (link)

   style: hasattr(self, "state") check is unnecessary since BaseAgent always has a state attribute initialized in __init__

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

3. strix/interface/cli.py, line 131 (link)

   logic: Redundant condition check - getattr(args, "resume", False) is already evaluated in the parent if statement on line 99

4. strix/interface/tui.py, line 342-347 (link)

   style: redundant condition check - getattr(args, "resume", False) is already checked on line 314

   _{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

5. strix/telemetry/checkpoint.py, line 161-167 (link)

   logic: Target validation only checks count, not content. Users could resume with different targets if counts match.

   Should target validation compare actual URLs/content instead of just count?

_{8 files reviewed, 5 comments}

_{Edit Code Review Agent Settings | Greptile}