The Developer Guide has been updated for the modern security landscape, concentrating less on covering everything in one document and more on introducing a subject/project and then suggesting where more in-depth information can be found.
The project has a team of leaders that oversee the project and contributions from members of the security community are positively encouraged. Refer to the The OWASP project page for the latest information and releases.
All contributions and suggestions are certainly welcome, and we ask that you follow the contributing Code of Conduct. Contributors can make suggestions and provide changes via a pull request.
Feel free to discuss topics in the project wiki and create new discussions.
- follow our Code of Conduct
- ensure that all contributions meet the license
- the use of generative AI is not prohibited but must be declared in the pull request
The Developer Guide does not seek to duplicate the information contained in the many OWASP documentation projects; these projects address their subject fully and completely. Instead the Developer Guide is a starting point on a wide range of subjects which a developer would need to know at least the basics. The Developer Guide should supply this basic knowledge only, and then refer the developer to further reading for more in-depth treatment of the subject. As a rule of thumb, if a section is more than two pages then it is probably too long; split the section up or refer to another more detailed project.
Github issues are used to coordinate contributions and keep track of progress towards each milestone:
- select an issue from the project board for the section you want to work on
- if this issue is free ask for it to be assigned to you
- if the issue has already been assigned then coordinate with the existing owner
- if there is not an existing issue that describes your content then suggest one
- provide your contributed content as a pull request
The Developer Guide will have many contributors, and it is an aim to keep the style of writing similar throughout. Follow the style used in OWASP flagship projects ASVS and WSTG, which is speaking from first person plural and semi-formal in tone.
Generally the guide is aimed at the introductory to medium technical levels, and should rarely deal with any subject at an advanced level. This is a deliberate policy that makes the guide accessible and keeps the length reasonable.
The overview/introduction of the main sections should be aimed at the introductory level, with more detail contained in the sub-sections at a medium technical level. Note this guide should not replicate the many detailed sources on specific security topics; instead provide links to these specialist security knowledge bases.
Each sub-section should deal with one specific subject, for example 'Threat modeling', or a single project such as the OWASP 'Threat Dragon' Builder/Tool project.
Sub-sections that describe an individual project should follow the same structure:
- Introduction, summarizing the project at a very high level: supply a couple of sentences on the project including its status as an OWASP project and where to find it
- The 'What', explaining what the project is to a general level: go into more detail about the project so that a developer can gain an overview of what this project can provide for them
- The 'Why', explaining why developers will want to use the project: provide more context for project that allows developers to determine whether to use it in their team
- The 'How', describe how to get started with the project give a brief outline of how the project provides value for a web application development team Do not repeat the project documentation itself; ideally provide a primer and a pointer to the project documentation
- Further reading or resources, if any, providing links on the project at an advanced/detailed level
Note that the page describing a project should not be the same as the project documentation on the OWASP site, the Developer Guide should strive to be a ' TL;DR ' for the project running to one or maybe two pages.
The OWASP projects have media kits that contain biographies of the project leaders and other project media. This can be used for logos and marketing material.
The pull requests have checks applied to them:
- Link checker for any broken links; if there is an imperative for a broken link then add it to
.lycheeignore - Markdown lint that ensures the markdown is consistent and valid
- Spell checker; new words that are not recognized should be added to
/.wordlist.txt
The pipeline will apply checks to all pull-requests, and will fail on any error. To run these checks locally before pushing a commit, run these commands from the top directory:
- Link checker:
lychee --max-retries 5 './**/*.md' - Markdown linter:
markdownlint-cli2 **/*.md - Spell checker:
pyspelling --config .spellcheck-en.yaml(for English language version)
Follow instructions to install the command line lychee and pandoc.
To install markdownlint-cli2 use npm: npm install markdownlint-cli2 --global,
and to install pyspelling use pip: pip install pyspelling
Test the web document locally before creating / updating a pull request.
On Windows install python and then install packages using pip:
python3 -m pip install mkdocs-open-in-new-tabpython3 -m pip install mkdocs-materialpython3 -m pip install mkdocs
Run the docs server and observe the document at http://127.0.0.1:8000/ :
python3 -m mkdocs serve
To generate site content for deployment build the web document with:
python3 -m mkdocs build
On Linux or MacOS install the packages using python's pip:
pip install mkdocs
pip install mkdocs-material
pip install mkdocs-open-in-new-tab
pip install mkdocs-with-pdf
Run the docs server and observe the document at http://127.0.0.1:8000/ :
mkdocs serve
Any changes to the markdown files are detected by the server and the site will rebuild.
To generate site content build the web document with:
mkdocs build
This will also create the PDF export at site/OWASP_Developer_Guide.pdf.
OWASP DevGuide: accessible security for developers