DevContainer Setup

Pre-configured development environment with all RAPTOR dependencies

Overview

The RAPTOR devcontainer provides a complete, pre-configured development environment with all security tools, debuggers, and dependencies installed. This eliminates manual installation and ensures consistency across platforms.

What's Included

• Python 3.12 environment
• All security testing tools (Semgrep, CodeQL, AFL++)
• Debuggers (GDB, rr)
• Build tools (gcc, clang, make, cmake)
• Browser automation (Playwright)
• All Python dependencies

---

Quick Start

1. Open in VS Code

   Open the RAPTOR repository in VS Code or any compatible editor:

   git clone https://github.com/gadievron/raptor.git
   cd raptor
   code .
   

   Then use the command: Dev Container: Open Folder in Container

2. Wait for Build

   The first build takes 5-10 minutes (container is ~6GB). Subsequent starts are instant.

3. Start Using RAPTOR

   Once the container is running, all tools are ready:

   # Just say "hi" in Claude Code
   claude
   

---

Alternative: Docker Build

Build and run the container manually with Docker:

Build Container

docker build -f .devcontainer/Dockerfile -t raptor-devcontainer:latest .

The --privileged flag is required for the rr debugger to function properly.

---

Included Tools

Security Analysis Tools

Semgrep

Version: Latest

Pattern-based static analysis scanner

semgrep --version

CodeQL CLI

Version: 2.15.5

Semantic code analysis engine

codeql version

AFL++

Version: Latest

American Fuzzy Lop fuzzer with enhancements

afl-fuzz -h

rr Debugger

Platform: Linux x86_64 only

Deterministic record-replay debugger

rr --version

Build & Debugging Tools

Compilers & Build Systems

• gcc - GNU C/C++ compiler with coverage support (gcov)
• g++ - GNU C++ compiler
• clang-format - Code formatter
• make - Build automation
• cmake - Cross-platform build system
• autoconf, automake, libtool - GNU build tools

Debuggers

• gdb - GNU Debugger
• gdb-multiarch - Multi-architecture debugging
• rr - Record-replay debugger (Linux x86_64)

Binary Analysis

• binutils - GNU binary utilities (nm, addr2line, objdump, strings)
• file - File type identification

Web Testing (Alpha)

Web testing is in alpha stage. Treat as experimental.

Playwright Browser Automation

Pre-installed browsers:

• Chromium
• Firefox
• WebKit

All browser binaries are pre-downloaded during container build.

python -m playwright --version

Python Environment

• Python: 3.12
• Base Image: mcr.microsoft.com/devcontainers/python:1-3.12-bookworm
• Dependencies: All packages from requirements.txt and requirements-dev.txt
• PYTHONPATH: Pre-configured for RAPTOR imports

---

Environment Configuration

The devcontainer sets up several environment variables:

Environment Variables

# CodeQL in PATH
PATH="/opt/codeql:$PATH"

# Git configuration
GIT_TERMINAL_PROMPT=0

# Python configuration
PYTHONUNBUFFERED=1
PYTHONPATH="/workspaces/raptor:/workspaces/raptor/packages:$PYTHONPATH"

The PYTHONPATH configuration allows importing RAPTOR packages from anywhere:

import core
import binary_analysis
import llm_analysis

---

Usage Instructions

Basic Workflow

1. Start Container

   Open the repository in VS Code and start the devcontainer.

2. Verify Installation

   Check that all tools are available:

   # Security tools
   semgrep --version
   codeql version
   afl-fuzz -h
   
   # Debuggers
   gdb --version
   rr --version  # Linux only
   
   # Python packages
   python3 -c "import anthropic; print('Ready!')"
   
3. Run RAPTOR

   Use any RAPTOR command:

   # Via Claude Code
   claude
   # Then: /scan or /analyze /test/data
   
   # Via Python CLI
   python3 raptor.py scan --repo /test/data
   

Working Directory

The container’s working directory is /workspaces/raptor, which maps to your local repository.

cd /workspaces/raptor
ls -la  # See your local files

Changes made inside the container are reflected in your local filesystem.

---

Troubleshooting

rr debugger fails with 'Permission denied'

Problem: rr requires kernel performance monitoring permissions.

Solution:

1. Ensure container runs with --privileged flag
2. Set kernel parameter (inside container):

echo 1 | sudo tee /proc/sys/kernel/perf_event_paranoid

3. Or add to devcontainer.json:

{
  "runArgs": ["--privileged"]
}

CodeQL not found in PATH

Problem: CodeQL binary not accessible.

Solution:

1. Check installation:

ls -la /opt/codeql/codeql

2. Manually add to PATH:

export PATH="/opt/codeql:$PATH"
codeql version

3. Restart container if issue persists

Python module import errors

Problem: Cannot import RAPTOR packages.

Solution:

1. Verify PYTHONPATH:

echo $PYTHONPATH
# Should include: /workspaces/raptor:/workspaces/raptor/packages

2. Set manually if needed:

export PYTHONPATH="/workspaces/raptor:/workspaces/raptor/packages:$PYTHONPATH"

3. Test import:

python3 -c "import core; print('Success!')"

Container build fails or is very slow

Problem: First build takes 5-10 minutes and downloads ~6GB.

Solutions:

• Slow internet: Wait for download to complete (one-time only)
• Disk space: Ensure 10GB+ free space
• Build errors: Check Docker logs for specific errors
• Platform issues: Some tools (like rr) are Linux x86_64 only

The container will skip unavailable tools with warnings rather than failing.

AFL++ fuzzing not working

Problem: AFL++ requires specific kernel configurations.

Solution:

1. Check AFL++ system settings:

afl-system-config

2. Apply recommended settings (may require privileged mode)

3. For testing, use AFL++ with -d flag to disable CPU binding:

afl-fuzz -d -i input -o output -- ./target

Playwright browsers not working

Problem: Playwright browser automation fails.

Solution:

1. Verify browsers are installed:

python -m playwright install --dry-run

2. Reinstall if needed:

python -m playwright install

3. Check X11 for GUI (if needed):

Most Playwright operations work headless, but for debugging:

# Run headless (default)
python -m playwright codegen --browser chromium

---

Container Size & Performance

Container Size

~6GB total

• Base Python 3.12 image: ~2GB
• Security tools: ~1.5GB
• Playwright browsers: ~1.5GB
• Build tools & dependencies: ~1GB

Build Time

5-10 minutes (first time)

• Download: 3-5 minutes
• Build: 2-5 minutes
• Subsequent starts: <10 seconds

The container caches layers, so rebuilds after changes are fast (typically <1 minute).

---

OSS Forensics Configuration

For OSS forensics investigations, configure Google Cloud credentials:

1. Create Service Account

   1. Go to Google Cloud Console
   2. Create a service account with BigQuery access
   3. Download credentials JSON file
2. Mount Credentials

   Add to devcontainer.json:

   {
     "mounts": [
       "source=${localEnv:HOME}/.config/gcloud,target=/home/vscode/.config/gcloud,type=bind"
     ]
   }
   
3. Set Environment Variable

   Inside container:

   export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
   

See Dependencies for more details on Google Cloud BigQuery setup.

---

Customization

Modify .devcontainer/Dockerfile to customize the environment:

Add Tools

# Add after existing RUN commands
RUN apt-get update && apt-get install -y \
    your-tool-here \
    && apt-get clean

Rebuild the container after changes:

# In VS Code
Dev Container: Rebuild Container

# Or with Docker
docker build -f .devcontainer/Dockerfile -t raptor-devcontainer:latest .

---

Platform Compatibility

Full Support

Linux (x86_64)

All tools including rr debugger

Partial Support

macOS (ARM64) / Windows (WSL2)

All tools except rr debugger

Container builds with warnings for unavailable tools

The rr debugger is Linux x86_64 only. On other platforms, RAPTOR falls back to GDB/LLDB for crash analysis.

---

Next Steps

Run Tests

Verify your environment with the test suite

Start Scanning

Begin using RAPTOR for security testing

Dependencies

Learn about licenses and restrictions

Contributing

Contribute to RAPTOR development