Client input policy and migration

These policies are introduced in the Auton 1.4.0 transition release. The default changes in Auton 2.0, available for isolated testing as 2.0.0rc3.

In the transition release, omitted allow-* settings retain the 1.x permissions and generate startup warnings for each affected endpoint/category. Warnings do not prevent startup and never contain argument or environment values. The read-only autond --check-migration -c config.yml also reports missing policies. In 2.0, omitted permissions deny client additions. A denial is an explicit HTTP 400 before admission; the daemon continues serving other requests. Invalid policy syntax is a configuration error at startup.

Arguments and environment

endpoints:
  report:
    plugin: subproc
    config:
      prog: /opt/scripts/report.sh
      args: ["--format", "pdf"]
      allow-args:
        month:
          regex: '20[0-9]{2}-(0[1-9]|1[0-2])'
          repeatable: true
          nargs: '+'
        verbose:
          nargs: 0
      allow-env:
        TZ:
          choices: [UTC, Europe/Paris]
      disallow-env: [LD_PRELOAD, PYTHONPATH]

allow-args: [month] accepts --month VALUE or --month=VALUE, with one value of any content and one occurrence. Bare names mean long options; use -m to allow precisely that short option. month: 'REGEX' is shorthand for a regex rule. A mapping may use regex, choices, repeatable and nargs. Regexes match the entire value with a bounded evaluation time. Choice values must be YAML strings; use quotes for numeric-looking values. Both constraints apply if both are configured. Environment names are literal and case-sensitive; nargs and repeatable apply only to arguments.

nargs accepts 0 (a flag), a fixed integer, + (one or more) or * (zero or more). Every value is checked separately. Repetition is refused unless repeatable: true. A restricted policy refuses unknown options, positional arguments, abbreviations and compact short forms such as -abc or -mVALUE. Values beginning with an option-like dash must use --month=VALUE; negative numbers such as -1 can also be separate values. Auton keeps the original argument tokens, repeats and ordering. It does not build a shell command, transform values or decide how the target program interprets repeated options.

Opening a category and exceptions

allow-args: true
allow-env: true
allow-argfiles: true
allow-envfiles: true
disallow-args: [dangerous-option, '-x']
disallow-env: [LD_PRELOAD]
disallow-envfiles: [/etc/auton/private.env]

This explicitly permits all four categories, except named denials. disallow-*: true forbids the whole category, even if allowed. false adds no denial; in 2.0 it does not grant permission by itself. Empty allowlists grant nothing. A deny list matches exact names, not program-specific aliases; list every alias or prefer an allowlist. Compact short options are refused when using unrestricted arguments with exceptions. A literal -- ends option processing only with unrestricted arguments. The called program is still responsible for its own semantics. Explicit unlimited access should be restricted to trusted callers.

Files

Files declared under the server’s args, env, argfiles or envfiles remain usable independently of client permissions.

Client argfiles are uploads, not paths selected on the server. Auton decodes the uploaded bytes into a private temporary directory and passes that file’s path to the program. allow-argfiles: ['-f'] permits that upload option; a mapping can validate its original filename and allow repeated upload options. The -f@ syntax is checked as -f and still passes an @path value to programs that support it. This permission is separate from allow-args; neither grants the other. The contents are opaque program data: JSON, certificates, binary files, etc. They are not parsed as CLI arguments. Do not authorize file options whose target-program behavior gives callers more authority than intended.

Client envfiles select existing server files. Set allow-envfiles to true or a list of exact absolute paths. Exceptions use disallow-envfiles. Resolved paths are checked, so a symlink alias cannot bypass a denied resolved path. Administrators must control allowed files and their parent directories. The old candidate name allow-client-envfiles remains an alias with a warning; configure only one of the two names.

allow-envfiles: [/etc/auton/report.env]
allow-env:
  TZ:
    choices: [UTC, Europe/Paris]

Every variable read from a client-selected file must also pass allow-env / disallow-env, including variables later overridden by another source. Auton reads each file once before queueing, validates it and executes with that saved snapshot; later file changes do not change admitted tasks. Reads are limited to regular UTF-8 files of at most 1 MiB. Empty values use NAME=; a key without = has no string value and is rejected. Explicit policies keep ${...} literal; they never expand the daemon’s environment. The transition keeps legacy dotenv interpolation only for wholly implicit envfile/environment policies. Move fixed files into server configuration or declare their paths and variable rules.

Migration checklist

  1. Review startup warnings or the offline migration report.

  2. Add selective policies for every client input used by the endpoint, or explicitly set its allow-* to true to retain unrestricted access.

  3. Test valid and invalid calls against the transition release.

  4. Test a copy of the configuration on 2.0 before upgrading production.

All four permissions must be explicit to retain unrestricted 1.x client input. Existing disallow-* booleans remain supported. Rules reject invalid input as a whole; Auton never silently drops a forbidden option or variable. Policy errors identify the option/category without echoing its value. A policy validates strings up to 64 KiB without NUL bytes; the normal request size/count limits also remain in force.

Reusing policy blocks

Auton 1.5.0 and 2.0.0rc3 support six terminal YAML block imports, including imports inside import_config. Imported rules use the same policy syntax.