Java Build Agent Workflow

This repository contains an OpenAI tool-calling workflow for building Java vulnerability benchmark snapshots into buggy/patched .class artifacts.

The workflow was extracted from a CVEfixes/Vul4J bytecode dataset construction project. It is designed for CVEfixes-style Java snapshots where each CVE has a buggy source snapshot and a patched source snapshot.

What This Project Does

Given a CVE ID and a target Java source file, the agent attempts to produce:

result_jar_extract/<CVE>/buggy/*.class
result_jar_extract/<CVE>/patched/*.class
result_jar_extract/<CVE>/build_meta.json

The core workflow is:

methods CSV + buggy/patched snapshots + local dependency stores
  -> precheck
  -> existing class recovery
  -> OpenAI tool-calling build loop
  -> Maven/Gradle/local dependency/javac fallback tools
  -> staged .class outputs
  -> optional integration into result_success + ByteTok output

Repository Layout

jar_extraction/
  agent/
    agent_build.py        # OpenAI tool-calling agent controller
    tools.py              # Tool library exposed to the LLM
  config.py               # Environment-driven path/config settings
  hybrid_build_remaining.py
  integrate_new_results.py
  diff_target_finder.py
  javac_compiler.py
  maven_central_client.py
  gradle_parser.py
reports/
docs/
scripts/

Main Entry Points

Agent Mode

jar_extraction/agent/agent_build.py runs the OpenAI tool-calling agent. The LLM reads build context and errors, then chooses tools from tools.py.

python3 jar_extraction/agent/agent_build.py \
  --cve CVE-2017-2599 \
  --file-path core/src/main/java/hudson/model/AbstractItem.java

Batch/Hybrid Mode

jar_extraction/hybrid_build_remaining.py reuses the same tool library in a deterministic order. This is useful for large retry batches and for reproducible handover runs.

python3 jar_extraction/hybrid_build_remaining.py --inventory-only
python3 jar_extraction/hybrid_build_remaining.py --run-builds --limit 10
python3 jar_extraction/hybrid_build_remaining.py --integrate-existing

Integration Mode

jar_extraction/integrate_new_results.py copies successful staged classes into result_success, optionally runs ByteTok, and appends metadata rows.

python3 jar_extraction/integrate_new_results.py --dry-run
python3 jar_extraction/integrate_new_results.py

Setup

1. Install Python dependencies.

python3 -m pip install -r requirements.txt

2. Copy and edit the environment file.

cp .env.example .env

At minimum, set:

OPENAI_API_KEY=...
CVEFIXES_DATASET_ROOT=/absolute/path/to/CVEfixes_dataset

The dataset root should contain:

out_java/
result_jar_extract/
result_success/
CVEfixes_v1.0.8/Data/methods_all_2025.csv

3. Verify the commands are importable.

python3 scripts/check_setup.py
python3 jar_extraction/agent/agent_build.py --help
python3 jar_extraction/hybrid_build_remaining.py --help
python3 jar_extraction/integrate_new_results.py --dry-run

Tool Library

The agent can call tools for:

• snapshot inspection
• source file and POM/Gradle inspection
• Maven/Gradle module inference
• offline dependency resolution
• local JAR/class search
• Maven/Gradle build attempts
• targeted javac fallback compilation
• existing class output recovery
• class file copy and build metadata recording

The workflow is offline-first by default:

MAVEN_OFFLINE=1
ALLOW_REMOTE_MAVEN=0

Remote Maven resolution can be enabled explicitly with:

ALLOW_REMOTE_MAVEN=1
MAVEN_OFFLINE=0

Notes

• Stub JAR generation exists as an exceptional fallback for internal/private dependencies, but it is not the normal build path.
• ByteTok integration is optional. If BYTETOK_BIN is not configured, class copying still works but ByteTok output is skipped.
• This repository intentionally excludes benchmark data, build outputs, local dependency caches, logs, API keys, and binary artifacts.