Each problem belongs in its own folder under the root folder of the repository. The name of the folder will become a readable identifier for the problem, so it should only contain letters, numbers, and `-`.
Inside this folder, there are 3 required files:
-`problem.yml`: This is probably the most important file. It contains all the metadata for the problem, including:
-`title`: The title of the problem.
-`category`: The category of the problem.
-`value`: An integer value for the problem.
-`hint`: A hint for the problem. (no markdown supported)
-`autogen`: (`true`/`false`) whether or not the problem is autogenerated. If you put `true`, read on to see what needs to be added to the grader.
-`description.md`: A problem description. As the extension suggests, you may use markdown in this file.
-`grader.py`: A python file containing several functions that relate to grading the problem (and generating, if autogen is enabled).
The Grader
--------------
At the most basic level, the grader should contain a `grade` function that takes in two parameters (you can call them whatever you like): (1) an instance of the random library used for autogenerating problems, and (2) the flag that the user actually typed into the input box. It should return a tuple `(correct, message)`, where `correct` is a boolean value signifying whether the user got the problem right, and `message`, a custom message to be displayed.
An example of a basic grader looks like this:
```python
def grade(random, key):
if key.find("this_is_the_flag") != -1:
return True, "Correct!"
return False, "Nope."
```
If autogen is not enabled, please do not use `random` while judging the key. It's meant for checking problems that were autogenerated with the same seed. Also, note that I'm using `key.find` rather than comparing them with equals. This is useful if you want to match both `flag{this_is_the_flag}` and `this_is_the_flag`, or if you are trying to perform a case-insensitive match.
If autogen were enabled, you would need to add an additional function to the grader, called `generate`. Essentially, this function is required for generating the problem. It takes in a single parameter, the same instance of `random` as the `grade` function gets, and must return a dictionary of values (obviously, this dictionary can be blank, but ideally it shouldn't be).
Possible keys that you can include in your dictionary are:
-`variables`: This should be another dictionary of variables that are inserted into the description during runtime. More details on how these variables are inserted comes in a later section. You would probably want to use the `random` variable that is passed to the function to generate a value that is different per team.
-`files`: This is similar to `variables` in that it is a dictionary of keys that are inserted into the description. However, instead of returning variables directly, you should return a function that takes in the `random` variable and returns a File object (could be StringIO as well). Files generated this way are stored into the static container during runtime.
An example using both `variables` and `files` is:
```python
from cStringIO import StringIO
def gen_b(random):
b = random.choice(range(50, 100))
return b
def generate(random):
a = random.choice(range(50, 100))
return dict(variables={
"a": a
}, files={
"b.txt": gen_b
})
```
Note that we are returning `gen_b` without `()`, since we want to return the function definition, rather than a value returned by the function. This way, the platform can call this function at runtime, generating a different problem for every user.
**This part is very important**. Filenames usually have extensions, like `ciphertext.txt`. In this case, we are passing the filename into the description as a string. But Python template strings don't allow symbols such as periods. Therefore, ALL FUNCTION NAMES ARE SANITIZED by replacing anything matching this regex: `[^a-zA-Z]+` with `_` (underscore). This way, `ciphertext.txt` becomes `ciphertext_txt` in the description. Here is a description that uses the above generator.
```markdown
Help me decipher [this](${b_txt}).
```
Here is a full example using autogen:
problem.yml:
```yaml
title: Caesar Cipher
value: 20
author: mzhang
autogen: true
```
description.md:
```markdown
Help me decipher [this ciphertext](${ciphertext_txt}).
```
grader.py:
```python
from cStringIO import StringIO
from string import maketrans
flag = "caesar_cipher_is_fun!"
alphabet = "abcdefghijklmnopqrstuvwxyz"
def get_problem(random):
n = random.randint(1, 25)
salt = "".join([random.choice("0123456789abcdef") for i in range(6)])
return (n, salt)
def generate_ciphertext(random):
n, salt = get_problem(random)
trans = maketrans(alphabet, alphabet[n:] + alphabet[:n])
In this way, not only is the shift randomly generated, so is the actual flag itself. Note that I use a helper function, `get_random` to actually generate the numbers to ensure that the numbers generated are the same for both the generation and the grading.
