Contribution

Contribution¶

We would like to THANK YOU for considering contributing to KICS!

KICS is a true community project. It's built as an open source from day one, and anyone can find his own way to contribute to the project.

Within just minutes, you can start making a difference, by sharing your expertise with a community of thousands of security experts and software developers.

Contribution Options¶

Good news! You don't have to contribute code. There are plenty of ways you can contribute to KICS project:

Reporting new bugs or issues
Help triaging issues
Improving and translating the documentation
Volunteering to maintain the project

Code of Conduct¶

By participating and contributing to the project, you agree to uphold our Code of Conduct.

Get Started!¶

Follow the instructions below to setup local KICS development environment and push your changes.

Fork the kics repo on GitHub.
Download and install Go 1.16 or higher from https://golang.org/dl/.

Clone your fork locally:

git clone https://github.com/Checkmarx/kics.git

Create a branch for local development. Use succinct but descriptive name (prefix with feature/issue#-descriptive-name> or hotfix/issue#-descriptive-name):
```
git checkout -b <name-of-your-issue>
```
Make your changes locally. We recommend running the E2E tests by following the steps recommended in the README.
Validate your changes to reassure they meet project quality and contribution standards:
```
golangci-lint run
```
```
go mod vendor
```
```
go test -mod=vendor -v ./...
```

Commit your changes and push your branch to GitHub:

git add .

We recommend following conventional commits messages

git commit -m "feat(CLI): add new flag --blabla"

git push --set-upstream origin <name-of-your-issue>

Submit a pull request on GitHub website.

If the changes do not pass the pipeline, we recommend following the steps outlined here, which cover some common cases.

How to Contribute¶

Contributions are made to this repo via Issues and Pull Requests (PRs). A few general guidelines that cover both:

Search for existing issues and pull requests before creating your own to avoid duplicates.
PRs will only be accepted if associated with an issue (enhancement or bug) that has been submitted and reviewed/labeled as accepted.
We will work hard to make sure issues that are raised are handled in a timely manner.

Issues¶

Issues should be used to report problems with the solution / source code, request a new feature, or to discuss potential changes before a PR is created. When you create a new Issue, a template will be loaded that will guide you through collecting and providing the information we need to investigate.

If you find an Issue that addresses the problem you're having, please add your own reproduction information to the existing issue rather than creating a new one. Adding a reaction can also help by indicating to our maintainers that a particular problem is affecting more than just the reporter.

Pull Requests¶

Pull Requests (PRs) are always welcome and can be a quick way to get your fix or improvement slated for the next release. In general, PRs should:

Only fix/add the functionality in question or address code style issues, not both.
Ensure all necessary details are provided and adhered to.
Add unit or integration tests for fixed or changed functionality (if a test suite already exists) or specify steps taken to ensure changes were tested and functionality works as expected.
Address a single concern in the least number of changed lines as possible.
Include documentation in the repo or Provide additional comments in Markdown comments that should be pulled/reflected in GitHub Wiki for the given project.
Be accompanied by a complete Pull Request template (loaded automatically when a PR is created).

For changes that address core functionality or would require breaking changes (e.g. a major release), please open an Issue to discuss your proposal first.

Pull Request Guidelines¶

Before you submit a pull request, please reassure that it meets these guidelines:

All validations and tests passed locally.
The pull request includes tests.
The relevant docs are updated, whether you're pushing new functionality or updating a query.
The pull request title should follow conventional commit messages:

<type>(<scope>): <subject> where (<scope>) is optional

feat - A new feature (example scopes: engine, parser, flags, query)
fix - A bug fix
docs - Documentation only changes, (example scopes: catalog, guides, platforms, architecture)
test - Adding missing tests or correcting existing tests (example scopes: unit, e2e)
ci - Changes to our CI configuration files and scripts (example scopes: ghactions, linters)
chore - Other changes that don't modify src or test files
build - Changes that affect the build system or external dependencies (example scope: makefile)
style - Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
refactor - A code change that neither fixes a bug nor adds a feature
perf - A code change that improves performance
revert - Reverts a previous commit

e.g: build(makefile): enhance make clean task

Templates¶

The following templates will be used when creating a new issue:

Enhancement/Feature Request Template
New (Approved) Feature Template
Query Template
Bug Report Template

Resources¶

Join the GitHub discussions. Or contact KICS core team at kics@checkmarx.com

And become one of our top contributors!

Tips¶

Github Actions failing on E2E tests¶

If an E2E test causes failures in Github actions, the recommended steps are:

Open the action that causes failure.
Go to Summary tab.
On the Summary page, go to the bottom of the page and download any artifact that does not have a .dockerbuild extension.
Extract the e2e-report and open the HTML in a browser.
Filter the tests to display only those that failed.
Check which test is causing the issue (e.g., E2E-CLI-032) and review the error description (e.g. number of lines not matching the expected value).
Navigate to the e2e/testcases directory on KICS github repository and open the Go file corresponding to the failing test (e.g. e2e-cli-032_scan_output-path_validate_json.go).
Manually run a scan using the arguments provided in the file. Example for E2E-CLI-032:
```
go run .\cmd\console\main.go scan -o "/path/e2e/output" --output-name "E2E_CLI_032_RESULT" -p "/path/e2e/fixtures/samples/positive.yaml"
```
Here, /path/e2e/output is where the scan results will be stored, and /path/e2e/fixtures/samples/positive.yaml is the input file that should be used by replacing path with the path to positive.yaml on your local machine.
Navigate to the path specified by the -o flag and compare the generated file with the version in the fixtures directory of the KICS repository.
Merge the generated file or add any missing data to the original file in the repository. Example: paste the generated E2E_CLI_032_RESULT into e2e/fixtures/e2e/E2E_CLI_032_RESULT.json.
Correct the path, to /path/e2e/fixtures/samples/positive.yaml, if it currently points to a local machine directory. Example: change C:\Users\john\Desktop\kics\e2e\fixtures\samples\positive.yaml to /path/e2e/fixtures/samples/positive.yaml.
Commit and push the changes.

GitGuard Security Checks failing on the pipeline¶

If the pipeline fails when submitting a Pull Request, it may be due to GitGuard detecting a secret. In such cases, the KICS team will review the detected secret. If the secret is confirmed to be used only for testing purposes, the action will be marked as a False Positive and can be safely ignored.

Flaky tests¶

There is a known set of tests that are considered flaky. These tests may fail intermittently due to timming issues, external dependencies or environment-specific conditions, rather than actual problems on the code. The team is aware of these cases and continues to monitor and improve them.

Below is a list of currently identified flaky tests:

CycloneDX
analyserPaths

Tests that compare terminal output are particularly prone to flakiness. Typically, a flacky test is detected when, for the unit tests, it passes for some of the operating systems but, for one in specific it does not. Normally, for this cases it's a flacky test, and the KICS team should re-run the actions.

Unit tests¶

When a unit test fails in the KICS pipeline, there are two recommended approaches:

Open the failing unit-test page, go to Test and Generate Report Dev, wait for the report to generate, then search for FAIL: to identify the issue.
Alternatively, access the Summary tab, download the artifact that includes the failing OS in its name (or any artifact if all OS tests fail), open it, and search for FAIL: or the name of the query (e.g., user_data_contains_encoded_private_key).

Unit test failures can occur due to incorrectly defined lines in positive_expected_result.json or missing tests in that file.

Grype or Trivy tests failing¶

Sometimes the KICS pipelines may fail due to issues in the Grype and Trivy tests. In such cases, it might be sufficient to just update a package version on the go.mod file. For such cases here are the recommended steps:

Open the action that is currently failing.
Go to the Summary tab on the top left corner.
Go to the Grype docker image scan or Trivy docker image scan jobs.
Download the artifact trivy-fs-scan-results or similar.
Open the results.txt file and check if there is any table that suggests which version of the package is causing the problem.
After that, go to the go.mod file that is on the root of the repository, change the version of the package to the version that is suggested on the file results.txt downloaded, under "fixed version".
Run go mod tidy.
Run go mod vendor.
Commit and push the changes.

NOTE: This is only a solution to solve the cases when the results provide a package that is on go.mod file and has a recommended fixed version. In some cases, there is no recommended version for the package on the results.txt or the package/library mentioned on the file is not on the go.mod file. For these cases, the typical solution is to update the image defined in the Dockerfile.

To check for the latest images available, you can refer to dockerhub checkmarx community organization

Special thanks to Lior Kaplan from Kaplan Open Source Consulting for his assistance in creating KICS.