From f8f280561e229855935859fdac4061880ecd109b Mon Sep 17 00:00:00 2001 From: jessica-tw Date: Mon, 4 Oct 2021 16:52:30 -0300 Subject: [PATCH] Updated readme.md and contributing.md Signed-off-by: jessica-tw Signed-off-by: wilian --- CONTRIBUTING.md | 173 +++++++++++++++++++++++++++++------------------- README.md | 127 ++++++++++++++++++++--------------- 2 files changed, 177 insertions(+), 123 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e29788e8..01548d25 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,91 +1,128 @@ -# Contributing +# **Contributing Guide** + +This is Horusec contributing guide. Please read the following sections to learn how to ask questions and how to work on something. + +## **Table of contents** +1. [**Getting Started**](#Getting-started) + 1. [**Before you contribute**](#Before-you-contribute) + 2. [**Code of Conduct**](#Code-of-Conduct) + 3. [**Legal**](#Legal) +2. [**Prerequisites**](#Prerequisites) + 1. [**Developer Certificate of Origin**](#Developer-Certificate-of-Origin) + 2. [**Code Review**](#Code-Review) + 3. [**Pull Requests**](#Pull-Requests) +3. [**How to contribute?**](#How-to-contribute?) + 1. [**Prepare your development environment**](#Using-Docker) + 2. [**First contribution**](#First-contribution) + 4. [**Add new feature, bugfixing or improvement**](#Add-new-feature-bugfixing-or-improvement) + 5. [**Pull Request's approval**](#Pull-Request's-approval) + 6. [**After your pull request's approval**](#After-your-pull-request's-approval) +4. [**Community**](#Community) -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. +## **Getting started** -Please note we have a code of conduct, please follow it in all your interactions with the project. +### **Before you contribute** -## Pull Request Process +### **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. -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. +### **Legal** +- Horusec is licensed over [**ASL - Apache License**](https://github.com/ZupIT/charlescd/blob/main/LICENSE), version 2, so new files must have the ASL version 2 header, for more information, please check out [**Apache license**](https://www.apache.org/licenses/LICENSE-2.0). -## Code of Conduct +- 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. -### Our Pledge +## **Prerequisites** +Check out the requisites before contributing to Horusec: -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. +### **Developer Certificate of Origin - DCO** -### Our Standards + This is a security layer for the project and for the developers. It is mandatory. + + There are two ways to use DCO, see them below: + +**1. Command line** + Follow the steps: + **Step 1:** Check out your local git: -Examples of behavior that contributes to creating a positive environment -include: + ``` +git config --global user.name “Name” +git config --global user.email “email@domain.com.br” +``` +**Step 2:** When you commit, add the sigoff via `-s` flag: -* 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 commit -s -m "This is my commit message" +``` +**2. GitHub website** -Examples of unacceptable behavior by participants include: +**Step 1:** When the commit changes box opens, add +``` +$ git commit -m “My signed commit” Signed-off-by: username +``` +Note: For this option, your e-mail must be the same in registered in GitHub. -* 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 +### **Code Review** +- All your submissions needs a review. -### Our Responsibilities +### **Pull Requests** +When opening a PR: +- You need to add a title describing the issue. +- Fill in the template, describe why you are opening the PR. -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. +## **How to contribute?** +See the guidelines to submit your changes: -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. +### **Prepare your development environment** +Horusec has other repositories and you can check the README for each one of them: -### Scope +- [**Admin**](https://github.com/ZupIT/horusec-admin) +- [**Charts**](https://github.com/ZupIT/charlescd/tree/main/circle-matcher) +- [**Devkit**](https://github.com/ZupIT/horusec-devkit) +- [**Jenkins**](https://github.com/ZupIT/horusec-jenkins-sharedlib) +- [**Platform**](https://github.com/ZupIT/horusec-platform) +- [**VSCode plugin**](https://github.com/ZupIT/horusec-vscode-plugin) +- [**Kotlin**](https://github.com/ZupIT/horusec-tree-sitter-kotlin) +- [**Vulnerabilities**](https://github.com/ZupIT/horusec-examples-vulnerabilities) -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. +### **First contribution** +Contributing to a new feature is only allowed in the [**main repository**](https://github.com/ZupIT/horusec). -### Enforcement +Before contributing to this repository, please discuss the changes you wish to make via email or [**forum**](https://forum.zup.com.br/c/en/horusec/14). -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. +### **Add new feature, bugfixing or improvement** +If you want to add an improvement, a new feature or bugfix, follow the steps to contribute: -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. +**Step 1:** Make sure your branch is based on main; +**Step 2:** When opening an issue, choose a template to answer the questions regarding the 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) -### Attribution +**Step 3:** Make your changes and open a GitHub pull request; -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] +**Step 4:** Make sure to write a title describing what you have done; -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ +**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 bugfix, 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 in our [**mailing list**](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 b81a47b3..d14c8fe6 100644 --- a/README.md +++ b/README.md @@ -21,39 +21,44 @@

-# Horusec-Operator -The main function of horusec-operator is to perform management between horusec web services and its kubernetes cluster. -Its creation came from an idea of the community where it can have a simpler way to install the services in an environment using kubernetes. -See all horusec operator details in [our documentation](https://horusec.io/docs/web/installation/install-with-horusec-operator/) - -## Requirements -To use horusec-operator you need to configure some secrets and dependencies of horusec, they are: -* [Kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) and connection with your cluster -* Connection with a database - * You can upload a pod from a PostgreSQL database [as shown in our example](#development-environment), or you can only create secrets of connection with your database. - * Create two databases for the horusec-platform and horusec-analytic -* Connection with a message broker - * You can upload a pod from a RabbitMQ message broker [as shown in our example](#development-environment), or you can only create secrets of connection with your message broker. -* Others secrets necessary - * The secrets you need to configure may vary depending on how you use horusec. [See possible configuration options](https://horusec.io/docs/web/installation/install-with-horusec-operator#resources). - -## Installing -After configuring your database connection, connecting to your broker and creating the secrets you need to install horusec-operator on your cluster, see an example below: +# **Horusec-Operator** +Horusec-operator performs management between horus web services and its Kubernetes cluster. It was created based on the community's idea and it can have a simpler way to install the services in an environment using Kubernetes. + +This is the Kubernetes operator that enhances the Horusec-Platform installation system in a unified way. + +## **Requirements** +To use horusec-operator you need to configure some secrets and dependencies, see them below: +* [**Kubectl**](https://kubernetes.io/docs/tasks/tools/#kubectl) and connection with your cluster +* Connection with a database: + * You can upload a pod from a PostgreSQL database [**you can see in the development environment example**](#development-environment), or you can create secrets of connection with your database. + * Create two databases for horusec-platform and horusec-analytic. +* Connection with a message broker: + * You can upload a pod from a RabbitMQ message broker or you can create secrets of connection with your message broker. +* Other secrets necessary: + * The secrets you need to configure may vary depending on how you use horusec. [**Check out the configuration options**](https://horusec.io/docs/web/installation/install-with-horusec-operator#resources). + +## **Installing Operator** +After configuring your machine according to the requirements, install horusec-operator on your cluster, see an example below: + +1. Run the command: + ```bash kubectl apply -k "https://github.com/ZupIT/horusec-operator/config/default?ref=v2.2.0" ``` -See the resource if was installed with success! +2. See if the resoruce was installed: ```bash kubectl api-resources | grep horus ``` -you can see an output like this: +3. You may see an output like this: ```text $ kubectl api-resources | grep horus horusecplatforms horus install.horusec.io true HorusecPlatform ``` -## Usage -And now just send the changes you want to kubenernetes. In this example we are using an [example yaml file](./config/samples/install_v2alpha1_horusecplatform.yaml), if you happen to send an empty yaml file like for example: +## **Usage** + +After installing, you need to send the changes you want to Kubenernetes. In this example we are using an [**example yaml file**](./config/samples/install_v2alpha1_horusecplatform.yaml), if you send an empty yaml file like the example below, it will take the [**default horusec settings**](./api/v2alpha1/horusec_platform_defaults.json): + ```yaml apiVersion: install.horusec.io/v2alpha1 kind: HorusecPlatform @@ -61,14 +66,14 @@ metadata: name: horusecplatform-sample spec: {} ``` -It will take the [default horusec settings](./api/v2alpha1/horusec_platform_defaults.json) -And now you apply your changes +And now you apply your changes: + ```bash kubectl apply -f "https://raw.githubusercontent.com/ZupIT/horusec-operator/main/config/samples/install_v2alpha1_horusecplatform.yaml" ``` -and you can see all horusec web services upload in your cluster, like this example: +You can see all horusec web services upload in your cluster, like this example: ```text $ kubectl get pods NAME READY STATUS RESTARTS AGE @@ -87,22 +92,29 @@ vulnerability-7d789fd655-tpjp8 1/1 Running 0 webhook-7b5c45c859-cq4nf 1/1 Running 0 73s ``` -## Development Environment -This only an dev example how usage horusec-operator. -For usage this example is necessary installing [helm](https://helm.sh/docs/intro/install/#from-script) and [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) in your local machine -After of you install you can run follow commands and see horusec-operator up all horusec web services. +## **Development Environment** +This is a development environment example on how to use horusec-operator. + +You will need to install: +- [**Helm**](https://helm.sh/docs/intro/install/#from-script) +- [**Kind**](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) + +Now, you can run the commands and see horusec-operator up all horusec web services. See the steps below: + +**Step 1.** Clone this project: -Clone this project ```bash git clone https://github.com/ZupIT/horusec-operator.git && cd horusec-operator ``` -Up kubernetes cluster with all dependencies and wait finish! +**Step 2.** Up kubernetes cluster with all dependencies and wait finish: + ```bash make up-sample ``` -If you see this message +If you see this message: + ```text Creating horusec_analytic_db... If you don't see a command prompt, try pressing enter. @@ -112,36 +124,39 @@ psql: could not connect to server: Connection refused pod "postgresql-client" deleted pod default/postgresql-client terminated (Error) ``` -Don't worry this is normal because the script is trying create new database, but the pod of the postgresql is not ready, it will run again until create new database. +Don't worry, this is normal because the script is trying create new database, but the pod of the postgresql is not ready, it will run again until create new database. -After script finish. Install Horusec-Operator +**Step 3.** After the script finishes, install Horusec-Operator: ```bash kubectl apply -k "https://github.com/ZupIT/horusec-operator/config/default?ref=v2.2.0" ``` -See the resource if was installed with sucess! +**Step 4.** Check if the resource was installed: + ```bash kubectl api-resources | grep horus ``` -you can see an output like this: +You can see an output like this: ```text $ kubectl api-resources | grep horus horusecplatforms horus install.horusec.io true HorusecPlatform ``` -And you can see the pod manager by this resource +And you can see the pod manager by the resource below: + ```text $ kubectl get pods -n horusec-operator-system NAME READY STATUS RESTARTS AGE horusec-operator-controller-manager-7b9696d4c4-t7w2q 2/2 Running 0 2m10s ``` -And now, you can pass [yaml with your configuration](https://horusec.io/docs/web/installation/install-with-horusec-operator#resources) to upload in your kubernetes cluster. See this example +**Step 5.** And now, pass the [**yaml with your configuration**](https://horusec.io/docs/web/installation/install-with-horusec-operator#resources) to upload in your Kubernetes cluster. See the example: + ```bash kubectl apply -f ./config/samples/install_v2alpha1_horusecplatform.yaml ``` -and you can see all horusec web services upload in your cluster, like this example: +You can see all horusec web services uploaded in your cluster, like this: ```text $ kubectl get pods NAME READY STATUS RESTARTS AGE @@ -160,29 +175,31 @@ vulnerability-7d789fd655-tpjp8 1/1 Running 0 webhook-7b5c45c859-cq4nf 1/1 Running 0 73s ``` -## Contributing Guide +## **Documentation** + +For more information about Horusec, please check out the [**documentation**](https://horusec.io/docs/). -Read our [contributing guide](CONTRIBUTING.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to horusec. -## Communication +## **Contributing** -We have a few channels for contact, feel free to reach out to us at: +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: -- [GitHub Issues](https://github.com/ZupIT/horusec-operator/issues) -- [Zup Open Source Forum](https://forum.zup.com.br) -## Contributing with others projects +- [**Admin**](https://github.com/ZupIT/horusec-admin) +- [**Charts**](https://github.com/ZupIT/charlescd/tree/main/circle-matcher) +- [**Devkit**](https://github.com/ZupIT/horusec-devkit) +- [**Jenkins**](https://github.com/ZupIT/horusec-jenkins-sharedlib) +- [**Platform**](https://github.com/ZupIT/horusec-platform) +- [**VSCode plugin**](https://github.com/ZupIT/horusec-vscode-plugin) +- [**Kotlin**](https://github.com/ZupIT/horusec-tree-sitter-kotlin) +- [**Vulnerabilities**](https://github.com/ZupIT/horusec-examples-vulnerabilities) -Feel free to use, recommend improvements, or contribute to new implementations. +## **Community** +Feel free to reach out to us at: -If this is our first repository that you visit, or would like to know more about Horusec, -check out some of our other projects. +- [**GitHub Issues**](https://github.com/ZupIT/horusec-devkit/issues) +- [**Zup Open Source Forum**](https://forum.zup.com.br) -- [Horusec CLI](https://github.com/ZupIT/horusec) -- [Horusec Platform](https://github.com/ZupIT/horusec-platform) -- [Horusec DevKit](https://github.com/ZupIT/horusec-devkit) -- [Horusec Engine](https://github.com/ZupIT/horusec-engine) -- [Horusec Admin](https://github.com/ZupIT/horusec-admin) -- [Horusec VsCode](https://github.com/ZupIT/horusec-vscode-plugin) This project exists thanks to all the contributors. You rock! ❤️🚀