ASH - Automated Security Helper

• Table of Contents
• Overview
• Key Features in ASH v3
• Built-In Scanners
• Prerequisites
  • Runtime Requirements
• Installation Options
  • Quick Install (Recommended)
  • Other Installation Methods
    • Using Homebrew (macOS/Linux)
    • Using pipx
    • 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
• Installing ASH into an AI Coding Agent
  • Option 1: Install the skill
  • Option 2: Install a platform plugin
  • Option 3: Configure the MCP server directly
• Configuration
• Using ASH with pre-commit
• Output Files
• FAQ
• Documentation
• Feedback and Contributing
• Security
• License
• Star History

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

• 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

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:

# 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.7.0"

# 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.7.0 $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.7.0 to stay up to date automatically. Pin a specific version (e.g., @v3.7.0) when you need reproducible builds.

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

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

# Use as normal
ash --help

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

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

# 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

                                                 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

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).

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

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)

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.7.0",
        "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.7.0",
        "ash",
        "mcp"
      ]
    }
  }
}

Cline (VS Code):

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

The ASH MCP server provides these tools:

The last four matter only on a network transport, where the client has no path on the server to name. Deliver a tree with them, then call run_ash_scan with no source_dir and it scans what you delivered. Each takes its session from the transport's Mcp-Session-Id header rather than from an argument, so one client cannot name another's workspace. See the streamable-HTTP guide for the limits and the security boundary.

Once configured, you can interact with ASH through natural language. Each of the sentences below represent prompts which can be used in the various coding CLIs (Q CLI, Cline, etc.) in order to inform the CLI to identify the ASH MCP tool and use it based on the instructions provided in the prompt.

Basic Security Scanning:

"Can you scan this project directory for security vulnerabilities?"
"Please run ASH on the ./src folder and analyze the results"
"Check this code for security issues with HIGH severity threshold"

Progress Monitoring:

"Start a security scan on this directory and show me the progress"
"Monitor the current scan and let me know when it's done"
"What's the status of my running security scans?"

Analysis & Reporting:

"Perform a comprehensive security audit and create a prioritized action plan"
"Scan this code and help me fix any critical security issues"
"Generate a security report with remediation recommendations"

The MCP server supports all ASH configuration methods:

• Configuration files: .ash/ash.yaml or custom config paths
• Environment variables: ASH_DEFAULT_SEVERITY_LEVEL, ASH_OFFLINE, etc.
• CLI parameters: Severity thresholds, custom output directories

For detailed information about streaming capabilities and advanced usage, see the MCP Streaming Guide.

You do not have to wire the MCP server by hand. This repository also ships prebuilt integrations under ash-agent-plugins/, generated from one source of truth so every agent gets the same content.

There are three ways in, ordered here by how much work they ask of you. They are alternatives, not steps — pick one. All three end up calling the same ASH MCP server, so scan behavior does not change between them.

Install ASH first and make sure ash runs from your shell; see Installation Options. These integrations tell an agent how to call ASH. They do not install ASH.

npx skills add awslabs/automated-security-helper

That installs the ash-mcp skill, which teaches an agent the start-scan, poll-progress, fetch-results workflow and when to reach for it. skills is Vercel's open agent-skills CLI. It detects which supported agent you have and writes the skill into that agent's own directory, so you do not need to know which one you are running or where it keeps its skills. Pass --list to see what it finds without installing anything, or --agent to target a specific agent.

A skill carries instructions, not MCP configuration. If your agent is not already pointed at the ASH MCP server, use one of the two options below as well.

A plugin is the fuller integration: MCP server wiring, slash commands, an agent definition, and rules files in the platform's native format. Two of the more common agents install with a single command, run from the repository root:

# Claude Code — load the plugin directly
claude --plugin-dir ./ash-agent-plugins/agentic-coding/plugins/claude

# Codex CLI — register the plugin marketplace, then install from it
codex plugin marketplace add ./ash-agent-plugins/agentic-coding/plugins/codex

Cursor and GitHub Copilot are copy-in rather than CLI installs. Working from ash-agent-plugins/agentic-coding/plugins/, copy cursor/.cursor/ into the root of your own repository; for Copilot copy both copilot/.github/ and copilot/.vscode/, which needs VS Code 1.104 or newer. Merge into a directory of the same name if you already have one rather than replacing it.

Fifteen platforms have a plugin tree and each has its own install step. ash-agent-plugins/README.md holds the full table, one generated tree per platform with the exact command or copy step for each. Treat that table as the authoritative list. It is deliberately not duplicated here, because it changes whenever a platform is added and a second copy would go stale.

If your agent has no plugin tree but does speak MCP, point it at the server yourself. Client Configuration above has JSON you can paste for Amazon Q Developer CLI, Claude Desktop, and Cline; the same shape works for any MCP client that takes a command and arguments.

ASH v3 uses a YAML configuration file (.ash/ash.yaml) with support for JSON Schema 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
  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

Add this to your .pre-commit-config.yaml:

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

Run with:

pre-commit run ash-simple-scan --all-files

ASH v3 produces several output files in the .ash/ash_output/ directory:

• ash_aggregated_results.json: Complete machine-readable results including validation checkpoints
• reports/ash.flat.json: Flattened JSON array of findings for scripts and dashboards
• reports/ash.sarif: SARIF 2.1.0 report for IDE and CI/CD integration
• reports/ash.summary.txt: Human-readable text summary
• reports/ash.summary.md: Markdown summary for GitHub PRs and other platforms
• reports/ash.html: Interactive HTML report
• reports/ash.csv: CSV report for filtering and sorting findings

ASH also supports CycloneDX, SPDX, OCSF, GitLab SAST, JUnit XML, and YAML output. Enable any combination of reporters in your .ash/ash.yaml configuration. For the complete schema reference, consumption examples, and format details, see Output Formats.

The ash_aggregated_results.json file includes comprehensive validation information that tracks scanner registration, enablement, execution, and result inclusion throughout the scan process. The Scanner Validation System can also generate detailed validation reports that provide comprehensive analysis of scanner states, validation checkpoints, dependency issues, and actionable recommendations for troubleshooting scan issues.

For complete documentation, visit the ASH Documentation.

• Create an issue here
• See CONTRIBUTING for contribution guidelines

See CONTRIBUTING for security issue reporting information.

This library is licensed under the Apache 2.0 License. See the LICENSE file.