Standardize agent's reports production

[konradsemsch]

The agent currently generates a number of scattered reports for a single operation, creating unnecessary clutter and confusion. Example from a recent run:

1. EXECUTIVE_BRIEFING.md - Crisis response
2. SECURITY_ASSESSMENT_REPORT.md - Technical analysis
3. EXECUTIVE_SUMMARY.md - Business impact
4. PROOF_OF_CONCEPT.md - Exploitation guide
5. README.md - Quick reference
6. INDEX.md - Documentation navigation
7. METRICS_REPORT.txt - Statistics
8. ASSESSMENT_COMPLETE.md - Closure
9. FINAL_DELIVERABLES.md - Complete guide

Current Issues

• Information fragmentation: Critical findings spread across 9 files makes it hard to get a complete picture
• Inconsistent content: No clear distinction between what goes in each file
• Maintenance burden: Multiple files to update when report format changes
• User confusion: Which report should users read first?
• No clear standard: Each operation may generate different combinations of reports

Proposed Solution

1. Single Final Report

• One report file: security_assessment_report.md (already implemented in react_bridge_handler.py:3146)
• Strictly defined structure: Use the existing report_template.md to ensure consistent sections
• Complete information: All findings, analysis, and recommendations in one place

2. Intermediary Notes Subdirectory

• Create outputs/<target>/<operation_id>/notes/ directory for:
  • Agent working notes
  • Tool outputs
  • Draft analysis
  • Temporary findings
• Keep main output directory clean with just the final report

3. Pluggable Report Templates

• Module-specific templates: Already supported via module_report_prompt(module_name) in report_generator.py
• Template system: Enhance the existing template system to support:
  • Domain-specific sections (CTF, threat emulation, code security)
  • Custom formatting based on module requirements
  • Flexible section ordering based on assessment type

4. Incremental Updates for Repeat Operations

For consecutive operations on the same target:

• Diff highlighting: Add "New Findings Since Last Assessment" section at top
• Comparison view: Show severity changes (new criticals, resolved issues)
• Temporal context: Reference previous operation IDs
• Change summary: Highlight what changed between assessments

Report Generation Flow

Handler (react_bridge_handler.py)
  └─> generate_security_report() (report_generator.py:24)
      └─> create_report_agent() (report_agent.py:40)
          └─> Agent with build_report_sections tool (report_builder.py:127)
              └─> Returns sections dictionary
          └─> Fill template (report_generator.py:120-224)
          └─> Return markdown report
      └─> Save to security_assessment_report.md (react_bridge_handler.py:3146)

Key Files

• src/modules/handlers/react/react_bridge_handler.py:3040-3218 - Calls report generation
• src/modules/handlers/report_generator.py - Main report generation logic
• src/modules/agents/report_agent.py - Report-specific agent factory
• src/modules/tools/report_builder.py - Evidence retrieval and formatting
• src/modules/prompts/templates/report_template.md - Report structure template