pySCG: avoid mixup with MITRE CWE numbers+title and consider using chapters to organize content

[myteron]

There is a risk that we confuse the reader due to using the exact same ID + TITLE as MITRE and we need to organize the rules into subjects to allow a continues reading experience (merged from #849 )

We like to keep :

• If possible avoid breaking links
• Avoid the need for scraping.
• Keep a overview of direct relations between pySCG and CWE
• The choice must allow staying under CC.

Renaming title's could be beneficial to pySCG as it allows to use more documentation friendly "Do's" rather than "Dont's".

Issue description

We basically face two issues that overlap, CWE mixup and adding chapters.

Main issue 1 CWE mixup

We must make clear that pySCG is not MITRE. Using the same ID+TITLE format also causes issues when referencing between different pySCG rules. We also avoid confusion when mixing links between MITRE Pillars and pySCG on the main readme.md file.

Example sections/chapters:

For example a reading:
CWE-390: Detection of Error Condition without Action

Allow exceptions to bubble up and handle exceptions at the right level in the stack.
Each except block must ensure that the program continues only with formally specified behavior by either:
.....

vs reading
CWE-390: Detection of Error Condition Without Action

The product detects a specific error, but takes no actions to handle the error.

Secondary issue 2. organize content into chapters

Subjects are partially in random order is confusion and also leading to partial duplicated content per rule. A useful set of chapters/sections that allows grouping needs to be found as done for the Introduction to Multithreading and Multiprocessing in Python

• Input validation
• Numbers and precision
• Any ctypes related stuff

Options:

Listed option's range from super cheaply replacing "CWE" with "pySCG" in option C to coming up with our own structure and title in option D. Given options can also be mixed. Main aim of listing options is to discover in what directly each core contributor prefers to go.

For instance we could mixup option 'C' and 'D" by remove pillar folders, all prefixes from folder titles, use our own "pySCG" while also organizing a flat assembly of folders with CWE numbering into chapters using the same approach we have for Introduction to Multithreading and Multiprocessing in Python.
We can also document related guidelines in a json or yaml file per rule to make it machine readable.

A) Move CWE IDs to main table

• CWE ID is removed from rule titles
• CWE ID is quoted in the "Related Guidelines" section.
• CWE ID added to overview table's linking to all rules readme.md.
• Renaming of titles is optional
• Folder structure remains as is.

Example CWE-390: Detection of Error Condition without Action would become Detection of Error Condition without Action.

Example row of main readme.md with links to all rules:
Add a CWE column to the main example

MITRE	Python Secure Coding	Prominent CVE
CWE-703	Improper Check or Handling of Exceptional Conditions
CWE-390	Detection of Error Condition without Action

B ) Same as A but also change all titles from "dont's" to "do's"

• CWE ID is removed from rule titles
• CWE ID is quoted in the "Related Guidelines" section.
• CWE ID added to overview table's linking to all rules readme.md.
• Renaming all titles
• Folder structure remains as is.

Example CWE-390: Detection of Error Condition without Action would become Allow exceptions to bubble up and handle exceptions at the right level in the stack..

C only replace prefix from "CWE" to "pySCG" like pySCG-390)

Replace MITRE CWE prefix with pySCG, remove prefix from folders, quote CWE in main readme as in option A

• CWE prefix is replaced to pySCG from rule titles and all links
• Renaming is optional
• Folder gets its prefix removed so that only the number remains.
• Consider removing the pillar as main folders to flatten out the structure.

Example CWE-390: Detection of Error Condition without Action would become pySCG-: Detection of Error Condition without Action
Its folder would have to change from CWE-703/CWE-390 to pySCG-703/pySCG-390.

D come up with a custom prefix, numbering, titles and structure)

• Custom prefix and numbering into 'chapters'
• All rules renamed to "Do's"
• Custom folder structure

Example CWE-390 would be under a chapter "Error handling" with a title "Allow exceptions to bubble up and handle exceptions at the right level in the stack." with the ID like pyEH.390

[stevechristeycoley]

Hello,

I'm posting in my role as CWE Technical Lead with comments related to the "CWE Mixup" question, after brief consultation with other CWE leads, including project lead Alec Summers. Thank you for reaching out to us!

To help frame this discussion, here are a couple observations:

• since around 2010, it's been our experience in CWE that there isn't a one-to-one relationship between secure coding rules/guidelines and individual CWE entries. A single rule might eliminate or at least mitigate multiple weaknesses at the same time; and alternately, a single CWE might not be fully addressed without following multiple rules/guidelines.
• past secure-coding efforts including CERT Secure Programming Rules, MISRA, OWASP ASVS, etc. focus more on the positive practices for developers to follow, since developers are their primary audience.
• as covered in the main body of this issue, we believe that there is a risk of confusion between MITRE CWE and pySCG rules/guidelines.

With this perspective, here are some brief comments on the proposed alternatives:

• A) Move CWE IDs to main table seems OK by disassociating CWE IDs directly from their names, but it's not ideal
• B) ... change all titles from "dont's" to "do's" is consistent with past secure-coding practices, and to me, is preferable
• C) only replace prefix from "CWE" to "pySCG" like pySCG-390 would address the issue of potential confusion with CWE, but it wouldn't address the disconnect that there is not a one-to-one relationship between "secure coding" and CWEs as outlined above
• D) come up with a custom prefix, numbering, titles and structure is always an option, though not necessarily the easiest one :)

I hope this helps, and we're glad to provide any additional feedback on request.

[myteron]

Hi @stevechristeycoley ,

Thank you very much for your feedback. Changing the titles to "do's" is probably for the best. Disconnecting from MITRE numbers will require a full restructuring as outlined in option D).

Our plan is to address the "CWE mixup" issue prior to the official release. Before the restructuring and release, we would like to add the remaining 13 rules into GitHub as part of #531, but this might take a few more months.

Please let us know if there are any concerns from the CWE leads regarding this timeline.