Improved codacy grade Checkmarx#1809 (Checkmarx#1842)

* Created documentation for missing exported elements

* Added documenting comments for terraform.go and comments.go

* Corrected codacy issues for .md files

* Minor corrections

.github/ISSUE_TEMPLATE/bug_report.md

@@ -6,21 +6,17 @@ labels: bug
 assignees: ''
 
 ---
-
 ### Expected Behavior
 
-
 ### Actual Behavior
-
-
 ### Steps to Reproduce the Problem
 
-  1.
-  1.
-  1.
+1.  step 1
+2.  step 2
+3.  step 3
 
 ### Specifications
 
-  - Version:
-  - Platform:
-  - Subsystem:
+-   Version:
+-   Platform:
+-   Subsystem:

.github/ISSUE_TEMPLATE/feature_request.md

@@ -8,7 +8,7 @@ assignees: ''
 ---
 
 **Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+A clear and concise description of what the problem is. Ex. I'm always frustrated when \[...\])
 
 **Describe the solution you'd like**
 A clear and concise description of what you want to happen.

.github/ISSUE_TEMPLATE/query.md

@@ -1,7 +1,7 @@
 ---
 name: Query
 about: Template to help create/update a query
-title: Add/Update [QUERY_NAME] query for [PLATFORM] (Terraform, Ansible, ..)
+title: Add/Update \[QUERY_NAME\] query for \[PLATFORM\] (Terraform, Ansible, ..)
 labels: query
 assignees: ''
 

README.md

@@ -25,21 +25,20 @@ It is as simple as running a CLI tool, making it easy to integrate into any proj
 
 Support of other solutions, such as Chef, and of additional cloud providers are on the [roadmap](docs/roadmap.md).
 
-
 ## Getting Started
 
 Setting up and using KICS is super-easy.
 
-- First, see how to [install and get KICS running](docs/getting-started.md).
-- Next, check how you can easily [integrate it into your CI](docs/integrations.md) for any project.
-- Eventually, [explore the output results format](docs/results.md) and quickly fix the issues detected.
+-   First, see how to [install and get KICS running](docs/getting-started.md).
+-   Next, check how you can easily [integrate it into your CI](docs/integrations.md) for any project.
+-   Eventually, [explore the output results format](docs/results.md) and quickly fix the issues detected.
 
 ## How it Works
 
 What makes KICS really powerful and popular is its built-in extensibility. This extensibility is achieved by:
 
-- Fully customizable and adjustable heuristics rules, called [queries](docs/queries.md). These can be easily edited, extended, and added.
-- Robust but yet simple [architecture](docs/architecture.md), which allows quick addition of support for new Infrastructure as Code solutions.
+-   Fully customizable and adjustable heuristics rules, called [queries](docs/queries.md). These can be easily edited, extended, and added.
+-   Robust but yet simple [architecture](docs/architecture.md), which allows quick addition of support for new Infrastructure as Code solutions.
 
 ## Contribution
 

cmd/builder/README.MD

@@ -1,14 +1,16 @@
 # Query by Example - the tool for query auto-generation
 
-#### What does this tool do
+## What does this tool do
+
 The query auto-generation tool generates queries by examples: its input is an example of a source file with security issues, 
-when there is a special comment marks lines with security issues; 
+when there is a special comment marks lines with security issues;
 its output is a query source in REGO format.
 
-#### Example
+## Example
 
-##### Terraform file with security issues marked with comments:
-```
+### Terraform file with security issues marked with comments
+
+```terraform
 resource "aws_lb_listener" "front_end" {
   load_balancer_arn = aws_lb.front_end.arn
   port              = "80"
@@ -37,8 +39,10 @@ resource "aws_alb_listener" "front_end" {
   }
 }
 ```
-##### Auto-generated Query in REGO format:
-```
+
+### Auto-generated Query in REGO format
+
+```rego
 package Cx
 
 CxPolicy [ result ] {
@@ -76,32 +80,37 @@ CxPolicy [ result ] {
 }
 ```
 
-#### How to run
-```
+## How to run
+
+```sh
 go run cmd/builder/main.go -i ./cmd/builder/example.tf -o ./out.rego
 ```
 
 Where `-i` - terraform file to parse, `-o` result query.
 
 Please ensure you have downloaded all tool dependencies, to do that please execute:
-```
+
+```sh
 go mod download
 go mod vendor
 ```
 
-### Supported Comment
+## Supported Comment
 
 The tool supports only comments which have Golang struct tag syntax, for example `// Comment:"attribute1,attribute2=value" Comment2`. (note: space is not allowed in comments attributes).
 For more example please take a look at the example files.
 
 Supported comment:
-* `MissingAttribute`
-* `RedundantAttribute`
-* `IncorrectValue`
-  * `resource` - to target a resource, can be `resource=*`, `resource=['s3_bucket','sqs_queue']`, by default resource from terraform file will be used 
-  * `any_key` - allow any element in condition, example `resosource.vars.name -> resource.vars[_]`
-  * `upper/lower` - to wrap condition, example `resosource.vars.name -> upper(resource.vars.name)`
-  * `regex` - use `re_match` for a condition, should be provided with a regex pattern as an attribute value
-  * `condition` - to set a custom condition, by default we use `==`
-  * `val` - to set custom condition value, by default we use the value from the provided terraform file
 
+*   `MissingAttribute`
+
+*   `RedundantAttribute`
+
+*   `IncorrectValue`
+    *   `resource` - to target a resource, can be `resource=*`, `resource=['s3_bucket','sqs_queue']`, by default resource from terraform file will be used 
+    *   `any_key` - allow any element in condition, example `resosource.vars.name -> resource.vars[_]`
+    *   `upper/lower` - to wrap condition, example `resosource.vars.name -> upper(resource.vars.name)`
+    *   `regex` - use `re_match` for a condition, should be provided with a regex pattern as an attribute value
+    *   `condition` - to set a custom condition, by default we use `==`
+    *   `val` - to set custom condition value, by default we use the value from the provided terraform file
+

internal/storage/memory.go

@@ -6,34 +6,41 @@ import (
 	"github.com/Checkmarx/kics/pkg/model"
 )
 
+// MemoryStorage is scans' results representation
 type MemoryStorage struct {
 	vulnerabilities []model.Vulnerability
 	allFiles        model.FileMetadatas
 }
 
+// SaveFile adds a new file metadata to files collection
 func (m *MemoryStorage) SaveFile(_ context.Context, metadata *model.FileMetadata) error {
 	m.allFiles = append(m.allFiles, *metadata)
 	return nil
 }
 
+// GetFiles returns a collection of files saved on MemoryStorage
 func (m *MemoryStorage) GetFiles(_ context.Context, _ string) (model.FileMetadatas, error) {
 	return m.allFiles, nil
 }
 
+// SaveVulnerabilities adds a list of vulnerabilities to vulnerabilities collection
 func (m *MemoryStorage) SaveVulnerabilities(_ context.Context, vulnerabilities []model.Vulnerability) error {
 	m.vulnerabilities = append(m.vulnerabilities, vulnerabilities...)
 
 	return nil
 }
 
+// GetVulnerabilities returns a collection of vulnerabilities saved on MemoryStorage
 func (m *MemoryStorage) GetVulnerabilities(_ context.Context, _ string) ([]model.Vulnerability, error) {
 	return m.vulnerabilities, nil
 }
 
+// GetScanSummary is not supported by MemoryStorage
 func (m *MemoryStorage) GetScanSummary(_ context.Context, _ []string) ([]model.SeveritySummary, error) {
-	return nil, nil // unsupported for this storage type
+	return nil, nil
 }
 
+// NewMemoryStorage creates a new MemoryStorage empty and returns it
 func NewMemoryStorage() *MemoryStorage {
 	return &MemoryStorage{
 		allFiles:        make(model.FileMetadatas, 0),

internal/tracker/ci.go

@@ -1,5 +1,7 @@
 package tracker
 
+// CITracker contains information of how many queries were loaded and executed
+// and how many files were found and executed
 type CITracker struct {
 	LoadedQueries      int
 	ExecutedQueries    int
@@ -8,18 +10,22 @@ type CITracker struct {
 	FailedSimilarityID int
 }
 
+// TrackQueryLoad adds a loaded query
 func (c *CITracker) TrackQueryLoad() {
 	c.LoadedQueries++
 }
 
+// TrackQueryExecution adds a query executed
 func (c *CITracker) TrackQueryExecution() {
 	c.ExecutedQueries++
 }
 
+// TrackFileFound adds a found file to be scanned
 func (c *CITracker) TrackFileFound() {
 	c.FoundFiles++
 }
 
+// TrackFileParse adds a successful parsed file to be scanned
 func (c *CITracker) TrackFileParse() {
 	c.ParsedFiles++
 }

pkg/builder/engine/engine.go

@@ -17,11 +17,13 @@ import (
 
 const resourceLabelsCount = 2
 
+// Engine contains the conditions of rules and comments positions
 type Engine struct {
 	commentParser *commentParser.Parser
 	conditions    []build.Condition
 }
 
+// Run parses files and execute engine.Run
 func Run(src []byte, filename string) ([]build.Rule, error) {
 	cp, err := commentParser.NewParser(src, filename)
 	if err != nil {
@@ -43,6 +45,7 @@ func Run(src []byte, filename string) ([]build.Rule, error) {
 	return e.Run(file.Body.(*hclsyntax.Body))
 }
 
+// Run initializes rules for Engine and returns it
 func (e *Engine) Run(body *hclsyntax.Body) ([]build.Rule, error) {
 	e.conditions = make([]build.Condition, 0)
 	if err := e.walkBody(body, []build.PathItem{}); err != nil {

pkg/builder/model/model.go

@@ -2,20 +2,24 @@ package model
 
 import "github.com/Checkmarx/kics/pkg/model"
 
+// PathItemType represents which type of path that item belongs on json representation
 type PathItemType string
 
+// Constants for kinds of PathItemTypes
 const (
 	PathTypeDefault      PathItemType = "DEFAULT"
 	PathTypeResource     PathItemType = "RESOURCE"
 	PathTypeResourceType PathItemType = "RESOURCE_TYPE"
 	PathTypeResourceName PathItemType = "RESOURCE_NAME"
 )
 
+// PathItem represents json's element name and type
 type PathItem struct {
 	Name string
 	Type PathItemType
 }
 
+// Condition represents a condition from a rule that should be checked
 type Condition struct {
 	Line int
 
@@ -25,10 +29,12 @@ type Condition struct {
 	Attributes map[string]interface{}
 }
 
+// Rule represents a list of conditions to validate a rule
 type Rule struct {
 	Conditions []Condition
 }
 
+// Attr add some configurations to the condition to return the condition to be matched
 func (c Condition) Attr(name string) (interface{}, bool) {
 	v, ok := c.Attributes[name]
 	if !ok {
@@ -38,6 +44,7 @@ func (c Condition) Attr(name string) (interface{}, bool) {
 	return v, true
 }
 
+// AttrAsString gets Attr and converts to string
 func (c Condition) AttrAsString(name string) (string, bool) {
 	v, ok := c.Attributes[name]
 	if !ok {

pkg/builder/parser/comment/comments.go

@@ -5,10 +5,12 @@ import (
 	"github.com/hashicorp/hcl/v2/hclsyntax"
 )
 
+// Parser represents a list of code tokens
 type Parser struct {
 	tokens hclsyntax.Tokens
 }
 
+// NewParser parses the content of a file and return a parser with its tokens
 func NewParser(src []byte, filename string) (*Parser, error) {
 	tokens, diags := hclsyntax.LexConfig(src, filename, hcl.Pos{Line: 0, Column: 0})
 	if diags != nil && diags.HasErrors() {
@@ -20,6 +22,7 @@ func NewParser(src []byte, filename string) (*Parser, error) {
 	}, nil
 }
 
+// ParseCommentsForNode returns a comment in the range given in rg, if exists
 func (p *Parser) ParseCommentsForNode(rg hcl.Range) (startComment, leadComment Comment) {
 	start, end := p.rangePosition(rg)
 	startLeadComment := p.leadCommentStarts(start)
@@ -84,19 +87,23 @@ func (p *Parser) lineCommentEnds(after int) int {
 	return len(p.tokens)
 }
 
+// Comment - struct with comment value and its position on file
 type Comment struct {
 	pos   hcl.Pos
 	value string
 }
 
+// IsEmpty returns true if comment is empty, otherwise returns false
 func (c Comment) IsEmpty() bool {
 	return c.value == ""
 }
 
+// Value returns comment value
 func (c Comment) Value() string {
 	return c.value
 }
 
+// Line returns the line comment starts
 func (c Comment) Line() int {
 	return c.pos.Line + 1
 }

pkg/builder/parser/tag/tag_parser.go

@@ -9,6 +9,7 @@ import (
 	"text/scanner"
 )
 
+// Tag contains the tag name reference and its atributtes
 type Tag struct {
 	Name       string
 	Attributes map[string]interface{}

pkg/builder/writer/rego.go

@@ -13,16 +13,19 @@ import (
 	"github.com/rs/zerolog/log"
 )
 
+// RegoWriter represents the template for a Rego rule
 type RegoWriter struct {
 	tmpl *template.Template
 }
 
+// Block represents a json block of a file for scan
 type Block struct {
 	Name string
 	All  bool
 	List []string
 }
 
+// RegoRule contains a block to be scanned and a rule to be applied
 type RegoRule struct {
 	Block Block
 	build.Rule
@@ -32,6 +35,7 @@ const (
 	stringValue = "\"%s\""
 )
 
+// NewRegoWriter initializes a default RegoWriter using builder template
 func NewRegoWriter() (*RegoWriter, error) {
 	tmpl, err := template.New("template.gorego").
 		Funcs(template.FuncMap{
@@ -75,6 +79,7 @@ func NewRegoWriter() (*RegoWriter, error) {
 	return &RegoWriter{tmpl: tmpl}, nil
 }
 
+// Render starts RegoWriter rules list passed as parameter
 func (w *RegoWriter) Render(rules []build.Rule) ([]byte, error) {
 	wr := bytes.NewBuffer(nil)