From 908beddeaa6d27159bf1d6f04e6227936ed9f49a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicklas=20K=C3=B6rtge?= Date: Wed, 12 Jun 2024 14:52:45 +0200 Subject: [PATCH] Update documentation (#15) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * add code of conduct Signed-off-by: Nicklas Körtge * add contribution, remove development Signed-off-by: Nicklas Körtge * add codeowners Signed-off-by: Nicklas Körtge * fix python library name --------- Signed-off-by: Nicklas Körtge Co-authored-by: Hugo Queinnec --- CODEOWNERS | 3 ++ CODE_OF_CONDUCT.md | 101 +++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 59 ++++++++++++++++++++++++++ DEVELOPMENT.md | 71 ------------------------------- README.md | 54 ++++++++++++++---------- 5 files changed, 196 insertions(+), 92 deletions(-) create mode 100644 CODEOWNERS create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md delete mode 100644 DEVELOPMENT.md diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 00000000..763d9951 --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,3 @@ +# see https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners + +* @n1ckl0sk0rtge @hugoqnc \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..b908ceb8 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,101 @@ +# Code of Conduct + +## Our Pledge + +The Community is dedicated to our values of treating every individual +with respect and dignity. In the interest of fostering an open and welcoming +environment, all participants, including attendees, speakers, sponsors, +volunteers, online contributors, and IBM employees are expected to show +courtesy for each other and our community by creating a harassment-free +experience for everyone, regardless of age, personal appearance, disability, +ethnicity, gender identity and expression, body size, level of experience, +nationality, race, religion, caste, or sexual identity and orientation. +Expected behavior applies to both online and offline engagement within the community. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints, experiences, and cultures +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members +- Being mindful of your surroundings and your fellow participants and listening + to others +- Valuing the contributions of all participants +- Engaging in collaboration before conflict +- Pointing out unintentionally racist, sexist, casteist, or biased comments and + jokes made by community members when they happen + +Examples of unacceptable behavior by participants, even when presented as +"ironic" or "joking," include: + +- The use of sexualized language or imagery and unwelcome physical contact, + sexual attention, or advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment, including offensive or degrading language +- Publishing others' private information, such as a physical or electronic + address, without explicit permission. This includes any sort of "outing" of + any aspect of someone's identity without their consent. +- "Doxxing," Publishing screenshots or quotes, especially from identity slack + channels, private chat, or public events, without all quoted users' explicit + consent. +- Engaging in spamming activities, such as repeatedly sending unsolicited messages, + LLMs (Large Language Models) output, advertisements, or promotional content to + community members without previous IBM authorization. +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +The entire community is responsible for upholding the terms of the Code +of Conduct in events and spaces and reporting violations if +they see them. The internal team at IBM is ultimately responsible for +clarifying the standards of acceptable behavior and enforcement, and is expected +to take appropriate and fair corrective action in response to any instances of +unacceptable behavior. + +If a participant or contributor engages in negative or harmful behavior, IBM +will take any action they deem appropriate, including but not limited to +issuing warnings, expulsion from an event with no refund, deleting comments, +permanent banning from future events or online community, or calling local law +enforcement. IBM has the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, or to temporarily or permanently ban any +contributor or participant for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public +spaces when an individual is representing the project or its community. +Examples of representing a project or community include using an official +project e-mail address, posting via an official social media account, +or acting as an appointed representative at an online or offline event. +Representation of a project may be further defined and clarified +by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at nicklas.koertge1@ibm.com. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +This Code of Conduct does not supersede existing IBM corporate policies, such as +the IBM Business Conduct Guidelines and IBM Business Partner Code of Conduct. +IBM employees must follow IBM's Business Conduct Guidelines. IBM's business +partners must follow the IBM Business Partner Code of Conduct. IBM employees +concerned with a fellow IBMer's behavior should follow IBM's own internal HR +reporting protocols, which include engaging the offending IBMer's manager and +involving IBM Concerns and Appeals. IBM employees concerned with an IBM +business partner's behavior should notify tellibm@us.ibm.com. + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..87f1f799 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,59 @@ +# Contributing + +The Sonar Cryptography Plugin is an open source project that aims to create +an easy way to discover the use of cryptography in source code and create CBOM. +This page describes how you can join the community in this goal. + +## Before you start + +If you are new to the community? We recommend you do the following before diving into the code: + +* Read the [Code of Conduct](https://github.com/IBM/sonar-cryptography/blob/main/CODE_OF_CONDUCT.md) +* Familiarize yourself with the community (via [GitHub](https://github.com/IBM/sonar-cryptography/discussions) etc.) + +## Choose an issue to work on +Qiskit uses the following labels to help non-maintainers find issues best suited to their interest and experience level: + +* [good first issue](https://github.com/IBM/sonar-cryptography/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) - these issues are typically the simplest available to work on, ideal for newcomers. They should already be fully scoped, with a clear approach outlined in the descriptions. +* [help wanted](https://github.com/IBM/sonar-cryptography/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) - these issues are generally more complex than good first issues. They typically cover work that core maintainers don't currently have capacity to implement and may require more investigation/discussion. These are a great option for experienced contributors looking for something a bit more challenging. + +## Code Style + +Check if all java files are well formated and license headers are in place. +```shell +mvn spotless:check +``` +Applies format and license headers to files. +```shell +mvn spotless:apply +``` +Spotless Maven Documentation: https://github.com/diffplug/spotless/blob/main/plugin-maven/README.md + +Check for coding style +```shell +mvn checkstyle::check +``` + +## Build + +In the project directory run the following command: +```shell +mvn clean package +``` +The `.jar` file will be stored in the target directory and also copied to +`.SonarQube/plugins`. + + +## Run the Plugin with SonarQube + +```shell +UID=${UID} GID=${GID} docker-compose up +``` + +### Configure SonarQube + +For the initial configuration and setup have a look to the [official SonarQube documentation](https://docs.sonarqube.org/latest/try-out-sonarqube/). + +### Create a Quality Profile with Crypto Rules + +See detailed instructions in the root [README.md](./README.md#create-a-quality-profile-with-crypto-rules) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md deleted file mode 100644 index b41d9ac7..00000000 --- a/DEVELOPMENT.md +++ /dev/null @@ -1,71 +0,0 @@ -# Development - -## Code Style - -### Format - -Check if all java files are well formated and license headers are in place. -```shell -mvn spotless:check -``` -Applies format and license headers to files. -```shell -mvn spotless:apply -``` - -Spotless Maven Documentation: https://github.com/diffplug/spotless/blob/main/plugin-maven/README.md - -### Coding - -Check for coding style -```shell -mvn checkstyle::check -``` - -## Build - -### Build the Plugin - -In the project directory run the following command: -```shell -mvn clean package -``` -The `.jar` file will be stored in the target directory and also copied to -`.SonarQube/plugins`. - -## Deploy - -### Set a new version - -```shell -mvn versions:set -DnewVersion=1.0.0-SNAPSHOT -``` -If you made a mistake, do - -```shell -mvn versions:revert -``` - -afterwards, or - -```shell -mvn versions:commit -``` - -if you're happy with the results. - -## Run the Plugin with SonarQube - -### Run SonarQube with Docker Compose - -```shell -UID=${UID} GID=${GID} docker-compose up -``` - -### Configure SonarQube - -For the initial configuration and setup have a look to the [official SonarQube documentation](https://docs.sonarqube.org/latest/try-out-sonarqube/). - -### Create a Quality Profile with Crypto Rules - -See detailed instructions in the root [README.md](./README.md#create-a-quality-profile-with-crypto-rules) diff --git a/README.md b/README.md index 30f035d3..2876a398 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,44 @@ # Sonar Cryptography Plugin +[![License](https://img.shields.io/github/license/IBM/sonar-cryptography.svg?)](https://opensource.org/licenses/Apache-2.0) +[![Current Release](https://img.shields.io/github/release/IBM/sonar-cryptography.svg?logo=IBM)](https://github.com/IBM/sonar-cryptography/releases) + + This repository contains a SonarQube Plugin that detects cryptographic assets -in source code and generates CBOM. +in source code and generates [CBOM](https://cyclonedx.org/capabilities/cbom/). -## Plugin version compatibility +## Version compatibility | Plugin Version | SonarQube Version | -| -------------- | -------------------- | +|----------------|----------------------| | 1.x.x and up | SonarQube 9.8 and up | -## Latest supported languages and libraries +## Supported languages and libraries -| Language | Cryptographic Library | Coverage | -| -------- | --------------------- | -------- | -| Java | JCA | 100% | -| | BouncyCastle | 80% | -| Pyrhon | pycrypto | 100% | +| Language | Cryptographic Library | Coverage | +|----------|-----------------------------------------------------------------------------------------------|----------| +| Java | [JCA](https://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/CryptoSpec.html) | 100% | +| | [BouncyCastle](https://github.com/bcgit/bc-java) | 80% | +| Python | [pyca/cryptography](https://cryptography.io/en/latest/) | 100% | > The plugin is designed so that it can be extended to support additional languages and recognition rules to support more libraries. Detailed instructions on how to add new languages and recognition rules will follow shortly. -## Development and Contribution - -See [development setup](DEVELOPMENT.md). - ## Installation -Copy the plugins (jar files) to $SONAR_INSTALL_DIR/extensions/plugins and restart +Copy the plugins (jar files) to `$SONARQUBE_HOME/extensions/plugins` and restart SonarQube ([more](https://docs.sonarqube.org/latest/setup-and-upgrade/install-a-plugin/)). ## Using -Each plugin provides new rules (IBM Cryptography Repository) related to the use of cryptography in Java or Python source code. -By enabling these rules, a source code scan will check the code for these rules and mark a new security -hotspot in case of violation. -In addition, a source code scan generates a CBOM with all cryptographic results and writes a `cbom.json` to -the scan directory. +The plugin provides new inventory rules (IBM Cryptography Repository) regarding the use of cryptography for +the supported languages. +If you enable these rules, a source code scan creates a cryptographic inventory by creating a +[CBOM](https://cyclonedx.org/capabilities/cbom/) with all cryptographic assets and writing +a `cbom.json` to the scan directory. -### Create a Quality Profile with Crypto Rules +### Create a Quality Profile with Cryptographic Rules -The crypto rules added by the plugin are not per default activated. Create a new quality profile for Java or Python. +The crypto rules added by the plugin are not per default activated. Create a new quality profile for a specific language. ![Quality Profile with Crypto Rules](.github/img/quality_profile.png) @@ -58,6 +58,18 @@ activated crypto rules. Now you can follow the [SonarQube documentation](https://docs.sonarqube.org/latest/analyzing-source-code/overview/) to start your first scan. +## Contribution Guidelines + +If you'd like to contribute to Sonar Cryptography Plugin, please take a look at our +[contribution guidelines](CONTRIBUTING.md). By participating, you are expected to uphold our [code of conduct](CODE_OF_CONDUCT.md). + +We use [GitHub issues](https://github.com/IBM/sonar-cryptography/issues) for tracking requests and bugs. For questions +start a discussion using [GitHub Discussions](https://github.com/IBM/sonar-cryptography/discussions). + +## License + +[Apache License 2.0](LICENSE.txt) +