README.md

Welcome to OWASP Cheat Sheet Series V2

This repository contains all the cheat sheets of the project and represent the V2 of the OWASP Cheat Sheet Series project.

Table of Contents

• Cheat Sheets index
• Migration process
• Editor & validation policy
• Conversion rules
• How to setup my contributor environment?
• How to contribute?
• Offline website
• Project leaders
• Folders
• Migration tasks list
• License

Migration process

A mass conversion from Mediawiki to GitHub flavored Markdown format has been performed using this tool based on PANDOC on 26th of december 2018 on all OWASP wiki pages flagged as Cheatsheets.

⚠️Cheat Sheets content is now frozen from this date:

• No modification will be performed anymore on the wiki content.
• Any modification will be made on this repository using the contribution issue templates defined in this repository.

Cheat Sheets index

This Index reference all migrated and released cheat sheets.

Project leaders

• Jim Manico.
• Dominique Righetto.

Folders

cheatsheets_to_convert:

• Contains the cheat sheets markdown files converted with PANDOC and for which a convertion work is needed in order to be cleanly converted to Github markdown.

cheatsheets_excluded:

• Contains the cheat sheets markdown files converted with PANDOC and for which a discution must be made in order to decide if we include them into the V2 of the project due to the content has not been updated since a long time or is not relevant anymore.

cheatsheets:

• Contains the final cheat sheets files.
• Any .md file present at the root of this folder is considered as converted and the associated cheat sheet is considered released.

assets:

• Contains the assets used by the cheat sheets (images, pdf, zip...).
  • Naming convention is [CHEAT_CHEET_MARKDOWN_FILE_NAME]_[IDENTIFIER].[EXTENSION]
  • Use PNG format for the images.

scripts:

• Contains all the utility scripts used to operate the project (markdown linter audit, dead link identification...).

templates:

• Contains templates used for different kinds of files (cheatsheet...).

.github:

• Contains materials used to configure different behaviors of GitHub.

.circleci / .travis.yml (file):

• Contains the definition of the integration jobs used to control the integrity and consistency of the whole project:
  • TravisCI is used to perform build and check actions at each Push or on each Pull Request.
  • CircleCI is used to perform regular scheduled build and check actions (night build).

Offline website

Unfortunately, a PDF file generation is not possible because the content is cut in some cheat sheets like for example the abuse case one.

However, to propose the possibility the consult, in a full offline mode, the collection of all cheat sheets, a script to generate a offline site using GitBook has been created. The script is here.

• book.json: Gitbook configuration file.
• Preface.md: Project preface description applied on the generated site.

Automated night build

This link provide the url where to download a night build of the offline website:

[ {
  "path" : "OfflineWebsite-NightBuild.zip",
  "pretty_path" : "OfflineWebsite-NightBuild.zip",
  "node_index" : 0,
  "url" : "https://14-162723104-gh.circle-artifacts.com/0/OfflineWebsite-NightBuild.zip"
} ]

The attribute url must be used to download the ZIP archive.

Manual build

Use the commands below to generate the site:

# Your python version must be >= 3.5
$ python --version
Python 3.5.3
# Dependencies:
#  sudo apt install -y nodejs
#  sudo npm install gitbook-cli -g
$ cd scripts
$ bash Generate_Site.sh
Generate a offline portable website with all the cheat sheets...
Step 1/5: Init work folder.
Step 2/5: Generate the summary markdown page.
Index updated.
Summary markdown page generated.
Step 3/5: Create the expected GitBook folder structure.
Step 4/5: Generate the site.
info: found 45 pages
info: found 86 asset files
info: >> generation finished with success in 14.2s !
Step 5/5: Cleanup.
Generation finished to the folder: ../generated/site
$ cd ../generated/site/
$ ls -l
drwxr-xr-x 1 Feb  3 11:05 assets
drwxr-xr-x 1 Feb  3 11:05 cheatsheets
drwxr-xr-x 1 Feb  3 11:05 gitbook
-rw-r--r-- 1 Feb  3 11:05 index.html
-rw-r--r-- 1 Feb  3 11:05 search_index.json

Conversion rules

• Use the markdown syntax described in this guide.
• Use this sheet for Superscript and Subscript characters.
• Use this sheet for Arrows (left, right, top, down) characters.
• Store all assets in the assets folder and use the following syntax:
  • ![ALTERNATE_NAME](../assets/ASSET_NAME.png) for the insertion of an image. Use PNG format for the images (this software can be used to handle format conversion).
  • [ALTERNATE_NAME](../assets/ASSET_NAME.EXT) for the insertion of other kinds of media (pdf, zip...).
• Use ATX style (# syntax) for section head.
• Use **bold** syntax for bold text.
• Use *italic* syntax for italic text.
• Use TAB for nested lists and not spaces.
• Use code fencing syntax along syntax highlighting for code snippet (prevent when possible horizontal scrollbar).
• If you use {{ or }} pattern in code fencing then add a space between the both curly braces (ex: { {) otherwise it break GitBook generation process.
• Same remark about the cheat sheet file name, only the following syntax is allowed: [a-zA-Z_]+.
• No HTML code is allowed, only markdown syntax is allowed!
• Use this site for generation of tables.
• Use a single new line between a section head and the begining of its content.

Editor & validation policy

Visual Studio Code is used for the work on the markdown files. It is also used for the work on the scripts.

The file Project.code-workspace is the workspace file in order to open the project in VSCode.

The following plugin is used to validate the markdown content.

The file .markdownlint.json define the central validation policy applied at VSCode (IDE) and TravisCI (CI) levels.

Details about rules is here.

The file .markdownlinkcheck.json define the configuration used to validate using this tool, at TravisCI level, all web and relatives links used in cheat sheets.

Migration tasks list

? All the tasks below represents the work that must be performed before that the V2 will be considered as Go Live! (CS = Cheat Sheet).

? = Critical task.

• Task 01: ? Migrate all the CS files of the folder cheatsheets_to_convert.
• Task 02: ? Update each OWASP WIKI page associated to a CS in order to indicate the redirection to the GitHub location in order to do not break cross-reference to CS.
• Task 03: Create a Python script to auto-generate an markdown index page of all CS like this page.
• Task 04: Create a markdown template file for the new CS.
• Task 05: Create the index page of the repository based on this README file to provide all the information about the repository and how to contribute.
• Task 06: Migrate the project Trello board content to Issues in this repository
  • Create labels for: Request from OPC, Internal task...
• Task 07: Create all the materials to generate a offline website of all the CS, automate it via a CircleCI job.
• Task 08: Create a template for the pull request in order to add a checklist like the one created by the MSTG.
• Task 09: Add a CI job to validate automatically the Pull Request when they are submitted.
• Task 10: ? Classify the CS collections in order to address the following important problem raised by the community:

Too many best practices:
It would be nice to have them structured so people drill down to Exactly what they want.
Like the @thoughtworks tech radar: https://www.thoughtworks.com/radar

Idea: In addition to the alphabetical index, the following indexes will be created:

• An Index from that will classify every cheat sheets by OWASP Proactive Controls sections.
• An Index from that will classify every cheat sheets by OWASP Application Security Verification Standard Project sections.

How to setup my contributor environment?

Follow these steps:

1. Install Visual Studio Code (named VSCode from here), it is cross platform and free.
2. Install this plugin from VSCode.
3. Open the file Project.code-workspace from VSCode via the menu File > Open Workspace....
4. You are ready to contribute ?

⏰ Before to push my update to my fork, what I need to verify?

1. Ensure that the markdown file you have created/modified do not have any warnings/errors raised by the linter, you can see it in this bottom bar when the markdown file is opened in VSCode:

1. Ensure that the markdown file you have created/modified do not have any deadlinks. You can verify that by using this plugin, if you cannot use this plugin then, at least, verify that all the links are valid before to push:
   1. Install NodeJS to install NPM.
   2. Install the validation plugin via the command npm install -g markdown-link-check
   3. Use this commmand (from the repository root folder) on your markdown file to verify the presence of any deadlinks:

$ markdown-link-check -c .markdownlinkcheck.json [MD_FILE]

See the example below:

$ markdown-link-check -c .markdownlinkcheck.json cheatsheets/Transaction_Authorization_Cheat_Sheet.md
FILE: cheatsheets/Transaction_Authorization_Cheat_Sheet.md
[✓] https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm
[✓] https://en.wikipedia.org/wiki/Chip_Authentication_Program
[✓] http://www.cl.cam.ac.uk/~sjm217/papers/fc09optimised.pdf
...
# If the program do not say to you that you have deadlinks so it's OK
# The identified deadlinks are showed using a red cross instead of a green tick before the link.

How to contribute?

Follow these steps:

1. Create an new Issue using either:
   • The new_cheatsheet_proposal template if you want to propose a new cheat sheet.
   • The update_cheatsheet_proposal template if you want to modify a existing cheat sheet.
2. After a discution on the topic/update and if the proposal is accepted by the project leaders then:
   1. Clone this GitHub repository.
   2. Either:
   • Create the cheat sheet using the dedicated template in case of a new cheat sheet.
   • Modify the target cheat sheet in case of a update/refactoring.
   1. Submit your Pull Request.
   2. Verify that the CI job applied on your Pull Request do not fail!

License