System Architecture

​

Architecture Overview

raptor/
├── core/                  # Shared utilities
├── packages/              # Independent security capabilities
│   ├── static-analysis/
│   ├── codeql/
│   ├── llm_analysis/
│   ├── autonomous/
│   ├── fuzzing/
│   ├── binary_analysis/
│   ├── recon/
│   ├── sca/
│   └── web/
├── engine/                # Analysis engines
├── tiers/                 # Expert personas
├── out/                   # All outputs
└── raptor*.py             # Entry points

​

Core Layer

​

RaptorConfig (core/config.py)

class RaptorConfig:
    @staticmethod
    def get_raptor_root() -> Path:
        """Get RAPTOR installation root"""

    @staticmethod
    def get_out_dir() -> Path:
        """Get output directory (raptor/out/)"""

    @staticmethod
    def get_logs_dir() -> Path:
        """Get logs directory (out/logs/)"""

• Single source of truth for all paths
• Environment variable support (RAPTOR_ROOT)
• Graceful fallback to auto-detection

​

Structured Logging (core/logging.py)

def get_logger(name: str = "raptor") -> logging.Logger:
    """Get configured logger with JSONL audit trail"""

• JSONL format for machine-readable logs
• Console output for human readability
• Timestamped log files (raptor_<timestamp>.jsonl)
• Automatic log directory creation

{
  "timestamp": "2025-11-09 05:22:00,081",
  "level": "INFO",
  "logger": "raptor",
  "module": "logging",
  "function": "info",
  "line": 111,
  "message": "RAPTOR logging initialized"
}

​

SARIF Parser (core/sarif/parser.py)

• parse_sarif(sarif_path) - Load and validate SARIF file
• get_findings(sarif) - Extract finding list
• get_severity(result) - Map SARIF levels to severity

​

Packages Layer

​

Design Principles

1. One responsibility per package
2. No cross-package imports (only import from core)
3. Standalone executability (each agent.py can run independently)
4. Clear CLI interface (argparse, help text, examples)

​

Package: static-analysis

python3 packages/static-analysis/scanner.py \
  --repo /path/to/code \
  --policy_groups secrets,owasp \
  --output /path/to/output

• Run Semgrep scans with configured policy groups
• Parse and normalize SARIF outputs
• Generate scan metrics (files scanned, findings count, severities)

• semgrep_<policy>.sarif - SARIF 2.1.0 findings per policy group
• scan_metrics.json - Scan statistics
• verification.json - Verification results

​

Package: codeql

• agent.py - Main CodeQL workflow orchestrator
• autonomous_analyzer.py - LLM-powered CodeQL analysis
• build_detector.py - Automatic build system detection
• database_manager.py - CodeQL database creation and management
• dataflow_validator.py - Validates dataflow paths from CodeQL results
• dataflow_visualizer.py - Generates visual dataflow diagrams
• language_detector.py - Programming language detection
• query_runner.py - CodeQL query execution

• Automatic language and build system detection
• Multi-language support (Python, Java, C/C++, JavaScript, Go, etc.)
• Dataflow path validation to reduce false positives
• Visual dataflow diagrams for complex taint flows

• codeql_*.sarif - CodeQL findings in SARIF format
• dataflow_*.json - Validated dataflow paths
• dataflow_*.svg - Visual dataflow diagrams
• codeql_analysis.json - Analysis summary

​

Package: llm_analysis

• agent.py at packages/llm_analysis/agent.py:1 - Standalone analysis (OpenAI/Anthropic compatible)
• orchestrator.py - Multi-agent orchestration (requires Claude Code)

• Parse SARIF findings
• Read vulnerable code files
• Analyze exploitability with LLM reasoning
• Generate working exploit PoCs (optional)
• Create secure patches (optional)
• Produce analysis reports

llm/
├── client.py       # Unified client interface
├── config.py       # API keys, model selection
└── providers.py    # Provider implementations (Anthropic, OpenAI, local)

• Provider-agnostic (swap OpenAI ↔ Anthropic easily)
• Configurable via environment variables
• Rate limiting and error handling

​

Package: autonomous

• corpus_generator.py - Intelligent fuzzing corpus generation
• dialogue.py - Agent dialogue and interaction management
• exploit_validator.py - Automated exploit code validation
• goal_planner.py - Goal-oriented task planning
• memory.py - Agent memory and context management
• planner.py - Task decomposition and planning

• Goal-oriented planning with LLM reasoning
• Automatic exploit compilation and execution testing
• Context-aware corpus generation for targeted fuzzing
• Persistent memory across agent interactions

​

Package: fuzzing

• afl_runner.py - AFL++ process management and monitoring
• crash_collector.py - Crash triage, deduplication, and ranking
• corpus_manager.py - Seed corpus generation and management

• Parallel fuzzing support (multiple AFL instances)
• Automatic crash deduplication by signal
• Early termination on crash threshold
• Support for AFL-instrumented binaries and QEMU mode

​

Package: binary_analysis

• Analyze crash inputs using GDB
• Extract stack traces, register states, disassembly
• Classify crash types (stack overflow, heap corruption, use-after-free, etc.)
• Provide context for LLM analysis

• Stack buffer overflows (SIGSEGV with stack address)
• Heap corruption (SIGSEGV with heap address, malloc errors)
• Use-after-free (SIGSEGV on freed memory)
• Integer overflows (SIGFPE, wraparound detection)
• Format string vulnerabilities (SIGSEGV in printf family)
• NULL pointer dereference (SIGSEGV at low addresses)

​

Package: recon

• Detect programming languages
• Identify frameworks and libraries
• Enumerate dependencies
• Map attack surface

​

Package: sca

• Detect dependency files (requirements.txt, package.json, pom.xml, etc.)
• Query vulnerability databases (OSV, NVD, etc.)
• Generate dependency vulnerability reports
• Suggest remediation (version upgrades)

​

Package: web

• client.py - HTTP client wrapper (session management, headers)
• crawler.py - Web crawler (enumerate endpoints)
• fuzzer.py - Input fuzzing (injection testing)
• scanner.py - Main orchestrator (OWASP Top 10 checks)

​

Analysis Engines

​

CodeQL Engine (engine/codeql/)

• suites/ - Custom CodeQL query suites for different languages
• Query configurations for taint tracking, security patterns, and dataflow analysis

​

Semgrep Engine (engine/semgrep/)

• rules/ - Custom Semgrep rules for security patterns
• semgrep.yaml - Semgrep configuration file
• tools/ - Utilities for rule development and testing

​

Entry Points

​

raptor.py - Interactive Launcher

• Claude Code integration for conversational analysis
• Progressive loading of expert personas from tiers/
• Slash command support (/scan, /fuzz, /web, /agentic, /codeql, /analyze, /exploit, /patch)
• On-demand loading of specialized guidance
• Session-based workflow management

​

raptor_agentic.py - Source Code Workflow

1. Phase 1: Scan code with Semgrep
2. Phase 2: Analyze findings autonomously
3. Phase 3: (Optional) Agentic orchestration with Claude Code

​

raptor_codeql.py - CodeQL Workflow

1. Phase 1: Language and build detection
2. Phase 2: CodeQL database creation
3. Phase 3: Query execution with custom suites
4. Phase 4: Dataflow path validation
5. Phase 5: Visual dataflow diagram generation
6. Phase 6: LLM exploitability analysis (optional)

​

raptor_fuzzing.py - Binary Fuzzing Workflow

1. Phase 1: Fuzz binary with AFL++
2. Phase 2: Collect and rank crashes
3. Phase 3: Analyze crashes with GDB
4. Phase 4: LLM exploitability assessment
5. Phase 5: Generate exploit PoC code

​

Output Structure

out/
├── logs/                       # JSONL structured logs
│   └── raptor_<timestamp>.jsonl
├── scan_<repo>_<timestamp>/    # Scan outputs
│   ├── semgrep_*.sarif
│   ├── scan_metrics.json
│   └── verification.json
├── codeql_<repo>_<timestamp>/  # CodeQL outputs
│   ├── database/
│   ├── codeql_*.sarif
│   ├── dataflow_*.json
│   └── dataflow_*.svg
└── fuzz_<binary>_<timestamp>/  # Fuzzing outputs
    ├── afl_output/
    ├── analysis/
    └── fuzzing_report.json

​

Import Patterns

# Add parent to path for core access
sys.path.insert(0, str(Path(__file__).parent.parent.parent))

from core.config import RaptorConfig
from core.logging import get_logger

​

LLM Quality Considerations

​

Exploit Generation Requirements

​

Technical Requirements for Exploit Code

• Precise knowledge of x86-64/ARM stack structures
• Correct register usage and calling conventions
• Understanding of heap allocator internals (glibc malloc, tcache)

• Valid x86-64/ARM assembly encoding
• Correct escape sequences (e.g., \x90\x31\xc0 not \T)
• NULL-byte avoidance for string-based exploits
• System call number correctness

• ROP chain construction with valid gadget addresses
• Stack pivot techniques for limited buffer sizes
• ASLR leak construction and information disclosure
• Heap feng shui for use-after-free exploitation

​

Recommendations

# Use Anthropic Claude (recommended)
export ANTHROPIC_API_KEY=your_key_here

# OR OpenAI GPT-4
export OPENAI_API_KEY=your_key_here