Merge pull request #21654 from bernt-matthias/credentials-docs

[25.1] Document security considerations for using secrets

Author: bernt-matthias

lib/galaxy/tool_util/xsd/galaxy.xsd

@@ -774,6 +774,23 @@ information separate from tool definitions. Multiple credentials sets can be def
 within a single ``requirements`` block, each with a unique name. Before executing a tool
 that requires credentials, users must provide the necessary credentials through the Galaxy UI.
 
+Security considerations:
+
+- Credentials are stored in the jobs "job script" (the script that sets up the job's environment
+  and starts the tool script which contains the generated command line). The job script may be
+  accessible to Galaxy admins during execution of the job (and depending on the configuration
+  of Galaxy, after execution too).
+- Credentials are not available as Cheetah variables, because they could be used in the ``command``
+  block which would expose their content in the generated command line which is stored in the
+ job's metadata (which is stored plain text in Galaxy's DB and can be shared with other users).
+- Also, credentials should not be passed to the command line through environment variables:
+  - They will be expanded by the executing shell before execution, i.e. they will be visible on the
+    process list which can be a problem when jobs are executed on shared systems.
+  - Values of credentials are not sanitized, i.e. users could abuse them for code injection.
+- If values/secrets can be supplied via a file, then a helper script that takes the variables from the
+  environment and writes them to a file can be used.
+- For transparency,  it is good to document the extent to which credentials are exposed in the tool help / credential help.
+
 ### Example
 
 ```xml
@@ -784,9 +801,9 @@ that requires credentials, users must provide the necessary credentials through
         <secret name="secret_key" inject_as_env="AWS_SECRET_ACCESS_KEY" optional="false" label="Secret Access Key" description="Your AWS secret access key" />
     </credentials>
     <credentials name="database" version="2.1" label="Database Connection" description="Database connection credentials">
-        <variable name="host" inject_as_env="DB_HOST" optional="false" label="Database Host" description="The hostname or IP address of the database server" />
-        <variable name="port" inject_as_env="DB_PORT" optional="true" label="Database Port" description="The port number (default: 5432)" />
-        <secret name="password" inject_as_env="DB_PASSWORD" optional="false" label="Database Password" description="The password for database authentication" />
+        <variable name="host" inject_as_env="PGHOST" optional="false" label="Database Host" description="The hostname or IP address of the database server" />
+        <variable name="port" inject_as_env="PGPORT" optional="true" label="Database Port" description="The port number (default: 5432)" />
+        <secret name="password" inject_as_env="PGPASSWORD" optional="false" label="Database Password" description="The password for database authentication" />
     </credentials>
 </requirements>
 ```
@@ -796,12 +813,19 @@ that requires credentials, users must provide the necessary credentials through
 Within your tool, access the injected credentials using the specified environment variable names:
 
 ```bash
-# Access AWS credentials
-aws s3 ls s3://my-bucket --region $AWS_REGION --access-key $AWS_ACCESS_KEY_ID --secret-key $AWS_SECRET_ACCESS_KEY
+# Access AWS credentials (insecure)
+aws s3 ls s3://my-bucket --region "\$AWS_REGION" --access-key "\$AWS_ACCESS_KEY_ID" --secret-key "\$AWS_SECRET_ACCESS_KEY"
 
-# Access database credentials
-psql -h $DB_HOST -p $DB_PORT -U myuser -d mydb -W $DB_PASSWORD
+# Access database credentials (the secure way, i.e. not use environment variables on the CLI)
+psql -U myuser -d mydb
 ```
+
+In the ``aws`` example, the content of the environment variables would be exposed in the process list of the
+machine that is executing the job. Additionally, users could supply characters that are harmful on the CLI (see security considerations).
+In modern versions of the ``aws`` interface credentials can only be supplied via a file.
+
+In the postgres example we deliberately used environment variables that are picked up automatically by ``psql``,
+i.e. we do not need to set it on the command line (which would expose them on the process list). 
 ]]></xs:documentation>
     </xs:annotation>
     <xs:sequence>