CM-45588 - Improve --help

.github/workflows/build_executable.yml

@@ -166,6 +166,7 @@ jobs:
         shell: cmd
         env:
           SM_HOST: ${{ secrets.SM_HOST }}
+          SM_KEYPAIR_ALIAS: ${{ secrets.SM_KEYPAIR_ALIAS }}
           SM_API_KEY: ${{ secrets.SM_API_KEY }}
           SM_CLIENT_CERT_PASSWORD: ${{ secrets.SM_CLIENT_CERT_PASSWORD }}
           SM_CODE_SIGNING_CERT_SHA1_HASH: ${{ secrets.SM_CODE_SIGNING_CERT_SHA1_HASH }}
@@ -174,7 +175,7 @@ jobs:
           curl -X GET  https://one.digicert.com/signingmanager/api-ui/v1/releases/smtools-windows-x64.msi/download -H "x-api-key:%SM_API_KEY%" -o smtools-windows-x64.msi 
           msiexec /i smtools-windows-x64.msi /quiet /qn
           C:\Windows\System32\certutil.exe -csp "DigiCert Signing Manager KSP" -key -user
-          smksp_cert_sync.exe
+          smctl windows certsync --keypair-alias=%SM_KEYPAIR_ALIAS%
 
           :: sign executable
           signtool.exe sign /sha1 %SM_CODE_SIGNING_CERT_SHA1_HASH% /tr http://timestamp.digicert.com /td SHA256 /fd SHA256 ".\dist\cycode-cli.exe" 

.pre-commit-hooks.yaml

@@ -3,10 +3,10 @@
   language: python
   language_version: python3
   entry: cycode
-  args: [ '--no-progress-meter', 'scan', '--scan-type', 'secret', 'pre_commit' ]
+  args: [ '--no-progress-meter', 'scan', '--scan-type', 'secret', 'pre-commit' ]
 - id: cycode-sca
   name: Cycode SCA pre-commit defender
   language: python
   language_version: python3
   entry: cycode
-  args: [ '--no-progress-meter', 'scan', '--scan-type', 'sca', 'pre_commit' ]
+  args: [ '--no-progress-meter', 'scan', '--scan-type', 'sca', 'pre-commit' ]

CONTRIBUTING.md

@@ -11,7 +11,7 @@ But it’s fine to use a higher version without using new features from these ve
 The project is under Poetry project management.
 To deal with it, you should install it on your system:
 
-Install Poetry (feel free to use Brew, etc):
+Install Poetry (feel free to use Brew, etc.):
 
 ```shell
 curl -sSL https://install.python-poetry.org | python - -y
@@ -70,6 +70,8 @@ poetry run ruff format .
 
 Many rules support auto-fixing. You can run it with the `--fix` flag.
 
+Plugin for JB IDEs with auto formatting on save is available [here](https://plugins.jetbrains.com/plugin/20574-ruff).
+
 ### Branching and versioning
 
 We use the `main` branch as the main one.

README.md

@@ -281,7 +281,7 @@ The following are the options and commands available with the Cycode CLI applica
 | [auth](#using-the-auth-command)           | Authenticate your machine to associate the CLI with your Cycode account.                                                                     |
 | [configure](#using-the-configure-command) | Initial command to configure your CLI client authentication.                                                                                 |
 | [ignore](#ignoring-scan-results)          | Ignores a specific value, path or rule ID.                                                                                                   |
-| [scan](#running-a-scan)                   | Scan the content for Secrets/IaC/SCA/SAST violations. You`ll need to specify which scan type to perform: commit_history/path/repository/etc. |
+| [scan](#running-a-scan)                   | Scan the content for Secrets/IaC/SCA/SAST violations. You`ll need to specify which scan type to perform: commit-history/path/repository/etc. |
 | [report](#report-command)                 | Generate report. You`ll need to specify which report type to perform.                                                                        |
 | status                                    | Show the CLI status and exit.                                                                                                                |
 
@@ -294,7 +294,7 @@ The Cycode CLI application offers several types of scans so that you can choose
 | Option                                                     | Description                                                                                                                                                                                                                                             |
 |------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `-t, --scan-type [secret\|iac\|sca\|sast]`                 | Specify the scan you wish to execute (`secret`/`iac`/`sca`/`sast`), the default is `secret`.                                                                                                                                                            |
-| `--secret TEXT`                                            | Specify a Cycode client secret for this specific scan execution.                                                                                                                                                                                        |
+| `--client-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](#showhide-secrets) section for more details.                                                                                                                                                        |
 | `--soft-fail BOOLEAN`                                      | Run scan without failing, always return a non-error status code. See [Soft Fail](#soft-fail) section for more details.                                                                                                                                  |
@@ -308,9 +308,9 @@ The Cycode CLI application offers several types of scans so that you can choose
 
 | Command                                | Description                                                     |
 |----------------------------------------|-----------------------------------------------------------------|
-| [commit_history](#commit-history-scan) | Scan all the commits history in this git repository             |
+| [commit-history](#commit-history-scan) | Scan all the commits history in this git repository             |
 | [path](#path-scan)                     | Scan the files in the path supplied in the command              |
-| [pre_commit](#pre-commit-scan)         | Use this command to scan the content that was not committed yet |
+| [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                       |
 
 ### Options
@@ -466,25 +466,25 @@ A commit history scan is limited to a local repository’s previous commits, foc
 
 To execute a commit history scan, execute the following:
 
-`cycode scan commit_history {{path}}`
+`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`
+`cycode scan commit-history ~/home/git/codebase`
 
 The following options are 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) |
+| `-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` (`-r`) followed by the name you specify.
+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` (`-r`) followed by the name you specify.
 
 Consider the previous example. If you wanted to scan only specific commits in your repository, you could execute the following:
 
-`cycode scan commit_history -r {{from-commit-id}}...{{to-commit-id}} ~/home/git/codebase`
+`cycode scan commit-history -r {{from-commit-id}}...{{to-commit-id}} ~/home/git/codebase`
 
 ### Pre-Commit Scan
 
@@ -823,7 +823,7 @@ 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-url` | Generate SBOM report for provided repository URI in the command |
 
 ### Repository
 

cycode/cli/app.py

@@ -25,10 +25,19 @@
 rich_utils.RICH_HELP = "Try [cyan]'{command_path} {help_option}'[/] for help."
 
 
+_cycode_cli_docs = 'https://github.com/cycodehq/cycode-cli/blob/main/README.md'
+_cycode_cli_epilog = f"""[bold]Documentation[/]
+
+
+
+For more details and advanced usage, visit: [link={_cycode_cli_docs}]{_cycode_cli_docs}[/link]
+"""
+
 app = typer.Typer(
     pretty_exceptions_show_locals=False,
     pretty_exceptions_short=True,
     context_settings=CLI_CONTEXT_SETTINGS,
+    epilog=_cycode_cli_epilog,
     rich_markup_mode='rich',
     no_args_is_help=True,
     add_completion=False,  # we add it manually to control the rich help panel
@@ -125,6 +134,7 @@ def app_callback(
         ),
     ] = False,
 ) -> None:
+    """[bold cyan]Cycode CLI - Command Line Interface for Cycode.[/]"""
     init_sentry()
     add_breadcrumb('cycode')
 

cycode/cli/apps/ai_remediation/__init__.py

@@ -2,8 +2,19 @@
 
 from cycode.cli.apps.ai_remediation.ai_remediation_command import ai_remediation_command
 
-app = typer.Typer(no_args_is_help=True)
-app.command(name='ai-remediation', short_help='Get AI remediation (INTERNAL).', hidden=True)(ai_remediation_command)
+app = typer.Typer()
+
+_ai_remediation_epilog = """
+Note: AI remediation suggestions are generated automatically and should be reviewed before applying.
+"""
+
+app.command(
+    name='ai-remediation',
+    short_help='Get AI remediation (INTERNAL).',
+    epilog=_ai_remediation_epilog,
+    hidden=True,
+    no_args_is_help=True,
+)(ai_remediation_command)
 
 # backward compatibility
 app.command(hidden=True, name='ai_remediation')(ai_remediation_command)

cycode/cli/apps/ai_remediation/ai_remediation_command.py

@@ -16,7 +16,14 @@ def ai_remediation_command(
         bool, typer.Option('--fix', help='Apply fixes to resolve violations. Note: fix could be not available.')
     ] = False,
 ) -> None:
-    """Get AI remediation (INTERNAL)."""
+    """:robot: [bold cyan]Get AI-powered remediation for security issues.[/]
+
+    This command provides AI-generated remediation guidance for detected security issues.
+
+    Example usage:
+    * `cycode ai-remediation <detection_id>`: View remediation guidance
+    * `cycode ai-remediation <detection_id> --fix`: Apply suggested fixes
+    """
     client = get_scan_cycode_client()
 
     try:

cycode/cli/apps/auth/__init__.py

@@ -1,12 +1,14 @@
 import typer
 
 from cycode.cli.apps.auth.auth_command import auth_command
-from cycode.cli.apps.auth.check_command import check_command
-
-app = typer.Typer(
-    name='auth',
-    help='Authenticate your machine to associate the CLI with your Cycode account.',
-    no_args_is_help=True,
-)
-app.callback(invoke_without_command=True)(auth_command)
-app.command(name='check')(check_command)
+
+_auth_command_docs = 'https://github.com/cycodehq/cycode-cli/blob/main/README.md#using-the-auth-command'
+_auth_command_epilog = f"""[bold]Documentation[/]
+
+
+
+For more details and advanced usage, visit: [link={_auth_command_docs}]{_auth_command_docs}[/link]
+"""
+
+app = typer.Typer(no_args_is_help=False)
+app.command(name='auth', epilog=_auth_command_epilog, short_help='Authenticate your machine with Cycode.')(auth_command)

cycode/cli/apps/auth/auth_command.py

@@ -8,14 +8,17 @@
 
 
 def auth_command(ctx: typer.Context) -> None:
-    """Authenticates your machine."""
+    """:key: [bold cyan]Authenticate your machine with Cycode.[/]
+
+    This command handles authentication with Cycode's security platform.
+
+    Example usage:
+    * `cycode auth`: Start interactive authentication
+    * `cycode auth --help`: View authentication options
+    """
     add_breadcrumb('auth')
     printer = ctx.obj.get('console_printer')
 
-    if ctx.invoked_subcommand is not None:
-        # if it is a subcommand, do nothing
-        return
-
     try:
         logger.debug('Starting authentication process')
 

cycode/cli/apps/auth/auth_common.py

@@ -1,15 +1,16 @@
-from typing import Optional
-
-import typer
+from typing import TYPE_CHECKING, Optional
 
 from cycode.cli.apps.auth.models import AuthInfo
 from cycode.cli.exceptions.custom_exceptions import HttpUnauthorizedError, RequestHttpError
 from cycode.cli.user_settings.credentials_manager import CredentialsManager
 from cycode.cli.utils.jwt_utils import get_user_and_tenant_ids_from_access_token
 from cycode.cyclient.cycode_token_based_client import CycodeTokenBasedClient
 
+if TYPE_CHECKING:
+    from typer import Context
+
 
-def get_authorization_info(ctx: Optional[typer.Context] = None) -> Optional[AuthInfo]:
+def get_authorization_info(ctx: 'Context') -> Optional[AuthInfo]:
     printer = ctx.obj.get('console_printer')
 
     client_id, client_secret = CredentialsManager().get_credentials()

cycode/cli/apps/auth/auth_manager.py

@@ -1,6 +1,6 @@
 import time
 import webbrowser
-from typing import TYPE_CHECKING, Tuple
+from typing import TYPE_CHECKING
 
 from cycode.cli.exceptions.custom_exceptions import AuthProcessError
 from cycode.cli.user_settings.configuration_manager import ConfigurationManager
@@ -78,7 +78,7 @@ def get_api_token_polling(self, session_id: str, code_verifier: str) -> 'ApiToke
     def save_api_token(self, api_token: 'ApiToken') -> None:
         self.credentials_manager.update_credentials(api_token.client_id, api_token.secret)
 
-    def _generate_pkce_code_pair(self) -> Tuple[str, str]:
+    def _generate_pkce_code_pair(self) -> tuple[str, str]:
         code_verifier = generate_random_string(self.CODE_VERIFIER_LENGTH)
         code_challenge = hash_string_to_sha256(code_verifier)
         return code_challenge, code_verifier

cycode/cli/apps/configure/__init__.py

@@ -2,7 +2,18 @@
 
 from cycode.cli.apps.configure.configure_command import configure_command
 
+_configure_command_docs = 'https://github.com/cycodehq/cycode-cli/blob/main/README.md#using-the-configure-command'
+_configure_command_epilog = f"""[bold]Documentation[/]
+
+
+
+For more details and advanced usage, visit: [link={_configure_command_docs}]{_configure_command_docs}[/link]
+"""
+
+
 app = typer.Typer(no_args_is_help=True)
-app.command(name='configure', short_help='Initial command to configure your CLI client authentication.')(
-    configure_command
-)
+app.command(
+    name='configure',
+    epilog=_configure_command_epilog,
+    short_help='Initial command to configure your CLI client authentication.',
+)(configure_command)

cycode/cli/apps/configure/configure_command.py

@@ -23,7 +23,20 @@ def _should_update_value(
 
 
 def configure_command() -> None:
-    """Configure your CLI client authentication manually."""
+    """:gear: [bold cyan]Configure Cycode CLI settings.[/]
+
+    This command allows you to configure various aspects of the Cycode CLI.
+
+    Configuration options:
+    * API URL: The base URL for Cycode's API (for on-premise or EU installations)
+    * APP URL: The base URL for Cycode's web application (for on-premise or EU installations)
+    * Client ID: Your Cycode client ID for authentication
+    * Client Secret: Your Cycode client secret for authentication
+
+    Example usage:
+    * `cycode configure`: Start interactive configuration
+    * `cycode configure --help`: View configuration options
+    """
     add_breadcrumb('configure')
 
     global_config_manager = CONFIGURATION_MANAGER.global_config_file_manager

cycode/cli/apps/ignore/ignore_command.py

@@ -83,7 +83,20 @@ def ignore_command(  # noqa: C901
         bool, typer.Option('--global', '-g', help='Add an ignore rule to the global CLI config.')
     ] = False,
 ) -> None:
-    """Ignores a specific value, path or rule ID."""
+    """:no_entry: [bold cyan]Ignore specific findings or paths in scans.[/]
+
+    This command allows you to exclude specific items from Cycode scans, including:
+    * Paths: Exclude specific files or directories
+    * Rules: Ignore specific security rules
+    * Values: Exclude specific sensitive values
+    * Packages: Ignore specific package versions
+    * CVEs: Exclude specific vulnerabilities
+
+    Example usage:
+    * `cycode ignore --by-path .env`: Ignore the tests directory
+    * `cycode ignore --by-rule GUID`: Ignore rule with the specified GUID
+    * `cycode ignore --by-package [email protected]`: Ignore lodash version 4.17.21
+    """
     add_breadcrumb('ignore')
 
     all_by_values = [by_value, by_sha, by_path, by_rule, by_package, by_cve]
@@ -145,4 +158,4 @@ def ignore_command(  # noqa: C901
             'exclusion_value': exclusion_value,
         },
     )
-    configuration_manager.add_exclusion(configuration_scope, scan_type, exclusion_type, exclusion_value)
+    configuration_manager.add_exclusion(configuration_scope, str(scan_type), exclusion_type, exclusion_value)

cycode/cli/apps/report/report_command.py

@@ -5,7 +5,11 @@
 
 
 def report_command(ctx: typer.Context) -> int:
-    """Generate report."""
+    """:bar_chart: [bold cyan]Generate security reports.[/]
+
+    Example usage:
+    * `cycode report sbom`: Generate SBOM report
+    """
     add_breadcrumb('report')
     ctx.obj['progress_bar'] = get_progress_bar(hidden=False, sections=SBOM_REPORT_PROGRESS_BAR_SECTIONS)
     return 1