Skip to content

BGGP Verifier Guide

Jump to bottom
mfavata edited this page Jun 21, 2024 · 2 revisions

Hello! Thank you for volunteering to be a BGGP verifier! This is an important role in the Binary Golf Grand Prix, as you will be responsible for testing entries and updating the repo. Verifiers get a Discord role, and are added to the BGGP Verifiers Github team in the binarygolf organization.

These are the steps to verify an entry.

0. Setting Up A Testing Environment

Set up a VM or other isolated testing environment for yourself to test entries on. When dealing with weird files, it's important to have a clean state to test on, as files may cause unintended effects which could affect your system. Please try not to run untrusted files on your main OS :))

We recommend the following

  • QEMU
  • Windows VM
  • Linux VM (Ubuntu)
  • Docker, because some BGGP entries have recommended docker containers to help run them

1. Triaging A New Entry

BGGP now takes in new entries via Github Issues here: https://github.com/binarygolf/BGGP/issues

An entry will be a filled out copy of this template.

---BEGIN BGGPx---
Submit Date: 
BGGP Challenge Number:
Author: 
Contact Info (Optional): 
Online Presence (Website/Social Media): 
Target File Type: 
File Size: 
SHA256 Hash: 
Target Environment (How do we run the file?): 
Any additional info?: 
Link to PoC video, screenshot, or console output, if any: 
Link to writeup, if any: 
File contents (base64 encoded please): 
---END BGGPx---
  • Look at issues that have both "BGGP Entry" and "Needs Verification" tags.
  • Check if the entry is a new entry, or an update to an existing entry. Note that people can only submit one update per entry per BGGP!
  • Check to see if anyone else has communicated with the author about testing their entry.

NOTE: There can be multiple verifiers per entry! If there is a file type you love or have an easy way to test, feel free to verify it too.

2. Verification Steps

  • Follow the author's instructions to run the program.
  • Verify that it does the behavior expected and works in the target environment.
    • If it doesn't, inform the author and wait for clarification
    • If you can't verify the entry even after clarification, or for other technical reasons, please inform the other verifiers or BGGP staff on Discord.
  • Once verified, fill out a verification stub
---BEGIN VERIFICATION---
Reviewer:
Review Date:
SHA256: 
Score: 
Note: 
---END VERIFICATION---

This is how scores are calculated:

BasePoints = 4096 - FileSize
FinalScore = BasePoints + Modifiers

The FinalScore should be in the score field.

The main modifier for BGGP is whether or not they submitted a writeup, which adds 1024 points to their score. If we have any other scoring modifiers you can add those too.

3. Adding An Entry To The Repo

  • In the year directory (eg 2024/), create a subdirectory in the entries/ directory named after the authors name. Then create a file named AUTHOR.FILETYPE(S).TXT

PROTIP: You can do this at the same time in the Github webapp, if you type authorname/authorname.filetype.txt in the file name field ;)

  • Paste the contents of their BGGPx entry and your verification stub
  • Update the README of the year with their entry and file size. (See Below)

Since we are doing this all by file type, put the new entry in the part of the document that has entries for the given file type. If it's a new file type, see Step 3.1

This is an example of a submission by an author with a 420 byte PE.

Size Author File Type Writeup Note
420 ExampleAuthor1 PE Link
  • Put a link to the author's entry in this repo in the Author field.
  • If there is a writeup or blog for this entry, create a link to it with the text "Link" in the table entry.
  • If there are any special notes that were mentioned by the author, include them in Note. These can include things like "Works on Linux Kernel 6.2 with Kconfig option CONFIG_SOMETHING" or "Uses command line input". If there aren't any caveats to document, you can leave the note blank.
  • If there is already a table for this file type, create a table entry like so and add it to the table above the entry with a larger size.
  • If the file is the smallest in a given category, put a crown emoji 👑 next to the authors name.

Example of a table entry

| 420 | [ExampleAuthor1](./ExampleAuthor1/ExampleAuthor1.PE.txt) 👑 | PE | [Link](https://binary.golf) | |

PE

Example of a table before

Size Author File Type Writeup Note
666 ExampleAuthor2 👑 PE
1024 ExampleAuthor3 PE

PE

Example of the PE table after

Size Author File Type Writeup Note
420 ExampleAuthor1 👑 PE Link
666 ExampleAuthor2 PE
1024 ExampleAuthor3 PE

3.1 Adding a new file type to the README of the challenge

If there is no entry for a file type, create a table and add your table entry there.

Create a heading with three pound symbols (eg ### ) followed by the file name. If you can find or write a small blurb (1 or 2 sentences) that explains the file type, put it between the heading and the table so people can know what the file type is. Here are some examples.

4. Final Steps

Inform the author that their entry has been verified on the github issue and thank them for submitting something! Remove the Needs Verification tag and add the Verified tag. Close the issue.

Getting Assistance

If you are ever unsure about something regarding an entry, don't hesitate to ask the ask the author via the github issue. If you have questions about the verification process, or need assistance from other verifiers or staff, please ask in the #verifiers-chat in the BGGP discord.

If there is anything unclear about this guide, please feel free to ping the BGGP staff on Discord.

Clone this wiki locally