#329 - Document that the contextual values may come from users and are logged

CHANGELOG.md

@@ -2,6 +2,7 @@ Latest
 ------
 
 ## Changes
+* [#329](https://github.com/cleverage/process-bundle/issues/329) Documentation: the contextual values may come from users who do not write the process configuration (console, parent process, UI) and are logged: keep them out of the options interpreted by the tasks (string `commandline` of `command_runner`, SQL...) and do not pass secrets in the context.
 * [#90](https://github.com/cleverage/process-bundle/issues/90) Installation documentation: describe the Symfony Flex recipe ([symfony/recipes-contrib#2081](https://github.com/symfony/recipes-contrib/pull/2081)), which registers the bundle and creates `config/packages/clever_age_process.yaml` importing the `config/packages/process/` directory, and the manual setup without Flex.
 
 v5.4

docs/01-quick_start.md

@@ -296,6 +296,16 @@ read:
 Note that placeholders are only resolved for keys existing in the context: if you run the process without the
 `file_name` context value, the option will keep the literal `{{ file_name }}` string.
 
+The context values are inserted as is, and they may come from people who do not write the process configuration (the
+console, a parent process, the launch form and the HTTP API of
+[cleverage/ui-process-bundle](https://github.com/cleverage/ui-process-bundle)...):
+- do not use them in options interpreted by the task, where a value could change the meaning of the option: a string
+  `commandline` of [command_runner](reference/tasks/command_runner_task.md) is run by the shell (`'x; id'` runs
+  `id`), and the same goes for an SQL query, a callback name or an expression. Prefer an array `commandline`, query
+  parameters, or a value checked beforehand (e.g. by a [validator](reference/tasks/validator_task.md) task)
+- do not pass secrets (passwords, tokens) in the context: it is added to every log record (and stored with each
+  execution by the UI bundle). Use environment variables or the configuration of your services instead
+
 ## Automation
 
 Once everything is working fine, you may want to automate your processes. The standard way is using the Unix cron jobs:

docs/05-good_practices.md

@@ -78,7 +78,9 @@ relying on the order in which branches are executed.
 
 Values that change between executions (a file name, a date, a limit...) should not be hard-coded in the process
 configuration: pass them as [contextual values](01-quick_start.md#contextual-values) (`-c key:value`) and use
-`{{ key }}` placeholders in the task options.
+`{{ key }}` placeholders in the task options. The context may come from untrusted users and is logged: keep it out of
+the options interpreted by the tasks (shell command, SQL...) and do not put secrets in it (see
+[contextual values](01-quick_start.md#contextual-values)).
 
 ## Extend the bundle without inheriting its classes
 

docs/reference/tasks/command_runner_task.md

@@ -69,4 +69,6 @@ Notes
 
 An array `commandline` is run with `new Process()`: each argument is escaped and no shell is involved. A string
 `commandline` is run with `Process::fromShellCommandline()`: it is interpreted by the shell, so never build it from
-untrusted input.
+untrusted input, `{{ key }}` context placeholders included (a context value such as `x; id` would run `id`). To use a
+context value, pass it as an argument of an array `commandline`, or as an `env` variable quoted in the command
+(`commandline: 'grep "$PATTERN" | wc -l'`, `env: { PATTERN: '{{ pattern }}' }`).