Automated Security Helper (ASH)

Open-source orchestration for code, infrastructure, secret, and dependency scanners.

Quick start · Reports · Integrations · Configuration · Documentation

Quick start

Use Python 3.10 to 3.14 and pipx. For container mode, also install an OCI-compatible runtime such as Docker, Finch, or Podman.

pipx install git+https://github.com/awslabs/[email protected]

# Run from the project you want to scan
ash --mode container

The first container run builds the image and prepares scanner dependencies. Open .ash/ash_output/reports/ash.html or run ash inspect findings.

Execution modes

Local and pre-commit workflows use uv for managed tool installation. The installation guide covers platform prerequisites and dependency setup.

uvx --from git+https://github.com/awslabs/[email protected] ash --help
uvx --from git+https://github.com/awslabs/[email protected] ash --mode container

pip install git+https://github.com/awslabs/[email protected]

brew tap awslabs/automated-security-helper https://github.com/awslabs/automated-security-helper.git
brew trust awslabs/automated-security-helper
brew install ash

git clone --branch v3.7.1 https://github.com/awslabs/automated-security-helper.git
cd automated-security-helper
pip install .

Reports

• Check the outcome and scanner coverage.
• Review findings by severity.
• Inspect rule IDs, locations, and evidence.

Example scan results.

Offline HTML reports include search, filters, finding details, and printing.

ash inspect findings    # Open the terminal findings explorer
ash report              # Read the text summary of the latest scan

Output files

Default output lives in .ash/ash_output/. Enabled reporters write into reports/.

ASH also supports JUnit XML, CycloneDX, SPDX, OCSF, GitLab, YAML, and AWS reporting destinations. See the complete format guide.

Exit status: 0 means no actionable findings, or findings are allowed by policy; 1 means execution needs attention; 2 means actionable findings with failure-on-findings enabled; 3 means a configuration ASH cannot use or an input it refuses; 4 means a workspace definition or policy error; 5 means a usage error. A scan with incomplete coverage needs follow-up. Filters change the view; configured thresholds determine the scan gate.

Integrations

See integration options.

Connect an AI assistant

After installing ASH, add this server to your MCP client's configuration:

{
  "mcpServers": {
    "ash": {
      "command": "ash",
      "args": ["mcp"]
    }
  }
}

Stop polling on completed, incomplete, failed, or cancelled. Check scanner coverage before reviewing findings.

For agent instructions, install the ash-mcp skill:

npx skills add awslabs/automated-security-helper

The skill supplies workflow guidance. Configure the MCP server as above, or use a platform integration that includes server wiring. The MCP server guide covers client-specific setup. The HTTP transport guide covers remote source delivery, session handling, and deployment configuration.

Add a pre-commit check

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/awslabs/automated-security-helper
    rev: v3.7.1
    hooks:
      - id: ash

Run pre-commit run ash --all-files to check the project.

The ash hook runs precommit mode (bandit, detect-secrets, checkov, cdk-nag and npm-audit) and installs the cdk extra into its environment. It needs pre-commit running on Python 3.10 to 3.14, and Node.js and npm on PATH for cdk-nag and npm-audit. ash-simple-scan is the same hook under its earlier id, and ash-full-scan scans in the ASH container image instead. See Run ASH with pre-commit for running without Node.js and for the container hook.

Configuration

Create .ashrc.yaml at the project root to name the project, set the severity gate, and choose scanner and reporter options (existing configs under the older .ash/.ash.yaml name keep loading). The schema provides editor validation.

# 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
scanners:
  bandit:
    enabled: true
    options:
      confidence_level: high
reporters:
  markdown:
    enabled: true
    options:
      include_detailed_findings: true

Use the configuration guide for settings and overrides, the suppression guide for an accepted finding with a recorded reason, and plugin development for new capabilities.

Documentation

Report bugs and feature requests through GitHub issues. For security concerns, follow Security issue notifications.

Licensed under Apache 2.0. Bundled fonts and icons retain their respective licenses alongside their assets.

Build with <3 at Amazon Web Services