snowflake-cli 3.5.0__py3-none-any.whl → 3.7.0__py3-none-any.whl

snowflake/cli/_plugins/auth/keypair/manager.py

@@ -0,0 +1,331 @@
+from enum import Enum
+from typing import Dict, List, Optional, Tuple
+
+from click import ClickException
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+from snowflake.cli._plugins.object.manager import ObjectManager
+from snowflake.cli.api import exceptions
+from snowflake.cli.api.cli_global_context import (
+    _CliGlobalContextAccess,
+    get_cli_context,
+)
+from snowflake.cli.api.config import (
+    connection_exists,
+    get_connection_dict,
+    set_config_value,
+)
+from snowflake.cli.api.console import cli_console
+from snowflake.cli.api.constants import ObjectType
+from snowflake.cli.api.identifiers import FQN
+from snowflake.cli.api.secret import SecretType
+from snowflake.cli.api.secure_path import SecurePath
+from snowflake.cli.api.sql_execution import SqlExecutionMixin
+from snowflake.connector import DictCursor
+from snowflake.connector.cursor import SnowflakeCursor
+
+
+class PublicKeyProperty(Enum):
+    RSA_PUBLIC_KEY = "RSA_PUBLIC_KEY"
+    RSA_PUBLIC_KEY_2 = "RSA_PUBLIC_KEY_2"
+
+
+class AuthManager(SqlExecutionMixin):
+    def setup(
+        self,
+        connection_name: Optional[str],
+        key_length: int,
+        output_path: SecurePath,
+        private_key_passphrase: SecretType,
+    ):
+        # When the user provide new connection name
+        if connection_name and connection_exists(connection_name):
+            raise ClickException(
+                f"Connection with name {connection_name} already exists."
+            )
+
+        cli_context = get_cli_context()
+        # When the use not provide connection name, so we overwrite the current connection
+        if not connection_name:
+            connection_name = cli_context.connection_context.connection_name
+
+        key_name = AuthManager._get_free_key_name(output_path, connection_name)  # type: ignore[arg-type]
+        self._generate_key_pair_and_set_public_key(
+            user=cli_context.connection.user,
+            key_length=key_length,
+            output_path=output_path,
+            key_name=key_name,  # type: ignore[arg-type]
+            private_key_passphrase=private_key_passphrase,
+        )
+
+        self._create_or_update_connection(
+            current_connection=cli_context.connection_context.connection_name,
+            connection_name=connection_name,  # type: ignore[arg-type]
+            private_key_path=self._get_private_key_path(
+                output_path=output_path, key_name=key_name  # type: ignore[arg-type]
+            ),
+        )
+
+    def rotate(
+        self,
+        key_length: int,
+        output_path: SecurePath,
+        private_key_passphrase: SecretType,
+    ):
+        cli_context = get_cli_context()
+        connection_name = cli_context.connection_context.connection_name
+
+        self._ensure_connection_has_private_key(
+            cli_context.connection_context.connection_name
+        )
+
+        public_key, public_key_2 = self._get_public_keys()
+
+        if not public_key and not public_key_2:
+            raise ClickException("No public key found. Use the setup command first.")
+
+        if public_key_2:
+            self.set_public_key(
+                cli_context.connection.user,
+                PublicKeyProperty.RSA_PUBLIC_KEY,
+                public_key_2,
+            )
+
+        key_name = AuthManager._get_free_key_name(output_path, connection_name)
+        public_key = self._generate_keys_and_return_public_key(
+            key_length=key_length,
+            output_path=output_path,
+            key_name=key_name,
+            private_key_passphrase=private_key_passphrase,
+        )
+        self.set_public_key(
+            cli_context.connection.user, PublicKeyProperty.RSA_PUBLIC_KEY_2, public_key
+        )
+        self._create_or_update_connection(
+            current_connection=cli_context.connection_context.connection_name,
+            connection_name=connection_name,
+            private_key_path=self._get_private_key_path(
+                output_path=output_path, key_name=key_name
+            ),
+        )
+
+    def _generate_key_pair_and_set_public_key(
+        self,
+        user: str,
+        key_length: int,
+        output_path: SecurePath,
+        key_name: str,
+        private_key_passphrase: SecretType,
+    ):
+        public_key_exists, public_key_2_exists = self._get_public_keys()
+
+        if public_key_exists or public_key_2_exists:
+            raise exceptions.CouldNotSetKeyPairError()
+
+        if not output_path.exists():
+            output_path.mkdir(parents=True)
+
+        public_key = self._generate_keys_and_return_public_key(
+            key_length=key_length,
+            output_path=output_path,
+            key_name=key_name,  # type: ignore[arg-type]
+            private_key_passphrase=private_key_passphrase,
+        )
+        self.set_public_key(user, PublicKeyProperty.RSA_PUBLIC_KEY, public_key)
+
+    def list_keys(self) -> List[Dict]:
+        key_properties = [
+            "RSA_PUBLIC_KEY",
+            "RSA_PUBLIC_KEY_FP",
+            "RSA_PUBLIC_KEY_LAST_SET_TIME",
+            "RSA_PUBLIC_KEY_2",
+            "RSA_PUBLIC_KEY_2_FP",
+            "RSA_PUBLIC_KEY_2_LAST_SET_TIME",
+        ]
+        cursor = ObjectManager(connection=self._conn).describe(
+            object_type=ObjectType.USER.value.sf_name,
+            fqn=FQN.from_string(self._conn.user),
+            cursor_class=DictCursor,
+        )
+        only_public_key_properties = [
+            p for p in cursor.fetchall() if p.get("property") in key_properties
+        ]
+        return only_public_key_properties
+
+    def set_public_key(
+        self, user: str, public_key_property: PublicKeyProperty, public_key: str
+    ) -> SnowflakeCursor:
+        return self.execute_query(
+            f"ALTER USER {user} SET {public_key_property.value}='{public_key}'"
+        )
+
+    def remove_public_key(
+        self, public_key_property: PublicKeyProperty
+    ) -> SnowflakeCursor:
+        cli_context = get_cli_context()
+        return self.execute_query(
+            f"ALTER USER {cli_context.connection.user} UNSET {public_key_property.value}"
+        )
+
+    def status(self):
+        cli_context = get_cli_context()
+        self._ensure_connection_has_private_key(
+            cli_context.connection_context.connection_name
+        )
+        cli_console.step("Private key set for connection - OK")
+        self._check_connection(cli_context)
+        cli_console.step("Test connection - OK")
+
+    def extend_connection_add(
+        self,
+        connection_name: str,
+        connection_options: Dict,
+        key_length: int,
+        output_path: SecurePath,
+        private_key_passphrase: SecretType,
+    ) -> Dict:
+        key_name = AuthManager._get_free_key_name(output_path, connection_name)
+
+        self._generate_key_pair_and_set_public_key(
+            user=connection_options["user"],
+            key_length=key_length,
+            output_path=output_path,
+            key_name=key_name,
+            private_key_passphrase=private_key_passphrase,
+        )
+
+        connection_options["authenticator"] = "SNOWFLAKE_JWT"
+        connection_options["private_key_file"] = str(
+            self._get_private_key_path(output_path=output_path, key_name=key_name).path
+        )
+        if connection_options.get("password"):
+            del connection_options["password"]
+
+        return connection_options
+
+    @staticmethod
+    def _ensure_connection_has_private_key(connection_name: str) -> None:
+        connection = get_connection_dict(connection_name)
+        if not connection.get("private_key_file") and not connection.get(
+            "private_key_path"
+        ):
+            raise ClickException(
+                f"The private key is not set in {connection_name} connection."
+            )
+
+    @staticmethod
+    def _check_connection(cli_context: _CliGlobalContextAccess) -> None:
+        cli_context.connection
+
+    def _get_public_keys(self) -> Tuple[str, str]:
+        keys = self.list_keys()
+        public_key = ""
+        public_key_2 = ""
+        for p in keys:
+            if (
+                p.get("property") == PublicKeyProperty.RSA_PUBLIC_KEY.value
+                and p.get("value") != "null"
+            ):
+                public_key = p.get("value")  # type: ignore
+            if (
+                p.get("property") == PublicKeyProperty.RSA_PUBLIC_KEY_2.value
+                and p.get("value") != "null"
+            ):
+                public_key_2 = p.get("value")  # type: ignore
+        return public_key, public_key_2
+
+    @staticmethod
+    def _generate_keys_and_return_public_key(
+        key_length: int,
+        output_path: SecurePath,
+        key_name: str,
+        private_key_passphrase: SecretType,
+    ) -> str:
+        private_key = rsa.generate_private_key(
+            public_exponent=65537,
+            key_size=key_length,
+        )
+
+        if private_key_passphrase:
+            pem = SecretType(
+                private_key.private_bytes(
+                    encoding=serialization.Encoding.PEM,
+                    format=serialization.PrivateFormat.PKCS8,
+                    encryption_algorithm=serialization.BestAvailableEncryption(
+                        private_key_passphrase.value.encode("utf-8")
+                    ),
+                )
+            )
+            cli_console.message(
+                "Set the `PRIVATE_KEY_PASSPHRASE` environment variable before using the connection."
+            )
+        else:
+            pem = SecretType(
+                private_key.private_bytes(
+                    encoding=serialization.Encoding.PEM,
+                    format=serialization.PrivateFormat.PKCS8,
+                    encryption_algorithm=serialization.NoEncryption(),
+                )
+            )
+
+        with AuthManager._get_private_key_path(output_path, key_name).open(
+            mode="wb"
+        ) as file:
+            file.write(pem.value)
+
+        public_key = private_key.public_key()
+        public_pem = public_key.public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+        with AuthManager._get_public_key_path(output_path, key_name).open(
+            mode="wb"
+        ) as file:
+            file.write(public_pem)
+
+        return public_pem.decode("utf-8")
+
+    @staticmethod
+    def _get_free_key_name(output_path: SecurePath, key_name: str) -> str:
+        new_private_key = f"{key_name}.p8"
+        new_public_key = f"{key_name}.pub"
+        new_key_name = key_name
+        counter = 1
+
+        while (
+            (output_path / new_private_key).exists()
+            and (output_path / new_public_key).exists()
+            and counter <= 100
+        ):
+            new_key_name = f"{key_name}_{counter}"
+            new_private_key = f"{new_key_name}.p8"
+            new_public_key = f"{new_key_name}.pub"
+            counter += 1
+
+        if counter == 100:
+            raise ClickException(
+                "Too many key pairs with the same name in the output directory."
+            )
+
+        return new_key_name
+
+    @staticmethod
+    def _get_private_key_path(output_path: SecurePath, key_name: str) -> SecurePath:
+        return (output_path / f"{key_name}.p8").resolve()
+
+    @staticmethod
+    def _get_public_key_path(output_path: SecurePath, key_name: str) -> SecurePath:
+        return (output_path / f"{key_name}.pub").resolve()
+
+    @staticmethod
+    def _create_or_update_connection(
+        current_connection: Optional[str],
+        connection_name: str,
+        private_key_path: SecurePath,
+    ):
+        connection = get_connection_dict(current_connection)
+        connection.pop("password", None)
+        connection["authenticator"] = "SNOWFLAKE_JWT"
+        connection["private_key_file"] = str(private_key_path.path)
+
+        set_config_value(["connections", connection_name], value=connection)

snowflake/cli/_plugins/auth/keypair/plugin_spec.py

@@ -0,0 +1,30 @@
+# Copyright (c) 2024 Snowflake Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from snowflake.cli._plugins.auth import app
+from snowflake.cli.api.plugins.command import (
+    SNOWCLI_ROOT_COMMAND_PATH,
+    CommandSpec,
+    CommandType,
+    plugin_hook_impl,
+)
+
+
+@plugin_hook_impl
+def command_spec():
+    return CommandSpec(
+        parent_command_path=SNOWCLI_ROOT_COMMAND_PATH,
+        command_type=CommandType.COMMAND_GROUP,
+        typer_instance=app.create_instance(),
+    )

snowflake/cli/_plugins/connection/commands.py

@@ -16,8 +16,9 @@ from __future__ import annotations
 
 import logging
 import os.path
+from copy import deepcopy
 from pathlib import Path
-from typing import Optional
+from typing import Dict, Optional, Tuple
 
 import typer
 from click import (  # type: ignore
@@ -28,10 +29,14 @@ from click import (  # type: ignore
 )
 from click.core import ParameterSource  # type: ignore
 from snowflake import connector
+from snowflake.cli._app.snow_connector import connect_to_snowflake
+from snowflake.cli._plugins.auth.keypair.commands import KEY_PAIR_DEFAULT_PATH
+from snowflake.cli._plugins.auth.keypair.manager import AuthManager
 from snowflake.cli._plugins.connection.util import (
     strip_if_value_present,
 )
 from snowflake.cli._plugins.object.manager import ObjectManager
+from snowflake.cli.api import exceptions
 from snowflake.cli.api.cli_global_context import get_cli_context
 from snowflake.cli.api.commands.flags import (
     PLAIN_PASSWORD_MSG,
@@ -61,12 +66,15 @@ from snowflake.cli.api.config import (
 )
 from snowflake.cli.api.console import cli_console
 from snowflake.cli.api.constants import ObjectType
+from snowflake.cli.api.feature_flags import FeatureFlag
 from snowflake.cli.api.output.types import (
     CollectionResult,
     CommandResult,
     MessageResult,
     ObjectResult,
 )
+from snowflake.cli.api.secret import SecretType
+from snowflake.cli.api.secure_path import SecurePath
 from snowflake.connector import ProgrammingError
 from snowflake.connector.constants import CONNECTIONS_FILE
 
@@ -282,6 +290,13 @@ def add(
     if connection_exists(connection_name):
         raise UsageError(f"Connection {connection_name} already exists")
 
+    if FeatureFlag.ENABLE_AUTH_KEYPAIR.is_enabled() and not no_interactive:
+        connection_options, keypair_error = _extend_add_with_key_pair(
+            connection_name, connection_options
+        )
+    else:
+        keypair_error = ""
+
     connections_file = add_connection_to_proper_file(
         connection_name,
         ConnectionConfig(**connection_options),
@@ -289,6 +304,12 @@ def add(
     if set_as_default:
         set_config_value(path=["default_connection_name"], value=connection_name)
 
+    if keypair_error:
+        return MessageResult(
+            f"Wrote new password-based connection {connection_name} to {connections_file}, "
+            f"however there were some issues during key pair setup. Review the following error and check 'snow auth keypair' "
+            f"commands to setup key pair authentication:\n * {keypair_error}"
+        )
     return MessageResult(
         f"Wrote new connection {connection_name} to {connections_file}"
     )
@@ -402,3 +423,59 @@ def generate_jwt(
         return MessageResult(token)
     except (ValueError, TypeError) as err:
         raise ClickException(str(err))
+
+
+def _extend_add_with_key_pair(
+    connection_name: str, connection_options: Dict
+) -> Tuple[Dict, str]:
+    if not _should_extend_with_key_pair(connection_options):
+        return connection_options, ""
+
+    configure_key_pair = typer.confirm(
+        "Do you want to configure key pair authentication?",
+        default=False,
+    )
+    if not configure_key_pair:
+        return connection_options, ""
+
+    key_length = typer.prompt(
+        "Key length",
+        default=2048,
+        show_default=True,
+    )
+
+    output_path = typer.prompt(
+        "Output path",
+        default=KEY_PAIR_DEFAULT_PATH,
+        show_default=True,
+        value_proc=lambda value: SecurePath(value),
+    )
+    private_key_passphrase = typer.prompt(
+        "Private key passphrase",
+        default="",
+        hide_input=True,
+        show_default=False,
+        value_proc=lambda value: SecretType(value),
+    )
+    connection = connect_to_snowflake(temporary_connection=True, **connection_options)
+    try:
+        connection_options = AuthManager(connection=connection).extend_connection_add(
+            connection_name=connection_name,
+            connection_options=deepcopy(connection_options),
+            key_length=key_length,
+            output_path=output_path,
+            private_key_passphrase=private_key_passphrase,
+        )
+    except exceptions.CouldNotSetKeyPairError:
+        return connection_options, "The public key is set already."
+    except Exception as e:
+        return connection_options, str(e)
+    return connection_options, ""
+
+
+def _should_extend_with_key_pair(connection_options: Dict) -> bool:
+    return (
+        connection_options.get("password") is not None
+        and connection_options.get("private_key_file") is None
+        and connection_options.get("private_key_path") is None
+    )

snowflake/cli/_plugins/helpers/commands.py

@@ -15,12 +15,14 @@
 from __future__ import annotations
 
 import logging
+import os
 from pathlib import Path
 from typing import Any, List, Optional
 
 import typer
 import yaml
 from click import ClickException
+from snowflake.cli._plugins.helpers.snowsl_vars_reader import check_env_vars
 from snowflake.cli.api.commands.snow_typer import SnowTyperFactory
 from snowflake.cli.api.config import (
     ConnectionConfig,
@@ -29,7 +31,12 @@ from snowflake.cli.api.config import (
     set_config_value,
 )
 from snowflake.cli.api.console import cli_console
-from snowflake.cli.api.output.types import CommandResult, MessageResult
+from snowflake.cli.api.output.types import (
+    CollectionResult,
+    CommandResult,
+    MessageResult,
+    MultipleResults,
+)
 from snowflake.cli.api.project.definition_conversion import (
     convert_project_definition_to_v2,
 )
@@ -293,3 +300,20 @@ def _validate_and_save_connections_imported_from_snowsql(
             path=["default_connection_name"],
             value=default_cli_connection_name,
         )
+
+
+@app.command(name="check-snowsql-env-vars", requires_connection=False)
+def check_snowsql_env_vars(**options):
+    """Check if there are any SnowSQL environment variables set."""
+
+    env_vars = os.environ.copy()
+    discovered, unused, summary = check_env_vars(env_vars)
+
+    results = []
+    if discovered:
+        results.append(CollectionResult(discovered))
+    if unused:
+        results.append(CollectionResult(unused))
+
+    results.append(MessageResult(summary))
+    return MultipleResults(results)

snowflake/cli/_plugins/helpers/snowsl_vars_reader.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+EnvVars = dict[str, str]
+
+DicoveredVars = list[dict[str, str]]
+UnusedVars = list[dict[str, str]]
+Summary = str
+
+CheckResult = tuple[DicoveredVars, UnusedVars, Summary]
+
+KNOWN_SNOWSQL_ENV_VARS = {
+    "SNOWSQL_ACCOUNT": {
+        "Found": "SNOWSQL_ACCOUNT",
+        "Suggested": "SNOWFLAKE_ACCOUNT",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-connections#use-environment-variables-for-snowflake-credentials",
+    },
+    "SNOWSQL_PWD": {
+        "Found": "SNOWSQL_PASSWORD",
+        "Suggested": "SNOWFLAKE_PASSWORD",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-connections#use-environment-variables-for-snowflake-credentials",
+    },
+    "SNOWSQL_USER": {
+        "Found": "SNOWSQL_USER",
+        "Suggested": "SNOWFLAKE_USER",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-connections#use-environment-variables-for-snowflake-credentials",
+    },
+    "SNOWSQL_REGION": {
+        "Found": "SNOWSQL_REGION",
+        "Suggested": "SNOWFLAKE_REGION",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-connections#use-environment-variables-for-snowflake-credentials",
+    },
+    "SNOWSQL_ROLE": {
+        "Found": "SNOWSQL_ROLE",
+        "Suggested": "SNOWFLAKE_ROLE",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-connections#use-environment-variables-for-snowflake-credentials",
+    },
+    "SNOWSQL_WAREHOUSE": {
+        "Found": "SNOWSQL_WAREHOUSE",
+        "Suggested": "SNOWFLAKE_WAREHOUSE",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-connections#use-environment-variables-for-snowflake-credentials",
+    },
+    "SNOWSQL_DATABASE": {
+        "Found": "SNOWSQL_DATABASE",
+        "Suggested": "SNOWFLAKE_DATABASE",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-connections#use-environment-variables-for-snowflake-credentials",
+    },
+    "SNOWSQL_SCHEMA": {
+        "found": "SNOWSQL_SCHEMA",
+        "Suggested": "SNOWFLAKE_SCHEMA",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-connections#use-environment-variables-for-snowflake-credentials",
+    },
+    "SNOWSQL_HOST": {
+        "Found": "SNOWSQL_HOST",
+        "Suggested": "SNOWFLAKE_HOST",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-connections#use-environment-variables-for-snowflake-credentials",
+    },
+    "SNOWSQL_PORT": {
+        "Found": "SNOWSQL_PORT",
+        "Suggested": "SNOWFLAKE_PORT",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-connections#use-environment-variables-for-snowflake-credentials",
+    },
+    "SNOWSQL_PROTOCOL": {
+        "Found": "SNOWSQL_PROTOCOL",
+        "Suggested": "SNOWFLAKE_PROTOCOL",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-connections#use-environment-variables-for-snowflake-credentials",
+    },
+    "SNOWSQL_PROXY_HOST": {
+        "Found": "SNOWSQL_PROXY_HOST",
+        "Suggested": "PROXY_HOST",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-cli#use-a-proxy-server",
+    },
+    "SNOWSQL_PROXY_PORT": {
+        "Found": "SNOWSQL_PROXY_HOST",
+        "Suggested": "PROXY_HOST",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-cli#use-a-proxy-server",
+    },
+    "SNOWSQL_PROXY_USER": {
+        "Found": "SNOWSQL_PROXY_PORT",
+        "Suggested": "PROXY_PORT",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-cli#use-a-proxy-server",
+    },
+    "SNOWSQL_PROXY_PWD": {
+        "Found": "SNOWSQL_PROXY_PWD",
+        "Suggested": "PROXY_PWD",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-cli#use-a-proxy-server",
+    },
+    "SNOWSQL_PRIVATE_KEY_PASSPHRASE": {
+        "Found": "SNOWSQL_PRIVATE_KEY_PASSPHRASE",
+        "Suggested": "PRIVATE_KEY_PASSPHRASE",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/connecting/configure-connections",
+    },
+    "EXIT_ON_ERROR": {
+        "Found": "EXIT_ON_ERROR",
+        "Suggested": "SNOWFLAKE_ENHANCED_EXIT_CODES",
+        "Additional info": "https://docs.snowflake.com/en/developer-guide/snowflake-cli/sql/execute-sql",
+    },
+}
+
+
+def check_env_vars(variables: EnvVars) -> CheckResult:
+    """Checks passed dict objects for possible SnowSQL variables.
+
+    Returns tuple of
+    - sequence of variables that can be adjusted
+    - sequence of variables that have no corresponding variables
+    - a summary messages
+    """
+    discovered: DicoveredVars = []
+    unused: UnusedVars = []
+
+    prefix_matched = (e for e in variables if e.lower().startswith("snowsql"))
+
+    for var in prefix_matched:
+        if suggestion := KNOWN_SNOWSQL_ENV_VARS.get(var, None):
+            discovered.append(suggestion)
+        else:
+            unused.append(
+                {
+                    "Found": var,
+                    "Suggested": "n/a",
+                    "Additional info": "Unused variable",
+                }
+            )
+
+    discovered_cnt = len(discovered)
+    unused_cnt = len(unused)
+
+    summary: Summary = (
+        f"Found {discovered_cnt + unused_cnt} SnowSQL environment variables,"
+        f" {discovered_cnt} with replacements, {unused_cnt} unused."
+    )
+
+    return discovered, unused, summary