Repository files navigation

This repository provides Docker images and GitHub Actionsfor use in CodeQL coursesonLearning Lab.

These actions allow you to specify workflowsthat can check that course participants' queries are correct,by running their queries against a well-known CodeQL database,and checking the results are as expected.Whatever the outcome,the action will post a comment on the commit which was pushedto add the queries.

When a user's results are incorrect,the comment will include details of which results are missing,and which are superfluous,including links to the lines of source code on GitHub when possible:

Screenshot:

Table of Contents

• Creating your own course
  • Creating the Query Checking Action
    • Testing the action
    • Adding new queries & calculating the contents for the CSV files
    • Publishing your action
  • Contributing your GitHub Action to this repository
  • Creating the Learning Lab Course
• Example Courses
• Contributing
  • Releasing new versions or updating dependencies
• License

There are two main components to any Learning Lab course for CodeQL that usesthe components in this repository:

• Query Checking Action:

  Each course has its own GitHub Action that is designed to be used in workflowsthat run when a course participant pushes new commits to their repo.The action will check which queries have changed in the push,and run the queries that it recognizes as part of the course(based on the filename).

  After running the queries,the action will check the results against a CSV file of expected results.It will then post a comment on the commit,detailing whether each query produced the correct results or not.And if not,it will include details of which results are missing,and which results are unexpected.

  These actions are bundled using Docker,and made available usingGitHub Packages.

• Learning Lab Course:

  This is the course itself.It creates the initial repository the participant will use for their course,posts instructions as GitHub issues,and listens for comments posted by the GitHub action to know when the userhas completed the current task correctly,and is ready to advance to the next one.

(for an example of a working action,seecourses/cpp/ctf-segv).

Course actions consist of anaction.yml file,and docker image built from the base imagecodeql-learninglab-check.

The base image expects course images built on-top of itto add the file/home/codeql/config/config.json,which details the configuration for the course.

The file should look something like this:

{"databasePath":"<path-to-database-directory>","locationPaths":"https://github.com/<owner>/<repo>/blob/<sha>{path}#L{line-start}-L{line-end}","expectedResults": {"step-01.ql":"step-01.csv","step-02.ql":"step-02.csv","step-03.ql":false,  }}

In addition to theconfig.json file above,a course image needs to also add the snapshot directorythat queries should be run against,and csv files for the expected results.

• databasePath should be a directory in the docker image,relative to theconfig.json file,that contains the extracted CodeQL database that queries will be run against.If you are using the template below,it will usually be the name of the only top-level directoryfrom inside the database zip file.
• locationPaths is an optional template string that can be used to enablesource links in comments, when participants have written queries that outputunexpected rows, or are missing results.<owner>,<repo> and<sha> should be replace as appropriate,the placeholders{path},{line-start} and{line-end} are used by thechecker, and should be left as-is.
• expectedResults is an object that maps expected query filenames to a csvfile detailing what the expected results for this query should be.Only the first expression for each row in the query results is checked.If instead of a CSV filename,false is used,then the checker will assume that the CSV file has simplynever been generated,and will print out the resulting output from the query for you to copy into anew file.

To simplify course creation,we recommend structuring your course folder like so:

├── answers               <─── Model Answers│   ├── qlpack.yml│   ├── step-01.ql        <─┬─ Answers with expected paths│   ├── step-02.ql        <─┤  (relative to answers/)│   └── ...               <─┘  as specified in config.json├── image│   ├── config│   │   ├── config.json   <─── Main course configuration│   │   ├── step-01.csv│   │   ├── step-02.csv│   │   └── ...│   └── Dockerfile└── action.yml

(For your convinience,we've created a template course that uses this file-structurein the foldertemplates/action.You can simply copy the folder,and follow the instructions in the template README for what things to replace).

action.yml should look something like this:

name:'Check queries'description:'Check that the queries that have been pushed (as part of the lesson) produce the correct results'author:'GitHub <opensource+codeql-learninglab-actions@github.com>'runs:using:'docker'image:'docker://docker.pkg.github.com/<owner>/<repo>/<package>'branding:icon:'check-circle'color:'purple'

andDockerfile should look something like:

FROM docker.pkg.github.com/github/codeql-learninglab-actions/codeql-learninglab-check:<version>## Add course configCOPY --chown=codeql:codeql config /home/codeql/configWORKDIR /home/codeql/config# Download, unzip and then delete the zip file in one step to reduce image sizeRUN wget --quiet <url-for-snapshot-zip> -O database.zip && unzip -qq database.zip && rm -rf database.zip

Note that we download, unzip and then delete the zip file of the snapshotin a single step here.This helps us reduce the size of the image,as separate steps would result in intermediate image layers that are builton-top of one another.

You can test the action either locally or on GitHub actions.

Locally:

To test a course locally,from the course directory,run either of these scripts:

• scripts/test-course-actual.sh:which will download and use the specific version ofcodeql-learninglab-checkthat is specified inDockerfile
• scripts/test-course-latest.sh:Which will also build thecodeql-learninglab-check image locally,and tag it with the expected base image of the course,allowing you to test how changes to thecodeql-learninglab-checkaffect this specific course,without publishing any new images.

Both scripts take as argument anoptional regexp string.If this string is passed, only the querieswith names matching the regexp will be run.Otherwise all queries are run.

In GitHub Actions:

If adding a course to this repository,extend the workflow file.github/workflows/ci.ymlto include your new course.Any subsequent pushes to any branch should trigger an Action to runthat will succeed only when all the expected queries produce the right results.

If you are creating a course in another repository,you can copy thescripts/test-course-actual.shandscripts/test-course-latest.sh filesinto that repository,and add a similar workflow file to the one mentioned above.

When testing the action (as detailed above),when a query that is run produces unexpected results,or it is specified asfalse inconfig.yml instead of listing a CSV filename,the actual results that it produces are printed out in the console.You can then store this output as the relevant CSV file.

So the workflow for adding a new query and CSV file looks like:

• add the query (.ql file) toanswers/.
• add the query to theexpectedResults property inconfig.json,with a starting value offalse.
• Test the action (whichever method you prefer).
• Copy the CSV output to the appropriate file inimage/config/.
• Re-test the action to ensure it marks the queryas producing the correct results.

The main thing you need to do here is publish your Docker image somewhere,and ensure thataction.yml referrs to a tag that is downloadable.

We recommend setting up a GitHub Actions Workflowto automatically publish your docker imagewith the versionlatest todocker.pkg.github.comwhenever you get a new push tomaster.This is what we do in.github/workflows/publish.yml.

Any courses that are added to this repositoryneed to be published in this manner.

If you want to add a course to this repository,ensure that:

• You're creating the course in thecourses/ folder,under the appropriate language sub-folder for the project.
• You update both.github/workflows/ci.yml and.github/workflows/publish.yml to includetesting and image publishing for your course.

If you have not created a Learning Lab course before,it is recommended to take thecourse on creating a course!

There are core repositories that need to be created as part of any learning-labcourse:

• The course repository:All the course configuration, instructions etc...
• The template repository:The initial contents that populate the repositorycreated on behalf of the course participant.(All courses are taken with respect to it's own repository)

We've created two template directoriesthat you can use as a starting point for your own CodeQL Learning Lab Course:

• templates/learninglab/course
• templates/learninglab/course-template

Simply copy the contents of these templates into their own repositories,and follow thetemplate instructions to get started.

(Remember that you need to create 2 separate repositoriesfor your Learning Lab course,they can't be directories in an existing repo).

• GitHub Security Lab CTF 1: SEGV hunt

Feel free to add your own courses to this list!SeeCONTRIBUTING.md.

We welcome contributions,both for new courses,and improvements to existing courses ot thecodeql-learninglab-check docker image.

See:Updating and Releasing

The code in this repository is licensed under MIT (seeLICENSE.md).However as it makes use of the CodeQL CLI,you must also abide by theGitHub CodeQL Terms and Conditions,whenever your usage involves the CodeQL CLI.

In particular,you are not permitted to use these docker images or actionsto create CodeQL databases using the CLI in CI/CD,as per theterms & conditions:

the Software cannot be used [...]To generate CodeQL databases for or during automated analysis,continuous integration or continuous delivery,whether as part of normal software engineering processes or otherwise.