Skip to content

config-reference.md

Latest commit

 

History

History
156 lines (112 loc) · 5.97 KB

config-reference.md

File metadata and controls

156 lines (112 loc) · 5.97 KB
Raw

Configuration Reference

The main backporting CLI reads a YAML file through load_yml() in src/backporting.py. See Provider Configuration for provider-specific environment variables and model examples.

Run:

python src/backporting.py --config case.yml

or:

python src/backporting.py --config case.yml --debug

Example

project: libtiff
project_url: https://github.com/libsdl-org/libtiff
new_patch: 881a070194783561fd209b7c789a4e75566f7f37
new_patch_parent: 6bb0f1171adfcccde2cd7931e74317cccb7db845
target_release: 13f294c3d7837d630b3e9b08089752bc07b730e6
sanitizer: LeakSanitizer
error_message: "ERROR: LeakSanitizer"
tag: CVE-2023-3576
openai_key: sk-...
project_dir: dataset/libsdl-org/libtiff
patch_dataset_dir: ~/backports/patch_dataset/libtiff/CVE-2023-3576/

llm_provider: openai
llm_model: gpt-4-turbo
llm_base_url: https://api.openai.com/v1
llm_temperature: 0.5
llm_max_tokens:
llm_thinking:

use_azure: false
# azure_endpoint: "https://your-resource.openai.azure.com/"
# azure_deployment: "gpt-5"
# azure_api_version: "2024-12-01-preview"

Required Fields

  • project: Human-readable project name used in log filenames.
  • project_url: Upstream repository URL passed to the LLM as project context.
  • project_dir: Local Git repository that contains new_patch, new_patch_parent, and target_release. This directory is mutated during runtime.
  • patch_dataset_dir: Case directory containing optional validation hooks and receiving a copy of the runtime log.
  • new_patch: Upstream fixed commit. RetroPatch reads this commit with git show and splits the resulting patch into hunks.
  • new_patch_parent: Parent or vulnerable-side commit for new_patch. This gives the agent a newer vulnerable reference for history tracing.
  • target_release: Older revision that should receive the backported fix.
  • openai_key: API key used by the main backporting LLM path. Azure mode also reads this field as the Azure OpenAI key. For regular OpenAI, this can also be supplied with OPENAI_API_KEY.

Optional Fields

  • tag: Case identifier used in log filenames. Common values are CVE IDs or bug IDs.
  • sanitizer: Metadata describing the sanitizer used by the case. The current main workflow does not make decisions from this field.
  • error_message: Text expected in poc.sh output when the bug is still triggered. If this field is empty, Project uses a placeholder value and the run logs a warning.
  • llm_provider: OpenAI-compatible provider name. Defaults to openai. Use deepseek for DeepSeek.
  • llm_model: Chat model name. Defaults to gpt-4-turbo, or deepseek-v4-pro when llm_provider: deepseek.
  • llm_base_url: OpenAI-compatible API base URL. Defaults to https://api.openai.com/v1, or https://api.deepseek.com when llm_provider: deepseek.
  • llm_temperature: Chat model temperature. Defaults to 0.5.
  • llm_max_tokens: Optional maximum completion token budget. Defaults to 4096 for DeepSeek because reasoning models may consume reasoning tokens before producing visible text.
  • llm_thinking: Optional DeepSeek thinking mode setting. Defaults to disabled for DeepSeek so tool-calling conversations do not need to replay provider-specific reasoning content.
  • use_azure: Boolean selecting the Azure OpenAI client path. Defaults to false.
  • azure_endpoint: Azure OpenAI endpoint. Required when use_azure: true.
  • azure_deployment: Azure OpenAI deployment name. Defaults to gpt-4 in the loader if omitted.
  • azure_api_version: Azure OpenAI API version. Defaults to 2024-12-01-preview.

Path Rules

project_dir and patch_dataset_dir are expanded with os.path.expanduser().

If either path does not end with /, the loader appends / internally. This means string concatenation in the current code assumes trailing slash behavior.

Both directories must already exist. The loader exits if either is missing.

Public benchmark case directories can be cloned from https://github.com/OS3Lab/patch_dataset and used as patch_dataset_dir values.

Commit Rules

The loader verifies these values against project_dir:

  • new_patch
  • new_patch_parent
  • target_release

Each value must resolve to a valid commit in the target repository. After validation, the loader replaces each value with its full hash via git rev-parse.

Main LLM Selection

The current main workflow has three model paths:

  • regular OpenAI, configured in src/agent/invoke_llm.py
  • DeepSeek or another OpenAI-compatible endpoint, selected with llm_provider
  • Azure OpenAI, selected with use_azure: true

DeepSeek example:

llm_provider: deepseek
llm_base_url: https://api.deepseek.com
llm_model: deepseek-v4-pro
llm_max_tokens: 4096
llm_thinking: disabled

Provide the key with DEEPSEEK_API_KEY or deepseek_key. Prefer the environment variable for local runs.

Azure mode reads deployment and endpoint fields from YAML and takes precedence when use_azure: true.

Prejudge Configuration

The prejudge pipeline does not use this YAML file.

Prejudge is invoked with CLI arguments:

python src/prejudge/prejudge.py <commit-id> <kernel-source-dir> <target-project-dir>

The LLM-backed prejudge path expects OPENROUTER_API_KEY in the environment and model provider settings from src/prejudge/judge_agent.py.

Validation Hook Contract

The case directory can provide:

  • build.sh
  • test.sh
  • poc.sh

Before full validation, files from patch_dataset_dir are copied into the target repository root.

If a hook is missing, the corresponding stage is treated as passed. Provide hooks deliberately based on the assurance level needed for the case.

Pre-Run Checklist

Before running:

python3 skills/retropatch-engineering/scripts/check_setup.py --config case.yml
git -C <project_dir> status --short

Confirm:

  • project_dir is a disposable clone
  • all three commit fields resolve
  • patch_dataset_dir exists
  • validation scripts are intentionally named and safe to copy
  • the selected API credentials are available