Update structure and presentation

CONTRIBUTING.md

@@ -1,14 +1,15 @@
-# Contributing
+# Contributing to Binary Security Resources
 
-These are recommendations when contributing to the contents of this repository.
-They consider contributions to both actual content (mostly Markdown) and support code (demo, lab activities) made via Git.
+These are recommendations when contributing to the contents of the Binary Security repository.
+They consider contributions to both actual content (mostly Markdown) and support code made via Git.
 
 ## First Steps
 
 Some good first steps and best practices when using Git are explained here:
-* the Git Immersion tutorial: https://gitimmersion.com/
-* the Atlassian tutorial: https://www.atlassian.com/git/tutorials/learn-git-with-bitbucket-cloud
-* this blog post on the ROSEdu Techblog: https://techblog.rosedu.org/git-good-practices.html
+
+* the Git Immersion tutorial: <https://gitimmersion.com/>
+* the Atlassian tutorial: <https://www.atlassian.com/git/tutorials/learn-git-with-bitbucket-cloud>
+* this blog post on the `ROSEdu Techblog`: <https://techblog.rosedu.org/git-good-practices.html>
 
 ## Language
 
@@ -30,16 +31,22 @@ Use phrases like "find the flag", "run this command", "download the tool".
 
 ## Images
 
+Use [draw.io](https://app.diagrams.net/) to create diagrams.
+If using external images / diagram, make sure they use a CC BY-SA license and give credits (mention author and / or add link to the image source).
+
+## Slides
+
+Slides are to be written in Markdown, using [`reveal-md`](https://github.com/webpro/reveal-md), itself based on [`reveal-js`](https://revealjs.com/).
+Use `reveal-md` and `reveal-js` specifics to split information in slides.
+Aim to make slides attractive, sleek and simple to follow.
+
 Images and diagrams would ideally be animated on slides.
-Aim to use reveal.js features to animate drawing of diagrams.
+Aim to use `reveal.js` features to animate drawing of diagrams.
 
-If reveal.js drawing is difficult, use [draw.io](https://app.diagrams.net/) to create diagrams.
+If `reveal.js` drawing is difficult, use [draw.io](https://app.diagrams.net/) to create diagrams.
 Ideally you would "animate" those diagrams by creating multiple incremental versions of the diagram and adding each to a slide;
 when browsing slides pieces of these diagrams will "appear" and complete the final image, rendering an animation-like effect.
 
-For text where no animation is required, use diagrams / images created with [draw.io](https://app.diagrams.net/).
-If using external images / diagram, make sure they use a CC BY-SA license and give credits (mention author and / or add link to the image source).
-
 ## Issues
 
 When opening an issue, please clearly state the problem.
@@ -64,8 +71,46 @@ If there are multiple commits belonging to a given change, please squash the com
 
 Also make sure one pull request covers only **one** topic.
 
+### Commits
+
+Before making a commit, configure your name and email locally using:
+
+```bash
+git config --global user.name "Your Name"
+git config --global user.email "[email protected]"
+```
+
+Then make sure the email you've just configured corresponds to the one you have [set on GitHub](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/adding-an-email-address-to-your-github-account).
+
+After this, make your changes, `git add` them and then commit them using `git commit -s`.
+Always sign your commits using the `-s` / `--signoff` arguments to `git commit`.
+This will add the following line at the end of the commit message:
+
+```text
+Signed-off-by: Your Name <[email protected]>
+```
+
+Notice that the details above are the name and email that you configured earlier.
+
+Now the `git commit` command will open your default editor and ask you to write a commit message.
+Prefix each commit message name with the chapter and content type it belongs to, e.g. `bin-analysis/reading`, `exploit/slides`, `mitigation/drills`.
+Following the prefix, write a short and expressive title on the first line.
 Use commit messages with verbs at imperative mood: "Add README", "Update contents", "Introduce feature".
-Prefix each commit message with the chapter it belongs to: `software-stack`, `data`, `compute`, `io`, `app-interact`.
-How a good commit message should look like: https://cbea.ms/git-commit/
 
-The use of `-s` / `--signoff` when creating a commit is optional, but strongly recommended.
+Leave an empty line, then add a relevant description of the changes made in that commit.
+This description should include why that change is needed (fixes a bug, improves something that was inefficient, etc.).
+Wrap the lines of this description to 75 characters.
+How a good commit message should look like: <https://cbea.ms/git-commit/>
+Below is an example of a good commit message:
+
+```text
+template-chapter/drills: Fix Makefile `CFLAGS` error
+
+`CFLAGS` was incorrectly set to optimise the code to the `-O3` level. This
+caused the function `vulnerable_func()` to be inlined into the caller
+`main()`, making it impossible to overwrite `main()`'s return address with
+that of `vulnerable_func()`. This commit fixes the issue by forcing the
+compiler to not optimise the code by replacing `-O3` with `-O0` in `CFLAGS`
+
+Signed-off-by: Your Name <[email protected]>
+```

COPYING.md

@@ -7,7 +7,7 @@ A copy of each license is below.
 
 Copy of CC BY-SA 4.0:
 
-```
+```text
 Attribution-NonCommercial-ShareAlike 4.0 International
 
 =======================================================================
@@ -59,7 +59,7 @@ exhaustive, and do not form part of our licenses.
      such as asking that all changes be marked or described.
      Although not required by our licenses, you are encouraged to
      respect those requests where reasonable. More considerations
-     for the public: 
+     for the public:
 	wiki.creativecommons.org/Considerations_for_licensees
 
 =======================================================================
@@ -449,7 +449,7 @@ Creative Commons may be contacted at creativecommons.org.
 
 Copy of BSD-3-Clause:
 
-```
+```text
 Copyright 2021 University POLITEHNICA of Bucharest
 
 Redistribution and use in source and binary forms, with or without

CPPLINT.cfg

@@ -0,0 +1,14 @@
+filter=-whitespace/tab
+filter=-whitespace/line-length
+filter=-whitespace/braces
+filter=-whitespace/semicolon
+filter=-legal/copyright
+filter=-whitespace/comments
+filter=-build/header_guard
+filter=-readability/multiline_comment
+filter=-readability/casting
+filter=-runtime/int
+filter=-runtime/printf
+filter=-readability/todo
+filter=-build/include_subdir
+linelength=120

README.md

@@ -1,49 +1,49 @@
 # Binary Security
 
-These are open educational resources ([OER](https://en.wikipedia.org/wiki/Open_educational_resources)).
-The repository should be used as a template for the your own classes.
+[![copying.md](https://img.shields.io/static/v1?label=license&message=CCBY-SA4.0&color=%23385177)](https://github.com/open-education-hub/binary-security/blob/master/COPYING.md)
+[![copying.md](https://img.shields.io/static/v1?label=license&message=BSD-3-clause&color=%23385177)](https://github.com/open-education-hub/binary-security/blob/master/COPYING.md)
+[![discord](https://img.shields.io/badge/users-93-7589D0?logo=discord)](www.bit.ly/OpenEduHub)
+[![contributors](https://img.shields.io/github/contributors/open-education-hub/binary-security)](https://github.com/open-education-hub/binary-security/graphs/contributors)
+[![reddit](https://img.shields.io/reddit/subreddit-subscribers/OpenEducationHub?style=social)](https://www.reddit.com/r/OpenEducationHub/)
+[![twitter](https://img.shields.io/twitter/url?style=social&url=https%3A%2F%2Ftwitter.com%2FOpenEduHub)](https://twitter.com/OpenEduHub)
+[![youtube](https://img.shields.io/youtube/channel/views/UCumS6d-kaVXreY46eZLtEvA?style=social)](https://www.youtube.com/@OpenEduHub/)
 
-## Using the Content
+These are open educational resources ([OER](https://en.wikipedia.org/wiki/Open_educational_resources)) for Binary Security classes.
 
-Content is located in the `content/` folder.
+## Using the Content
 
-Each chapter has its own folder.
-Content for each chapter is split in two subfolders:
+Content is located in the `chapters/` directory.
+Each chapter has its own directory:
 
-- `lecture/`: content to be presented and discussed as part of lectures / presentations
-- `practice/`: content to be worked on as practical activities
+- [Binary Analysis](chapters/binar-analysis)
+- [Exploitation Techniques](chapters/exploitation-techniques)
+- [Mitigations and Defensive Strategies](chapters/mitigations-and-defensive-strategies)
+- [Extra](chapters/extra)
 
-Lecture content is expected to be presented and followed.
-Practice content is expected to be used hands-on individually or as part of team.
+### Chapter Contents
 
-## Publishing Workflow
+Chapters consists of sections, each presenting a given topic.
+Each chapter has a directory, with a subdirectory for each section.
+Content types are stored for each section.
 
-Before building the repository you have to set up the following items:
+Content is written in [GitHub Markdown](https://guides.github.com/features/mastering-markdown/).
 
-- Select the GitHub Pages branch by following the [Configuring a publishing source for your GitHub Pages site](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) tutorial.
-  You will have to set up the `gh-pages` branch as the publishing branch.
-- Add a publishing key named `ACCESS_TOKEN` by following the [Automatic token authentication](https://docs.github.com/en/actions/security-guides/automatic-token-authentication) tutorial.
+### Contributing
 
-In order to publish the content of this repository, we use a GitHub workflow located in `.github/workflows/deployment.yml`.
-This workflow will build the site using [Docusaurus](https://docusaurus.io/) and publish the contents to a link similar to `<github_username>.github.io`.
+Contributions are welcome.
+See the [contribution guide](CONTRIBUTING.md) on how you could report or fix issues and on how you can improve the content.
 
-## Your first TODOs
+Reviewers are requested to follow the [reviewing guide](REVIEWING.md).
 
-To configure this repo for the class for which you intend to develop content, you must make the following changes:
+## Publishing the Content
 
-- Change the repository name to match your class name (the default name is `oer-template`).
-- In `config.yaml`:
-  - Change `title` to you class name.
-  - Change `url` to `<github_usename>.github.io`.
-  - Change `baseurl` to `/` if the repository is the only one with a GitHub page in your profile.
-    Otherwise, change it to `/<repository_name>/`.
-  - Change links to social media sites, if applicable.
+In order to publish the content of this repository, we use a GitHub workflow located in `.github/workflows/deployment.yml`.
+This workflow will build the site using [Docusaurus](https://docusaurus.io/) and publish the contents to <https://open-education-hub.github.io/methodology/>.
 
-## Running Locally
+### Running Locally
 
 When testing locally, you will have to build the container that will run the builder based on the [`Dockerfile`](Dockerfile).
 For this, the simplest way is the use the [`Makefile`](Makefile).
-First, edit the `Makefile` and update the `REPO_NAME` variable to the preferred name of your future website.
 
 To generate the web contents locally, run:
 
@@ -57,55 +57,4 @@ To view the local contents, start a web server by running the command:
 make serve
 ```
 
-As the output of the command tells, point your browser to `http://localhost:8080/$REPO_NAME`, where `$REPO_NAME` is the name of the repository you configured in the [`Makefile`](Makefile)..
-
-## Chapter Contents
-
-### Lecture
-
-Lecture content consists of slides, demos, media files and quizzes in the `lecture/` subfolder of each chapter.
-
-Slides are written in [GitHub Markdown](https://guides.github.com/features/mastering-markdown/) and use [reveal-md](https://github.com/webpro/reveal-md) and [reveal.js](https://revealjs.com/) to render HTML output.
-Building slides requires [MarkdownPP](https://github.com/amyreese/markdown-pp).
-Lecture slides are built from the `slides.mdpp` file using the `make` command (and the `Makefile`).
-`slides.mdpp` is a wrapper / index file;
-actual content is stored in Markdown format in files in the `slides/` subfolder.
-Output is generated in the `_site/` subfolder;
-open the `_site/index.html` in a browser to view the slides.
-
-Demos are snippets of code and support files that showcase concepts and ideas related to the lecture.
-Demos are located in the `demo/` subfolder.
-Each demo has its own folder with source code, `Makefile` or other build files (if required) and support files.
-
-Media files are images and films used in slides for visual support.
-Media files are located in the `media/` subfolder.
-
-Quizzes are used in slides to trigger interactivity with participants and as a form of (self-)assessment.
-Quizzes are located in the `quiz/` subfolder.
-Quiz questions are stored in [Markdown format](https://guides.github.com/features/mastering-markdown/), one file per quiz.
-
-### Practice
-
-Practice content consists of background text, media files, support files and quizzes in the `practice/` subfolder of each chapter.
-
-Background text is located in `content/` folder as a series of sections.
-Each section consists of general information, tutorial information followed by description of actual work items and a quiz.
-Sections are indexed in the `README.md` file.
-
-Support files for work items are stored in the `support/` subfolder.
-There is a subfolder for each section.
-Each section subfolder contains source code, `Makefile` (or other build files, if required) and support files.
-
-Media files are images and films used in text for visual support.
-Media files are located in the `media/` subfolder.
-
-Quizzes are referenced at the end of each section as a form of (self-)assessment.
-Quizzes are located in the `quiz/` subfolder.
-Quiz questions are stored in [Markdown format](https://guides.github.com/features/mastering-markdown/), one file per quiz.
-
-## Contributing
-
-Contributions are welcome.
-See the [contribution guide](CONTRIBUTING.md) on how you could report or fix issues and on how you can improve the content.
-
-Reviewers are requested to follow the [reviewing guide](REVIEWING.md).
+As the output of the command tells, point your browser to `http://localhost:8080/binary-security`.

chapters/README.md

@@ -6,4 +6,4 @@ slug: /
 
 This is a landing page for your course.
 
-Here you will add infomation about your course that a student might want to know at first glance.
+Here you will add information about your course that a student might want to know at first glance.

chapters/binary-analysis/dynamic-analysis/activities/04-challenge-call-me/src/calc_offset.py

@@ -3,10 +3,10 @@
 f = open("../flag")
 flag = f.readline().strip()
 f.close()
-char = '\n'
+char = "\n"
 
 res = []
 for i in range(0, len(flag)):
     res += [ord(flag[i]) - ord(char)]
 
-print "{" + ", ".join("{}".format(r) for r in res) + "};"
+print("{" + ", ".join("{}".format(r) for r in res) + "};")

chapters/binary-analysis/dynamic-analysis/activities/06-challenge-phone-home/sol/encrypt.py

@@ -1,29 +1,30 @@
 from pwn import *
 
 flag = "SSS_CTF{0bad3910f14d10569b8bfe11aa1081e970e72e}\x00"
-flag = ''.join(chr((ord(x) - 13) & 0xff) for x in flag)
+flag = "".join(chr((ord(x) - 13) & 0xFF) for x in flag)
 parts = unpack_many(flag, 32)
 
 for i in range(len(parts)):
-	print('strvec[%d] = 0x%x;' % (i, parts[i]))
+    print("strvec[%d] = 0x%x;" % (i, parts[i]))
 
 
 def encrypt(data):
-	res = map(ord, data)
-	n = len(data)
-	print(hexdump(data))
-	for i in range(n / 2):
-		res[i] = res[i] ^ res[n - i - 1]
-		res[n - i - 1] = (res[n - i - 1] - 1) & 0xff
-	return ''.join(map(chr, res))
+    res = map(ord, data)
+    n = len(data)
+    print(hexdump(data))
+    for i in range(n / 2):
+        res[i] = res[i] ^ res[n - i - 1]
+        res[n - i - 1] = (res[n - i - 1] - 1) & 0xFF
+    return "".join(map(chr, res))
+
 
 binary = ELF("./phone_home")
-context.arch = 'i386'
+context.arch = "i386"
 
 func_ea = binary.symbols["gen_flag"]
 chunk = binary.read(func_ea, 4096)
-func_sz = chunk.find(asm('ret')) + 1
-print('Function size: 0x%x' % func_sz)
+func_sz = chunk.find(asm("ret")) + 1
+print("Function size: 0x%x" % func_sz)
 
 func = encrypt(chunk[:func_sz])
 binary.write(func_ea, func)