Configuration reference¶
This page is generated from the configuration models in the ASH source code by scripts/generate_config_reference.py. Edits made to this file by hand are overwritten the next time it is generated.
Every key is listed with its type, default and the description the model carries. A key whose model has no description says so. Keys inside a list are written key[].field: global_settings.suppressions[].rule_id is the rule_id of one entry in the suppressions list. A default written as from NAME, else value is read from that environment variable when ASH starts; value applies when the variable is not set.
Where ASH finds its configuration¶
A path given with --config, -c, or the ASH_CONFIG environment variable is used as is, and nothing is discovered.
Otherwise ASH looks in the scan's source directory and uses the first of these it finds. Sources are never merged: every other one that exists is ignored, with a warning naming it.
.ash.yml.ash/.ash.yml.ash.yaml.ash/.ash.yaml.ash.json.ash/.ash.jsonash.yml.ash/ash.ymlash.yaml.ash/ash.yamlash.json.ash/ash.json.ashrc.toml.ashrc.yaml.ashrc.yml.ashrc.jsonashrc.tomlashrc.yamlashrc.ymlashrc.jsonpyproject.toml
pyproject.toml counts only when it has a [tool.ash] table; one without it is not a configuration source.
These are read from the source directory only, never from .ash/: .ashrc.toml, .ashrc.yaml, .ashrc.yml, .ashrc.json, ashrc.toml, ashrc.yaml, ashrc.yml, ashrc.json, pyproject.toml.
A config file can name base files with extends. A chain may be at most 10 levels deep and read at most 50 files.
Top-level keys¶
A key not listed here is ignored, without an error, when the configuration is loaded.
| Key | Type | Default | Description |
|---|---|---|---|
project_name |
string | from ASH_PROJECT_NAME, else ash-scan |
Name of the project being scanned |
global_settings |
section | see the section | Global default settings for ASH shared across scanners. If the same setting exists at the scanner level and is set in both places, the scanner level settings take precedence. |
fail_on_findings |
boolean | true |
Whether to exit with non-zero code if findings are detected |
fail_on_incomplete_scanners |
boolean | true |
Whether to exit with a non-zero code when a selected scanner did not complete -- status ERROR (ran and failed) or MISSING (dependencies unavailable, never ran). A SKIPPED scanner, one not selected or one with nothing of its kind to scan, does not trip this by itself, but a run in which every scanner is SKIPPED, such as one where no selected scanner had a file to scan, exits 1 while this is on. Independent of fail_on_findings: one answers 'was anything found', this one answers 'did what I asked for actually run'. Selects on the scanner's status, so it covers only a failure that reached that status. Defaults to True, so a scanner recorded ERROR or MISSING does not report the exit code of a clean scan. Converters count too: one that crashed, one that could not convert some of its inputs, and one whose tool is missing while it had inputs make the scan exit non-zero the same way. Set it to False, or pass --no-fail-on-incomplete-scanners, to accept a partial scan's exit code; excluding the scanner whose tool is unavailable is usually better, because an excluded scanner is recorded SKIPPED and the report then says what was not measured. One ending overrides this setting: a run where ASH could not stop a scanner's tool exits 1 either way, because the tool may still be running and writing into the output directory. |
honor_ignore_files |
boolean | true |
Whether the .gitignore and .ignore files in the scanned tree decide which files are left out of ASH's scan set, the file list detect-secrets, cfn-nag, cdk-nag, cfn-lint, cfn-guard, actionlint, zizmor, npm-audit and the converters read. True (the default) leaves out every file they match. False scans those files too; ASH's own exclusions (.git, CDK assets, its own output directory) still apply. An operator setting: a config file inside the scanned tree, or one an MCP client supplied, cannot change it, and its value there is ignored with a warning. Set it in a config file outside the tree, with --config-overrides, or with --no-honor-ignore-files / --honor-ignore-files. Every scan records the outcome in metadata.ignore_file_exclusions. |
sandbox |
section | see the section | OS-level sandboxing of scanner subprocesses. |
content_db_staleness |
one of fail, warn |
fail |
What a scan does when a scanner's content database (grype's or trivy's vulnerability database, the offline semgrep/opengrep rulesets) was built longer ago than the bound declared for it in automated_security_helper/utils/content_databases.py. 'fail' (the default) keeps the scanner's findings and exits 1, naming the database, its build time, its age and the bound. 'warn' lets the scan pass and records the same warning in the log and in the reports (summary, SARIF invocation notifications, flat JSON). The CLI flag --allow-stale-content-db sets 'warn' for one scan and takes precedence over this value; --no-allow-stale-content-db sets 'fail'. |
content_db_staleness_overrides |
list of section | [] |
Per-database exceptions to content_db_staleness, each with a required expiration date and reason. An entry holds one named database to its own policy until 00:00 UTC on its expiration date, and every database not named keeps content_db_staleness. An expired entry is ignored with a warning. Empty by default. Either form of --allow-stale-content-db clears this list for that scan, so the flag still decides for every database. |
content_db_staleness_offline_image_default |
boolean | true |
Whether an image built with OFFLINE=YES holds trivy-db to 'warn' rather than to content_db_staleness: fail. Such an image carries the trivy database it was built with, and trivy's own bound would fail every scan in it from a day after the build; with this, those scans pass and every report records the stale database. Only trivy-db: grype-db and the offline rulesets keep content_db_staleness. ASH_OFFLINE_AT_BUILD_TIME=YES in ASH's environment, which the image sets from its OFFLINE build argument, turns it on; without that variable this does nothing, whatever it says. Set false to hold trivy-db to content_db_staleness in the image too. A content_db_staleness_overrides entry for trivy-db outranks it, and either form of --allow-stale-content-db sets this to false for that scan. |
ash_plugin_modules |
list of string | [] |
List of Python modules to import containing ASH plugins and/or event subscribers. These are loaded in addition to the default modules. |
external_reports_to_include |
list of string | [] |
List of external reports to include in the final report. These can be paths to SARIF or CycloneDX reports produced by other tools. |
build |
section or null | null |
Build-time configuration settings. ash config validate warns that this key is an internal field, and still passes the config; a scan accepts it. |
converters |
section | see the section | Converter configurations by name. |
scanners |
section | see the section | Scanner configurations by name. |
reporters |
section | see the section | Reporter configurations by name. |
output_formats |
list of one of aggregated, text, flat-json, yaml, csv, html, dict, junitxml, markdown, sarif, asff, ocsf, cyclonedx, spdx, custom, github-ghas, gitlab-sast, gitlab-cyclonedx, unused-suppressions, aws-security-hub, bedrock-summary-reporter, cloudwatch-logs, s3 |
[] |
Reports to write, by reporter name (for example sarif, markdown, github-ghas): a list, one name, or names separated by commas. Narrows the enabled reporters; it does not enable a disabled one. Empty or null writes every enabled reporter. A --output-formats list on the command line replaces this list. |
mcp-resource-management |
section | see the section | Configuration for MCP server resource management and limits. Also accepted as mcp_resource_management. |
workspace |
section | see the section | Workspace-mode execution settings. Read from the config resolved for the workspace root; a project's own copy of this block is ignored, because how many projects run at once is not a project's decision. |
extends |
string, list of string, or null | null |
Base config file(s) this config extends: a path, or a list of paths applied in order, relative to this file. Mappings merge key by key; lists and scalars from this file replace the base's. Paths must stay inside the repository being scanned; URLs are refused. Read when the file is loaded and not written back when a config is saved. |
patch |
list of mapping of string to any or null | null |
RFC 6902 JSON-Patch operations (add, remove, replace, test) applied after this file is merged over its bases. Use 'add' at '/global_settings/suppressions/-' to append to a base's list. Read when the file is loaded and not written back when a config is saved. |
Sections¶
global_settings¶
A key not listed here is an error when the configuration is loaded.
| Key | Type | Default | Description |
|---|---|---|---|
severity_threshold |
one of ALL, LOW, MEDIUM, HIGH, CRITICAL |
from ASH_DEFAULT_SEVERITY_LEVEL, else MEDIUM |
Global minimum severity level to consider findings as failures across all scanners |
ignore_paths |
list of section | [] |
Global list of IgnorePaths. Each path requires a reason for ignoring, e.g. 'Folder contains test data only and is not committed'. |
suppressions |
list of section | [] |
Global list of suppression rules. Each rule specifies findings to suppress based on rule ID, file path, and optional line numbers. |
mcp |
section | see the section | MCP-server-specific configuration (runtime override allowlist, etc.). |
global_settings.ignore_paths[]¶
Represents a path exclusion entry.
Each entry in the list has these keys.
A key not listed here is accepted and kept, without validation.
global_settings.suppressions[]¶
Represents a finding suppression rule.
Each entry in the list has these keys.
A key not listed here is accepted and kept, without validation.
global_settings.mcp¶
MCP-server-specific config bundle (transport-agnostic).
A key not listed here is an error when the configuration is loaded.
| Key | Type | Default | Description |
|---|---|---|---|
runtime_overrides |
section | see the section | Allowlist for runtime JSON-Patch overrides. |
global_settings.mcp.runtime_overrides¶
Allowlist + denylist controlling which JSON-Patch ops the MCP server accepts.
A key not listed here is an error when the configuration is loaded.
sandbox¶
OS-level sandboxing of scanner subprocesses. Off by default.
A key not listed here is an error when the configuration is loaded.
content_db_staleness_overrides[]¶
One content database held to a different staleness policy, until a fixed date.
Each entry in the list has these keys.
A key not listed here is an error when the configuration is loaded.
build¶
Configuration model for build-time settings.
A key not listed here is an error when the configuration is loaded.
mcp-resource-management¶
Configuration model for MCP resource management settings.
A key not listed here is an error when the configuration is loaded.
workspace¶
How many projects a workspace scan runs at once, and how long each may take.
A key not listed here is an error when the configuration is loaded.
Plugin sections¶
scanners, reporters and converters each map a plugin name to that plugin's configuration. Every plugin's entry has these keys; what goes under options is specific to the plugin and is listed on its reference page.
| Key | Type | Default | Description |
|---|---|---|---|
name |
string, length at least 1, matches ^[a-zA-Z][\w-]+$ |
the plugin's own name | Name of the component using letters, numbers, underscores and hyphens. Must begin with a letter. ash config validate warns that it is internal-only in a scanner, reporter, or converter entry, and still passes the config; a scan accepts it. |
enabled |
boolean | true |
Whether the component is enabled |
options |
mapping | the plugin's defaults | The plugin's options. Each plugin's are listed on its reference page: scanners, reporters, converters. |
scanners¶
The scanners ASH declares a configuration for. Other scanner names are accepted too (the section allows extra keys), for scanners loaded from ash_plugin_modules.
| Key | Enabled by default | Scanner options |
|---|---|---|
actionlint |
yes | actionlint options |
bandit |
yes | bandit options |
cdk-nag |
yes | cdk-nag options |
cfn-guard |
yes | cfn-guard options |
cfn-lint |
yes | cfn-lint options |
cfn-nag |
yes | cfn-nag options |
checkov |
yes | checkov options |
detect-secrets |
yes | detect-secrets options |
gitleaks |
yes | gitleaks options |
grype |
yes | grype options |
npm-audit |
yes | npm-audit options |
opengrep |
yes on Linux and macOS; no on Windows | opengrep options |
semgrep |
yes on Linux and macOS; no on Windows | semgrep options |
syft |
yes | syft options |
trivy |
yes | trivy options |
zizmor |
yes | zizmor options |
reporters¶
The reporters ASH declares a configuration for. Other reporter names are accepted too (the section allows extra keys), for reporters loaded from ash_plugin_modules.
| Key | Enabled by default | Reporter options |
|---|---|---|
csv |
yes | csv options |
cyclonedx |
yes | cyclonedx options |
gitlab-cyclonedx |
yes | gitlab-cyclonedx options |
html |
yes | html options |
flat-json |
yes | flat-json options |
gitlab-sast |
yes | gitlab-sast options |
github-ghas |
yes | github-ghas options |
junitxml |
yes | junitxml options |
markdown |
yes | markdown options |
ocsf |
yes | ocsf options |
sarif |
yes | sarif options |
spdx |
no | spdx options |
text |
yes | text options |
unused-suppressions |
yes | unused-suppressions options |
yaml |
no | yaml options |
converters¶
The converters ASH declares a configuration for. Other converter names are accepted too (the section allows extra keys), for converters loaded from ash_plugin_modules.
| Key | Enabled by default | Converter options |
|---|---|---|
archive |
yes | archive options |
jupyter |
yes | jupyter options |
Workspace policy file¶
In workspace mode, policy that applies to every project lives in its own file, separate from any project's configuration.
ASH looks for it at the workspace root and then in .ash/, under any of these names: .ash-workspace.yml, .ash-workspace.yaml, .ash-workspace.json, ash-workspace.yml, ash-workspace.yaml, ash-workspace.json.
Exactly one may exist: when ASH finds more than one, it refuses the workspace rather than choose.
Workspace policy keys¶
A key not listed here is an error when the configuration is loaded.
| Key | Type | Default | Description |
|---|---|---|---|
workspace |
section | see the section | Workspace-wide policy. Distinct from AshConfig.workspace, which holds execution scheduling knobs in a project config; nothing here can be set from a project's own file. |
Workspace policy workspace¶
Workspace-wide policy: the workspace block of the policy file.
A key not listed here is an error when the configuration is loaded.
| Key | Type | Default | Description |
|---|---|---|---|
max_severity_threshold |
one of ALL, LOW, MEDIUM, HIGH, CRITICAL, or null |
null |
The LOOSEST severity threshold any project may use. A project configuring something stricter keeps it; a project configuring something looser is tightened to this value. 'max' refers to permissiveness, not to severity: the strictness order is ALL < LOW < MEDIUM < HIGH < CRITICAL, so raising this value LOOSENS the ceiling. Unset means no ceiling. Case-sensitive. |
suppressions |
list of section | [] |
Suppressions that apply across the workspace. Paths are WORKSPACE-relative (e.g. 'api/src/legacy.py') and are rewritten into each project's own coordinates before being applied. A suppression that cannot match inside a project is not passed to it; one that cannot be rewritten soundly refuses the workspace. |
ignore_paths |
list of section | [] |
Paths excluded across the workspace. Workspace-relative and pushed down per project, exactly as 'suppressions' are. |
additional_scanners |
list of string | [] |
Scanners every project must run, in addition to whatever it enables itself. Additive only -- this cannot disable a scanner a project enabled. A scanner the project already declares runs under the project's own config and its findings are the project's; a scanner added only by this policy runs with default config and its findings are tagged 'origin: workspace-policy' and reported separately. |
policy_scanners_gate |
boolean | false |
Whether findings from policy-added scanners affect a project's exit code. Default false: a workspace that adds a scanner to gather visibility should not thereby fail projects that never opted into it, and turning it on is the operator saying they have triaged what the new scanner reports. |
Workspace policy workspace.suppressions[]¶
Represents a finding suppression rule.
Each entry in the list has these keys.
A key not listed here is accepted and kept, without validation.
Workspace policy workspace.ignore_paths[]¶
Represents a path exclusion entry.
Each entry in the list has these keys.
A key not listed here is accepted and kept, without validation.