From ef5a56351c6275a16fd2c9f61084dd2a7f2230b5 Mon Sep 17 00:00:00 2001 From: Jakub Balhar Date: Wed, 23 Aug 2023 12:22:59 +0000 Subject: [PATCH 01/13] Add initial testing state. Signed-off-by: Jakub Balhar --- .../guidelines/coding-style.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) diff --git a/Technical-Steering-Committee/guidelines/coding-style.md b/Technical-Steering-Committee/guidelines/coding-style.md index b13fe091c..7f73dfe26 100644 --- a/Technical-Steering-Committee/guidelines/coding-style.md +++ b/Technical-Steering-Committee/guidelines/coding-style.md @@ -26,3 +26,82 @@ Each of the common languages in Zowe have code-documentation-generation tools, e - If you are writing in an area of the codebase that does not yet have a definition file for jsdoc, be sure to define a configuration file that can be used for future documentation of that code. - Java - [Javadoc](https://en.wikipedia.org/wiki/Javadoc) - C - [Doxygen](www.doxygen.org) + +## Quality Assurance + +### Testing (Self-audit) + +The usage of the automated tools outlined below was proposed among others by OpenSSF (Tools analysis), which is part of the Linux Foundation responsible for proposing the standards to be held in all the Open Source projects. + +There are two key types of tools: + +1) Static analysis - Going through the created artifacts such as the code and looking for potential risks +2) Dynamic analysis - Testing against the running applications what is the behavior for certain known and common vulnerabilities + +We already use tools for static as well as dynamic analysis. In some cases it’s done by one of the vendors who share the results with the community. + +#### Static analysis + +- Quality scanners (linters) - We use Java and JavaScript linters as a part of our daily work +- Security Code Scanners (Static Application Security Testing (SAST) Tools) - SonarCloud, CodeQL +- Secret Scanning Tools - GitHub does some work in the area +- Software Component Analysis (SCA)/Dependency Analysis tools - BlackDuck, LFX Security + +#### Dynamic analysis +- Traditional testing for security (Unit testing, Integration testing) + - Statement and branch coverage - Provided to us by Sonarcloud +- Fuzzers + - Explore https://github.com/google/oss-fuzz +- Web Application Scanner - AppScan + +### Pen Testing + +The current situation is that the companies are pen testing Zowe internally and share the results. This basically means that we are triplicating the effort. I believe we should be able to do this out in the open. + +To make sure that open means that only trusted actors will be involved and notified of the risks, I propose we keep the information within the security-reports repository and within the security workgroup. This should give us enough transparency without risking security for users. + +#### Internal testing + +##### Red Team Pen Testing + +This is a more complex issue as there are more ways to approach the topic. In general the name comes from either an internal or external team that acts as the adversary and tries to get access to the systems, steal the data, make the services inaccessible and so on. + +There is also a second team known as Blue team which tries to prevent the success of the red team. + +The GitLab explains how they use the red team in their security operations here: https://about.gitlab.com/handbook/engineering/security/security-operations/red-team/. Among others advocating the approach is the UK government (https://www.gov.uk/government/publications/a-guide-to-red-teaming and https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/1027158/20210625-Red_Teaming_Handbook.pdf). + +Keeping the whole red team would be quite expensive and complex in an open source environment and therefore what I recommend here is an one day exercise as a part of innovation week where Zowe splits to two teams. One trying to gain access to the system via Zowe and second trying to prevent this as well proving that such effort will be shown in the systems. + +If we find this exercise valuable, then we should figure out a way to do it regularly e.g. once a PI or at least once a year. + +#### External guarantees (External Audit) + +This section covers the actors without direct stake in the Zowe and that will help the community and the users trust the delivered solution. + +##### Bug Bounties + +The Bug Bounty is a concept where the external parties to the project gets money from uncovering vulnerabilities within the software and reporting them via the standard security process to the community. + +The aim is to persuade more white hat hackers to explore the code as there is tangible benefit for them to find and share the bugs. + +It’s used for example by Google. Here: https://bughunters.google.com/ you can learn more about the community that was built by Google for bug hunting. + +##### External Pen Testing Companies + +At the moment the major vendors involved within Zowe such as IBM, Rocket and Broadcom each conduct the penetration tests internally. The results are shared with the Security workgroup. + +The possibility here would be to pool the resources used to do the testing by the companies to either hire better companies or to change the scope and look for more potential issues. + +### Auditing + +This section covers how we audit that we actually follow the procedures outlined above. + +#### Internal Audit + +What can we automate to make us aware of some things not happening? + +Security workgroup going over the potentially risky actions across repositories storing the code. + +#### External security audit + +What can OMP do for us in this area? From 06122e73559a83afcd6c252c3944867e20f2eedc Mon Sep 17 00:00:00 2001 From: Jakub Balhar Date: Wed, 23 Aug 2023 12:43:09 +0000 Subject: [PATCH 02/13] Improve formatting. Signed-off-by: Jakub Balhar --- .../guidelines/coding-style.md | 21 ++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/Technical-Steering-Committee/guidelines/coding-style.md b/Technical-Steering-Committee/guidelines/coding-style.md index 7f73dfe26..1006e217b 100644 --- a/Technical-Steering-Committee/guidelines/coding-style.md +++ b/Technical-Steering-Committee/guidelines/coding-style.md @@ -36,19 +36,26 @@ The usage of the automated tools outlined below was proposed among others by Ope There are two key types of tools: 1) Static analysis - Going through the created artifacts such as the code and looking for potential risks -2) Dynamic analysis - Testing against the running applications what is the behavior for certain known and common vulnerabilities - -We already use tools for static as well as dynamic analysis. In some cases it’s done by one of the vendors who share the results with the community. +2) Dynamic analysis - Testing against the running applications what is the behavior for certain known and common vulnerabilities. The typical tests written by developers and executed on every run belong to this category. #### Static analysis -- Quality scanners (linters) - We use Java and JavaScript linters as a part of our daily work -- Security Code Scanners (Static Application Security Testing (SAST) Tools) - SonarCloud, CodeQL -- Secret Scanning Tools - GitHub does some work in the area -- Software Component Analysis (SCA)/Dependency Analysis tools - BlackDuck, LFX Security +- Quality scanners (linters) + - We use Java and JavaScript linters as a part of our daily work +- Security Code Scanners (Static Application Security Testing (SAST) Tools) + - SonarCloud + - CodeQL +- Secret Scanning Tools + - GitHub does some work in the area +- Software Component Analysis (SCA)/Dependency Analysis tools + - BlackDuck + - LFX Security #### Dynamic analysis - Traditional testing for security (Unit testing, Integration testing) + - Unit testing + - Functional testing + - System Testing - Integration and testing of the interaction between components. - Statement and branch coverage - Provided to us by Sonarcloud - Fuzzers - Explore https://github.com/google/oss-fuzz From 16b0bf605484606099fa645d346a5f43a7fa675f Mon Sep 17 00:00:00 2001 From: Jakub Balhar Date: Mon, 28 Aug 2023 14:00:43 +0000 Subject: [PATCH 03/13] Message management Quality Assurance - Focus on possible team work. Signed-off-by: Jakub Balhar --- .../best-practices/message-management.md | 25 ----- .../guidelines/coding-style.md | 97 ++++++++++++++----- 2 files changed, 71 insertions(+), 51 deletions(-) delete mode 100644 Technical-Steering-Committee/best-practices/message-management.md diff --git a/Technical-Steering-Committee/best-practices/message-management.md b/Technical-Steering-Committee/best-practices/message-management.md deleted file mode 100644 index 1b53514e0..000000000 --- a/Technical-Steering-Committee/best-practices/message-management.md +++ /dev/null @@ -1,25 +0,0 @@ -# Message Management - -### Message ID Components (message prefixes) -OMP -ZWE - -### Zowe Components -A - API Mediation Layer -C - Zowe CLI -D - Zowe Desktop -E - Zowe Explorer -S - Zowe System Services - -### Message Formats -ZWEcnnnnt where: - -**ZWE** - static for Zowe messages. - -**c** - one of the registered Components ... (see above). Components need the ZLC to approve the use of the component to ensure consistency across all of the projects. - -**nnnn** - is a linear sequence starting from 0001 to 9999. Projects may choose to use the first digit to divide the number space. ** - -**t** - is a Type. One of (I, E, A, W) General conventions by IBM are **I**nform, **E**ventual Action (often construed as error), **A**ction, **W**arning or **S**evere error - -Messages should be sent to the doc-team and follow the general IBM format as described in Messages and Codes. \ No newline at end of file diff --git a/Technical-Steering-Committee/guidelines/coding-style.md b/Technical-Steering-Committee/guidelines/coding-style.md index 1006e217b..a54d215c7 100644 --- a/Technical-Steering-Committee/guidelines/coding-style.md +++ b/Technical-Steering-Committee/guidelines/coding-style.md @@ -1,8 +1,6 @@ -# Coding style guidelines for Zowe sub-projects +# Coding style guidelines for Zowe projects -Zowe's codebase is split into a few key areas, with both unique and shared guidelines on how new code should be written. For each area of the codebase, there are established and favored languages for the code to be written in. Each repo in Github identifies the primary language used. - -These guidelines are meant to apply to all areas of the Zowe project. Each sub-project may adopt additional coding style guidelines specific to thier sub-project and the language(s) used. +Zowe is split into the projects. Each of the projects may have unique guidelines on how the code needs to be writen. This documents outlines the areas that are common across the whole Zowe codebase wherever applicable. ## Whitespaces @@ -27,31 +25,82 @@ Each of the common languages in Zowe have code-documentation-generation tools, e - Java - [Javadoc](https://en.wikipedia.org/wiki/Javadoc) - C - [Doxygen](www.doxygen.org) +## Message Management + +### Message ID Components (message prefixes) + +OMP +ZWE + +### Zowe Projects + +A - API Mediation Layer +C - Zowe CLI +D - Zowe Desktop +E - Zowe Explorer +S - Zowe System Services + +### Message Formats + +TODO: This doesn't represent the current state. +TODO: How do we reflect the WTO vs. the System.out. + +ZWEcnnnnt where: + +**ZWE** - static for Zowe messages. + +**c** - one of the registered Components ... (see above). Components need the ZLC to approve the use of the component to ensure consistency across all of the projects. + +**nnnn** - is a linear sequence starting from 0001 to 9999. Projects may choose to use the first digit to divide the number space. ** + +**t** - is a Type. One of (I, E, A, W) General conventions by IBM are **I**nform, **E**ventual Action (often construed as error), **A**ction, **W**arning or **S**evere error + +Messages should be sent to the doc-team and follow the general IBM format as described in Messages and Codes. + ## Quality Assurance +All new code added to the Zowe and it's projects needs to be of certain quality, at least before reaching GA status or above. The following guidelines explains what is expected from the projects that matured at least to GA. + ### Testing (Self-audit) -The usage of the automated tools outlined below was proposed among others by OpenSSF (Tools analysis), which is part of the Linux Foundation responsible for proposing the standards to be held in all the Open Source projects. +TODO: Is there any way to showcase how we follow the guidelines? -There are two key types of tools: +The first stage of the testing and in general of quality assurance lies with the developers developing the code. They are responsible for the quality of the code. There are tools helping them ensure high quality of the code and preventing unnecessary issues with the code. What are the tools that we expect the developers to work with and integrate to their pipelines. There are two wider categories of the tools: 1) Static analysis - Going through the created artifacts such as the code and looking for potential risks 2) Dynamic analysis - Testing against the running applications what is the behavior for certain known and common vulnerabilities. The typical tests written by developers and executed on every run belong to this category. #### Static analysis +The tools in this category goes through the code and/or artifacts as they are written and look for known problems and risks. Some of them are easy to integrate in a local workflow, some of them are better integrated via the workflow in Github Actions. These tools needs to be run at least on a per release basis and the output neds to be either cleansed or approved by either the squad or by security workgroup in case of security issues. + +- Compilers + - In case the language uses compilers, the first quality control is to fix all the warnings and above unless approved by the squad on the squad meeting. Every squad should keep list of the warnings approved by the squad. - Quality scanners (linters) - - We use Java and JavaScript linters as a part of our daily work + - Available for every language used in our code. + - Java - [checkstyle](https://checkstyle.org/) + - Javascript - [ESLint](https://eslint.org/) or JSLint (https://www.jslint.com/) + - Typescript - [typescript-eslint](https://typescript-eslint.io/) + - C - lint, gcc + - Kotlin - [KTLint](https://github.com/pinterest/ktlint) + - Python - [PyLint](https://pylint.org/) - Security Code Scanners (Static Application Security Testing (SAST) Tools) - - SonarCloud - - CodeQL + - [SonarCloud](https://sonarcloud.io/organizations/zowe/projects) - is also a quality tool. + TODO: What is the threshold over which we shouldn't release the projects? + - CodeQL - Tool integrated to the GitHub, the details aren't shown anywhere + TODO: Security needs to be fixed or agreed upon by Security Workgroup + TODO: Where and how the security workgroup keep this information. - Secret Scanning Tools - - GitHub does some work in the area + - TODO: GitHub does some work in the area - Software Component Analysis (SCA)/Dependency Analysis tools - - BlackDuck - - LFX Security + - BlackDuck + - The information are shared by one of the vendor running the tool. Overall this is imperfect solution. + - LFX Security - Work in progress as the current information keeps information from previous branches and as such doesn't represent the current situation. + +TODO: Where and how do I find the results? #### Dynamic analysis + - Traditional testing for security (Unit testing, Integration testing) - Unit testing - Functional testing @@ -61,7 +110,16 @@ There are two key types of tools: - Explore https://github.com/google/oss-fuzz - Web Application Scanner - AppScan -### Pen Testing +##### + +How do we improve our capability to catch the security related issues? +Is there any decent way to introduce the other companies into this? + +It would be great to be able to think more like and adversary. + +### Penetration Testing + +Probably another class of tests that focuses on the security The current situation is that the companies are pen testing Zowe internally and share the results. This basically means that we are triplicating the effort. I believe we should be able to do this out in the open. @@ -99,16 +157,3 @@ At the moment the major vendors involved within Zowe such as IBM, Rocket and Bro The possibility here would be to pool the resources used to do the testing by the companies to either hire better companies or to change the scope and look for more potential issues. -### Auditing - -This section covers how we audit that we actually follow the procedures outlined above. - -#### Internal Audit - -What can we automate to make us aware of some things not happening? - -Security workgroup going over the potentially risky actions across repositories storing the code. - -#### External security audit - -What can OMP do for us in this area? From 561ce3013211e29d9f18fb07e31b4da8112bc616 Mon Sep 17 00:00:00 2001 From: Jakub Balhar Date: Tue, 5 Sep 2023 14:36:50 +0000 Subject: [PATCH 04/13] Move copyright to the actual policy documentation Signed-off-by: Jakub Balhar --- .../{best-practices => }/license-copyright.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Technical-Steering-Committee/{best-practices => }/license-copyright.md (100%) diff --git a/Technical-Steering-Committee/best-practices/license-copyright.md b/Technical-Steering-Committee/license-copyright.md similarity index 100% rename from Technical-Steering-Committee/best-practices/license-copyright.md rename to Technical-Steering-Committee/license-copyright.md From f68368daf3c465bbba570a2cc1c3b68bea26c8bb Mon Sep 17 00:00:00 2001 From: Jakub Balhar Date: Tue, 5 Sep 2023 14:37:14 +0000 Subject: [PATCH 05/13] Remove outdated coding style Signed-off-by: Jakub Balhar --- .../guidelines/coding-style.md | 159 ------------------ 1 file changed, 159 deletions(-) delete mode 100644 Technical-Steering-Committee/guidelines/coding-style.md diff --git a/Technical-Steering-Committee/guidelines/coding-style.md b/Technical-Steering-Committee/guidelines/coding-style.md deleted file mode 100644 index a54d215c7..000000000 --- a/Technical-Steering-Committee/guidelines/coding-style.md +++ /dev/null @@ -1,159 +0,0 @@ -# Coding style guidelines for Zowe projects - -Zowe is split into the projects. Each of the projects may have unique guidelines on how the code needs to be writen. This documents outlines the areas that are common across the whole Zowe codebase wherever applicable. - -## Whitespaces - -Tabs should not be used for whitespace, instead being replaced with 2 spaces per tab. - -## Naming Conventions - -Function and Method Naming Self-documenting code reduces the need for extended code comments. It is encouraged to use names as long as necessary to describe what is occurring. Generally speaking, methods should be named as verbs (Think: get or set), while Objects/Classes should be nouns. Objects and functions should be CamelCase, while methods on Objects should be dromedaryCase Variable Naming Constants should be CAPITALIZED_AND_UNDERSCORED for clarity, while variables can remain dromedaryCase as methods are. Avoid non-descriptive variable names such as single letters (except for iteration in loops such as i or j) and variable names that have been arbitrarily shortened (Don't strip vowels, long variable names are OK) - -## Commenting - -Uncertainties, unimplemented but known future action items, and odd/specific constants should all be accompanied with a short comment to make others aware of the reasoning that went into the code. - -## Code documentation - -It's expected that all new code added comes with documentation. Documentation for component functionality should be included in the Zowe Docs, and documentation for individual classes and functions should be inline with the using the tools specific to that language. - -Each of the common languages in Zowe have code-documentation-generation tools, each with their own in-code comment style requirements to adhere to in order to generate nice, readable API references. Objects and functions of interest should be commented in accordance to the language-specific tools to result in output that serves as the first point of documentation for APIs. - -- Typescript - [JSDoc](http://usejsdoc.org/) - - If you are writing in an area of the codebase that does not yet have a definition file for jsdoc, be sure to define a configuration file that can be used for future documentation of that code. -- Java - [Javadoc](https://en.wikipedia.org/wiki/Javadoc) -- C - [Doxygen](www.doxygen.org) - -## Message Management - -### Message ID Components (message prefixes) - -OMP -ZWE - -### Zowe Projects - -A - API Mediation Layer -C - Zowe CLI -D - Zowe Desktop -E - Zowe Explorer -S - Zowe System Services - -### Message Formats - -TODO: This doesn't represent the current state. -TODO: How do we reflect the WTO vs. the System.out. - -ZWEcnnnnt where: - -**ZWE** - static for Zowe messages. - -**c** - one of the registered Components ... (see above). Components need the ZLC to approve the use of the component to ensure consistency across all of the projects. - -**nnnn** - is a linear sequence starting from 0001 to 9999. Projects may choose to use the first digit to divide the number space. ** - -**t** - is a Type. One of (I, E, A, W) General conventions by IBM are **I**nform, **E**ventual Action (often construed as error), **A**ction, **W**arning or **S**evere error - -Messages should be sent to the doc-team and follow the general IBM format as described in Messages and Codes. - -## Quality Assurance - -All new code added to the Zowe and it's projects needs to be of certain quality, at least before reaching GA status or above. The following guidelines explains what is expected from the projects that matured at least to GA. - -### Testing (Self-audit) - -TODO: Is there any way to showcase how we follow the guidelines? - -The first stage of the testing and in general of quality assurance lies with the developers developing the code. They are responsible for the quality of the code. There are tools helping them ensure high quality of the code and preventing unnecessary issues with the code. What are the tools that we expect the developers to work with and integrate to their pipelines. There are two wider categories of the tools: - -1) Static analysis - Going through the created artifacts such as the code and looking for potential risks -2) Dynamic analysis - Testing against the running applications what is the behavior for certain known and common vulnerabilities. The typical tests written by developers and executed on every run belong to this category. - -#### Static analysis - -The tools in this category goes through the code and/or artifacts as they are written and look for known problems and risks. Some of them are easy to integrate in a local workflow, some of them are better integrated via the workflow in Github Actions. These tools needs to be run at least on a per release basis and the output neds to be either cleansed or approved by either the squad or by security workgroup in case of security issues. - -- Compilers - - In case the language uses compilers, the first quality control is to fix all the warnings and above unless approved by the squad on the squad meeting. Every squad should keep list of the warnings approved by the squad. -- Quality scanners (linters) - - Available for every language used in our code. - - Java - [checkstyle](https://checkstyle.org/) - - Javascript - [ESLint](https://eslint.org/) or JSLint (https://www.jslint.com/) - - Typescript - [typescript-eslint](https://typescript-eslint.io/) - - C - lint, gcc - - Kotlin - [KTLint](https://github.com/pinterest/ktlint) - - Python - [PyLint](https://pylint.org/) -- Security Code Scanners (Static Application Security Testing (SAST) Tools) - - [SonarCloud](https://sonarcloud.io/organizations/zowe/projects) - is also a quality tool. - TODO: What is the threshold over which we shouldn't release the projects? - - CodeQL - Tool integrated to the GitHub, the details aren't shown anywhere - TODO: Security needs to be fixed or agreed upon by Security Workgroup - TODO: Where and how the security workgroup keep this information. -- Secret Scanning Tools - - TODO: GitHub does some work in the area -- Software Component Analysis (SCA)/Dependency Analysis tools - - BlackDuck - - The information are shared by one of the vendor running the tool. Overall this is imperfect solution. - - LFX Security - Work in progress as the current information keeps information from previous branches and as such doesn't represent the current situation. - -TODO: Where and how do I find the results? - -#### Dynamic analysis - -- Traditional testing for security (Unit testing, Integration testing) - - Unit testing - - Functional testing - - System Testing - Integration and testing of the interaction between components. - - Statement and branch coverage - Provided to us by Sonarcloud -- Fuzzers - - Explore https://github.com/google/oss-fuzz -- Web Application Scanner - AppScan - -##### - -How do we improve our capability to catch the security related issues? -Is there any decent way to introduce the other companies into this? - -It would be great to be able to think more like and adversary. - -### Penetration Testing - -Probably another class of tests that focuses on the security - -The current situation is that the companies are pen testing Zowe internally and share the results. This basically means that we are triplicating the effort. I believe we should be able to do this out in the open. - -To make sure that open means that only trusted actors will be involved and notified of the risks, I propose we keep the information within the security-reports repository and within the security workgroup. This should give us enough transparency without risking security for users. - -#### Internal testing - -##### Red Team Pen Testing - -This is a more complex issue as there are more ways to approach the topic. In general the name comes from either an internal or external team that acts as the adversary and tries to get access to the systems, steal the data, make the services inaccessible and so on. - -There is also a second team known as Blue team which tries to prevent the success of the red team. - -The GitLab explains how they use the red team in their security operations here: https://about.gitlab.com/handbook/engineering/security/security-operations/red-team/. Among others advocating the approach is the UK government (https://www.gov.uk/government/publications/a-guide-to-red-teaming and https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/1027158/20210625-Red_Teaming_Handbook.pdf). - -Keeping the whole red team would be quite expensive and complex in an open source environment and therefore what I recommend here is an one day exercise as a part of innovation week where Zowe splits to two teams. One trying to gain access to the system via Zowe and second trying to prevent this as well proving that such effort will be shown in the systems. - -If we find this exercise valuable, then we should figure out a way to do it regularly e.g. once a PI or at least once a year. - -#### External guarantees (External Audit) - -This section covers the actors without direct stake in the Zowe and that will help the community and the users trust the delivered solution. - -##### Bug Bounties - -The Bug Bounty is a concept where the external parties to the project gets money from uncovering vulnerabilities within the software and reporting them via the standard security process to the community. - -The aim is to persuade more white hat hackers to explore the code as there is tangible benefit for them to find and share the bugs. - -It’s used for example by Google. Here: https://bughunters.google.com/ you can learn more about the community that was built by Google for bug hunting. - -##### External Pen Testing Companies - -At the moment the major vendors involved within Zowe such as IBM, Rocket and Broadcom each conduct the penetration tests internally. The results are shared with the Security workgroup. - -The possibility here would be to pool the resources used to do the testing by the companies to either hire better companies or to change the scope and look for more potential issues. - From ef6b1f287eadceb6722d284f7f9c040ee6955836 Mon Sep 17 00:00:00 2001 From: Jakub Balhar Date: Tue, 5 Sep 2023 14:37:33 +0000 Subject: [PATCH 06/13] Move logging into policies Signed-off-by: Jakub Balhar --- Technical-Steering-Committee/logging.md | 31 +++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 Technical-Steering-Committee/logging.md diff --git a/Technical-Steering-Committee/logging.md b/Technical-Steering-Committee/logging.md new file mode 100644 index 000000000..7d28aee8e --- /dev/null +++ b/Technical-Steering-Committee/logging.md @@ -0,0 +1,31 @@ +## Message Management + +### Message ID Components (message prefixes) + +OMP +ZWE + +### Zowe Projects + +A - API Mediation Layer +C - Zowe CLI +D - Zowe Desktop +E - Zowe Explorer +S - Zowe System Services + +### Message Formats + +TODO: This doesn't represent the current state. +TODO: How do we reflect the WTO vs. the System.out. + +ZWEcnnnnt where: + +**ZWE** - static for Zowe messages. + +**c** - one of the registered Components ... (see above). Components need the ZLC to approve the use of the component to ensure consistency across all of the projects. + +**nnnn** - is a linear sequence starting from 0001 to 9999. Projects may choose to use the first digit to divide the number space. ** + +**t** - is a Type. One of (I, E, A, W) General conventions by IBM are **I**nform, **E**ventual Action (often construed as error), **A**ction, **W**arning or **S**evere error + +Messages should be sent to the doc-team and follow the general IBM format as described in Messages and Codes. \ No newline at end of file From e6a8c31a45f4cfad680f7fdfebb2e634a41500fc Mon Sep 17 00:00:00 2001 From: Jakub Balhar Date: Tue, 5 Sep 2023 14:37:57 +0000 Subject: [PATCH 07/13] Create new testing focused policy Signed-off-by: Jakub Balhar --- Technical-Steering-Committee/testing.md | 94 +++++++++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 Technical-Steering-Committee/testing.md diff --git a/Technical-Steering-Committee/testing.md b/Technical-Steering-Committee/testing.md new file mode 100644 index 000000000..c383ae412 --- /dev/null +++ b/Technical-Steering-Committee/testing.md @@ -0,0 +1,94 @@ +TODO: Is there any way to showcase how we follow the guidelines? + +The first stage of the testing and in general of quality assurance lies with the developers developing the code. They are responsible for the quality of the code. There are tools helping them ensure high quality of the code and preventing unnecessary issues with the code. What are the tools that we expect the developers to work with and integrate to their pipelines. There are two wider categories of the tools: + +1) Static analysis - Going through the created artifacts such as the code and looking for potential risks +2) Dynamic analysis - Testing against the running applications what is the behavior for certain known and common vulnerabilities. The typical tests written by developers and executed on every run belong to this category. + +#### Static analysis + +The tools in this category goes through the code and/or artifacts as they are written and look for known problems and risks. Some of them are easy to integrate in a local workflow, some of them are better integrated via the workflow in Github Actions. These tools needs to be run at least on a per release basis and the output neds to be either cleansed or approved by either the squad or by security workgroup in case of security issues. + +- Compilers + - In case the language uses compilers, the first quality control is to fix all the warnings and above unless approved by the squad on the squad meeting. Every squad should keep list of the warnings approved by the squad. +- Quality scanners (linters) + - Available for every language used in our code. + - Java - [checkstyle](https://checkstyle.org/) + - Javascript - [ESLint](https://eslint.org/) or JSLint (https://www.jslint.com/) + - Typescript - [typescript-eslint](https://typescript-eslint.io/) + - C - lint, gcc + - Kotlin - [KTLint](https://github.com/pinterest/ktlint) + - Python - [PyLint](https://pylint.org/) +- Security Code Scanners (Static Application Security Testing (SAST) Tools) + - [SonarCloud](https://sonarcloud.io/organizations/zowe/projects) - is also a quality tool. + TODO: What is the threshold over which we shouldn't release the projects? + - CodeQL - Tool integrated to the GitHub, the details aren't shown anywhere + TODO: Security needs to be fixed or agreed upon by Security Workgroup + TODO: Where and how the security workgroup keep this information. +- Secret Scanning Tools + - TODO: GitHub does some work in the area +- Software Component Analysis (SCA)/Dependency Analysis tools + - BlackDuck + - The information are shared by one of the vendor running the tool. Overall this is imperfect solution. + - LFX Security - Work in progress as the current information keeps information from previous branches and as such doesn't represent the current situation. + +TODO: Where and how do I find the results? + +#### Dynamic analysis + +- Traditional testing for security (Unit testing, Integration testing) + - Unit testing + - Functional testing + - System Testing - Integration and testing of the interaction between components. + - Statement and branch coverage - Provided to us by Sonarcloud +- Fuzzers + - Explore https://github.com/google/oss-fuzz +- Web Application Scanner - AppScan + +##### + +How do we improve our capability to catch the security related issues? +Is there any decent way to introduce the other companies into this? + +It would be great to be able to think more like and adversary. + +### Penetration Testing + +Probably another class of tests that focuses on the security + +The current situation is that the companies are pen testing Zowe internally and share the results. This basically means that we are triplicating the effort. I believe we should be able to do this out in the open. + +To make sure that open means that only trusted actors will be involved and notified of the risks, I propose we keep the information within the security-reports repository and within the security workgroup. This should give us enough transparency without risking security for users. + +#### Internal testing + +##### Red Team Pen Testing + +This is a more complex issue as there are more ways to approach the topic. In general the name comes from either an internal or external team that acts as the adversary and tries to get access to the systems, steal the data, make the services inaccessible and so on. + +There is also a second team known as Blue team which tries to prevent the success of the red team. + +The GitLab explains how they use the red team in their security operations here: https://about.gitlab.com/handbook/engineering/security/security-operations/red-team/. Among others advocating the approach is the UK government (https://www.gov.uk/government/publications/a-guide-to-red-teaming and https://assets.publishing.service.gov.uk/government/uploads/system/uploads/attachment_data/file/1027158/20210625-Red_Teaming_Handbook.pdf). + +Keeping the whole red team would be quite expensive and complex in an open source environment and therefore what I recommend here is an one day exercise as a part of innovation week where Zowe splits to two teams. One trying to gain access to the system via Zowe and second trying to prevent this as well proving that such effort will be shown in the systems. + +If we find this exercise valuable, then we should figure out a way to do it regularly e.g. once a PI or at least once a year. + +#### External guarantees (External Audit) + +This section covers the actors without direct stake in the Zowe and that will help the community and the users trust the delivered solution. + +##### Bug Bounties + +The Bug Bounty is a concept where the external parties to the project gets money from uncovering vulnerabilities within the software and reporting them via the standard security process to the community. + +The aim is to persuade more white hat hackers to explore the code as there is tangible benefit for them to find and share the bugs. + +It’s used for example by Google. Here: https://bughunters.google.com/ you can learn more about the community that was built by Google for bug hunting. + +##### External Pen Testing Companies + +At the moment the major vendors involved within Zowe such as IBM, Rocket and Broadcom each conduct the penetration tests internally. The results are shared with the Security workgroup. + +The possibility here would be to pool the resources used to do the testing by the companies to either hire better companies or to change the scope and look for more potential issues. + From a437f68bce083e4d3daf6572c19175dd4fecb29e Mon Sep 17 00:00:00 2001 From: Jakub Balhar Date: Wed, 20 Sep 2023 14:54:19 +0000 Subject: [PATCH 08/13] Update logging to reflect current state Signed-off-by: Jakub Balhar --- Technical-Steering-Committee/logging.md | 41 +++++++++++++++++-------- 1 file changed, 28 insertions(+), 13 deletions(-) diff --git a/Technical-Steering-Committee/logging.md b/Technical-Steering-Committee/logging.md index 7d28aee8e..8684d6c5a 100644 --- a/Technical-Steering-Committee/logging.md +++ b/Technical-Steering-Committee/logging.md @@ -1,31 +1,46 @@ -## Message Management +# Message Management + +## How do we log ### Message ID Components (message prefixes) -OMP -ZWE +OMP - Open Mainframe Project +ZWE - Zowe, This should be used as default for all Zowe messages. -### Zowe Projects +### Zowe server side Projects A - API Mediation Layer C - Zowe CLI -D - Zowe Desktop -E - Zowe Explorer +D - Zowe App Framework +E - Zowe VSCode Explorer +H - Zowe Chat +I - Zowe Intellij Explorer +J - Client Java SDK +K - Client Kotlin SDK +N - Client Node.js SDK +P - Client Python SDK S - Zowe System Services ### Message Formats -TODO: This doesn't represent the current state. -TODO: How do we reflect the WTO vs. the System.out. - -ZWEcnnnnt where: +ZWEcnnnnt or ZWEcsnnnt {Actual message} where: **ZWE** - static for Zowe messages. -**c** - one of the registered Components ... (see above). Components need the ZLC to approve the use of the component to ensure consistency across all of the projects. +**c** - one of the registered Components ... (see above). Components need the TSC to approve the use of the project letter to ensure consistency across all of the projects. -**nnnn** - is a linear sequence starting from 0001 to 9999. Projects may choose to use the first digit to divide the number space. ** +**s** - potentially a sub component within the component space. An example from API Mediation Layer would be G for Gateway + +**nnnn** - is a linear sequence starting from 0001 to 9999. **t** - is a Type. One of (I, E, A, W) General conventions by IBM are **I**nform, **E**ventual Action (often construed as error), **A**ction, **W**arning or **S**evere error -Messages should be sent to the doc-team and follow the general IBM format as described in Messages and Codes. \ No newline at end of file +Messages should be sent to the doc-team and follow the general IBM format as described in Messages and Codes. All the messages needs to have associated explanatory message in the Zowe docs. + +An example of a message is: *ZWEAG123E An error with z/OSMF authentication* + +## What do we log + +In the default configuration we should be logging only the errors and warnings. Errors should be problems that prevents usage of either whole Zowe or some part of Zowe. Warnings should represent potential problems that may have an impact on functionality but won't prevent usage. + +Apart from that all the components should log their startup and turndown when it happens as an Information. \ No newline at end of file From 1794476c0a88799047b6fccd02d0c28f32ae69fe Mon Sep 17 00:00:00 2001 From: Jakub Balhar Date: Wed, 27 Sep 2023 08:25:12 +0200 Subject: [PATCH 09/13] Update logging.md Signed-off-by: Jakub Balhar --- Technical-Steering-Committee/logging.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Technical-Steering-Committee/logging.md b/Technical-Steering-Committee/logging.md index 8684d6c5a..ba7742d69 100644 --- a/Technical-Steering-Committee/logging.md +++ b/Technical-Steering-Committee/logging.md @@ -7,7 +7,7 @@ OMP - Open Mainframe Project ZWE - Zowe, This should be used as default for all Zowe messages. -### Zowe server side Projects +### Zowe Projects A - API Mediation Layer C - Zowe CLI @@ -43,4 +43,4 @@ An example of a message is: *ZWEAG123E An error with z/OSMF authentication* In the default configuration we should be logging only the errors and warnings. Errors should be problems that prevents usage of either whole Zowe or some part of Zowe. Warnings should represent potential problems that may have an impact on functionality but won't prevent usage. -Apart from that all the components should log their startup and turndown when it happens as an Information. \ No newline at end of file +Apart from that all the components should log their startup and turndown when it happens as an Information. From 7ce1ea8ac078b748389d307d5549f02f69df796c Mon Sep 17 00:00:00 2001 From: Jakub Balhar Date: Wed, 15 Nov 2023 08:14:53 +0000 Subject: [PATCH 10/13] Add proposal for the X for extensions. Signed-off-by: Jakub Balhar --- Technical-Steering-Committee/logging.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/Technical-Steering-Committee/logging.md b/Technical-Steering-Committee/logging.md index ba7742d69..ec6246c4a 100644 --- a/Technical-Steering-Committee/logging.md +++ b/Technical-Steering-Committee/logging.md @@ -4,14 +4,21 @@ ### Message ID Components (message prefixes) -OMP - Open Mainframe Project ZWE - Zowe, This should be used as default for all Zowe messages. ### Zowe Projects +There are server and client side components that are logging separately as such we may have duplication of logging for Server side and Client side. + +#### Server Side + A - API Mediation Layer -C - Zowe CLI D - Zowe App Framework +S - Zowe System Services + +#### Client Side + +C - Zowe CLI E - Zowe VSCode Explorer H - Zowe Chat I - Zowe Intellij Explorer @@ -19,17 +26,20 @@ J - Client Java SDK K - Client Kotlin SDK N - Client Node.js SDK P - Client Python SDK -S - Zowe System Services ### Message Formats -ZWEcnnnnt or ZWEcsnnnt {Actual message} where: +ZWEcnnnnt, ZWEcsnnnt or ZWEcsxnnt {Actual message} where: **ZWE** - static for Zowe messages. **c** - one of the registered Components ... (see above). Components need the TSC to approve the use of the project letter to ensure consistency across all of the projects. -**s** - potentially a sub component within the component space. An example from API Mediation Layer would be G for Gateway +**s** - potentially a sub component within the component space. An example from API Mediation Layer would be G for Gateway. + +**x** - potentially a space for extensions. For the extensions the expectation is that there will be X as sub component. An example would be ZWEDXA11E + +**nnn** - is a linear sequence starting from 001 to 999. **nnnn** - is a linear sequence starting from 0001 to 9999. From 4ec09d3a36d75f9bfe3fb4f3d8b22466a822789c Mon Sep 17 00:00:00 2001 From: Jakub Balhar Date: Wed, 15 Nov 2023 08:15:39 +0000 Subject: [PATCH 11/13] Add explanation Signed-off-by: Jakub Balhar --- Technical-Steering-Committee/guidelines/README.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 Technical-Steering-Committee/guidelines/README.md diff --git a/Technical-Steering-Committee/guidelines/README.md b/Technical-Steering-Committee/guidelines/README.md new file mode 100644 index 000000000..2a2dddb80 --- /dev/null +++ b/Technical-Steering-Committee/guidelines/README.md @@ -0,0 +1,3 @@ +# Guidelines + +The files in this repository represents recommendation and guidelines not a strict policies that the squads has to follow. \ No newline at end of file From ba14f898075e22bee26581c91109f7016e85bdb1 Mon Sep 17 00:00:00 2001 From: Jakub Balhar Date: Wed, 15 Nov 2023 08:16:04 +0000 Subject: [PATCH 12/13] Change wording to represent the actual wording Signed-off-by: Jakub Balhar --- .../guidelines/branching-strategy.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Technical-Steering-Committee/guidelines/branching-strategy.md b/Technical-Steering-Committee/guidelines/branching-strategy.md index fad1bdb0a..afee0c907 100644 --- a/Technical-Steering-Committee/guidelines/branching-strategy.md +++ b/Technical-Steering-Committee/guidelines/branching-strategy.md @@ -1,6 +1,6 @@ # Branches Guideline -This documentation introduces guideline for using branches in Zowe project, including all component projects. We try to keep consistent and apply the same branching model to all source code repositories. Subproject may use a different branch model to better suit its needs, but it should be properly documented. For example, Zowe CLI used a different [Versioning](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md) to better work with NPM package tags. +This documentation introduces guideline for using branches in Zowe project, including all sub-projects. We try to keep consistent and apply the same branching model to all source code repositories. Subproject may use a different branch model to better suit its needs, but it should be properly documented. For example, Zowe CLI used a different [Versioning](https://github.com/zowe/zowe-cli/blob/master/docs/MaintainerVersioning.md) to better work with NPM package tags. Zowe project follows [Semantic Versioning](https://semver.org). So all versions mentioned in this documentation follows `[major].[minor].[patch]` version pattern. @@ -12,7 +12,7 @@ Zowe project follows [Semantic Versioning](https://semver.org). So all versions Branches listed below are mandatory and should exist all the time. These branches should be **protected** from updating. So any changes go into these branches should be through **Pull Request** and reviewed by other committers. - * **master** - this is the main release branch. It contains the most recent stable formal release. The release tag is created on this branch. If the component has dependencies, only static version of dependent artifacts should be listed. For example, a dependency on another sub-project version `~5.2.0` (which means latest patch release of `5.2.*`) is not acceptable. This _master_ branch should not be merged back into _staging_ branch. In certain circumstances, we will _cherry-pick_ hot fixes back into _staging_ branch. + * **main** - this is the main release branch. It contains the most recent stable formal release. The release tag is created on this branch. If the component has dependencies, only static version of dependent artifacts should be listed. For example, a dependency on another sub-project version `~5.2.0` (which means latest patch release of `5.2.*`) is not acceptable. This _master_ branch should not be merged back into _staging_ branch. In certain circumstances, we will _cherry-pick_ hot fixes back into _staging_ branch. * **staging** - this is the main development thread. It contains the most recent code for **next** (the coming) release. If the component has dependencies, dynamic patch-level version of dependent artifacts is recommended and acceptable. For example, `~5.2.0` is acceptable because it means `5.2.*`. But `^5.2.0` is not acceptable because it means `5.*`. This branch will be merged into _master_ branch during release process. - Optional Ephemeral Branches @@ -38,7 +38,7 @@ With an example of main thread are ready for v2.x release, then v1.x became LTS - Long-Lived Branches - * **v1.x/master** - branched out from _master_ branch. + * **v1.x/main** - branched out from _main_ branch. * **v1.x/staging** - branched out from _staging_ branch. - Optional Ephemeral Branches From d905744dcc09d61b1d08eb9b21349fab10800533 Mon Sep 17 00:00:00 2001 From: Jakub Balhar Date: Mon, 11 Dec 2023 11:55:33 +0000 Subject: [PATCH 13/13] Add the first draft for the support policy Signed-off-by: Jakub Balhar --- Technical-Steering-Committee/support.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 Technical-Steering-Committee/support.md diff --git a/Technical-Steering-Committee/support.md b/Technical-Steering-Committee/support.md new file mode 100644 index 000000000..550be7ba1 --- /dev/null +++ b/Technical-Steering-Committee/support.md @@ -0,0 +1,14 @@ +# Zowe Community statement on Support + +Zowe is an Open Source project that's being driven by the community. As such any effort provided by the community in on best-effort basis. +If you need a support with SLA's please consult our list of [Conformant Support Providers](https://openmainframeproject.org/our-projects/zowe-conformant-support-provider-program/) + +## Validating pre-requisities + +The Zowe community has access only to limited set of hardware. This limits our capacity to run automated test suites. We keep the list of the pre-requisites that +Zowe is tested on in [Zowe docs](https://github.com/zowe/docs-site/blob/tsc/support/matrix/docs/user-guide/systemrequirements-zos.md) + +## Out of support prerequisites + +For the pre-requisites that end their support Zowe doesn't guarantee any support for running. E.g. Zowe doesn't have to support z/OS 2.2 as it's already out of support. +As such changes that break support for such version aren't considered as breaking change. \ No newline at end of file