From c08719f70a16599217e2c14cae275533b743e2cc Mon Sep 17 00:00:00 2001 From: jessica-tw <66262423+jessica-tw@users.noreply.github.com> Date: Mon, 4 Oct 2021 14:53:08 -0300 Subject: [PATCH] Updated README and CONTRIBUTING (#46) Signed-off-by: jessica-tw Signed-off-by: wilian --- CONTRIBUTING.md | 174 +++++++++++++++++++++++++++++------------------- README.md | 91 +++++++++++++------------ 2 files changed, 154 insertions(+), 111 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e29788e..f5a0ef3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,91 +1,129 @@ -# 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) +- [**Operator**](https://github.com/ZupIT/horusec-operator) +- [**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 0d20b60..609a501 100644 --- a/README.md +++ b/README.md @@ -18,60 +18,43 @@ -# Horusec Engine +# **Horusec Engine** -This repository contains the standalone SAST engine used by the Horusec project. +This repository contains the standalone SAST engine used by Horusec. -The goal of this project is to provide a baseline functionality and the basic building blocks -for you to build your own SAST tool. +Horusec-Engine provides baseline functionality and the basic building blocks for you to build your own SAST tool. -## But what is a SAST tool anyway? -A Static Application Security Testing tool is an automated scanner for security issues in your source code or binary artifact -The main goal of it is to identify, as soon as possible in your development lifecycle, any possible threat to your infrastructure -and your user's data. One important thing to remember is that no SAST tool found actual vulnerabilities, because the tool never -actually executes the program being analyzed, therefore, you still have to keep testing your applications with more traditional -pentesting and any other tests that you can execute. +## **What is a SAST tool?** +A Static Application Security Testing tool is an automated scanner for security issues in your source code or binary artifact. The main goal is to identify, as soon as possible in your development lifecycle, any possible threat to your infrastructure and your user's data. +SAST tools don't actually find vulnerabilities because the tool never executes the program being analyzed, therefore, you still have to keep testing your applications with more traditional pen testing and any other tests that you can execute. -## With so many SAST tools out there, why even bother to right my own? -The main benefit you can get for writing your own is the amount of knowledge about your own application you can impress -on your tool. Sure that, in the first months a off-the-shelf tool will have more rules and more corner cases covered than yours -but with the right amount of dedication of improving and expanding the techniques your tool uses, you can easily overcome -the regular market tools. +### **There are many SAST tools out there, why write my own?** +The main benefit you can get for writing your own is the amount of knowledge about your application you can add to your tool. In the beginning, the off-the-shelf tool will have more rules and more corner cases covered than yours, but with the right amount of dedication to improve and expand the techniques your tool uses, you can easily overcome the regular market tools. -## Okay, I decided write my own tool, what does this engine helps me? -Right now the only built-in technique our engine uses is the syntax pattern matching technique, a powerful yet simple technique -to uncover the most common mistakes that you can left in your code base. +### **Why does this engine help me?** +The only built-in technique our engine uses is the syntax pattern matching technique, a powerful yet simple technique to uncover the most common mistakes you can leave in your codebase. But, the extensibility of the engine is the main advantage it presents. All the design around our solution was focused on the extensibility and interoperability of techniques in one single analysis. -But, as I shall show to you, the extensibility of the engine is the main advantage it presents. +To achieve that, Horusec-Engine uses three simple and expressive components that can be easily extended to suit your needs and it allows you to expand the functionality of the engine with new techniques, while still having a common ground for all of them. +See it below: -All the design around our solution was focused on extensibility and iteroperability of techniques in one single analysis. -To achieve that, we make use of three simple yet very expressive components that can be easily extended to suit your needs -and allows you to expand the functionality of the engine with new techniques, while still having a common ground for all of them. +### **1. Unit** +A unit is a piece of your code that makes sense to be analyzed as one. So every Unit is a lexical scope, for example, a C++ namespace or a Java Class. The engine will treat all the files and code inside a unit as one thing, and it will only be able to cross-reference anything inside a single unit. +We are working on a complex lexical analysis between units and even a more deeper one inside units, [**if you want to help us, check out our GitHub issues**](https://github.com/ZupIT/horusec-engine/issues). +### **2. Rule** +The engine won't help you here because you have to provide your own rules. The FOSS version of Horusec's tool has a lot of rules you can use, but this interface is here to encourage you to learn more about how security issues manifest in your favorite language syntax, and therefore how to identify them with your tool. -## The main components +### **3. Finding** +The finding is a key part of your tool. You can actually extract useful insights from the source code analysis. +The struct is focused on simplicity, but we are working to implement it following the[**SARIF**](https://github.com/oasis-tcs/sarif-spec) specification, so you can have complete control of where you import your data. -### Unit -The most important of them, an unit is a piece of your code that makes sense to be analyzed as one. So every Unit is -a lexical scope, you can imagine for example, a C++ namespace or a Java Class. The engine will treat all the files and code inside -an unit as one thing, and will only be able to cross reference anything inside a single unit. -We are working on a more profound and complex lexical analysis between units and even a more deeper one inside units, [so any help is welcome!](https://github.com/ZupIT/horusec-engine/issues) -### Rule -This is the only part that the engine won't help you, because you have to provide your own rules. The FOSS version of the Horusec -tool have a lot of rules that you can use, but this interface is here to exactly encourage you to learn more about how security -issues manifest in your favorite language syntax, and therefore how to identify them with your tool. - -### Finding -The finding is a key part of your tool, since it's with it that you actually extract useful insight from the source code being analyzed. -The struct right now is focused on simplicity, but we are working to implement it following the [SARIF](https://github.com/oasis-tcs/sarif-spec) specification, so you can have complete control of where you import your data. - - -## Examples +## **Examples** A simple analysis of an inmemory string: + ```go var exampleGoFile = `package version @@ -126,10 +109,32 @@ func (v *Version) CreateCobraCmd() *cobra.Command { t.Log(finding.SourceLocation) } ``` +## **Documentation** + +For more information about Horusec, please check out the [**documentation**](https://horusec.io/docs/). + + +## **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: + + +- [**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) +- [**Operator**](https://github.com/ZupIT/horusec-operator) +- [**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) + +## **Community** +Feel free to reach out to us at: -## Communication +- [**GitHub Issues**](https://github.com/ZupIT/horusec-devkit/issues) +- [**Zup Open Source Forum**](https://forum.zup.com.br) -We have a few channels for contact, feel free to reach out to us at: -- [GitHub Issues](https://github.com/ZupIT/horusec-engine/issues) -- [Zup Open Source Forum](https://forum.zup.com.br) +This project exists thanks to all the contributors. You rock! ❤️🚀 \ No newline at end of file