{"id":50101827,"url":"https://github.com/aws-samples/sample-mcp-security-scanner","last_synced_at":"2026-06-08T23:01:17.194Z","repository":{"id":350482231,"uuid":"1094492675","full_name":"aws-samples/sample-mcp-security-scanner","owner":"aws-samples","description":"This pattern describes how to implement a Model Context Protocol (MCP) server that integrates three industry-standard security scanning tools (Checkov, Semgrep, and Bandit) to provide comprehensive code security analysis. The server enables AI coding assistants like Kiro and Amazon Q Developer to automatically scan code snippets.","archived":false,"fork":false,"pushed_at":"2026-04-23T17:33:15.000Z","size":10377,"stargazers_count":11,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-23T19:27:37.550Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit-0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws-samples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"security_scanner_mcp_server/__init__.py","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-11T19:27:55.000Z","updated_at":"2026-04-14T18:07:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aws-samples/sample-mcp-security-scanner","commit_stats":null,"previous_names":["aws-samples/sample-mcp-security-scanner"],"tags_count":0,"template":false,"template_full_name":"amazon-archives/__template_MIT-0","purl":"pkg:github/aws-samples/sample-mcp-security-scanner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Fsample-mcp-security-scanner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Fsample-mcp-security-scanner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Fsample-mcp-security-scanner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Fsample-mcp-security-scanner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws-samples","download_url":"https://codeload.github.com/aws-samples/sample-mcp-security-scanner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-samples%2Fsample-mcp-security-scanner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34083848,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-23T08:00:31.591Z","updated_at":"2026-06-08T23:01:17.171Z","avatar_url":"https://github.com/aws-samples.png","language":"Python","funding_links":[],"categories":["🔌 MCP Security"],"sub_categories":["Scanners and Auditors"],"readme":"# MCP Security Scanner: Real-Time Protection for AI Code Assistants\n\nThis pattern describes how to implement a Model Context Protocol (MCP) server that integrates four industry-standard security scanning tools (Checkov, Semgrep, Bandit, and ASH) to provide comprehensive code security analysis. The server enables AI coding assistants to automatically scan code snippets and Infrastructure as Code (IaC) configurations for security vulnerabilities, misconfigurations, and compliance violations.\n\nThe solution combines Checkov for scanning IaC files (including Terraform, CloudFormation, and Kubernetes manifests), Semgrep for analyzing multiple programming languages (such as Python, JavaScript, Java, and others), Bandit for specialized Python security scanning, and ASH (Automated Security Helper) for comprehensive multi-tool scanning with aggregated results.\n\nIt provides a unified interface for security scanning with standardized response formats, making it easier to integrate security checks into development workflows. The pattern uses Python and the MCP framework to deliver automated security feedback, helping developers identify and address security issues early in the development process while learning about security best practices through detailed findings.\n\nThis pattern is particularly valuable for organizations looking to enhance their development security practices through AI-assisted coding tools, providing continuous security scanning capabilities across multiple programming languages and infrastructure definitions.\n\nKey features:\n - Delta scanning of new code segments, reducing computational overhead\n - Isolated security tool environments preventing cross-tool contamination\n - Seamless integration with AI tools (Amazon Q Developer, Kiro, others)\n - Real-time security feedback during code generation\n - Customizable scanning rules for organizational compliance\n\n\n## Demo\n\n### Code Scanning Demo\n\nTry these sample prompts with your AI assistant:\n1. \"Scan the current script and tell me the results\"\n2. \"Scan lines 20-60 and tell me the results\"\n3. \"Scan this Amazon DynamoDB table resource and tell me the result\"\n\n![Code Scanning Demo](docs/demo_code_scan.gif)\n\n### Code Generation with Security Scanning Demo\n\nTry these sample prompts to generate secure code:\n1. \"Generate a Terraform configuration to create a DynamoDB table with encryption enabled and scan it for security issues\"\n2. \"Create a Python Lambda function that writes to DynamoDB and scan it for vulnerabilities\"\n3. \"Generate a CloudFormation template for an S3 bucket with proper security settings and verify it passes security checks\"\n4. \"Write a Python script to query DynamoDB with pagination and scan for security best practices\"\n5. \"Create a Kubernetes deployment manifest for a microservice with security hardening and validate it\"\n\n![Code Generation Demo](docs/demo_code_generation.gif)\n\n\n\n## Architecture\n![Architecture Diagram](docs/diagram.png)\n\n## Features\n\nThis MCP server enables AI assistants to perform comprehensive security analysis on code snippets using four powerful security scanning tools:\n\n### 🛡️ Checkov - Infrastructure as Code Security\n- Scans Infrastructure as Code (IaC) files for security misconfigurations\n- Supports: Terraform, CloudFormation, Kubernetes, Dockerfile, ARM, Bicep, and more\n- Detects compliance violations and security best practices\n\n### 🔍 Semgrep - Source Code Security  \n- Analyzes source code for security vulnerabilities and bugs\n- Supports: Python, JavaScript, TypeScript, Java, Go, C/C++, C#, Ruby, PHP, Scala, Kotlin, Rust\n- Uses security-focused rulesets for comprehensive analysis\n\n### 🐍 Bandit - Python Security Specialist\n- Specialized Python security scanner\n- Detects common Python security issues like insecure functions, hardcoded secrets, injection vulnerabilities\n- Provides detailed confidence and severity ratings\n\n### 🚀 ASH - Automated Security Helper\n- Comprehensive multi-tool security scanner\n- Runs multiple scanners in parallel: Bandit, Checkov, cfn-nag, cdk-nag, detect-secrets, grype, syft, npm-audit\n- Delta scanning support for analyzing code changes\n- Aggregated results from all scanners with unified reporting\n- Supports all formats from the above tools plus additional scanners\n- **Note:** Semgrep is excluded from ASH scans to avoid duplication with the standalone `scan_with_semgrep` tool\n\n### 📦 Directory Scanning with File Output\n- All directory scanning tools save results to dedicated folders by default\n- Prevents context window overflow in LLM interactions\n- Output directories: `.grype/`, `.checkov/`, `.bandit/`, `.semgrep/`, `.ash/`, `.sbom/`, `.trivy/`\n- Returns lightweight summaries with file paths\n- Optional `return_output=True` parameter to get full results instead\n- Timestamped files for tracking scan history\n- See [SCANNER_FILE_OUTPUT.md](docs/SCANNER_FILE_OUTPUT.md) for details\n\n## Installation\n\n\u003e **Note:** The following instructions are for macOS/Linux. For Windows and other code assistants, see the [AWS MCP Repository README](https://github.com/awslabs/mcp) for platform-specific instructions.\n\n### Prerequisites\n- Python \u003e=3.10, \u003c=3.13\n- uv package manager (install from [Astral](https://docs.astral.sh/uv/getting-started/installation/))\n- (Optional) ASH - Automated Security Helper for comprehensive multi-tool scanning\n\n### Local Installation\n\nThis MCP server is not available via PyPI for enhanced security and control:\n\n- **Security**: Verify the exact code you're running by inspecting the repository\n- **Control**: Pin to specific versions and review changes before updating\n- **Performance**: Local caching improves startup speed and reduces network dependencies\n- **Trust**: Avoid potential package name confusion or use of unsecure mcp servers\n\nYou can install this server using one of two methods:\n\n#### Option 1: Install from Local Path\n\nClone or download the repository locally:\n\n```bash\ngit clone git@github.com:aws-samples/sample-mcp-security-scanner.git\ncd sample-mcp-security-scanner\n```\n\nThen configure your MCP client to use the local path (see configuration examples below).\n\n#### Option 2: Install from GitHub\n\nConfigure your MCP client to install directly from GitHub using:\n```\ngit+https://github.com/aws-samples/sample-mcp-security-scanner.git@main\n```\n\nThis method automatically downloads and installs the server without requiring a local clone (see configuration examples below).\n \n### Dependencies\nThe server automatically installs:\n- `checkov\u003e=3.0.0` - IaC security scanner\n- `semgrep\u003e=1.45.0` - Source code security scanner  \n- `bandit\u003e=1.7.5` - Python security scanner\n- `mcp[cli]\u003e=1.11.0` - MCP framework\n- `pydantic\u003e=1.10.0` - Data validation\n- `loguru\u003e=0.6.0` - Logging\n\n### Optional: ASH Integration\n\nFor comprehensive multi-tool scanning with ASH (Automated Security Helper):\n\n```bash\n# Install ASH using uvx (recommended)\nuvx git+https://github.com/awslabs/automated-security-helper.git@v3.2.5\n\n# Or install with pip\npip install git+https://github.com/awslabs/automated-security-helper.git@v3.2.5\n\n# Or install with pipx (isolated environment)\npipx install git+https://github.com/awslabs/automated-security-helper.git@v3.2.5\n\n# Verify installation\nash --version\n```\n\nASH provides additional scanners beyond the core three:\n- **cfn-nag**: CloudFormation security analysis\n- **cdk-nag**: AWS CDK security checks\n- **detect-secrets**: Secret detection in code\n- **grype**: Vulnerability scanning for dependencies\n- **syft**: Software Bill of Materials (SBOM) generation\n- **npm-audit**: Node.js dependency security\n\nNote: ASH requires Python 3.10+ and uses UV for package management. Some scanners may require additional dependencies (see [ASH documentation](https://github.com/awslabs/automated-security-helper)).\n\n## Usage\n\n### MCP Configuration\n\nConfigure your MCP client to use the server. The configuration varies by client and supports both local path and GitHub installation methods.\n\n### Getting Started with Kiro\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall in Kiro\u003c/summary\u003e\n\nSee [Kiro Model Context Protocol Documentation](https://kiro.dev/docs/mcp/configuration/) for details.\n\n1. Navigate `Kiro` \u003e `MCP Servers`\n2. Add a new MCP server by clicking the `Open MCP Config` button.\n3. Paste one of the configurations below:\n\n#### Option 1: Install from Local Path\n\nReplace `/path/to/sample-mcp-security-scanner` with your actual repository path:\n\n#### `.kiro/settings/mcp.json` (local) or `~/.kiro/settings/mcp.json` (global)\n\n```json\n{\n  \"mcpServers\": {\n    \"security-scanner\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"/path/to/sample-mcp-security-scanner\",\n        \"security_scanner_mcp_server\"\n      ],\n      \"env\": {\n        \"FASTMCP_LOG_LEVEL\": \"ERROR\",\n        \"WORKSPACE_ROOT\": \"/path/to/your/workspace\"\n      },\n      \"timeout\": 120000,\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\n#### Option 2: Install from GitHub\n\n```json\n{\n  \"mcpServers\": {\n    \"security-scanner\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"git+https://github.com/aws-samples/sample-mcp-security-scanner.git@main\",\n        \"security_scanner_mcp_server\"\n      ],\n      \"env\": {\n        \"FASTMCP_LOG_LEVEL\": \"ERROR\",\n        \"WORKSPACE_ROOT\": \"/path/to/your/workspace\"\n      },\n      \"timeout\": 120000,\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n### Getting Started with Amazon Q Developer\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall in Amazon Q Developer\u003c/summary\u003e\n\nSee [Amazon Q Developer documentation](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/qdev-mcp.html) for details.\n\n1. **Manual Configuration**\n   - Edit the MCP configuration file at `~/.aws/amazonq/mcp.json` (global) or `.amazonq/mcp.json` (local).\n   - Use one of the configurations below:\n\n#### Option 1: Install from Local Path\n\nReplace `/path/to/sample-mcp-security-scanner` with your actual repository path:\n\n#### `~/.aws/amazonq/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"security-scanner\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"/path/to/sample-mcp-security-scanner\",\n        \"security_scanner_mcp_server\"\n      ],\n      \"env\": {\n        \"FASTMCP_LOG_LEVEL\": \"ERROR\",\n        \"WORKSPACE_ROOT\": \"/path/to/your/workspace\"\n      },\n      \"timeout\": 120000\n    }\n  }\n}\n```\n\n#### Option 2: Install from GitHub\n\n```json\n{\n  \"mcpServers\": {\n    \"security-scanner\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"git+https://github.com/aws-samples/sample-mcp-security-scanner.git@main\",\n        \"security_scanner_mcp_server\"\n      ],\n      \"env\": {\n        \"FASTMCP_LOG_LEVEL\": \"ERROR\",\n        \"WORKSPACE_ROOT\": \"/path/to/your/workspace\"\n      },\n      \"timeout\": 120000\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n### Getting Started with Cline\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall in Cline\u003c/summary\u003e\n\n1. Install the [Cline VS Code Extension](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev).\n2. Click the extension to open it and select **MCP Servers**.\n3. Select the **Installed** tab, then click **Configure MCP Servers** to open the `cline_mcp_settings.json` file.\n4. Add one of the configurations below:\n\n#### Option 1: Install from Local Path\n\nReplace `/path/to/sample-mcp-security-scanner` with your actual repository path:\n\n#### `cline_mcp_settings.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"security-scanner\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"/path/to/sample-mcp-security-scanner\",\n        \"security_scanner_mcp_server\"\n      ],\n      \"env\": {\n        \"FASTMCP_LOG_LEVEL\": \"ERROR\",\n        \"WORKSPACE_ROOT\": \"/path/to/your/workspace\"\n      },\n      \"timeout\": 120000,\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\n#### Option 2: Install from GitHub\n\n```json\n{\n  \"mcpServers\": {\n    \"security-scanner\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"git+https://github.com/aws-samples/sample-mcp-security-scanner.git@main\",\n        \"security_scanner_mcp_server\"\n      ],\n      \"env\": {\n        \"FASTMCP_LOG_LEVEL\": \"ERROR\",\n        \"WORKSPACE_ROOT\": \"/path/to/your/workspace\"\n      },\n      \"timeout\": 120000,\n      \"disabled\": false,\n      \"autoApprove\": []\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n### Other Code Assistants\n\nFor configuration instructions for Cursor, Windsurf, VS Code, Claude Desktop, and other MCP clients, see the [AWS MCP Repository README](https://github.com/awslabs/mcp).\n\n### Available Tools\n\n#### 1. `scan_with_checkov`\nScan Infrastructure as Code files for security issues.\n\n**Parameters:**\n- `code` (string): IaC content to scan\n- `format_type` (string): Format type (terraform, cloudformation, kubernetes, dockerfile, etc.)\n\n#### 2. `scan_with_semgrep`\nScan source code for security vulnerabilities.\n\n**Parameters:**\n- `code` (string): Source code content to scan\n- `language` (string): Programming language (python, javascript, java, etc.)\n\n#### 3. `scan_with_bandit`\nScan Python code for security issues (Python-specific).\n\n**Parameters:**\n- `code` (string): Python code content to scan\n\n#### 4. `scan_with_ash`\nScan code using ASH for comprehensive multi-tool security analysis.\n\n**Parameters:**\n- `code` (string): Code content to scan\n- `file_extension` (string): File extension (e.g., .py, .tf, .js, Dockerfile)\n- `severity_threshold` (string, optional): Minimum severity threshold (LOW, MEDIUM, HIGH, CRITICAL). Default: MEDIUM\n\n**Features:**\n- Runs multiple security scanners in parallel\n- Provides aggregated results from all applicable scanners\n- Delta scanning optimized for code snippets\n- Unified severity reporting across all tools\n\n#### 5. `scan_with_trivy`\nScan Infrastructure as Code or Dockerfile using Trivy for security issues.\n\n**Parameters:**\n- `code` (string): Code content to scan (Dockerfile or IaC config)\n- `scan_type` (string, optional): Type of scan (dockerfile, terraform, kubernetes, config). Default: dockerfile\n\n#### 6. `check_ash_availability`\nCheck if ASH is installed and available, including which individual scanners are available.\n\n**Returns:** Installation status, version information, scanner availability details, and a formatted report\n\n**Example Response:**\n```json\n{\n  \"success\": true,\n  \"available\": true,\n  \"version\": \"3.2.1\",\n  \"message\": \"ASH is installed and available: 3.2.1\",\n  \"scanner_summary\": {\n    \"available\": 6,\n    \"total\": 9,\n    \"unavailable\": 3\n  },\n  \"formatted_report\": \"ASH Status: ✅ Installed (version 3.2.1)\\nScanner Availability: 6 out of 9 scanners available\\n\\n✅ Available Scanners:\\n  • Bandit - Python security linter (python-based)\\n  • Semgrep - Multi-language SAST (python-based)\\n  • Checkov - IaC security scanner (python-based)\\n  • cdk-nag - AWS CDK security scanner (npm-based)\\n  • detect-secrets - Secret detection (python-based)\\n  • npm-audit - Node.js dependency scanner (npm-based)\\n\\n❌ Missing Scanners:\\n  • cfn-nag - CloudFormation security scanner (ruby-based)\\n    Install with: gem install cfn-nag\\n  • Grype - Vulnerability scanner (binary)\\n    Install with: Install Grype from official source\\n  • Syft - SBOM generator (binary)\\n    Install with: Install Syft from official source\\n\\nThe tool successfully shows which scanners are available and which ones need additional OS-level dependencies.\",\n  \"scanners\": {\n    \"bandit\": {\n      \"name\": \"Bandit\",\n      \"description\": \"Python security linter\",\n      \"available\": true,\n      \"dependency_type\": \"python\",\n      \"file_types\": [\".py\"],\n      \"status\": \"installed\"\n    },\n    \"semgrep\": {\n      \"name\": \"Semgrep\",\n      \"description\": \"Multi-language SAST\",\n      \"available\": true,\n      \"dependency_type\": \"python\",\n      \"file_types\": [\".py\", \".js\", \".ts\", \".java\", \".go\", \".rb\", \".php\"],\n      \"status\": \"installed\"\n    },\n    \"checkov\": {\n      \"name\": \"Checkov\",\n      \"description\": \"IaC security scanner\",\n      \"available\": true,\n      \"dependency_type\": \"python\",\n      \"file_types\": [\".tf\", \".yaml\", \".yml\", \".json\", \"Dockerfile\"],\n      \"status\": \"installed\"\n    },\n    \"cfn-nag\": {\n      \"name\": \"cfn-nag\",\n      \"description\": \"CloudFormation security scanner\",\n      \"available\": false,\n      \"dependency_type\": \"ruby\",\n      \"file_types\": [\".yaml\", \".yml\", \".json\", \".template\"],\n      \"status\": \"not installed\",\n      \"install_hint\": \"gem install cfn-nag\"\n    },\n    \"cdk-nag\": {\n      \"name\": \"cdk-nag\",\n      \"description\": \"AWS CDK security scanner\",\n      \"available\": true,\n      \"dependency_type\": \"npm\",\n      \"file_types\": [\".ts\", \".js\"],\n      \"status\": \"installed\"\n    },\n    \"detect-secrets\": {\n      \"name\": \"detect-secrets\",\n      \"description\": \"Secret detection\",\n      \"available\": true,\n      \"dependency_type\": \"python\",\n      \"file_types\": [\"*\"],\n      \"status\": \"installed\"\n    },\n    \"grype\": {\n      \"name\": \"Grype\",\n      \"description\": \"Vulnerability scanner\",\n      \"available\": false,\n      \"dependency_type\": \"binary\",\n      \"file_types\": [\"*\"],\n      \"status\": \"not installed\",\n      \"install_hint\": \"Install Grype from official source\"\n    },\n    \"syft\": {\n      \"name\": \"Syft\",\n      \"description\": \"SBOM generator\",\n      \"available\": false,\n      \"dependency_type\": \"binary\",\n      \"file_types\": [\"*\"],\n      \"status\": \"not installed\",\n      \"install_hint\": \"Install Syft from official source\"\n    },\n    \"npm-audit\": {\n      \"name\": \"npm-audit\",\n      \"description\": \"Node.js dependency scanner\",\n      \"available\": true,\n      \"dependency_type\": \"npm\",\n      \"file_types\": [\"package.json\", \"package-lock.json\"],\n      \"status\": \"installed\"\n    }\n  }\n}\n```\n\n**Formatted Report Output:**\nWhen you call this tool, the AI assistant will display the `formatted_report` field which provides a clean, readable summary:\n\n```\nASH Status: ✅ Installed (version 3.2.1)\nScanner Availability: 6 out of 9 scanners available\n\n✅ Available Scanners:\n  • Bandit - Python security linter (python-based)\n  • Semgrep - Multi-language SAST (python-based) (disabled in ASH - use standalone scan_with_semgrep tool)\n  • Checkov - IaC security scanner (python-based)\n  • cdk-nag - AWS CDK security scanner (npm-based)\n  • detect-secrets - Secret detection (python-based)\n  • npm-audit - Node.js dependency scanner (npm-based)\n\n❌ Missing Scanners:\n  • cfn-nag - CloudFormation security scanner (ruby-based)\n    Install with: gem install cfn-nag\n  • Grype - Vulnerability scanner (binary)\n    Install with: Install Grype from official source\n  • Syft - SBOM generator (binary)\n    Install with: Install Syft from official source\n\nThe tool successfully shows which scanners are available and which ones need additional OS-level dependencies.\n```\n\n**Note:** Semgrep is excluded from ASH scans to avoid duplication with the standalone `scan_with_semgrep` tool, which provides more focused and faster scanning.\n\n**Use this tool to:**\n- Verify ASH installation before running scans\n- Check which scanners are available in your environment\n- Identify missing dependencies (e.g., cfn-nag requires Ruby, grype/syft are binaries)\n- Get installation hints for missing scanners\n\n#### 7. `get_supported_formats`\nGet information about supported formats and languages for all tools.\n\n#### 8. `generate_security_report`\nGenerate a SECURITY.md report from scan results.\n\n**Parameters:**\n- `project_name` (string): Name of the project being analyzed\n- `scan_results` (string): JSON string with scan results from any scanning tool. Can be a single result object or an array of result objects.\n\n**Workflow:**\n1. Scan relevant files using the appropriate scanner tools\n2. Collect all scan result JSON objects into an array\n3. Call `generate_security_report` with `project_name` and `scan_results` (JSON string)\n4. Save the returned `report` field as `SECURITY.md`\n\n**Report includes:**\n- Executive Summary — risk level (CRITICAL/HIGH/MEDIUM/LOW) and total finding counts\n- Scan Results — breakdown by scanner, format, and severity\n- Critical \u0026 High Severity Findings — detailed per-finding info\n- Medium \u0026 Low Severity Findings — summary table\n- Threat Model Inputs — STRIDE classification\n- Compliance \u0026 Regulatory Notes — SOC2, PCI-DSS, HIPAA, GDPR observations\n- Recommendations — prioritized actions by severity tier\n\n### Directory Scanning Tools\n\nThe following tools scan entire project directories and save results to files by default to prevent context window overflow:\n\n#### 8. `scan_directory_with_grype`\nScan a project directory for dependency vulnerabilities.\n\n**Parameters:**\n- `directory_path` (string): Path to the directory to scan\n- `severity_threshold` (string, optional): Minimum severity threshold (LOW, MEDIUM, HIGH, CRITICAL). Default: MEDIUM\n- `return_output` (bool, optional): Return full output instead of saving to file. Default: False\n\n**Output:** Saves to `.grype/grype_scan_{directory}_{timestamp}.json` and returns summary\n\n#### 9. `scan_directory_with_checkov`\nScan a project directory for IaC security issues.\n\n**Parameters:**\n- `directory_path` (string): Path to the directory to scan\n- `severity_threshold` (string, optional): Minimum severity threshold (LOW, MEDIUM, HIGH, CRITICAL). Default: MEDIUM\n- `return_output` (bool, optional): Return full output instead of saving to file. Default: False\n\n**Output:** Saves to `.checkov/checkov_scan_{directory}_{timestamp}.json` and returns summary\n\n#### 10. `scan_directory_with_bandit`\nScan a project directory for Python security issues.\n\n**Parameters:**\n- `directory_path` (string): Path to the directory to scan\n- `severity_threshold` (string, optional): Minimum severity threshold (LOW, MEDIUM, HIGH). Default: MEDIUM\n- `return_output` (bool, optional): Return full output instead of saving to file. Default: False\n\n**Output:** Saves to `.bandit/bandit_scan_{directory}_{timestamp}.json` and returns summary\n\n#### 11. `scan_directory_with_semgrep`\nScan a project directory for source code security issues.\n\n**Parameters:**\n- `directory_path` (string): Path to the directory to scan\n- `severity_threshold` (string, optional): Minimum severity threshold (LOW, MEDIUM, HIGH, CRITICAL). Default: MEDIUM\n- `return_output` (bool, optional): Return full output instead of saving to file. Default: False\n\n**Output:** Saves to `.semgrep/semgrep_scan_{directory}_{timestamp}.json` and returns summary\n\n#### 12. `scan_directory_with_ash`\nScan a project directory with ASH for comprehensive multi-tool security analysis.\n\n**Parameters:**\n- `directory_path` (string): Path to the directory to scan\n- `severity_threshold` (string, optional): Minimum severity threshold (LOW, MEDIUM, HIGH, CRITICAL). Default: MEDIUM\n- `return_output` (bool, optional): Return full output instead of saving to file. Default: False\n\n**Output:** Saves to `.ash/ash_scan_{directory}_{timestamp}.json` and returns summary\n\n#### 13. `scan_directory_with_syft`\nGenerate Software Bill of Materials (SBOM) for a project directory.\n\n**Parameters:**\n- `directory_path` (string): Path to the directory to scan\n- `output_format` (string, optional): Output format (json, cyclonedx-json, spdx-json, table). Default: json\n- `save_sbom` (bool, optional): Save full SBOM to file. Default: False (only returns summary)\n\n**Output:** Saves to `.sbom/sbom_{directory}_{timestamp}.{extension}` and returns summary\n\n#### 14. `scan_image_with_trivy`\nScan a container image for vulnerabilities.\n\n**Parameters:**\n- `image_name` (string): Container image to scan (e.g., nginx:latest, python:3.9)\n- `severity_threshold` (string, optional): Minimum severity threshold (LOW, MEDIUM, HIGH, CRITICAL). Default: MEDIUM\n- `return_output` (bool, optional): Return full output instead of saving to file. Default: False\n\n**Output:** Saves to `.trivy/trivy_scan_{image}_{timestamp}.json` and returns summary\n\n**Note:** All directory scanning tools automatically save full results to dedicated folders and return lightweight summaries. Use `return_output=True` to get full results in the response instead. See [SCANNER_FILE_OUTPUT.md](docs/SCANNER_FILE_OUTPUT.md) for more details.\n\n## Supported Formats\n\n### Checkov (IaC)\n- **terraform**: .tf, .tfvars, .tfstate\n- **cloudformation**: .yaml, .yml, .json, .template  \n- **kubernetes**: .yaml, .yml\n- **dockerfile**: Dockerfile\n- **arm**: .json (Azure Resource Manager)\n- **bicep**: .bicep\n- **serverless**: .yml, .yaml\n- **helm**: .yaml, .yml, .tpl\n- **github_actions**: .yml, .yaml\n- **gitlab_ci**: .yml, .yaml\n- **ansible**: .yml, .yaml\n\n### Semgrep (Source Code)\n- **python**: .py\n- **javascript**: .js\n- **typescript**: .ts\n- **java**: .java\n- **go**: .go\n- **c**: .c\n- **cpp**: .cpp\n- **csharp**: .cs\n- **ruby**: .rb\n- **php**: .php\n- **scala**: .scala\n- **kotlin**: .kt\n- **rust**: .rs\n\n### Bandit (Python Only)\n- **python**: .py files\n\n## Response Format\n\nAll scanning tools return a consistent response format:\n\n```json\n{\n  \"success\": true,\n  \"tool\": \"checkov|semgrep|bandit|ash\",\n  \"format_type\": \"terraform\",\n  \"language\": \"python\", \n  \"total_issues\": 3,\n  \"findings\": [\n    {\n      \"check_id\": \"CKV_AWS_20\",\n      \"severity\": \"HIGH\",\n      \"description\": \"S3 Bucket has an ACL defined which allows public access\",\n      \"line_number\": 3,\n      \"resource\": \"aws_s3_bucket.example\"\n    }\n  ],\n  \"summary\": {\n    \"high\": 1,\n    \"medium\": 2,\n    \"low\": 0\n  }\n}\n```\n\n## Integration with AI Assistants\n\nThis MCP server is designed to work with AI coding assistants like Kiro, Amazon Q Developer, Cline and others. The AI can:\n\n1. **Analyze generated code**: Automatically scan code snippets for security issues\n2. **Provide context-aware suggestions**: Get language and format-specific security recommendations  \n3. **Continuous security feedback**: Integrate security scanning into the development workflow\n4. **Educational insights**: Learn about security best practices through detailed findings\n\n## Kiro Power: Security Scanner\n\nThis repository is also packaged as a [Kiro Power](https://kiro.dev/docs/powers/) — a plug-and-play capability bundle that includes the MCP server, steering files, and documentation. Installing the power gives Kiro automatic access to all scanning tools without manual MCP configuration.\n\n### What's included\n\n```\nsample-mcp-security-scanner/\n├── POWER.md                          # Power metadata and documentation (repo root)\n├── mcp.json                          # Pre-configured MCP server (auto-approve all tools)\n├── steering/\n│   ├── scanning-workflows.md         # Auto-included: scanner selection, scan-fix-rescan loop, report generation\n│   └── secure-coding.md              # Auto-included: application, infrastructure, and dependency security rules\n├── security_scanner_mcp_server/      # MCP server source code\n├── agents/                           # Pre-built Kiro agent configs\n├── hooks/                            # Kiro hook definitions\n├── tests/                            # Test suite\n└── docs/                             # Documentation, examples, and assets\n```\n\n### How it works\n\n- **`mcp.json`** — Pre-configured MCP server definition with all scanning tools auto-approved. Kiro automatically starts the security scanner server when the power is installed.\n- **`scanning-workflows.md`** (auto-included steering) — Guides Kiro to pick the right scanner for each file type, run scan-fix-rescan loops, and generate SECURITY.md reports.\n- **`secure-coding.md`** (auto-included steering) — Instructs Kiro to proactively apply secure coding practices when generating or reviewing code (input validation, parameterized queries, no hardcoded secrets, strong crypto, least-privilege IAM, etc.).\n\n### Installing the power\n\n1. Open Kiro and navigate to the **Powers** panel.\n2. Click **Add Custom Power**.\n3. Select **Import power from GitHub**.\n4. Paste the repository URL and press Enter:\n   ```\n   https://github.com/aws-samples/sample-mcp-security-scanner\n   ```\n\nThe power auto-configures the MCP server and steering files — no manual setup needed.\n\n### Usage with the power\n\nOnce installed, Kiro automatically applies the steering rules in every conversation. You can use prompts like:\n\n- \"Scan the current file for security vulnerabilities\"\n- \"Scan this Terraform config, fix any issues, and re-scan until clean\"\n- \"Run security scans on the project and generate a SECURITY.md report\"\n- \"Scan the entire project directory and summarize the findings\"\n\nKiro will automatically select the right scanner based on file type, apply secure coding practices, and follow the scan-fix-rescan workflow.\n\n## Kiro Agent: Sec-Lazio\n\nThis repository includes a pre-built [Kiro](https://kiro.dev) agent that uses the MCP Security Scanner to provide security-first coding assistance.\n\n| Feature | Description |\n|---------|-------------|\n| Auto-scan | Scans every code change with Semgrep, Bandit, or Checkov |\n| Fix loop | Finds vulnerabilities → fixes them → re-scans until clean |\n| SECURITY.md | Generates structured reports with STRIDE threat model |\n| Secure by default | Applies security best practices when generating code |\n| Compliance hints | Flags SOC2, PCI-DSS, HIPAA, GDPR relevant patterns |\n\n### Quick install\n\n```bash\n# Global (all projects)\ncp agents/sec-lazio/sec-lazio.json ~/.kiro/agents/\n\n# Or project-specific\nmkdir -p .kiro/agents\ncp agents/sec-lazio/sec-lazio.json .kiro/agents/\n```\n\n### Activate\n\n```\n/agent sec-lazio\n```\n\nOr use the keyboard shortcut: `Ctrl+Shift+S`\n\nSee [agents/README.md](agents/README.md) for full documentation and example prompts.\n\n## Scanning Strategy\n\nUse the right scanner for the job:\n\n| File type | Primary scanner | Secondary scanner |\n|-----------|----------------|-------------------|\n| Python (.py) | `scan_with_bandit` | `scan_with_semgrep` |\n| JavaScript (.js), TypeScript (.ts) | `scan_with_semgrep` | — |\n| Java, Go, Rust, Kotlin, C# | `scan_with_semgrep` | — |\n| Terraform (.tf, .tfvars) | `scan_with_checkov` | — |\n| CloudFormation (.yaml, .yml, .json) | `scan_with_checkov` | — |\n| Kubernetes manifests | `scan_with_checkov` | — |\n| Dockerfile | `scan_with_checkov` | `scan_with_trivy` |\n| Container images | `scan_image_with_trivy` | — |\n| Dependency manifests | `scan_directory_with_grype` | — |\n| Full project | `scan_directory_with_*` variants | — |\n\nFor Python files, run both Bandit and Semgrep — they catch different classes of issues.\n\n## Severity Handling\n\n| Severity | Action |\n|----------|--------|\n| CRITICAL | Must be fixed before deployment — block the release |\n| HIGH | Fix in the current sprint — these are exploitable vulnerabilities |\n| MEDIUM | Triage and plan — fix in the next sprint or accept with justification |\n| LOW | Backlog — review for risk acceptance or opportunistic fix |\n\n## Development\n\n### Running Locally\n```bash\n# Clone and install\ngit clone git@github.com:aws-samples/sample-mcp-security-scanner.git\ncd sample-mcp-security-scanner\nuv pip install -e .\n\n# Run the server\npython -m security_scanner_mcp_server.server\n```\n\n### Testing\n\nThe project includes several test scripts to verify functionality:\n\n#### 1. Comprehensive Scanner Tests\n```bash\n# Test all scanners (Checkov, Semgrep, Bandit, ASH)\npython tests/test_scanner.py\n```\nThis script tests:\n- Checkov with Terraform code (S3 bucket and security group misconfigurations)\n- Semgrep with Python code (SQL injection and hardcoded secrets)\n- Bandit with Python code (insecure pickle usage and weak crypto)\n\n#### 2. ASH Integration Tests\n```bash\n# Test ASH availability and scanning\npython tests/test_ash_integration.py\n```\nThis script tests:\n- ASH installation and version check\n- ASH scanning with Python code containing security issues\n- Scanner availability reporting\n\n#### 3. Simple Standalone Tests\n```bash\n# Test scanners without MCP dependencies\npython tests/simple_test.py\n```\nThis script tests:\n- Basic Checkov functionality\n- Basic Semgrep functionality\n- Basic Bandit functionality\n- Useful for troubleshooting scanner installations\n\n#### 4. ASH Import Test\n```bash\n# Verify ASH module can be imported\npython test_ash_import.py\n```\nThis script verifies:\n- ASH module is properly installed\n- ASH version can be retrieved\n- Python environment is correctly configured\n\n### Sample Kiro Hooks\n\nThe project includes sample Kiro hooks in the `hooks/` directory that demonstrate automated security scanning workflows. These hooks can be installed in your Kiro IDE to enable automatic security scanning.\n\n#### 1. Security Scanner with Auto-Remediation\n**File:** `hooks/security-scan-on-save.kiro.hook`\n\nThis hook automatically scans files when saved and offers to fix security issues:\n\n**Features:**\n- Triggers on file save for source code and IaC files\n- Automatically selects the appropriate scanner:\n  - Bandit for Python files\n  - Semgrep for multi-language source code\n  - Checkov for Infrastructure as Code\n- Performs initial security scan\n- Offers to remediate findings (with approval):\n  - Replaces insecure functions with secure alternatives\n  - Removes hardcoded secrets\n  - Fixes SQL injection vulnerabilities\n  - Updates insecure configurations\n- Rescans after remediation to verify fixes\n- Provides detailed before/after comparison report\n\n**Supported File Types:**\n- Source code: `.py`, `.js`, `.ts`, `.java`, `.go`, `.c`, `.cpp`, `.cs`, `.rb`, `.php`, `.scala`, `.kt`, `.rs`\n- IaC: `.tf`, `.tfvars`, `.yaml`, `.yml`, `.json`, `.bicep`, `Dockerfile*`\n\n#### 2. Security Scanner Report (Read-Only)\n**File:** `hooks/security-scan-report-on-save.kiro.hook`\n\nThis hook scans all open editor files and provides a security report without modifying code:\n\n**Features:**\n- Triggers on file save\n- Scans ALL currently open editor files (not just the active one)\n- Automatically selects appropriate scanner per file type\n- Reports security issues with severity levels\n- Provides remediation recommendations\n- Read-only mode - never modifies source code\n- Reuses current chat session for continuous feedback\n\n**Use Cases:**\n- Security audits of multiple files\n- Pre-commit security checks\n- Learning about security issues without auto-fixing\n- Team code reviews with security focus\n\n#### Installing Hooks in Kiro\n\n1. **Copy hooks to your project:**\n   ```bash\n   # Copy to workspace-level hooks (project-specific)\n   cp hooks/*.kiro.hook .kiro/hooks/\n   \n   # Or copy to user-level hooks (global)\n   cp hooks/*.kiro.hook ~/.kiro/hooks/\n   ```\n\n2. **Enable hooks in Kiro:**\n   - Open Kiro IDE\n   - Navigate to the \"Agent Hooks\" section in the explorer view\n   - Enable the desired hooks\n   - Or use Command Palette: \"Open Kiro Hook UI\"\n\n3. **Customize hooks:**\n   - Edit the `.kiro.hook` files to adjust file patterns\n   - Modify the prompts to change scanning behavior\n   - Enable/disable auto-remediation as needed\n\n**Note:** Hooks require the security-scanner MCP server to be configured and running in Kiro.\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| Environment setup issues | Verify Python 3.10+ is installed. Ensure `uv` package manager is installed. |\n| Scanner issues | Verify file formats are supported. Check file syntax is valid. Ensure proper file extensions are used. |\n| Integration problems | Verify the MCP server is running. Check the configuration file is correct. Validate API endpoints. |\n| ASH not available | Install ASH using `uvx git+https://github.com/awslabs/automated-security-helper.git@v3.2.5` |\n| Trivy not found | macOS: `brew install trivy`. Linux: see [Trivy installation](https://aquasecurity.github.io/trivy/latest/getting-started/installation/). |\n\nTo enable debug logging, set `\"FASTMCP_LOG_LEVEL\"` to `\"DEBUG\"` in your MCP configuration.\n\n## Related Resources\n\n- [AWS Prescriptive Guidance Pattern](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/deploy-real-time-coding-security-validation-by-using-an-mcp-server-with-kiro-and-other-coding-assistants.html)\n- [MCP Security Scanner on GitHub](https://github.com/aws-samples/sample-mcp-security-scanner)\n- [Model Context Protocol (MCP) documentation](https://modelcontextprotocol.io/)\n- [Kiro documentation](https://kiro.dev/docs/)\n- [Amazon Q Developer documentation](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/)\n- [OWASP Secure Coding Practices](https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/)\n- [Bandit documentation](https://bandit.readthedocs.io/)\n- [Checkov documentation](https://www.checkov.io/1.Welcome/Quick%20Start.html)\n- [Semgrep documentation](https://semgrep.dev/docs/)\n- [ASH documentation](https://github.com/awslabs/automated-security-helper)\n\n## Contributing\n\nContributions welcome! Please read CONTRIBUTING.md for guidelines.\n\n## Authors\n\nPattern created by Ivan Girardi (AWS) and Iker Reina Fuente (AWS).\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis library is licensed under the MIT-0 License. See the LICENSE file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-samples%2Fsample-mcp-security-scanner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-samples%2Fsample-mcp-security-scanner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-samples%2Fsample-mcp-security-scanner/lists"}