Skip to content

CM-28234 - Add SBOM report to the readme #171

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 19, 2023
Merged

CM-28234 - Add SBOM report to the readme #171

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 110 additions & 56 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,35 +15,39 @@ This guide will guide you through both installation and usage.
1. [On Unix/Linux](#on-unixlinux)
2. [On Windows](#on-windows)
2. [Install Pre-Commit Hook](#install-pre-commit-hook)
3. [Cycode Command](#cycode-command)
4. [Running a Scan](#running-a-scan)
1. [Repository Scan](#repository-scan)
1. [Branch Option](#branch-option)
2. [Monitor Option](#monitor-option)
3. [Report Option](#report-option)
4. [Package Vulnerabilities Scan](#package-vulnerabilities-option)
1. [License Compliance Option](#license-compliance-option)
2. [Severity Threshold](#severity-threshold)
5. [Path Scan](#path-scan)
1. [Terraform Plan Scan](#terraform-plan-scan)
6. [Commit History Scan](#commit-history-scan)
1. [Commit Range Option](#commit-range-option)
7. [Pre-Commit Scan](#pre-commit-scan)
5. [Scan Results](#scan-results)
1. [Show/Hide Secrets](#showhide-secrets)
2. [Soft Fail](#soft-fail)
3. [Example Scan Results](#example-scan-results)
1. [Secrets Result Example](#secrets-result-example)
2. [IaC Result Example](#iac-result-example)
3. [SCA Result Example](#sca-result-example)
4. [SAST Result Example](#sast-result-example)
6. [Ignoring Scan Results](#ignoring-scan-results)
1. [Ignoring a Secret Value](#ignoring-a-secret-value)
2. [Ignoring a Secret SHA Value](#ignoring-a-secret-sha-value)
3. [Ignoring a Path](#ignoring-a-path)
4. [Ignoring a Secret, IaC, or SCA Rule](#ignoring-a-secret-iac-sca-or-sast-rule)
5. [Ignoring a Package](#ignoring-a-package)
7. [Syntax Help](#syntax-help)
3. [Cycode Command](#cycode-cli-commands)
4. [Scan Command](#scan-command)
1. [Running a Scan](#running-a-scan)
1. [Repository Scan](#repository-scan)
1. [Branch Option](#branch-option)
2. [Monitor Option](#monitor-option)
3. [Report Option](#report-option)
4. [Package Vulnerabilities Scan](#package-vulnerabilities-option)
1. [License Compliance Option](#license-compliance-option)
2. [Severity Threshold](#severity-threshold)
5. [Path Scan](#path-scan)
1. [Terraform Plan Scan](#terraform-plan-scan)
6. [Commit History Scan](#commit-history-scan)
1. [Commit Range Option](#commit-range-option)
7. [Pre-Commit Scan](#pre-commit-scan)
2. [Scan Results](#scan-results)
1. [Show/Hide Secrets](#showhide-secrets)
2. [Soft Fail](#soft-fail)
3. [Example Scan Results](#example-scan-results)
1. [Secrets Result Example](#secrets-result-example)
2. [IaC Result Example](#iac-result-example)
3. [SCA Result Example](#sca-result-example)
4. [SAST Result Example](#sast-result-example)
3. [Ignoring Scan Results](#ignoring-scan-results)
1. [Ignoring a Secret Value](#ignoring-a-secret-value)
2. [Ignoring a Secret SHA Value](#ignoring-a-secret-sha-value)
3. [Ignoring a Path](#ignoring-a-path)
4. [Ignoring a Secret, IaC, or SCA Rule](#ignoring-a-secret-iac-sca-or-sast-rule)
5. [Ignoring a Package](#ignoring-a-package)
5. [Report command](#report-command)
1. [Generating Report](#generating-report)
2. [Report Result](#report-results)
6. [Syntax Help](#syntax-help)

# Prerequisites

Expand Down Expand Up @@ -226,9 +230,12 @@ The following are the options and commands available with the Cycode CLI applica
| [configure](#use-configure-command) | Initial command to authenticate your CLI client with Cycode using client ID and client secret. |
| [ignore](#ingoring-scan-results) | Ignore a specific value, path or rule ID. |
| [scan](#running-a-scan) | Scan content for secrets/IaC/SCA/SAST violations. You need to specify which scan type: `ci`/`commit_history`/`path`/`repository`/etc. |
| [report](#running-a-report) | Generate report for SCA SBOM. |
| version | Show the version and exit. |

# Running a Scan
# Scan Command

## Running a Scan

The Cycode CLI application offers several types of scans so that you can choose the option that best fits your case. The following are the current options and commands available:

Expand All @@ -253,7 +260,7 @@ The Cycode CLI application offers several types of scans so that you can choose
| [pre_commit](#pre-commit-scan) | Use this command to scan the content that was not committed yet |
| [repository](#repository-scan) | Scan git repository including its history |

## Repository Scan
### Repository Scan

A repository scan examines an entire local repository for any exposed secrets or insecure misconfigurations. This more holistic scan type looks at everything: the current state of your repository and its commit history. It will look not only for secrets that are currently exposed within the repository but previously deleted secrets as well.

Expand All @@ -271,7 +278,7 @@ The following option is available for use with this command:
|---------------------|-------------|
| `-b, --branch TEXT` | Branch to scan, if not set scanning the default branch |

### Branch Option
#### Branch Option

To scan a specific branch of your local repository, add the argument `-b` (alternatively, `--branch`) followed by the name of the branch you wish to scan.

Expand All @@ -283,7 +290,7 @@ or:

`cycode scan repository ~/home/git/codebase --branch dev`

## Monitor Option
### Monitor Option

> :memo: **Note**<br/>
> This option is only available to SCA scans.
Expand All @@ -303,7 +310,7 @@ When using this option, the scan results from this scan will appear in the knowl
> :warning: **NOTE**<br/>
> You must be an `owner` or an `admin` in Cycode to view the knowledge graph page.

## Report Option
### Report Option

> :memo: **Note**<br/>
> This option is only available to SCA scans.
Expand Down Expand Up @@ -366,7 +373,7 @@ The report page will look something like below:

![](https://raw.githubusercontent.com/cycodehq-public/cycode-cli/main/images/scan_details.png)

## Package Vulnerabilities Option
### Package Vulnerabilities Option

> :memo: **Note**<br/>
> This option is only available to SCA scans.
Expand All @@ -381,7 +388,7 @@ or:

`cycode scan --scan-type sca --sca-scan package-vulnerabilities repository ~/home/git/codebase`

### License Compliance Option
#### License Compliance Option

> :memo: **Note**<br/>
> This option is only available to SCA scans.
Expand All @@ -396,7 +403,7 @@ or:

`cycode scan --scan-type sca --sca-scan license-compliance repository ~/home/git/codebase`

### Severity Threshold
#### Severity Threshold

> :memo: **Note**<br/>
> This option is only available to SCA scans.
Expand All @@ -411,7 +418,7 @@ or:

`cycode scan --scan-type sca --security-threshold MEDIUM repository ~/home/git/codebase`

## Path Scan
### Path Scan

A path scan examines a specific local directory and all the contents within it, instead of focusing solely on a GIT repository.

Expand All @@ -424,7 +431,7 @@ For example, consider a scenario in which you want to scan the directory located
`cycode scan path ~/home/git/codebase`


### Terraform Plan Scan
#### Terraform Plan Scan

Cycode CLI supports Terraform plan scanning (supporting Terraform 0.12 and later)

Expand Down Expand Up @@ -453,7 +460,7 @@ _How to generate a Terraform plan from Terraform configuration file?_
`cycode scan -t iac path ~/PATH/TO/YOUR/{tfplan}.json`


## Commit History Scan
### Commit History Scan

A commit history scan is limited to a local repository’s previous commits, focused on finding any secrets within the commit history, instead of examining the repository’s current state.

Expand All @@ -471,7 +478,7 @@ The following options are available for use with this command:
|---------------------------|-------------|
| `-r, --commit_range TEXT` | Scan a commit range in this git repository, by default cycode scans all commit history (example: HEAD~1) |

### Commit Range Option
#### Commit Range Option

The commit history scan, by default, examines the repository’s entire commit history, all the way back to the initial commit. You can instead limit the scan to a specific commit range by adding the argument `--commit_range` followed by the name you specify.

Expand All @@ -483,15 +490,15 @@ OR

`cycode scan commit_history --commit_range {{from-commit-id}}...{{to-commit-id}} ~/home/git/codebase`

## Pre-Commit Scan
### Pre-Commit Scan

A pre-commit scan automatically identifies any issues before you commit changes to your repository. There is no need to manually execute this scan; simply configure the pre-commit hook as detailed under the Installation section of this guide.

After your install the pre-commit hook and, you may, on occasion, wish to skip scanning during a specific commit. Simply add the following to your `git` command to skip scanning for a single commit:

`SKIP=cycode git commit -m <your commit message>`

# Scan Results
## Scan Results

Each scan will complete with a message stating if any issues were found or not.

Expand All @@ -511,7 +518,7 @@ Secret SHA: a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0

In the event an issue is found, review the file in question for the specific line highlighted by the result message. Implement any changes required to resolve the issue, then execute the scan again.

## Show/Hide Secrets
### Show/Hide Secrets

In the above example, a secret was found in the file `secret_test`, located in the subfolder `cli`. The second part of the message shows the specific line the secret appears in, which in this case is a value assigned to `googleApiKey`.

Expand All @@ -533,15 +540,15 @@ Secret SHA: a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0
2 | \ No newline at end of file
```

## Soft Fail
### Soft Fail

Utilizing the soft fail feature will not fail the CI/CD step within the pipeline if the Cycode scan finds an issue. Additionally, in case an issue occurs from Cycode’s side, a soft fail will automatically execute to avoid interference.

Add the `--soft-fail` argument to any type of scan to configure this feature, then assign a value of `1` if you want found issues to result in a failure within the CI/CD tool or `0` for scan results to have no impact (result in a `success` result).

## Example Scan Results
### Example Scan Results

### Secrets Result Example
#### Secrets Result Example

```bash
⛔ Found issue of type: generic-password (rule ID: ce3a4de0-9dfc-448b-a004-c538cf8b4710) in file: config/my_config.py
Expand All @@ -551,7 +558,7 @@ Secret SHA: a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0
2 | \ No newline at end of file
```

### IaC Result Example
#### IaC Result Example

```bash
⛔ Found issue of type: Resource should use non-default namespace (rule ID: bdaa88e2-5e7c-46ff-ac2a-29721418c59c) in file: ./k8s/k8s.yaml ⛔
Expand All @@ -561,7 +568,7 @@ Secret SHA: a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0
9 | resourceVersion: "4228"
```

### SCA Result Example
#### SCA Result Example

```bash
⛔ Found issue of type: Security vulnerability in package 'pyyaml' referenced in project 'Users/myuser/my-test-repo': Improper Input Validation in PyYAML (rule ID: d003b23a-a2eb-42f3-83c9-7a84505603e5) in file: Users/myuser/my-test-repo/requirements.txt ⛔
Expand All @@ -571,7 +578,7 @@ Secret SHA: a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0
3 | cleo==1.0.0a5
```

### SAST Result Example
#### SAST Result Example

```bash
⛔ Found issue of type: Detected a request using 'http://'. This request will be unencrypted, and attackers could listen into traffic on the network and be able to obtain sensitive information. Use 'https://' instead. (rule ID: 3fbbd34b-b00d-4415-b9d9-f861c076b9f2) in file: ./requests.py ⛔
Expand All @@ -581,7 +588,7 @@ Secret SHA: a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0
4 | print(res.content)
```

# Ignoring Scan Results
## Ignoring Scan Results

Ignore rules can be added to ignore specific secret values, specific SHA512 values, specific paths, and specific Cycode secret and IaC rule IDs. This will cause the scan to not alert these values. The ignore rules are written and saved locally in the `./.cycode/config.yaml` file.

Expand Down Expand Up @@ -612,7 +619,7 @@ Secret SHA: a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0

If this is a value that is not a valid secret, then use the the `cycode ignore` command to ignore the secret by its value, SHA value, specific path, or rule ID. If this is an IaC scan, then you can ignore that result by its path or rule ID.

## Ignoring a Secret Value
### Ignoring a Secret Value

To ignore a specific secret value, you will need to use the `--by-value` flag. This will ignore the given secret value from all future scans. Use the following command to add a secret value to be ignored:

Expand All @@ -624,7 +631,7 @@ In the example at the top of this section, the command to ignore a specific secr

In the example above, replace the `h3110w0r1d!@#$350` value with your non-masked secret value. See the Cycode scan options for details on how to see secret values in the scan results.

## Ignoring a Secret SHA Value
### Ignoring a Secret SHA Value

To ignore a specific secret SHA value, you will need to use the `--by-sha` flag. This will ignore the given secret SHA value from all future scans. Use the following command to add a secret SHA value to be ignored:

Expand All @@ -636,7 +643,7 @@ In the example at the top of this section, the command to ignore a specific secr

In the example above, replace the `a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0` value with your secret SHA value.

## Ignoring a Path
### Ignoring a Path

To ignore a specific path for either secret, IaC, or SCA scans, you will need to use the `--by-path` flag in conjunction with the `-t, --scan-type` flag (you must specify the scan type). This will ignore the given path from all future scans for the given scan type. Use the following command to add a path to be ignored:

Expand Down Expand Up @@ -664,7 +671,7 @@ In the example at the top of this section, the command to ignore a specific path

In the example above, replace the `~/home/my-repo/config` value with your path value.

## Ignoring a Secret, IaC, SCA, or SAST Rule
### Ignoring a Secret, IaC, SCA, or SAST Rule

To ignore a specific secret, IaC, SCA, or SAST rule, you will need to use the `--by-rule` flag in conjunction with the `-t, --scan-type` flag (you must specify the scan type). This will ignore the given rule ID value from all future scans. Use the following command to add a rule ID value to be ignored:

Expand Down Expand Up @@ -692,7 +699,7 @@ In the example at the top of this section, the command to ignore the specific SC

In the example above, replace the `dc21bc6b-9f4f-46fb-9f92-e4327ea03f6b` value with the rule ID you want to ignore.

## Ignoring a Package
### Ignoring a Package

> :memo: **Note**<br/>
> This option is only available to the SCA scans.
Expand All @@ -711,6 +718,44 @@ In the example below, the command to ignore a specific SCA package is as follows

In the example above, replace `pyyaml` with package name and `5.3.1` with the package version you want to ignore.

# Report Command

## Generating SBOM Report

A software bill of materials (SBOM) is an inventory of all constituent components and software dependencies involved in the development and delivery of an application.
Using this command you can create an SBOM report for your local project or for your repository URI.

The following options are available for use with this command:
| Option | Description | Required | Default |
|---------------------|-------------|----------|---------|
| `-f, --format [spdx-2.2\|spdx-2.3\|cyclonedx-1.4]` | SBOM format | Yes | |
| `-o, --output-format [JSON]` | Specify the output file format | No | json |
| `--output-file PATH` | Output file | No | autogenerated filename saved to the current directory |
| `--include-vulnerabilities` | Include vulnerabilities | No | False |
| `--include-dev-dependencies` | Include dev dependencies | No | False |

The following commands are available for use with this command:
| Command | Description |
|---------------------|-------------|
| `path` | Generate SBOM report for provided path in the command |
| `repository_url` | Generate SBOM report for provided repository URI in the command |

### Repository

To create an SBOM report for a repository URI:\
`cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> repository_url <repository url>`

For example:\
`cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies repository_url https://github.com/cycodehq-public/cycode-cli.git`

### Local Project

To create an SBOM report for a path:\
`cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> path </path/to/project>`

For example:\
`cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies path /path/to/local/project`

# Syntax Help

You may add the `--help` argument to any command at any time to see a help message that will display available options and their syntax.
Expand All @@ -734,3 +779,12 @@ For example, to see options available for a Path Scan, you would simply enter:
To see the options available for the ignore scan function, use this command:

`cycode ignore --help`

To see the options available for report, use this command:

`cycode report --help`


To see the options available for a specific type of report, enter:

`cycode scan {{option}} --help`