ASH - Automated Security Helper

Table of Contents

• Table of Contents
• Overview
• Key Features in ASH v3
• Built-In Scanners
• Prerequisites
• Runtime Requirements
• Installation Options
• Quick Install (Recommended)
• Other Installation Methods
  • Using uvx
  • Using pip
  • Clone the Repository
• Basic Usage
• Sample Output
• AI Integration with MCP
• MCP Server Features
• Installation and Setup
  • Prerequisites
  • Client Configuration
• Available MCP Tools
• Usage Examples
• Configuration Support
• Configuration
• Using ASH with pre-commit
• Output Files
• FAQ
• Documentation
• Feedback and Contributing
• Security
• License
• Star History

Overview

ASH (Automated Security Helper) is a security scanning tool designed to help you identify potential security issues in your code, infrastructure, and IAM configurations as early as possible in your development process.

• ASH is not a replacement for human review or team/customer security standards
• It leverages lightweight, open-source tools for flexibility and portability
• ASH v3 has been completely rewritten in Python with significant improvements to usability and functionality

Key Features in ASH v3

• Python-based CLI: ASH now has a Python-based CLI entrypoint while maintaining backward compatibility with the shell script entrypoint
• Multiple Execution Modes: Run ASH in local, container, or precommit mode depending on your needs
• Enhanced Configuration: Support for YAML/JSON configuration files with overrides via CLI parameters
• Improved Reporting: Multiple report formats including JSON, Markdown, HTML, and CSV
• Scanner Validation System: Comprehensive validation ensures all expected scanners are registered, enabled, queued, executed, and included in results
• Pluggable Architecture: Extend ASH with custom plugins, scanners, and reporters
• Unified Output Format: Standardized output format that can be exported to multiple formats (SARIF, JSON, HTML, Markdown, CSV)
• UV Package Management: ASH now uses UV for faster dependency resolution and tool isolation
• Comprehensive Testing: Extensive integration test suite validates UV migration functionality across platforms

Built-In Scanners

ASH v3 integrates multiple open-source security tools as scanners. Tools like Bandit, Checkov, and Semgrep are managed via UV's tool isolation system, which automatically installs and runs them in isolated environments without affecting your project dependencies:

Prerequisites

Runtime Requirements

Installation Options

Quick Install (Recommended)

# Install uv on Linux/macOS if it isn't installed already
curl -sSfL https://astral.sh/uv/install.sh | sh

# Create an alias for ASH
alias ash="uvx git+https://github.com/awslabs/automated-security-helper.git@v3.5.6"

# Install uv on Windows with PowerShell if it isn't installed already
irm https://astral.sh/uv/install.ps1 | iex

# Create a function for ASH
function ash { uvx git+https://github.com/awslabs/automated-security-helper.git@v3.5.6 $args }

Floating tag v3: We also maintain a v3 floating tag that always points to the latest stable v3.x release. You can use @v3 instead of @v3.5.6 to stay up to date automatically. Pin a specific version (e.g., @v3.5.6) when you need reproducible builds.

Other Installation Methods

Click to expand other installation options

Using Homebrew (macOS/Linux)

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

Using pipx

# Install with pipx (isolated environment)
pipx install git+https://github.com/awslabs/automated-security-helper.git@v3.0,1

# Use as normal
ash --help

Using pip

pip install git+https://github.com/awslabs/automated-security-helper.git@v3.5.6

Clone the Repository

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

Basic Usage

# Run a scan in local mode (Python only)
ash --mode local

# Run a scan in container mode (all tools)
ash --mode container

# Run a scan in precommit mode (fast subset of tools)
ash --mode precommit

Sample Output

                                                 ASH Scan Results Summary
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━┳━━━━━━━━┳━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ Scanner        ┃ Suppressed ┃ Critical ┃ High ┃ Medium ┃ Low ┃ Info ┃ Duration ┃ Actionable ┃ Result ┃ Threshold       ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━╇━━━━━━━━╇━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ bandit         │ 7          │ 0        │ 1    │ 0      │ 56  │ 0    │ 19.9s    │ 1          │ FAILED │ MEDIUM (global) │
│ cdk-nag        │ 0          │ 0        │ 30   │ 0      │ 0   │ 5    │ 48.7s    │ 30         │ FAILED │ MEDIUM (global) │
│ cfn-nag        │ 0          │ 0        │ 0    │ 15     │ 0   │ 0    │ 45.1s    │ 15         │ FAILED │ MEDIUM (global) │
│ checkov        │ 10         │ 0        │ 25   │ 0      │ 0   │ 0    │ 38.9s    │ 25         │ FAILED │ MEDIUM (global) │
│ detect-secrets │ 0          │ 0        │ 48   │ 0      │ 0   │ 0    │ 18.9s    │ 48         │ FAILED │ MEDIUM (global) │
│ grype          │ 0          │ 0        │ 2    │ 1      │ 0   │ 0    │ 40.3s    │ 3          │ FAILED │ MEDIUM (global) │
└────────────────┴────────────┴──────────┴──────┴────────┴─────┴──────┴──────────┴────────────┴────────┴─────────────────┘
                                                     source-dir: '.'
                                              output-dir: '.ash/ash_output'

=== ASH Scan Completed in 1m 6s: Next Steps ===
View detailed findings...
  - SARIF: '.ash/ash_output/reports/ash.sarif'
  - JUnit: '.ash/ash_output/reports/ash.junit.xml'
  - ASH aggregated results JSON available at: '.ash/ash_output/ash_aggregated_results.json'

=== Actionable findings detected! ===
To investigate...
  1. Open one of the summary reports for a user-friendly table of the findings:
    - HTML report of all findings: '.ash/ash_output/reports/ash.html'
    - Markdown summary: '.ash/ash_output/reports/ash.summary.md'
    - Text summary: '.ash/ash_output/reports/ash.summary.txt'
  2. Use ash report to view a short text summary of the scan in your terminal
  3. Use ash inspect findings to explore the findings interactively
  4. Review scanner-specific reports and outputs in the '.ash/ash_output/scanners' directory

=== ASH Exit Codes ===
  0: Success - No actionable findings or not configured to fail on findings
  1: Error during execution
  2: Actionable findings detected when configured with `fail_on_findings: true`. Default is True. Current value: True
ERROR (2) Exiting due to 122 actionable findings found in ASH scan

AI Integration with MCP

ASH includes a Model Context Protocol (MCP) server that enables AI assistants to perform security scans and analyze results through a standardized interface. This allows you to integrate ASH with AI development tools like Amazon Q CLI, Claude Desktop, and Cline (VS Code).

MCP Server Features

The ASH MCP server provides:

• Real-time Progress Tracking: Monitor scan progress with streaming updates
• Background Scanning: Start scans and continue other work while they run
• Multiple Scan Management: Handle concurrent scans with unique identifiers
• Comprehensive Error Handling: Detailed error messages and recovery suggestions
• Configuration Support: Full support for ASH configuration files and environment variables

Installation and Setup

Prerequisites

1. Install UV: Install uv from Astral or the GitHub README
2. Install Python 3.10+: Use uv python install 3.10 (or a more recent version)

Client Configuration

Amazon Q Developer CLI - Add to ~/.aws/amazonq/mcp.json:

{
  "mcpServers": {
    "ash": {
      "command": "uvx",
      "args": [
        "--from=git+https://github.com/awslabs/automated-security-helper@v3.5.6",
        "ash",
        "mcp"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Claude Desktop - Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ash-security": {
      "command": "uvx",
      "args": [
        "--from=git+https://github.com/awslabs/automated-security-helper@v3.5.6",
        "ash",
        "mcp"
      ]
    }
  }
}

Cline (VS Code): ```json { "mcpServers": {