Skip to content

Configuration Overrides

ASH supports runtime configuration overrides through the --config-overrides CLI parameter. This allows you to modify configuration values without editing the configuration file.

Basic Usage

ash --config-overrides 'reporters.markdown.options.include_detailed_findings=true'

You can specify multiple overrides by using the parameter multiple times:

ash \
  --config-overrides 'reporters.cloudwatch-logs.options.aws_region=us-west-2' \
  --config-overrides 'global_settings.severity_threshold=LOW'

Supported Value Types

The configuration override system automatically converts values to appropriate types:

  • Strings: 'key=value'
  • Numbers: 'key=123' or 'key=3.14'
  • Booleans: 'key=true' or 'key=false'
  • Null: 'key=null' or 'key=none'
  • Lists: 'key=[item1, item2, item3]' or 'key=["item1", "item2", "item3"]'
  • Dictionaries: 'key={"subkey1": "value1", "subkey2": "value2"}'

Advanced Features

List Append Mode

You can append to existing lists by adding a + at the end of the key path:

# Add a new plugin module without replacing existing ones
ash --config-overrides 'ash_plugin_modules+=["my_ash_plugins"]'

Complex Structures

For complex structures, you can use JSON syntax:

# Add a new ignore path
ash --config-overrides 'global_settings.ignore_paths+=[{"path": "build/", "reason": "Generated files"}]'

Examples

  1. Change severity threshold: 

    ash --config-overrides 'global_settings.severity_threshold=LOW'

  2. Enable a specific scanner: 

    ash --config-overrides 'scanners.bandit.enabled=true'

  3. Configure AWS region for CloudWatch Logs reporter: 

    ash --config-overrides 'reporters.cloudwatch-logs.options.aws_region=us-west-2'

  4. Replace the list of plugin modules: 

    ash --config-overrides 'ash_plugin_modules=["automated_security_helper.plugin_modules.ash_aws_plugins"]'

  5. Add a plugin module to the existing list: 

    ash --config-overrides 'ash_plugin_modules+=["automated_security_helper.plugin_modules.custom_plugin"]'

  6. Configure multiple scanner options: 

    ash \
  --config-overrides 'scanners.bandit.options.confidence_level=high' \
  --config-overrides 'scanners.bandit.options.ignore_nosec=true'

Configuration Management

ASH provides several ways to manage your configuration:

Configuration File

ASH uses YAML configuration files by default. The standard location is .ash/.ash.yaml in your project directory. You can also use JSON format with .ash/.ash.json.

A basic configuration file looks like this:

# yaml-language-server: $schema=https://raw.githubusercontent.com/awslabs/automated-security-helper/refs/heads/main/automated_security_helper/schemas/AshConfig.json
project_name: my-project
global_settings:
  severity_threshold: MEDIUM
  ignore_paths:
    - path: 'tests/test_data'
      reason: 'Test data only'
scanners:
  bandit:
    enabled: true
    options:
      confidence_level: high
reporters:
  markdown:
    enabled: true
    options:
      include_detailed_findings: true

JSON Schema Support

ASH provides a JSON schema for configuration files, which enables validation and auto-completion in compatible editors. Add this line at the top of your YAML file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/awslabs/automated-security-helper/refs/heads/main/automated_security_helper/schemas/AshConfig.json

Configuration Commands

ASH provides several commands to manage your configuration:

Initialize a Configuration

Create a new configuration file:

ash config init

This creates a default configuration file at .ash/.ash.yaml.

View Current Configuration

View the current configuration:

ash config get

You can also apply overrides when viewing the configuration:

ash config get --config-overrides 'scanners.bandit.enabled=false'

Update Configuration

Update an existing configuration file:

ash config update --set 'scanners.bandit.enabled=false' --set 'global_settings.severity_threshold=LOW'

You can use the same syntax as --config-overrides, including list operations:

# Add a new ignore path
ash config update --set 'global_settings.ignore_paths+=[{"path": "build/", "reason": "Generated files"}]'

# Preview changes without writing to file
ash config update --set 'scanners.semgrep.enabled=false' --dry-run

Validate Configuration

Validate your configuration file:

ash config validate

You can also validate with overrides:

ash config validate --config-overrides 'scanners.bandit.options.confidence_level=high'

Custom Plugins

You can add custom plugins to ASH by specifying them in the ash_plugin_modules list. The top-level package must be inside ASH's plugin namespace: either under automated_security_helper., or a top-level package whose name ends in ash_plugins (my_ash_plugins, acme_ash_plugins). A module outside that namespace is skipped with a warning rather than imported, so a name like my_plugins silently registers nothing.

ash_plugin_modules:
  - my_ash_plugins

Or using the override:

ash --config-overrides 'ash_plugin_modules+=["my_ash_plugins"]'

Notes

  • Configuration overrides are applied after loading the configuration file
  • Overrides work with both default and explicit configurations
  • An override that cannot be parsed, or that produces a configuration failing validation, stops the run with exit code 3 (invalid config). Nothing is scanned, because continuing would mean scanning with settings you did not choose. Note that a top-level key ASH does not recognise is still ignored rather than rejected, for compatibility with configuration files written against other ASH versions.
  • For complex values, use valid JSON syntax
  • Environment variables can be referenced in YAML configuration files using !ENV ${VAR_NAME:default_value} syntax. VAR_NAME must begin with ASH_, or be one of AWS_REGION, AWS_DEFAULT_REGION or AWS_PROFILE. A reference to any other name is left in the configuration exactly as written and a warning names it; ASH does not read the variable. The names are matched exactly, so write them in upper case.

ASH reads the configuration file it finds in the directory it is scanning, so which variables that file may name is ASH's decision rather than the file's. To reference a variable of your own, give it an ASH_ prefix — ASH_MY_BUCKET rather than MY_BUCKET — and set it under that name wherever you run ASH.

A reference with no default, ${VAR_NAME}, has never resolved and still does not; write ${VAR_NAME:default_value}. A reference must also be the whole value, not part of a longer string.