Skip to content

MEMORY.md

Latest commit

 

History

History
51 lines (39 loc) · 4.54 KB

MEMORY.md

File metadata and controls

51 lines (39 loc) · 4.54 KB
Raw

🧠 MEMORY.md - Long-Term Memory

Project Overview: PulseLab Pentesting Suite

Advanced autonomous security analysis platform integrating MAS, specialized adapters, and a dynamic RE-AI lab.

🏗️ Core Architecture (Updated 2026-05-15)

  • Virtual Workspace System: Implemented WorkspaceManager and VirtualPathMapper.
    • Global Root: The system now dynamically maps /workspace/ to the invocation directory.
    • Session Persistence: Path mappings are consistent even across bridge restarts.
  • Agent Orchestration: ReAct loop via core/agent.py with CodeBlockExtractor for direct command execution.
  • Safety: Robust HITL approval system and per-session volume isolation.

📈 Current State

Recent Milestones

  1. Persistent Virtual Workspaces: Decoupled tool operations from hardcoded project paths. Tools now use workspace:// protocol.
  2. Global Invocation: Consola (mcp_console.py) updated for remote orchestration via --url and --session.
  3. Dynamic Container Remounting: Docker sandbox now hot-swaps volumes when engagement scope changes.
  4. RE-AI Sprints 0-4: Full Ghidra/Frida/ML pipeline operational.
  5. Technical Debt & Refactoring Plans: Defined five comprehensive refactoring specifications in docs/plans/tech_debt/ covering SRP violations, circular dependency resolution, error handling robustness, finding signatures, and structured CLI parsers.
  6. Core Framework Bug-Fixes (2026-05-18): Resolved major issues in WebSocket direct-broadcast deduplication, fixed the LLMFallbackParser method calling error, and corrected regex newlines in ResultCompactor.
  7. Modernized CLI Adapters & Pydantic Schemas: Standardized all key pentesting adapters (Nmap, Nikto, Nuclei, Gobuster, Masscan, Sqlmap) to parse machine-readable outputs natively into structured Pydantic schemas, with self-correcting LLM Fallback parsing under strict schema validation. Fixed critical SCM core validation mode logic bugs.
  8. Native Windows Tools execution (2026-05-26): Added capabilities for tools to break out of Docker and run natively on Windows host (hash_crack_sha256), solving path coupling and isolation issues with tools like Hashcat.
  9. Asynchronous Streaming Tools (2026-05-26): Re-engineered live_packet_analysis to operate entirely in the background. It returns immediately to unblock the agent, streams decoded packets directly to the internal EventBus in batches, and simultaneously writes rolling .pcap files using ring buffers.

⚠️ Critical Context

  • Invocation Root: Everything in this repository is managed relative to where main.py is started.
  • Network Mode: Always check HOST vs SANDBOX before running port_scan.
  • SCM Layer: SCM is managed and validated externally, which simplifies internal security gates.
  • Investigation Philosophy: Investigations must generate findings that serve as action plans. Purely theoretical research without actionable paths violates operational standards.

💡 Lessons Learned

  • Path Portability: Hardcoded Windows paths break containers. Always use workspace_manager.resolve_container() or the workspace:// URI.
  • Command Sanitization: LLMs often add $ or # to bash commands; the ArgumentNormalizer now strips these.
  • Modular Boundaries: Designing abstract interfaces before addressing concrete dependencies is crucial to break Python circular import traps cleanly.
  • Subscriber Signature Introspection: When augmenting framework callbacks to pass additional metadata (like event_id for deduplication), we can use inspect.signature to dynamically inspect subscriber signatures. This maintains seamless backward-compatibility without breaking older or third-party subscriptions.
  • Tool Blocking: Network scanning/capture tools MUST NOT block the main thread. Streaming architectures utilizing the internal EventBus and background workers keep the orchestrator highly responsive.
  • Reality Checks: Extended agent memory (like MEMORY.md and memory/YYYY-MM-DD.md) acts as an operational anchor ("reality check") ensuring that deep, prolonged execution doesn't drift from core goals.

🎯 Next Steps

  • Technical Debt Execution: Begin refactoring inline imports (02_dependency_boundaries.md) and the God class PentestAgent (01_srp_agent_refactoring.md).
  • Cryptographic Finding Signatures: Replace fragile description substring deduplication in tools/reporting.py.
  • XML/JSON Adapter Modernization: Move CLI tool adapters to natively parse machine-readable outputs.