cycode 0.2.1

Perform secrets/iac scans for your sources using Cycode's engine

Cycode CLI User Guide

The Cycode Command Line Interface (CLI) is an application you can install on your local machine which can scan your locally stored repositories for any secrets or infrastructure as code misconfigurations.

This guide will guide you through both installation and usage.

Prerequisites

• The Cycode CLI application requires Python version 3.8 or later.
• Use the cycode auth command to authenticate to Cycode with the CLI
  • Alternatively, a Cycode Client ID and Client Secret Key can be acquired using the steps from the Service Account Token and Personal Access Token pages for details on obtaining these values.

Installation

The following installation steps are applicable on both Windows and UNIX / Linux operating systems.

:memo: Note
The following steps assume the use of python3 and pip3 for Python-related commands, but some systems may instead use the python and pip commands, depending on your Python environment’s configuration.

Install Cycode CLI

To install the Cycode CLI application on your local machine, perform the following steps:

1. Open your command line or terminal application.

2. Execute the following command:

   pip3 install cycode

3. Navigate to the top directory of the local repository you wish to scan.

4. There are three methods to set the Cycode client ID and client secret:

   • cycode auth (Recommended)
   • cycode configure
   • Add them to your environment variables

Use auth Command

:memo: Note
This is the recommended method for setting up your local machine to authenticate with Cycode CLI.

1. Type the following command into your terminal/command line window:

   cycode auth

2. A browser window will appear, asking you to log into Cycode (as seen below):

3. Enter you login credentials on this page and log in.

4. You will eventually be taken to this page, where you will be asked to choose the business group you want to authorize Cycode with (if applicable):

:memo: Note
This will be the default method for authenticating with the Cycode CLI.

5. Click the Allow button to authorize the Cycode CLI on the chosen business group.

6. Once done, you will see the following screen, if it was successfully selected:

7. In the terminal/command line screen, you will see the following when exiting the browser window:

Successfully logged into cycode

Use configure Command

:memo: Note
If you already setup your Cycode client ID and client secret through the Linux or Windows environment variables, those credentials will take precedent over this method

1. Type the following command into your terminal/command line window:

   cycode configure

   You will see the following appear:

   Update credentials in file (/Users/travislloyd/.cycode/credentials.yaml)
   cycode client id []:
   

2. Enter your Cycode client ID value.

   cycode client id []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d
   

3. Enter your Cycode client secret value.

   cycode client secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e
   

4. If the values were entered successfully, you will see the following message:

   Successfully configured CLI credentials!
   

If you go into the .cycode folder under you user folder, you will find these credentials were created and placed in the credentials.yaml file in that folder.

Add to Environment Variables

On Unix/Linux:

export CYCODE_CLIENT_ID={your Cycode ID}
export CYCODE_CLIENT_SECRET={your Cycode Secret Key}

On Windows

1. From the Control Panel, navigate to the System menu:

2. Next, click Advanced system settings:

3. In the System Properties window that opens, click the Environment Variables button:

4. Create CYCODE_CLIENT_ID and CYCODE_CLIENT_SECRET variables with values matching your ID and Secret Key, respectively:

Install Pre-Commit Hook

Cycode’s pre-commit hook can be set up within your local repository so that the Cycode CLI application will automatically identify any issues with your code before you commit it to your codebase.

Perform the following steps to install the pre-commit hook:

1. Install the pre-commit framework:

   pip3 install pre-commit

2. Navigate to the top directory of the local repository you wish to scan.

3. Create a new YAML file named .pre-commit-config.yaml (include the beginning .) in the repository’s top directory that contains the following:

repos:
  - repo: https://github.com/cycodehq-public/cycode-cli
    rev: 0.1.6
    hooks:
      - id: cycode
        language_version: python3
        stages:
          - commit

4. Install Cycode’s hook:

   pre-commit install

:memo: Note
Successful hook installation will result in the message:
Pre-commit installed at .git/hooks/pre-commit

Pre-receive Hook

Prerequisites

1. Install Cycode CLI on your Git server - Install the Cycode CLI by running pip3 install cycode --user. Check that the CLI installed successfully by running cycode. If you get cycode: command not found, you need to add the installation path to the PATH environment variable.
2. Cycode service account

Instructions

Install for a specific repository

1. Find the repository location in the Git server instance.

   • For GitLab Enterprise: Git server hooks | GitLab

2. Create the pre-receive hook.

   • Create a new file in the repository's Git hook location under the repository location you found in step 1, and name it pre-receive.

   • Copy the following script to the pre-recive file:

     #!/bin/sh
     
     # optional
     # Update the server URL only if you have Cycode self managed
     # export CYCODE_API_URL = "<cycode server url>"
     export CYCODE_CLIENT_ID="<client_id>"
     export CYCODE_CLIENT_SECRET="<client_secret>"
     
     set -e
     cycode scan pre_receive
     

   • Make the file executable by running chmod +x pre-receive.

   • Change the file owner and owner group to git user:

     • chown git pre-receive (change file owner).
     • chgrp git pre-receive (change file group owner).
     • Verify it by running ls -l. The output should be -rwxr-xr-x 1 git git 662 Mar 2 09:15 pre-receive (first git is the file's owner, second git is the file's group owner).

3. Configure the Cycode token.

   • There are two methods to set it:
     • In the script above, fill in the client ID and secret.
     • Set environment variables on the instance.

4. [Optional] Update Cycode API url (relevant only for on-prem customers) - Update CYCODE_API_URL in the pre-receive file.

Install pre-recive hook globaly (For all the repositories)

1. Set the global hooks directory in the Git server instance.

   • For GitLab Enterprise (https://docs.gitlab.com/ee/administration/server_hooks.html#create-global-server-hooks-for-all-repositories) :
     • Set in /etc/gitlab/gitlab.rb the gitaly['custom_hooks_dir'] value or just use the default location by uncommenting it.
     • Run gitlab-ctl reconfigure.
     • Follow the steps here

2. Add the pre-receive hook according to the Git server requirements.

   • For GitLab Enterprise:
     • Go to the directory and create a directory named pre-receive.d.
     • Inside the directory, follow the steps of "Install for a specific repository" above.

Skipping the pre-receive hook

Cycode's pre-receive hook can be skipped easily by adding -o skip-cycode-scan to the git push command.

Notice: Verify that the option receive.advertisePushOptions is enabled in the instance Git configuration. For enabling it, run git config receive.advertisePushOptions true. It seems that in GitLab, it's enabled by default.

Cycode Command

The following are the options and commands available with the Cycode CLI application:

Option	Description
-v, --verbose	Show detailed logs
--version	Show the version and exit.
--help	Show options for given command.

Command	Description
auth	Authenticates your machine to associate CLI with your cycode account.
configure	Initial command to authenticate your CLI client with Cycode using client ID and client secret.
ignore	Ignore a specific value, path or rule ID
scan	Scan content for secrets/IaC violations, You need to specify which scan type: ci/commit_history/path/repository/etc

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:

Option	Description
-t, --scan-type [secret|iac]	Specify the scan you wish to execute (secret/iac), the default is secret
--secret TEXT	Specify a Cycode client secret for this specific scan execution
--client-id TEXT	Specify a Cycode client ID for this specific scan execution
--show-secret BOOLEAN	Show secrets in plain text. See Show/Hide Secrets section for more details.
--soft-fail BOOLEAN	Run scan without failing, always return a non-error status code. See Soft Fail section for more details.
--help	Show options for given command.

Command	Description
commit_history	Scan all the commits history in this git repository
path	Scan the files in the path supplied in the command
pre_commit	Use this command to scan the content that was not committed yet
repository	Scan git repository including its history

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 currently exposed secrets within the repository but previously deleted secrets as well.

To execute a full repository scan, execute the following:

cycode scan repository {{path}}

For example, consider a scenario in which you want to scan your repository stored in ~/home/git/codebase. You could then execute the following:

cycode scan repository ~/home/git/codebase

The following option is available for use with this command:

Option	Description
-b, --branch TEXT	Branch to scan, if not set scanning the default branch

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.

Consider the previous example. If you wanted to only scan a branch named dev, you could execute the following:

cycode scan repository ~/home/git/codebase -b dev

or:

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

Path Scan

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

To execute a directory scan, execute the following:

cycode scan path {{path}}

For example, consider a scenario in which you want to scan the directory located at ~/home/git/codebase. You could then execute the following:

cycode scan path ~/home/git/codebase

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.

To execute a commit history scan, execute the following:

cycode scan commit_history {{path}}

For example, consider a scenario in which you want to scan the commit history for a repository stored in ~/home/git/codebase. You could then execute the following:

cycode scan commit_history ~/home/git/codebase

The following option is available for use with this command:

Option	Description
-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

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.

Consider the previous example. If you wanted to scan only specific commits on your repository, you could execute the following:

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

OR

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

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

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

If no secrets or misconfigurations are found, the scan ends with the following success message:

Good job! No issues were found!!! 👏👏👏

If a secret or misconfiguration is found, a Found issue of type: message appears upon completion instead:

⛔  Found issue of type: generic-password (rule ID: ce3a4de0-9dfc-448b-a004-c538cf8b4710) in file: config/my_config.py
Secret SHA: a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0  ⛔
0 | @@ -0,0 +1 @@
1 | +my_password = 'h3l***********350'
2 | \ No newline at end of file

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

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.

Note how the above example obscures the actual secret value, replacing most of the secret with asterisks. Scans obscure secrets by default, but you may optionally disable this feature in order to view the full secret (assuming the machine you are viewing the scan result on is sufficiently secure from prying eyes).

To disable secret obfuscation, add the --show-secret argument to any type of scan, then assign it a 1 value to show the full secret in the result message, or 0 to hide the secret (which is done by default).

In the following example, a Path Scan is executed against the cli subdirectory with the option enabled to display any secrets found in full:

cycode scan --show-secret=1 path ./cli

The result would then not be obfuscated:

⛔  Found issue of type: generic-password (rule ID: ce3a4de0-9dfc-448b-a004-c538cf8b4710) in file: config/my_config.py
Secret SHA: a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0  ⛔
0 | @@ -0,0 +1 @@
1 | +my_password = 'h3110w0r1d!@#$350'
2 | \ No newline at end of file

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).

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.

:warning: Warning
Adding values to be ignored should be done with careful consideration of the values, paths, and policies to ensure that the scans will pick up true positives. The following are the options available for the cycode ignore command:

Option	Description
--by-value TEXT	Ignore a specific value while scanning for secrets. See Ignoring a Secret Value for more details.
--by-sha TEXT	Ignore a specific SHA512 representation of a string while scanning for secrets. See Ignoring a Secret SHA Value for more details.
--by-path TEXT	Avoid scanning a specific path. Need to specify scan type. See Ignoring a Path for more details.
--by-rule TEXT	Ignore scanning a specific secret rule ID/IaC rule ID. See Ignoring a Secret or Iac Rule for more details.
-t, --scan-type [secret|iac]	The scan you wish to run, The default value is secret
-g, --global	Add an ignore rule and update it in the global .cycode config file

In the following example, a pre-commit scan runs and finds the following:

⛔  Found issue of type: generic-password (rule ID: ce3a4de0-9dfc-448b-a004-c538cf8b4710) in file: config/my_config.py
Secret SHA: a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0  ⛔
0 | @@ -0,0 +1 @@
1 | +my_password = 'h3l***********350'
2 | \ No newline at end of file

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, SHA512 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

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:

cycode ignore --by-value {{secret-value}}

In the example at the top of this section, the command to ignore a specific secret value is as follows:

cycode ignore --by-value h3110w0r1d!@#$350

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

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:

cycode ignore --by-sha {{secret-sha-value}}

In the example at the top of this section, the command to ignore a specific secret SHA value is as follows:

cycode ignore --by-sha a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0

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

Ignoring a Path

To ignore a specific path for either secret or IaC 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:

cycode ignore -t {{scan-type}} --by-path {{path}}

OR

cycode ignore --scan-type {{scan-type}} --by-path {{path}}

In the example at the top of this section, the command to ignore a specific path for a secret is as follows:

cycode ignore -t secret --by-path ~/home/my-repo/config

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

In the example at the top of this section, the command to ignore a specific path from IaC scans is as follows:

cycode ignore -t iac --by-path ~/home/my-repo/config

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

Ignoring a Secret or IaC Rule

To ignore a specific secret or IaC 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:

cycode ignore -t {{scan-type}} --by-rule {{rule-ID}}

OR

cycode ignore --scan-type {{scan-type}} --by-rule {{rule-ID}}

In the example at the top of this section, the command to ignore the specific secret rule ID is as follows:

cycode ignore --scan-type secret --by-rule ce3a4de0-9dfc-448b-a004-c538cf8b4710

In the example above, replace the ce3a4de0-9dfc-448b-a004-c538cf8b4710 value with the rule ID you want to ignore.

In the example at the top of this section, the command to ignore the specific secret rule ID is as follows:

cycode ignore --scan-type iac --by-rule bdaa88e2-5e7c-46ff-ac2a-29721418c59c

In the example above, replace the bdaa88e2-5e7c-46ff-ac2a-29721418c59c value with the rule ID you want to ignore.

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.

To see general help, simply enter the command:

cycode --help

To see scan options, enter:

cycode scan --help

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

cycode scan {{option}} --help

For example, to see options available for a Path Scan, you would simply enter:

cycode scan path --help

To see the options available for the ignore scan function, use this command:

cycode ignore --help