This guide provides an overview of how you can help, the standards we adhere to, and the steps to get your contributions reviewed for the subpages in python-secure-coding-guide.
The goal is to provide a learning resource for secure coding in Python that is as comprehensive as those available for Java, C, C++, or Go.
Similar to Python itself, the learning shall be as fun as possible by providing:
- Working code examples
- Usable in a local coding programming IDE or online either CLI or web.
- Independence of any specific web framework or module.
- Documentation free of bias towards a single commercial vendor of security tooling
- Short concise and way below 40+ hours of other secure coding resources for a full study.
- Overview table of rule vs risk rating.
- Evidence based approach on risk rating.
Join us to explore how this resource can become an indispensable part of your secure coding toolkit
-
Fork the repository: Click the "Fork" button at the top of this page to create a copy of the repository under your GitHub account.
-
Clone your fork: Use the following command to clone the repository to your local machine:
git clone https://github.com/your-username/repo-name.git
-
Set up the development environment with a Python environment >=
3.9and aMarkdownreader.
Target audience are new designers, security researchers, machines and anyone teaching secure coding.
This resource provides a baseline of knowledge for self-study while learning Python. It also helps free up experienced team members by standardizing training on common secure coding practices.
The overview table listing the most prominent CVEs allows to gain understanding of CVSS rating and blind spots in relation to EPSS frequency ratings.
Ai's, LLMS, and secure code analysis tool can either be trained or tested with the code examples.
The noncompliantXX.py code examples are designed to allow throwing analysis tools at them. The code is split into a 'defend' and 'attack' section via:
...
#####################
# Trying to exploiting above code example
#####################
...The attack section is not suitable for automated analysis and would need to be stripped or ignored. Language based solutions must also rename the noncompliantXX.py and strip all comments to avoid language based bias.
The compliantXX.py code examples are not suitable for automated analysis as they address only one issue, they do NOT supply end to end secure code!
Provided content is designed for self learning, the open source license invites anyone using it as part of their own teaching.
We welcome contributions in many forms—whether it’s fixing a bug or typo, improving the readability of the guide, adding a new code example, or creating entirely new pages to cover missing material. Before you start, please check for existing issues.
Become part of the reviewers for upcoming pull requests (PRs) by joining slack and our bi-weekly meetings.
Steps to join #secure-coding-guide-for-python slack channel as per Beginner to builder steps:
- Request access https://slack.openssf.org/
- in the search bar at the top:
/join secure-coding-guide-for-python
Become part of organizing bigger changes via our bi-weekly online meeting, see details in:
It is helpful to know:
- Why we do this, as explained in our mission statement.
- Our documentation style
- Code standards, Python and Markdown linters and such
- Folder, file layout and naming conventions
Please read and adhere to our Code of Conduct. We are committed to creating a welcoming and inclusive environment for all contributors.
- Bottom Line Up Front (BLUF), conclusion is in the first sentence of a rule
- Keep It Small and Simple (KISS)
- Working code examples
- Academic in wording whilst aiming for low word count.
- No fluff, "in software security it is important to be aware of ...."
- Use imperative "do x and y to ensure z" instead of vague wording "might want to, could be a good idea..."
- Rule titles are in Title Case (start uppercase unless its a conjunction; "to" or "for")
- Rule IDs are lowercase (pyscg-0040)
- Bibliography, follow the Harvard reference guide
A template for a rule is available here: README_TEMPLATE.md with inline documentation on each section.
The psycg guide structure starts below docs/Secure-Coding-Guide-for-Python with the its main readme.md showing the learning path in its main table.
Folder on this level represent a Section such as "Introduction" in 01_introduction.
The pyscg main readme.md is expected to contain:
- Section such as "01 Introduction"
- Rules in that section such as "pyscg-0040"
- Rule related base or class level CWE
- Rule related single representative CVE with CVSS and EPSS rating
- Automated detection
- Automated correction
The sublevel from a section, such as 01_introduction, has individual folders per rule such as pyscg-0040.
A section, such as 01_introduction, may contain a readme.md outlining knowledge that spans across all rules in that section.
Each rule folder, such as pyscg-0040, is expected to have:
- Only one
README.mdfile - At least one
noncompliant01.pydemonstrating an antipattern. - At least one
compliant01.pyproviding a reasonable solution. - Optional
example01.pyorexample01.shcode orimage01.png
A code example should be around 20 lines and only demonstrate countermeasures for the discussed issue. The writer can indicated requirements for a wider range of issues by leaving a comment # TODO: verify xyz.... Rules without working code examples might be required must be avoided.
Example structure with mocked up data below docs/Secure-Coding-Guide-for-Python/:
# pyscg main readme:
./readme.md
# license file copies:
./licenses/MIT.txt
./licenses/CC-BY-4.0.txt
# template folder:
./templates/compliant01.py
./templates/example01.py
./templates/noncompliant01.py
./templates/README_TEMPLATE.md
# section with its own readme.md, example01.py code and rule pyscg-0040 and pyscg-0041 below that:
./01_introduction/readme.md
./01_introduction/example01.py
./01_introduction/pyscg-0040/README.md
./01_introduction/pyscg-0040/example01.py
./01_introduction/pyscg-0040/noncompliant01.py
./01_introduction/pyscg-0040/compliant01.py
./01_introduction/pyscg-0041/README.md
./01_introduction/pyscg-0041/example01.py
./01_introduction/pyscg-0041/noncompliant01.py
./01_introduction/pyscg-0041/compliant01.py
Titles should:
- Be written in APA Title Case style [APA 2022]
- Be action-oriented
- Preferably describe wanted design over anti-pattern
Idealistically we have a noncompliantXX.py code matching in number the XX number of a compliantXX.py example with minimal changes between the two. The noncompliant and compliant code example's are also expected to contain the defensive code at the top while having the attacker code after the "#attempting to exploit" comment. Any code examples that do not qualify as compliant or noncompliant are named exampleXX.py.
To avoid running into linters or lighting up the programming IDE of others ensure to have the following installed:
Ruffwith enabledflake8-banditpluginGitHubMarkdownlinter such asmarkdownlint(this is enforced via GitHub action) *Pythontype hints.
Linter warnings should be kept to a minimum.
Keep code examples as short while using simple Python, it's not about showing off python programming skills and must be kept accessible to beginners.
There is the option to add # TODO: instead of overloading compliant code examples with all aspects of an end to end secure solution.
The guide follows a MAJOR.MINOR.PATCH scheme such as v1.0.0.
- MAJOR: structural changes that break automation consuming the guide (e.g. renamed columns in
readme.md, file naming convention changes, removal or merging of rules). - MINOR: content changes that preserve structure (new rules, title renames, updated code examples).
- PATCH: bugs, typo fixes, bibliography corrections, minor wording improvements.
The pyscg-XXXX rule IDs are intended as stable references within a released version. Re-use of pyscg-XXXX id's is therefore not permitted and withdrawn instead.
Any alpha or beta can have pyscg-XXXX ids, titles and chapter relations changed.
A withdrawn rule keeps its id forever (never reused) and is clearly marked as withdrawn.
See RELEASING.md for the release procedure and whatsnew/ for per-release change notes.
The main is the development branch for future releases and a released version gets its own release branch such as 1.x tagged as Latest and published as GitHub Release.
main ──●──●──●──●──●──●──▶ (v2 development)
(v1.0.0)
●─────●─────●──────▶ 1.x (maintenance branch)
│ │ │
v1.0.1 v1.0.2 v1.0.3 ← tags along the branch
Pre-release stages use CPython-style qualifiers appended to the version:
v1.1.0a1— alpha (seriala1,a2, ...), unstable, everything can changev1.1.0b1— beta (feature freeze), stabilize pyscg-id's, titles and parent section relationsv1.1.0rc1— release, only cosmetics, typo and code fixing remainv1.1.0— final release
Pre-release tags are published as GitHub Pre-release (not marked Latest).
- Fork the project into your own github space: cllick on the Fork option while viewing the top level of the project.
- Create a new branch: Use descriptive names for branches, e.g.,
issue-123oradd-logging-featureusinggit checkout -b branch-name - Make your changes: Commit your changes with clear and concise commit messages.
- Push your changes: Push your branch to your forked repository.
git push origin branch-name - Submit a pull request: Go to the original repository and click on "New Pull Request". Fill out the template provided, detailing your changes and their purpose.
A Pull Request is expected to have approval of at least 2 reviewers. One reviewer must be part of the core team for this Python project. The second can be anyone feeling bra1ve enough who has a GitHub account.
Once you submit a pull request:
- A project maintainer will review your submission.
- You may be asked to make revisions based on feedback.
- Once approved, your changes will be merged into the main branch.