CodeForge

Docker-based fuzzing and development environment for VSCode

CodeForge is a VSCode extension that provides automated fuzzing infrastructure for C/C++ projects. It manages Docker containers, builds fuzzing targets, runs LibFuzzer, and analyzes crashes - all from within VSCode.

What is Fuzzing?

Fuzzing is an automated testing technique that finds bugs by feeding random/mutated inputs to your code. CodeForge integrates LibFuzzer (LLVM's fuzzing engine) with VSCode to help you find crashes, memory leaks, and security vulnerabilities.

Requirements

• Docker: Must be installed and running
• VSCode: Version 1.103.0 or higher
• For Fuzzing: CMake-based C/C++ project with fuzz targets

Getting Started

1. Initialize CodeForge in Your Project

Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run:

CodeForge: Initialize Project

This will:

• Create .codeforge/ directory in your workspace
• Generate a Dockerfile based on your project type (CMake or Rust)
• Copy fuzzing scripts into .codeforge/scripts/
• Build the Docker image

2. Access the Control Panel

Click the CodeForge hammer icon in the Activity Bar (left sidebar) to open the control panel. From here you can:

• View discovered fuzz targets
• Build and run fuzzers
• View crashes and their details
• Manage Docker containers

Features

Fuzzing Workflow

CodeForge automates the entire fuzzing process:

1. Discover Fuzz Targets: Automatically finds fuzz targets defined in your CMakePresets.json
2. Build Fuzzers: Compiles your fuzz targets with LibFuzzer instrumentation
3. Run Fuzzers: Executes fuzzers in parallel inside Docker containers
4. Detect Crashes: Monitors for crashes and collects crash inputs
5. Analyze Crashes: Integrates with GDB for stack traces and debugging

Running Fuzzing Tests

Command Palette:

CodeForge: Run Fuzzing Tests

This command will:

• Discover all fuzz targets in your project
• Build them with LibFuzzer
• Run them with your configured settings
• Display results in the CodeForge control panel

To build without running:

CodeForge: Build Fuzzing Tests

Setting Up Fuzz Targets

CodeForge looks for fuzz targets in your CMakePresets.json. Example configuration:

{
  "version": 3,
  "configurePresets": [
    {
      "name": "fuzzing-debug",
      "binaryDir": "${sourceDir}/build-fuzzing",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug",
        "CMAKE_CXX_COMPILER": "clang++",
        "CMAKE_CXX_FLAGS": "-fsanitize=fuzzer,address -g"
      }
    }
  ],
  "buildPresets": [
    {
      "name": "fuzzing-debug",
      "configurePreset": "fuzzing-debug"
    }
  ]
}

Your fuzz target should implement the LibFuzzer interface:

// my_fuzzer.cpp
extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
    // Your code to test
    return 0;
}

Add it to your CMakeLists.txt:

add_executable(my_fuzzer my_fuzzer.cpp)
target_link_libraries(my_fuzzer my_library)

Docker Container Management

CodeForge runs all commands in Docker containers to provide isolation and consistent environments.

Launch Interactive Terminal

CodeForge: Launch Terminal in Container

Opens a bash terminal inside your Docker container with your workspace mounted.

Run Tasks in Containers

CodeForge provides a custom task type that runs commands in Docker containers.

Quick Task Registration:

CodeForge: Register Task

Then enter a command like npm test or make build. The extension creates a task configuration automatically.

Manual Configuration (.vscode/tasks.json):

{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "codeforge",
      "label": "Build Project",
      "command": "cmake --build build",
      "detail": "Build the project in Docker"
    },
    {
      "type": "codeforge",
      "label": "Run Tests",
      "command": "ctest --test-dir build",
      "detail": "Run tests in Docker"
    },
    {
      "type": "codeforge",
      "label": "Start Dev Server",
      "command": "npm run dev",
      "ports": ["3000:3000"],
      "detail": "Start development server with port forwarding"
    }
  ]
}

Required: Every CodeForge task must have a "command" property.

Optional: Add "ports" array for port forwarding (format: "hostPort:containerPort").

Run tasks via: Terminal → Run Task... or Ctrl+Shift+P → Tasks: Run Task

Crash Analysis

When fuzzing finds crashes, CodeForge provides tools to analyze them:

View Crashes in Control Panel

The CodeForge control panel displays:

• List of discovered crashes
• Crash type (e.g., "heap-buffer-overflow", "SEGV")
• Crash hash (for deduplication)
• File path to crash input

View Crash Details

Click on a crash in the control panel or use:

CodeForge: View Crash

This opens a read-only editor showing the crash input data (with hex view for binary data).

Debug Crashes with GDB

CodeForge: Analyze Crash

This command:

1. Launches GDB inside Docker
2. Runs the fuzzer with the crash input
3. Extracts stack trace
4. Shows detailed crash information

Refresh Crash List

CodeForge: Reevaluate Crashes

Rescans the fuzzing output directories and updates the crash list.

Regenerate Fuzzer List

CodeForge: Regenerate Fuzzer List

Rediscovers fuzz targets from your CMake configuration.

Docker Image Management

Update Docker Image

CodeForge: Update Docker Image

Pulls the latest base image from the registry and rebuilds your project's Docker image.

Configuration

Configure CodeForge through VSCode settings (Ctrl+, / Cmd+,):

Docker Settings

{
  "codeforge.dockerCommand": "docker",
  "codeforge.removeContainersAfterRun": true,
  "codeforge.mountWorkspace": true,
  "codeforge.workspaceMount": "/workspace",
  "codeforge.defaultShell": "/bin/bash",
  "codeforge.defaultPortMappings": ["8080:8080", "3000:3000"]
}

Fuzzing Settings

{
  // LibFuzzer execution parameters
  "codeforge.fuzzing.libfuzzer.runs": 16,
  "codeforge.fuzzing.libfuzzer.jobs": 8,
  "codeforge.fuzzing.libfuzzer.maxTotalTime": 300,
  "codeforge.fuzzing.libfuzzer.maxLen": 4096,

  // Crash handling
  "codeforge.fuzzing.ignoreCrashes": true,
  "codeforge.fuzzing.exitOnCrash": false,
  "codeforge.fuzzing.minimizeCrashes": true,

  // Resource limits
  "codeforge.fuzzing.memoryLimit": 2048,
  "codeforge.fuzzing.timeoutPerRun": 25,

  // Output configuration
  "codeforge.fuzzing.outputDirectory": ".codeforge/fuzzing",
  "codeforge.fuzzing.preserveCorpus": true
}

Key Settings Explained:

• runs: Number of test iterations per fuzzing job (default: 16)
• jobs: Number of parallel fuzzing processes (default: 8)
• maxTotalTime: Maximum fuzzing duration in seconds (0 = unlimited, default: 300)
• maxLen: Maximum input length in bytes (default: 4096)
• memoryLimit: Memory limit per fuzzer in MB (default: 2048)
• ignoreCrashes: Continue fuzzing after finding crashes (default: true)
• minimizeCrashes: Automatically minimize crash inputs to smallest reproducing case (default: true)
• preserveCorpus: Keep corpus files between sessions for better coverage (default: true)

Project Structure

After initialization, CodeForge creates:

.codeforge/
├── Dockerfile                    # Generated Docker image
├── scripts/                      # Fuzzing scripts (copied from extension)
│   ├── find-fuzz-tests.sh        # Discovers fuzz targets
│   ├── build-fuzz-tests.sh       # Builds fuzzers
│   ├── run-fuzz-tests.sh         # Executes fuzzers
│   └── launch-process-in-docker.sh
├── fuzzing/                      # Fuzzing output (created on first run)
│   ├── my_fuzzer                 # Built fuzzer binary
│   └── my_fuzzer-output/         # Fuzzing results
│       └── corpus/
│           ├── crash-*           # Crash inputs
│           └── *.txt             # Corpus files
└── tracked-containers            # Active container tracking

Available Commands

All commands are accessible via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

Setup & Management

• CodeForge: Initialize Project - Set up CodeForge in current workspace
• CodeForge: Update Docker Image - Update to latest Docker base image
• CodeForge: Register Task - Quick task registration helper

Docker Operations

• CodeForge: Launch Terminal in Container - Open interactive shell in Docker

Fuzzing Operations

• CodeForge: Build Fuzzing Tests - Compile fuzz targets
• CodeForge: Run Fuzzing Tests - Build and run all fuzzers
• CodeForge: Regenerate Fuzzer List - Refresh available fuzzers

Crash Analysis

• CodeForge: Reevaluate Crashes - Rescan for crashes
• Individual crash operations available through control panel

Troubleshooting

"Docker is not installed or not running"

Ensure Docker Desktop is running:

docker ps

If this fails, start Docker Desktop.

"No fuzz tests found"

Check:

1. Your project has a CMakePresets.json file
2. You have fuzz targets defined in CMakeLists.txt
3. The Docker image is built (CodeForge: Initialize Project)

"Build failed"

Common causes:

1. Missing dependencies: Update Dockerfile in .codeforge/Dockerfile
2. Wrong compiler flags: Check CMakePresets.json includes -fsanitize=fuzzer
3. CMake configuration errors: Check CMake preset names match

View detailed errors in:

• VSCode Output panel (View → Output → CodeForge)
• CodeForge control panel build logs

"Image not found" or "Container errors"

Reinitialize the project:

CodeForge: Initialize Project

This rebuilds the Docker image.

Fuzzing runs but no crashes found

This is normal! Not all code has bugs. To verify fuzzing is working:

1. Check the terminal output shows fuzzing progress
2. Look for coverage statistics in the output
3. Add an intentional bug to verify detection works

Example: Setting Up a New Fuzzing Project

1. Create a fuzz target (fuzz/string_parser_fuzz.cpp):

#include <stdint.h>
#include <stddef.h>
#include "my_string_parser.h"

extern "C" int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
    if (Size == 0) return 0;

    std::string input(reinterpret_cast<const char*>(Data), Size);
    parse_string(input);  // Your function to test

    return 0;
}

2. Add to CMakeLists.txt:

add_executable(string_parser_fuzz fuzz/string_parser_fuzz.cpp)
target_link_libraries(string_parser_fuzz my_library)

3. Create CMakePresets.json (if you don't have one):

{
  "version": 3,
  "configurePresets": [
    {
      "name": "fuzzing",
      "binaryDir": "${sourceDir}/build-fuzz",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug",
        "CMAKE_CXX_COMPILER": "clang++",
        "CMAKE_CXX_FLAGS": "-fsanitize=fuzzer,address -g"
      }
    }
  ],
  "buildPresets": [
    {
      "name": "fuzzing",
      "configurePreset": "fuzzing"
    }
  ]
}

4. Initialize CodeForge:

   • Open Command Palette: CodeForge: Initialize Project
   • Wait for Docker image to build

5. Run fuzzing:

   • Click CodeForge icon in Activity Bar
   • Click "Run Fuzzing Tests" button
   • Or use Command Palette: CodeForge: Run Fuzzing Tests

6. View results:

   • Crashes appear in the CodeForge control panel
   • Click on a crash to view the input
   • Use "Analyze Crash" to get stack trace with GDB

Port Forwarding

When running services in containers (web servers, databases, etc.), use port forwarding:

In tasks.json:

{
  "type": "codeforge",
  "command": "python -m http.server 8080",
  "ports": ["8080:8080"]
}

Global default (applies to all tasks unless overridden):

{
  "codeforge.defaultPortMappings": ["8080:8080", "3000:3000"]
}

Format: "hostPort:containerPort" or just "port" (uses same port on host and container)

Support & Contributing

• Issues: GitHub Issues
• Homepage: https://github.com/tuliptreetech/codeforge

License

MIT License - See LICENSE file

About

Developed by Tulip Tree Technology