Update documentation

actions/iac/action.yml

@@ -5,16 +5,9 @@ author: GitGuardian <support@gitguardian.com>
 inputs:
   args:
     description: |
-      Arguments to be passed to ggshield iac scan
-      Options:
-        --exit-zero                     Always return a 0 (non-error) status code, even if issues
-                                        are found. The env var GITGUARDIAN_EXIT_ZERO can also be used
-                                        to set this option.
-        --minimum-severity              [LOW|MEDIUM|HIGH|CRITICAL]
-                                        Minimum severity of the policies
-        --ignore-policy, --ipo TEXT     Policies to exclude from the results.
-        --ignore-path, --ipa PATH       Do not scan the specified paths.
-        --json                          JSON output.
+      Arguments to pass to `ggshield iac scan ci`.
+
+      [`ggshield iac scan ci` reference](https://docs.gitguardian.com/ggshield-docs/reference/iac/scan/ci).
     required: false
 branding:
   icon: 'shield'

actions/sca/action.yml

@@ -5,14 +5,9 @@ author: GitGuardian <support@gitguardian.com>
 inputs:
   args:
     description: |
-      Arguments to be passed to ggshield sca scan
-      Options:
-        --exit-zero                     Always return a 0 (non-error) status code, even if issues
-                                        are found. The env var GITGUARDIAN_EXIT_ZERO can also be used
-                                        to set this option.
-        --minimum-severity              [LOW|MEDIUM|HIGH|CRITICAL]
-                                        Minimum severity of the policies
-        --ignore-path, --ipa PATH       Do not scan the specified paths.
+      Arguments to pass to `ggshield sca scan ci`.
+
+      [`ggshield iac sca ci` reference](https://docs.gitguardian.com/ggshield-docs/reference/sca/scan/ci).
     required: false
 branding:
   icon: 'shield'

actions/secret/action.yml

@@ -9,14 +9,9 @@ branding:
 inputs:
   args:
     description: |
-      Arguments to be passed to ggshield secret scan
-      Options:        
-        --json                        Output results in JSON format  [default: False]
-        --show-secrets                Show secrets in plaintext instead of hiding them.
-        --all-policies                Present fails of all policies (Filenames, FileExtensions,
-                                      Secret Detection). By default, only Secret Detection is shown.
-        --exit-zero                   Always return a 0 (non-error) status code, even if incidents are found.
-        -b, --banlist-detector TEXT   Exclude results from a detector.
+      Arguments to pass to `ggshield secret scan ci`.
+
+      [`ggshield secret scan ci` reference](https://docs.gitguardian.com/ggshield-docs/reference/secret/scan/ci).
     required: false
 
 runs:

changelog.d/20230913_171100_aurelien.gateau_update_action_doc.md

@@ -0,0 +1,3 @@
+### Changed
+
+- Help messages have been improved and are now kept in sync with [ggshield online reference documentation](https://docs.gitguardian.com/ggshield-docs/reference/overview).

ggshield/cmd/auth/login.py

@@ -75,12 +75,14 @@ def print_default_instance_message(config: Config) -> None:
     required=False,
     type=str,
     help="URL of the instance to authenticate against.",
+    metavar="URL",
 )
 @click.option(
     "--sso-url",
     required=False,
     type=str,
     help="URL of your SSO login page to force the authentication flow through your workspace SSO.",
+    metavar="URL",
 )
 @click.option(
     "--token-name",
@@ -94,6 +96,7 @@ def print_default_instance_message(config: Config) -> None:
     type=click.IntRange(0),
     default=None,
     help="Number of days before the token expires. 0 means the token never expires.",
+    metavar="DAYS",
 )
 @add_common_options()
 @click.pass_context
@@ -107,16 +110,20 @@ def login_cmd(
     **kwargs: Any,
 ) -> int:
     """
-    Authenticate with a GitGuardian workspace.
+    Authenticate with a GitGuardian instance.
+
     A successful authentication results in a personal access token.
     This token is stored in your configuration and used to authenticate your future requests.
 
-    The default authentication method is "web".
-    ggshield launches a web browser to authenticate you to your GitGuardian workspace,
+    The default authentication method is `web`.
+    ggshield launches a web browser to authenticate you to your GitGuardian instance,
     then automatically generates a token on your behalf.
 
     Alternatively, you can use `--method token` to authenticate using an already existing token.
     The minimum required scope for the token is `scan`.
+
+    If a valid personal access token is already configured, this command simply displays
+    a success message indicating that ggshield is already ready to use.
     """
     config: Config = ctx.obj["config"]
 

ggshield/cmd/auth/logout.py

@@ -23,14 +23,20 @@
     required=False,
     type=str,
     help="URL of the instance to logout from.",
+    metavar="URL",
 )
 @click.option(
     "--revoke/--no-revoke",
     is_flag=True,
     default=True,
     help="Whether the token should be revoked on logout before being removed from the configuration.",
 )
-@click.option("--all", "all_", is_flag=True, help="Iterate over every saved tokens.")
+@click.option(
+    "--all",
+    "all_",
+    is_flag=True,
+    help="Remove authentication for all instances.",
+)
 @add_common_options()
 @click.pass_context
 def logout_cmd(
@@ -81,7 +87,6 @@ def check_account_config_exists(config: Config, instance_url: str) -> None:
 
 
 def revoke_token(config: Config, instance_url: str) -> None:
-
     instance = config.auth_config.get_instance(instance_url)
 
     assert instance.account is not None

ggshield/cmd/config/config_get.py

@@ -2,14 +2,26 @@
 
 import click
 
-from ggshield.cmd.config.constants import FIELD_NAMES, FIELDS
+from ggshield.cmd.config.constants import FIELD_NAMES, FIELD_NAMES_DOC, FIELDS
 from ggshield.cmd.utils.common_options import add_common_options
 from ggshield.core.config import Config
 from ggshield.core.errors import UnknownInstanceError
 
 
-@click.command()
-@click.argument("field_name", nargs=1, type=click.Choice(FIELD_NAMES), required=True)
+@click.command(
+    help=f"""
+Print the value of the given configuration key.
+If `--instance` is passed, retrieve the value for this specific instance.
+
+{FIELD_NAMES_DOC}"""
+)
+@click.argument(
+    "field_name",
+    nargs=1,
+    type=click.Choice(FIELD_NAMES),
+    required=True,
+    metavar="KEY",
+)
 @click.option(
     "--instance",
     "instance_url",
@@ -23,10 +35,6 @@
 def config_get_cmd(
     ctx: click.Context, field_name: str, instance_url: Optional[str], **kwargs: Any
 ) -> int:
-    """
-    Print the value of the given configuration key.
-    If --instance is passed, retrieve the value for this specific instance.
-    """
     config: Config = ctx.obj["config"]
     field = FIELDS[field_name]
 

ggshield/cmd/config/config_set.py

@@ -8,7 +8,7 @@
 from ggshield.core.config.user_config import UserConfig
 from ggshield.core.config.utils import find_global_config_path
 
-from .constants import FIELD_NAMES, FIELDS, ConfigField
+from .constants import FIELD_NAMES, FIELD_NAMES_DOC, FIELDS, ConfigField
 
 
 def set_user_config_field(field: ConfigField, value: Any) -> None:
@@ -18,8 +18,19 @@ def set_user_config_field(field: ConfigField, value: Any) -> None:
     user_config.save(config_path)
 
 
-@click.command()
-@click.argument("field_name", nargs=1, type=click.Choice(FIELD_NAMES), required=True)
+@click.command(
+    help=f"""Update the value of the given configuration key.
+
+{FIELD_NAMES_DOC}
+"""
+)
+@click.argument(
+    "field_name",
+    nargs=1,
+    type=click.Choice(FIELD_NAMES),
+    required=True,
+    metavar="KEY",
+)
 @click.argument("value", nargs=1, type=click.STRING, required=True)
 @click.option(
     "--instance",
@@ -37,9 +48,6 @@ def config_set_cmd(
     instance: Optional[str],
     **kwargs: Any,
 ) -> int:
-    """
-    Update the value of the given configuration key.
-    """
     config: Config = ctx.obj["config"]
 
     field = FIELDS[field_name]

ggshield/cmd/config/config_unset.py

@@ -6,11 +6,24 @@
 from ggshield.core.config import Config
 
 from .config_set import set_user_config_field
-from .constants import FIELD_NAMES, FIELDS
+from .constants import FIELD_NAMES, FIELD_NAMES_DOC, FIELDS
 
 
-@click.command()
-@click.argument("field_name", nargs=1, type=click.Choice(FIELD_NAMES), required=True)
+@click.command(
+    help=f"""Remove the value of the given configuration key.
+
+If `--all` is passed, iterates over all instances.
+
+{FIELD_NAMES_DOC}
+"""
+)
+@click.argument(
+    "field_name",
+    nargs=1,
+    type=click.Choice(FIELD_NAMES),
+    required=True,
+    metavar="KEY",
+)
 @click.option(
     "--instance",
     "instance_url",
@@ -19,7 +32,7 @@
     metavar="URL",
     help="Set per instance configuration.",
 )
-@click.option("--all", "all_", is_flag=True, help="Iterate over every instances.")
+@click.option("--all", "all_", is_flag=True, help="Iterate over all instances.")
 @add_common_options()
 @click.pass_context
 def config_unset_cmd(
@@ -29,10 +42,6 @@ def config_unset_cmd(
     all_: bool,
     **kwargs: Any,
 ) -> int:
-    """
-    Remove the value of the given configuration key.
-    If --all is passed, it iterates over all instances.
-    """
     config: Config = ctx.obj["config"]
     field = FIELDS[field_name]
 

ggshield/cmd/config/constants.py

@@ -37,3 +37,5 @@ class ConfigField:
 FIELDS = {x.name: x for x in _FIELDS}
 
 FIELD_NAMES = sorted(FIELDS.keys())
+
+FIELD_NAMES_DOC = "Supported keys:\n" + "\n".join(f"- `{x}`" for x in FIELD_NAMES)

ggshield/cmd/hmsl/check.py

@@ -45,7 +45,9 @@ def check_cmd(
     **kwargs: Any,
 ) -> int:
     """
-    Check if secrets have leaked in one command.
+    Check if secrets have leaked.
+
+    Note: Secrets can be read from stdin using `ggshield hmsl check -`.
     """
 
     # Collect secrets

ggshield/cmd/hmsl/fingerprint.py

@@ -31,8 +31,9 @@ def validate_prefix(prefix: str) -> str:
     "--prefix",
     "-p",
     default="",
-    help="Prefix for output file names.",
+    help="Prefix for output file names. For instance `-p foo` produces `foo-payload.txt` and `foo-mapping.txt`.",
     callback=lambda _, __, value: validate_prefix(value),
+    metavar="PREFIX",
 )
 @full_hashes_option
 @naming_strategy_option
@@ -50,6 +51,8 @@ def fingerprint_cmd(
     Collect secrets and compute fingerprints.
 
     Fingerprints are to be used later by the `decrypt` command.
+
+    Note: Secrets can be read from stdin using `ggshield hmsl fingerprint -`.
     """
     # Opens the file or stdin
     input = cast(TextIO, click.open_file(path, "r"))

ggshield/cmd/hmsl/hmsl_common_options.py

@@ -20,10 +20,12 @@
     default="key",
     show_default=True,
     help="""Strategy to generate the hints in the output.
-            With "censored", only the first and last characters are displayed.
-            With "cleartext", the full secret is used as a hint (Not recommended!).
-            With "none", no hint is generated.
-            With "key", the key name is selected if available (e.g. in .env files), otherwise censored is used.""",
+
+            \b
+            - `censored`: only the first and last characters are displayed.
+            - `cleartext`: the full secret is used as a hint (Not recommended!).
+            - `none`: no hint is generated.
+            - `key`: the key name is selected if available (e.g. in .env files), otherwise censored is used.""",
     callback=lambda _, __, value: NAMING_STRATEGIES[value],
 )
 input_type_option = click.option(
@@ -34,14 +36,20 @@
     default="file",
     show_default=True,
     help="""Type of input to process.
-            With "file", the input is a simple file containing secrets.
-            With "env", the input is a file containing environment variables.""",
+
+            \b
+            - `file`: the input is a simple file containing secrets.
+            - `env`: the input is a file containing environment variables.""",
     callback=lambda _, __, value: InputType[value.upper()],
 )
 full_hashes_option = click.option(
     "-f",
     "--full-hashes",
     is_flag=True,
     default=False,
-    help="Send full hashes to the API instead of prefixes.",
+    help=(
+        "Put the full hashes into the payload instead of the prefixes. This is useful"
+        " for partners that trust GitGuardian because it allows to send more hashes"
+        " per batch, and consumes less credits, but leaks more data to GitGuardian."
+    ),
 )

ggshield/cmd/hmsl/query.py

@@ -27,7 +27,11 @@ def query_cmd(
     **kwargs: Any,
 ) -> int:
     """
-    Query HasMySecretLeaked using outputs of `fingerprint` command.
+    Query HasMySecretLeaked using outputs from the `fingerprint` command.
+
+    Note: If you used the `-f` option during stage one, the results will not be
+    encrypted. It is still useful to pass them through `decrypt` to properly format the
+    output.
     """
 
     # Opens the file or stdin

ggshield/cmd/honeytoken/create.py

@@ -33,14 +33,14 @@ def _dict_to_string(data: Dict, space: bool = False) -> str:
     required=False,
     type=str,
     help="Specify a name for your honeytoken. If this option is not provided, a unique name will be generated with a \
-'ggshield-' prefix.",
+`ggshield-` prefix.",
 )
 @click.option(
     "--type",
     "type_",
     required=True,
     type=click.Choice(("AWS",)),
-    help="Specify the type of honeytoken that you want to create. (For now only AWS honeytokens are supported!)",
+    help="Specify the type of honeytoken that you want to create. (For now only AWS honeytokens are supported)",
 )
 @click.option(
     "--description",
@@ -70,8 +70,10 @@ def create_cmd(
 ) -> int:
     """
     Command to create a honeytoken.
-    This action is restricted to authorized users only. To learn more, visit
-    <https://docs.gitguardian.com/honeytoken/getting-started>
+
+    The prerequisites to use this command are the following:
+    - you have the necessary permissions as a user (for now, Honeytoken is restricted to users with a manager role),
+    - the personal access token used by ggshield has the required scopes. (`honeytoken:read` and `honeytoken:write`).
     """
     # if name is not given, generate a random one
     if not name:

ggshield/cmd/iac/scan/all.py

@@ -41,6 +41,8 @@ def scan_all_cmd(
 ) -> int:
     """
     Scan a directory for all IaC vulnerabilities in the current state.
+
+    The scan is successful if no IaC vulnerability (known or new) was found.
     """
     if directory is None:
         directory = Path().resolve()