diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e29788e8b..cc236ee6a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,91 +1,175 @@ -# Contributing +# **Contributing Guide** -When contributing to this repository, please first discuss the change you wish to make via issue, -email, or any other method with the owners of this repository before making a change. +This is Horusec contributing guide. Please read the following sections to learn how to ask questions and how to work on something. -Please note we have a code of conduct, please follow it in all your interactions with the project. +## **Table of contents** +### 1. [**Before you contribute**](#before-you-contribute) +> #### 1.1. [**Code of Conduct**](#code-of-conduct) +> #### 1.2. [**Legal**](#legal) +### 2. [**Prerequisites**](#prerequisites) +> #### 2.1. [**Developer Certificate of Origin**](#developer-certificate-of-origin---dco) +> #### 2.2. [**Code Review**](#code-review) +> #### 2.3. [**Pull Requests**](#pull-requests) +### 3. [**How to contribute?**](#how-to-contribute) + > #### 3.1. [**Prepare your development environment**](#prepare-your-development-environment) +> #### 3.2. [**First contribution**](#first-contribution) +> #### 3.3. [**Add new feature, bug fixing or improvement**](#add-new-feature-bug-fixing-or-improvement) +> #### 3.4. [**Pull Request's approval**](#pull-requests-approval) +> #### 3.5. [**After your pull request's approval**](#after-your-pull-requests-approval) +### 4. [**Community**](#community) -## Pull Request Process +## **Before you contribute** -1. Ensure any install or build dependencies are removed before the end of the layer when doing a - build. -2. Update the README.md with details of changes to the interface, this includes new environment - variables, exposed ports, useful file locations and container parameters. -3. Everyone must commit to complying with the DCO rules. It will need to be [signed-off](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt--s) and [verified](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification/about-commit-signature-verification). Example: ` git commit -s --amend`. -4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you - do not have permission to do that, you may request the second reviewer to merge it for you. +### **Code of Conduct** +Please follow the [**Code of Conduct**](https://github.com/ZupIT/horusec/blob/main/CODE_OF_CONDUCT.md) in all your interactions with our project. -## Code of Conduct +### **Legal** +- Horusec is licensed over [**ASF - Apache License**](https://github.com/ZupIT/horusec/blob/main/LICENSE), version 2, so new files must have the ASF version 2 header. For more information, please check out [**Apache license**](https://www.apache.org/licenses/LICENSE-2.0). -### Our Pledge +- All contributions are subject to the [**Developer Certificate of Origin (DCO)**](https://developercertificate.org). +When you commit, use the ```**-s** ``` option to include the Signed-off-by line at the end of the commit log message. -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. +## **Prerequisites** +Check out the requisites before contributing to Horusec: -### Our Standards +### **Developer Certificate of Origin - DCO** -Examples of behavior that contributes to creating a positive environment -include: + This is a security layer for the project and for the developers. It is mandatory. + + Follow one of these two methods to add DCO to your commits: + +**1. Command line** + Follow the steps: + **Step 1:** Configure your local git environment adding the same name and e-mail configured at your GitHub account. It helps to sign commits manually during reviews and suggestions. -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members + ``` +git config --global user.name “Name” +git config --global user.email “email@domain.com.br” +``` +**Step 2:** Add the Signed-off-by line with the `'-s'` flag in the git commit command: -Examples of unacceptable behavior by participants include: +``` +$ git commit -s -m "This is my commit message" +``` +**2. GitHub website** -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting +You can also manually sign your commits during GitHub reviews and suggestions, follow the steps below: -### Our Responsibilities +**Step 1:** When the commit changes box opens, manually type or paste your signature in the comment box, see the example: -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. +``` +Signed-off-by: Name < e-mail address > +``` -Project maintainers have 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 ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. +For this method, your name and e-mail must be the same registered on your GitHub account. -### Scope +### **Code Review** +- All your submissions needs a review. -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. +### **Pull Requests** +When you open a Pull Request, follow the requirements below: -### Enforcement +1. Add a title with the following pattern: -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at "channel will be created and inserted here". 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. +#### **[PKG][TYPE]: Description** -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. +#### **PKG:** Name of the package or main service you want to change. -### Attribution +#### **TYPE**: Add what your Pull Request (PR) refers to: +- **FEATURE:** PR refers to a new activity. +- **BUGFIX:** PR refers to corrections for the next release. +- **HOTFIX:** PR refers to corrections where you will need a cherry-pick and the update of the minor version. +- **CHORE:** PR refers to changes for the next release, but it was only maintenance without an activity impact. -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] +**Example:** **[start][bugfix]: Fix bug when Horusec haven't read the new flag of authorization** -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ + +2. Answer the questions about what you did, how to verify it and a short description for the changelog, see an example below: + +

architecture

+ + +## **How to contribute?** +See the guidelines to submit your changes: + +### **Prepare your development environment** +To start contributing with Horusec, you need to install [**Go**](https://golang.org/dl/). The minimal version required to build is 1.17. +[**GNU Make**](https://www.gnu.org/software/make/) is also required to development. + +After installing Go you can build using `make build-dev`. + + +#### **Testing** +Horusec has a suite of unit and end-to-end tests you can run them using the following commands. + +``` +make test + +make test-e2e +``` + +Make sure all the tests pass before you commit and push :) + +#### **Coverage** +You can get the test coverage using the following command. + +```bash +make coverage + +go tool cover -html=coverage.out # Open coverage status in your browser +``` + +#### **Repositories** +Horusec has other repositories and you can check the README for each one of them: + +- [**Horusec**](https://github.com/ZupIT/horusec) +- [**Devkit**](https://github.com/ZupIT/horusec-devkit) +- [**Documentation**](https://github.com/ZupIT/horusec-docs) +- [**Engine**](https://github.com/ZupIT/horusec-engine) +- [**Operator**](https://github.com/ZupIT/horusec-operator) +- [**VSCode plugin**](https://github.com/ZupIT/horusec-vscode-plugin) +- [**Horusec C4-Model**](https://github.com/ZupIT/horusec-c4model) +- [**Vulnerabilities**](https://github.com/ZupIT/horusec-examples-vulnerabilities) + +### **First contribution** +Contributing to a new feature is only allowed in the [**main repository**](https://github.com/ZupIT/horusec). + +Before contributing to this repository, please discuss the changes you wish to make via e-mail or [**forum**](https://forum.zup.com.br/c/en/horusec/14). + +### **Add new feature, bug fixing or improvement** +If you want to add an improvement, a new feature or bugfix, follow the steps to contribute: + +**Step 1:** Make sure your branch is based on main; + +**Step 2:** When opening an issue, choose a template to answer the questions regarding what you want to contribute: +- [**Bug Report**](https://github.com/ZupIT/horusec/blob/main/.github/ISSUE_TEMPLATE/bug_report.md) +- [**Feature request**](https://github.com/ZupIT/horusec/blob/main/.github/ISSUE_TEMPLATE/feature_request.md) +- [**Improvement**](https://github.com/ZupIT/horusec/blob/main/.github/ISSUE_TEMPLATE/improvement.md) +- [**Support request**](https://github.com/ZupIT/horusec/blob/main/.github/ISSUE_TEMPLATE/support_request.md) + +**Step 3:** Make your changes and open a GitHub pull request; + +**Step 4:** Make sure to write a title describing what you have done; + +**Step 5:** Fill in the template in the PR, here you need to write what you did and how the team can verify it; + +**Step 6:** You must commit to comply with the DCO rules. It will need to be [**signed-off**](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt--s) and [**verified**](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification/about-commit-signature-verification). Example: ` git commit -s --amend`. + + +### **Pull Request's approval** +Your pull request is approved when: +- 2 code owners approve it. +- Pass all GitHub actions checking process (lint, test, coverage, license, build, e2e, security, dco). + +### **After your pull request's approval** +- If it is a bug fix, the team will perform the changes and there will be a new release. +- If it is a feature, it will be in the next release. + +## **Community** + +- Do you have any question about Horusec? Send to our e-mail **horusec@zup.com.br**. +- Let's chat in our [**forum**](https://forum.zup.com.br/c/en/horusec/14). + +Thank you for your contribution, you rock! 🚀 + +**Horusec team** \ No newline at end of file diff --git a/README.md b/README.md index 4f7d7b32a..04c8e5e08 100644 --- a/README.md +++ b/README.md @@ -31,27 +31,39 @@ # **Horusec Platform** -Horusec Platform is a set of web services that integrate with [**Horusec CLI**](https://github.com/ZupIT/horusec) to make it easier for you to see and manage the vulnerabilities. +## **Table of contents** +### 1. [**About**](#about) +### 2. [**Usage**](#usage) +>#### 2.1. [**Requirements**](#requirements) +>#### 2.2. [**Installation**](#installation) +### 3. [**Features**](#features) +### 4. [**Documentation**](#documentation) +### 5. [**Contributing**](#contributing) +### 6. [**License**](#license) +### 7. [**Community**](#community) + +## **About** +Horusec Platform is a set of web services that integrate with [**Horusec-CLI**](https://github.com/ZupIT/horusec) to make it easier for you to see and manage the vulnerabilities. [comment]: <> (@todo add a gif of manager usage) -## **How to install?** +## **Usage** ### **Requirements** -You need to have: +See below the requirements to install Horusec-Platform: - [**RabbitMQ**](https://www.rabbitmq.com/) - [**PostgreSQL**](https://www.postgresql.org/) +### **Installation** +There are several ways to install the Horusec-Platform in your environment. +In some of them, we use a **`make`** command to simplify the process. +If you want to know everything that will be executed, take a look at the **`Makefile`** located at the project's root. -There are several ways to install the Horusec Platform in your environment. -In some types of installations, we use a `make` command to simplify the process. -If you want to know everything that will be executed, take a look at the `Makefile` located at the project's root. +Choose what type of installation you want below, but remember to change the default environment variables values to new and secure ones. -You can choose what type of installation you want below, but remember to change the default environment variables values to new and secure ones. - -### **Install with docker compose** +### **1. Install with docker compose** Follow the steps: **Step 1:** Run the command: @@ -59,11 +71,11 @@ Follow the steps: make install ``` -**Step 2:** Start the docker compose file **`compose.yml`**. It contains all services, migrations and the needed dependencies. +**Step 2:** Start the docker compose file **`compose.yml`**. It has all services, migrations and the needed dependencies. - You can find the compose file in **`deployments/compose/compose.yaml`**; - You can find migrations in **`migrations/source`**. -**Step 3:** After this, the installation is ready with all default values, the latest versions, and the following user for tests: +**Step 3:** Now the installation is ready with all default values, the latest versions, and the user for tests, see below: ``` Username: dev@example.com @@ -75,26 +87,26 @@ In the production environments' case, make sure to **change the values of the en > :warning: We **do not recommend** using docker-compose installation in a productive environment. -For more information about Docker compose, check out [**Docker compose installation section in our documetation**](https://horusec.io/docs/web/installation/install-with-docker-compose). +For more information about Docker compose, check out [**Docker compose installation section**](https://horusec.io/docs/web/installation/install-with-docker-compose). -### **Install with Helm** +### **2. Install with Helm** Each release contains its own helm files for that specific version, you can find them [**in the repository**](https://github.com/ZupIT/horusec-platform/releases) and in the folder **`deployments/helm`**. -In both cases they will be separated by each service of the architecture. +In both cases, they will be separated by each service of the architecture. -For more information, check out [**the installing with Helm section in our documentation**](https://horusec.io/docs/web/installation/install-with-helm). +For more information, check out [**the installing with Helm section**](https://horusec.io/docs/web/installation/install-with-helm). -### **Install with Horusec-Operator** +### **3. Install with Horusec-Operator** -Horusec-Operator performs management between Horusec web services and its Kubernetes cluster. It was created based on a community’s idea to have a simpler way to install the services in an environment using Kubernetes. +Horusec-Operator manages Horusec web services and its Kubernetes cluster. It was created based on the community’s idea to have a simpler way to install the services in an environment using Kubernetes. -- Check out how to install Horusec-Operator in our [**installing section**](https://horusec.io/docs/web/installation/install-with-operator/). -- You can see more about Kubernetes Operators [**in their documentation**](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/). +- Check out how to install Horusec-Operator in our [**installation section**](https://horusec.io/docs/web/installation/install-with-operator/). +- For more information about Kubernetes Operators, [**check out the documentation**](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/). ## **Features** -Horusec Platform provides several features, see some of them below. +Horusec-Platform provides several features, see some of them below. ### **MultiTenancy** @@ -104,13 +116,13 @@ It distributes only the necessary [**permissions**](https://horusec.io/docs/web/ ### **Dashboard** -The dashboard shows you various metrics about your vulnerabilities for workspaces and repositories: +The dashboard shows you several metrics about your workspaces and repositories' vulnerabilities:

dashboard

### **Vulnerability Management** -The vulnerability management screen allows you to identify false positives, accepted risk, and even modify a severity to an appropriate value to the reality of the vulnerability: +The vulnerability management screen allows you to identify false positives and accepted risks. You can modify a severity to an appropriate value to the reality of the vulnerability:

vuln-management

@@ -122,7 +134,7 @@ It creates workspaces or repositories authentication ### **Authentication Types** -You can choose which form of authentication you will use with Horusec Platform. +You can choose which form of authentication you will use with Horusec-Platform. There are three possibilities: @@ -145,22 +157,44 @@ For more information about Horusec, please check out the [**documentation**](htt ## **Contributing** -If you want to contribute to this repository, access our [**Contributing Guide**](https://github.com/ZupIT/charlescd/blob/main/CONTRIBUTING.md). -And if you want to know more about Horusec, check out some of our other projects: +If you want to contribute to this repository, access our [**Contributing Guide**](https://github.com/ZupIT/horusec-platform/blob/main/CONTRIBUTING.md). +### **Developer Certificate of Origin - DCO** -- [**Horusec CLI**](https://github.com/ZupIT/horusec) -- [**Horusec Devkit**](https://github.com/ZupIT/horusec-platform) -- [**Horusec Engine**](https://github.com/ZupIT/horusec-engine) -- [**Horusec Operator**](https://github.com/ZupIT/horusec-operator) -- [**Horusec Admin**](https://github.com/ZupIT/horusec-admin) -- [**Horusec VsCode**](https://github.com/ZupIT/horusec-vscode-plugin) + This is a security layer for the project and for the developers. It is mandatory. + + Follow one of these two methods to add DCO to your commits: + +**1. Command line** + Follow the steps: + **Step 1:** Configure your local git environment adding the same name and e-mail configured at your GitHub account. It helps to sign commits manually during reviews and suggestions. -## **Community** -Feel free to reach out to us at: + ``` +git config --global user.name “Name” +git config --global user.email “email@domain.com.br” +``` +**Step 2:** Add the Signed-off-by line with the `'-s'` flag in the git commit command: + +``` +$ git commit -s -m "This is my commit message" +``` + +**2. GitHub website** +You can also manually sign your commits during GitHub reviews and suggestions, follow the steps below: -- [**GitHub Issues**](https://github.com/ZupIT/horusec-devkit/issues) -- [**Zup Open Source Forum**](https://forum.zup.com.br) +**Step 1:** When the commit changes box opens, manually type or paste your signature in the comment box, see the example: + +``` +Signed-off-by: Name < e-mail address > +``` + +For this method, your name and e-mail must be the same registered on your GitHub account. + +## **License** +[**Apache License 2.0**](https://github.com/ZupIT/horusec-platform/blob/main/LICENSE). + +## **Community** +Do you have any question about Horusec? Let's chat in our [**forum**](https://forum.zup.com.br/). This project exists thanks to all the contributors. You rock! ❤️🚀 diff --git a/assets/pr-template.PNG b/assets/pr-template.PNG new file mode 100644 index 000000000..4790d851d Binary files /dev/null and b/assets/pr-template.PNG differ