How awslabs/automated-security-helper works
Project type and purpose
• ASH is an open-source, Python-based CLI security scanning framework with a pluggable architecture and an optional AI-integration MCP server.
• It orchestrates multiple “scanner” tools (Bandit, Checkov, Semgrep, etc.) in isolated UV environments, applies optional conversion or inspection phases, aggregates results, and emits reports in many formats (SARIF, JSON, HTML, Markdown, CSV).
File structure to extract the main architectural components
• CLI : automated_security_helper/cli (entrypoints: ash, ash-multi, shell scripts under ash/ and support in utils/ash_helpers.*)
• Core engine : automated_security_helper/core (orchestrator, execution engine, phases pipeline: convert, scan, inspect, report)
• Plugin system :
• Plugin base classes: automated_security_helper/base
• Plugin manager / loader: automated_security_helper/plugins
• Built-in plugins: plugin_modules/ash_builtin (converters, scanners, reporters, event handlers) and plugin_modules/ash_aws_plugins
• Resource management : core/resource_management (task manager, scan registry/tracking, shutdown manager, state manager)
• Models & schemas : automated_security_helper/models (ASharpModel, ScanResultsContainer, vulnerability models) and automated_security_helper/schemas (JSON schema definitions)
• Configuration : automated_security_helper/config + .ash/.yaml config files + CLI flags
• Interactions : automated_security_helper/interactions (container runner, MCP server entrypoint)
• Utilities : utils/ and automated_security_helper/utils
• Documentation & examples : docs/, examples/
• Tests & CI : tests/, .github/workflows/, Dockerfile, mkdocs.yml
Readme insights
• Emphasizes phases (scan, inspect, report), multiple modes (local, container, precommit), UV tool isolation, pluggability, and AI integration via MCP.
• Highlights built-in scanners, reporting formats, and configuration override mechanisms.
Main components and their interactions
a. User Interfaces
• Shell script (ash / ash-multi) or uvx ... ash CLI entrypoint
• CLI module parses arguments and loads configuration.
b. Orchestrator / Execution Engine
• Coordinates pipeline phases:
1. Convert phase (normalize inputs)
2. Scan phase (invoke scanner plugins)
3. Inspect phase (post-processing of findings)
4. Report phase (emit structured outputs)
• Uses PluginManager to discover and schedule plugins.
c. Plugin System
• Scanners: execute external tools (via UV or system installation), fetch raw results (SARIF, JSON), then convert to internal models.
• Converters: e.g., archive or Jupyter converters to unwrap inputs.
• Reporters: flatten aggregated results into various formats.
• Event Handlers: listen to lifecycle events (scan start, scan end, suppression expiration).
• Plugin Base / Interfaces: ensure consistent plugin lifecycle and configuration.
d. Resource Management
• Manages concurrent scans, tracks progress, handles shutdowns, retries, error handling.
e. Models & Metrics
• Internal data classes represent findings, metrics, unified output.
• Validation system ensures scanner registration → enablement → execution → result collection.
f. Interactions & MCP Server
• MCP server module exposes engine via a streaming, concurrent-scan API for AI integrations (Amazon Q, Claude Desktop, VSCode).
• Tools: scan_directory, scan_directory_with_progress, get_scan_progress, etc.
g. Configuration Loader
• Loads .ash/ash.yaml or CLI parameters into typed configuration objects (JSON Schema validated).
h. Output
• Write aggregated JSON to .ash/ash_output/ash_aggregated_results.json
• Subfolders for per-scanner raw data and multi-format reports under .ash/ash_output/reports
Architectural patterns & principles
• Plugin architecture (Inversion of Control) allowing extension of scanners, reporters, converters, and event handlers.
• Pipeline / phased processing for modularity and predictable data flow.
• Resource manager to support concurrency, progress tracking, and graceful shutdown.
• UV tool isolation decouples scanner dependencies from project.
• MCP server implements an RPC-style interface over CLI for AI-driven workflows.
• Configuration-as-code validated by JSON Schema, override by env vars or CLI flags.