DevContainer Setup

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

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

Wait for Build

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

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:

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: LatestPattern-based static analysis scanner

semgrep --version

CodeQL CLI

Version: 2.15.5Semantic code analysis engine

codeql version

AFL++

Version: LatestAmerican Fuzzy Lop fuzzer with enhancements

afl-fuzz -h

rr Debugger

Platform: Linux x86_64 onlyDeterministic 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:

# 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

Start Container

Open the repository in VS Code and start the devcontainer.

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!')"

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:

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

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

Or add to devcontainer.json:

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

CodeQL not found in PATH

Problem: CodeQL binary not accessible.Solution:

Check installation:

ls -la /opt/codeql/codeql

Manually add to PATH:

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

Restart container if issue persists

Python module import errors

Problem: Cannot import RAPTOR packages.Solution:

Verify PYTHONPATH:

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

Set manually if needed:

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

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:

Check AFL++ system settings:

afl-system-config

Apply recommended settings (may require privileged mode)
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:

Verify browsers are installed:

python -m playwright install --dry-run

Reinstall if needed:

python -m playwright install

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:

Create Service Account

Go to Google Cloud Console
Create a service account with BigQuery access
Download credentials JSON file

Mount Credentials

Add to devcontainer.json:

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

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 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 debuggerContainer 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

Resources

DevContainer Setup

Overview

What's Included

Quick Start

Alternative: Docker Build

Included Tools

Security Analysis Tools

Semgrep

CodeQL CLI

AFL++

rr Debugger

Build & Debugging Tools

Web Testing (Alpha)

Python Environment

Environment Configuration

Usage Instructions

Basic Workflow

Working Directory

Troubleshooting

Container Size & Performance

Container Size

Build Time

OSS Forensics Configuration

Customization

Platform Compatibility

Full Support

Partial Support

Next Steps

Run Tests

Start Scanning

Dependencies

Contributing

Build docs developers (and LLMs) love

Resources

​Overview

What's Included

​Quick Start

​Alternative: Docker Build

​Included Tools

​Security Analysis Tools

Semgrep

CodeQL CLI

AFL++

rr Debugger

​Build & Debugging Tools

​Web Testing (Alpha)

​Python Environment

​Environment Configuration

​Usage Instructions

​Basic Workflow

​Working Directory

​Troubleshooting

​Container Size & Performance

Container Size

Build Time

​OSS Forensics Configuration

​Customization

​Platform Compatibility

Full Support

Partial Support

​Next Steps

Run Tests

Start Scanning

Dependencies

Contributing

Build docs developers (and LLMs) love

Overview

Quick Start

Alternative: Docker Build

Included Tools

Security Analysis Tools

Build & Debugging Tools

Web Testing (Alpha)

Python Environment

Environment Configuration

Usage Instructions

Basic Workflow

Working Directory

Troubleshooting

Container Size & Performance

OSS Forensics Configuration

Customization

Platform Compatibility

Next Steps