Skip to content

Latest commit

 

History

History
243 lines (160 loc) · 11.3 KB

CONTRIBUTING.md

File metadata and controls

243 lines (160 loc) · 11.3 KB

Contributor Guide

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.

Mission Statement

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

Getting Started

  1. Fork the repository: Click the "Fork" button at the top of this page to create a copy of the repository under your GitHub account.

  2. 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
  3. Set up the development environment with a Python environment >= 3.9 and a Markdown reader.

Target Audience

Target audience are new designers, security researchers, machines and anyone teaching secure coding.

New designers

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.

Security Researchers

The overview table listing the most prominent CVEs allows to gain understanding of CVSS rating and blind spots in relation to EPSS frequency ratings.

Machines

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!

Teaching secure coding

Provided content is designed for self learning, the open source license invites anyone using it as part of their own teaching.

How to Contribute

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:

  1. Request access https://slack.openssf.org/
  2. 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

Code of Conduct

Please read and adhere to our Code of Conduct. We are committed to creating a welcoming and inclusive environment for all contributors.

Documentation Style

  • 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.

Structure Guide, from a reader perspective

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

Structure Guide, from a author perspective

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.md file
  • At least one noncompliant01.py demonstrating an antipattern.
  • At least one compliant01.py providing a reasonable solution.
  • Optional example01.py or example01.sh code or image01.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

Rule Titles

Titles should:

  • Be written in APA Title Case style [APA 2022]
  • Be action-oriented
  • Preferably describe wanted design over anti-pattern

Coding Examples

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:

  • Ruff with enabled flake8-bandit plugin
  • GitHub Markdown linter such as markdownlint (this is enforced via GitHub action) * Python type 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.

Versioning

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.

Rule ID Stability Contract

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.

Branch model

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

Release channels via tags

Pre-release stages use CPython-style qualifiers appended to the version:

  • v1.1.0a1 — alpha (serial a1, a2, ...), unstable, everything can change
  • v1.1.0b1 — beta (feature freeze), stabilize pyscg-id's, titles and parent section relations
  • v1.1.0rc1 — release, only cosmetics, typo and code fixing remain
  • v1.1.0 — final release

Pre-release tags are published as GitHub Pre-release (not marked Latest).

Submitting Your Contribution

  1. Fork the project into your own github space: cllick on the Fork option while viewing the top level of the project.
  2. Create a new branch: Use descriptive names for branches, e.g., issue-123 or add-logging-feature using git checkout -b branch-name
  3. Make your changes: Commit your changes with clear and concise commit messages.
  4. Push your changes: Push your branch to your forked repository. git push origin branch-name
  5. 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.

Review Process

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.