trailofbits-buttercup/program-model

Program Model

Indexes a program into a graph database.

Requirements

n2-highmem-8 instance.

Setup

Set up working directory and tasks directory.

cd afc-crs-trail-of-bits/

cp env.template .env

sudo mkdir /crs_scratch/ && sudo chown `whoami`:`whoami` /crs_scratch && sudo mount --bind ./crs_scratch /crs_scratch

sudo mkdir /tasks_storage && sudo chown `whoami`:`whoami` /tasks_storage && sudo mount --bind ./tasks_storage /tasks_storage

Set up GitHub token.

gh auth login
GitHub.com
SSH
No
Paste an authentication token

echo <token> | docker login ghcr.io -u <username> --password-stdin

Download Kythe.

cd afc-crs-trail-of-bits/

mkdir -p program-model/scripts/gzs/kythe/

gh release download v0.0.2 -R github.com/trailofbits/aixcc-kythe -D program-model/scripts/gzs/

tar -xvzf program-model/scripts/gzs/kythe-v0.0.67.tar.gz -C program-model/scripts/gzs/kythe/ --strip-components=1

Usage

Prepare example challenge project.

cd afc-crs-trail-of-bits/

mkdir -p tasks_storage/example-libpng/src/ && mkdir -p tasks_storage/example-libpng/fuzz-tooling/

git clone --branch aixcc-exemplar-challenge-01 git@github.com:aixcc-finals/example-libpng.git tasks_storage/example-libpng/src/example-libpng

git clone --branch master git@github.com:aixcc-finals/oss-fuzz-aixcc.git tasks_storage/example-libpng/fuzz-tooling/fuzz-tooling

Start up CRS.

cd afc-crs-trail-of-bits/

docker compose up -d --build --remove-orphans

# cd common/
# uv run src/buttercup/common/msg_publisher.py send tasks_ready_queue ../program-model/mock_data/ready_msg.json

Send task to Program Model via Redis queue.

docker compose logs -f program-model

cd afc-crs-trail-of-bits/program-model/

uv run mock/trigger_pm.py \
  --build_type full \
  --package_name libpng \
  --sanitizer AddressSanitizer \
  --task_dir ../tasks_storage/example-libpng \
  --task_id libpng

Testing on Challenges

See challenges.md.

Development

Create a new virtual environment and enter it:

cd afc-crs-trail-of-bits/program-model/

uv venv
source .venv/bin/activate
uv sync --all-extras

Run tests:

pytest

Lock, reformat, and lint before committing changes:

just lock
just reformat
just lint

FAQs

• Why does this use a ubuntu base image?
  • Since Kythe uses OSS Fuzz to build and index the challenge source code, we have to use the same base image as ClusterFuzz.
• Why does this use Python 3.10?
  • ClusterFuzz uses Python 3.10.
• How do I build Kythe?
  • Follow the instructions in dev.md.
• What are available APIs for this component?
  • See api.md.