Feature/ferret scan plugin (#233)

* feat: add ferret-scan community plugin for sensitive data detection

Adds a new community scanner plugin that integrates ferret-scan for
detecting sensitive data (PII, credentials, secrets) in source code
and documents.

Features:
- Wraps ferret-scan CLI with SARIF output for ASH integration
- Supports configurable confidence levels and check filtering
- Bundled profiles: quick, debug, ci, security-audit, comprehensive
- Version compatibility validation (>=1.0.0, <2.0.0)
- Graceful handling of empty directories and missing dependencies

Includes:
- Plugin module with scanner, config, and documentation
- 64 unit tests with full coverage
- Test data fixtures
- Community plugin registration in .ash_community_plugins.yaml
- CI workflow updates for ferret-scan installation
- Hugo documentation page for the plugin

* remived ferret from .ash.yaml

* updated dev readme

* fixed logging options for plugin so as not to be confused with ash options. updated test data. updated docs.

* suppressed false positives triggered by test data

* fixed windows path separator issue in ferret-scan test

* fixed false positive suppression. fixed ferret-scan config to catch only high confidence matches

* updated documentation to reflect ferret-scan testing changes

* changed test var to prevent triggering false positive

* added a test/validation/hygeine script to improve build success

* replaced false positives in docs

* suppressed false positives in docs

* communit plugins suppression did not work. Re-adding to ash.yaml

* communit plugins suppression did not work. Re-adding to ash.yaml

* fix: remove PyYAML dependency from validate_ferret_plugin.py

Replace yaml.safe_load with stdlib-only line parser for reading
suppressions from .ash_community_plugins.yaml. PyYAML is not
available in the CI test environment where the validation script
runs via subprocess (not uv run).

Fixes TestFerretPluginValidation::test_validate_ferret_plugin_passes
failing on all CI platforms with ModuleNotFoundError: No module named
'yaml'.

* fix: eliminate SECRET-SECRET-KEYWORD trigger from DEVELOPMENT.md line 501

Split API_KEY from the assignment operator in the documentation example
so the keyword + '=' pattern no longer triggers the SECRET-SECRET-KEYWORD
rule. Removed the now-unnecessary suppression entry from the community
plugins config.

* Revert "fix: eliminate SECRET-SECRET-KEYWORD trigger from DEVELOPMENT.md line 501"

This reverts commit 802d496.

* fix: add ferret-scan suppressions to both .ash.yaml and community plugins config

All ferret-related suppressions (DEVELOPMENT.md SECRET-SECRET-KEYWORD,
ferret_scanner.py B404/B603/B607, generate_test_docx.py B311/HEX,
conftest.py SECRET-SECRET-KEYWORD) now appear in both config files
with line numbers for precision.

* docs: update suppression guidance to reflect both config files

Suppressions must be in both .ash.yaml and .ash_community_plugins.yaml.

* fix: eliminate SECRET-SECRET-KEYWORD trigger from DEVELOPMENT.md:501

GitHub code scanning does not honor SARIF suppressions field — alerts
appear regardless. Split API_KEY from assignment operator into separate
inline code spans to break the detection pattern while keeping the
documentation readable. Suppressions remain in both configs as defense
in depth for ASH's own suppression system.

* Bump version to 3.2.0

---------

Co-authored-by: Nikhil Prabhakar <>
Co-authored-by: Rafael Pereyra <31078199+rafaelpereyra@users.noreply.github.com>

Author: prabnikaws

.ash/.ash.yaml

@@ -33,6 +33,41 @@ global_settings:
     - path: tests/unit/plugin_modules/ash_aws_plugins/test_cloudwatch_logs_reporter*
       rule_id: SECRET-SECRET-KEYWORD
       reason: False positive, dummy test data and not an actual secret.
+    - path: automated_security_helper/plugin_modules/ash_ferret_plugins/DEVELOPMENT.md
+      rule_id: SECRET-SECRET-KEYWORD
+      line_start: 501
+      line_end: 501
+      reason: Documentation example showing the SECRET-SECRET-KEYWORD detection pattern.
+    - path: automated_security_helper/plugin_modules/ash_ferret_plugins/ferret_scanner.py
+      rule_id: B404
+      line_start: 9
+      line_end: 9
+      reason: Subprocess module required — ferret-scan is an external CLI tool invoked via subprocess with list args (no shell=True).
+    - path: automated_security_helper/plugin_modules/ash_ferret_plugins/ferret_scanner.py
+      rule_id: B603
+      line_start: 410
+      line_end: 435
+      reason: Subprocess calls use list args (no shell=True) with validated inputs. ferret-scan binary path comes from shutil.which().
+    - path: automated_security_helper/plugin_modules/ash_ferret_plugins/ferret_scanner.py
+      rule_id: B607
+      line_start: 410
+      line_end: 435
+      reason: Partial executable path resolved via shutil.which() in validate_plugin_dependencies(). Standard ASH scanner pattern.
+    - path: scripts/generate_test_docx.py
+      rule_id: B311
+      line_start: 1
+      line_end: 203
+      reason: Standard random is intentional — generates synthetic test data with random.seed(42) for reproducibility, not used for security/crypto.
+    - path: tests/unit/plugin_modules/ash_ferret_plugins/conftest.py
+      rule_id: SECRET-SECRET-KEYWORD
+      line_start: 146
+      line_end: 146
+      reason: False positive — SETTING = "placeholder" uses a neutral variable name.
+    - path: scripts/generate_test_docx.py
+      rule_id: SECRET-HEX-HIGH-ENTROPY-STRING
+      line_start: 175
+      line_end: 177
+      reason: False positive — runtime-generated synthetic credit card numbers from seeded random for test data.
     - path: .github/workflows/run-ash-security-scan.yml
       rule_id: yaml.github-actions.security.run-shell-injection.run-shell-injection
       reason: Troubleshooting swapping from direct injection to evaluating interpolated env vars

.ash/.ash_community_plugins.yaml

@@ -5,10 +5,46 @@ fail_on_findings: true
 ash_plugin_modules:
   - automated_security_helper.plugin_modules.ash_snyk_plugins
   - automated_security_helper.plugin_modules.ash_trivy_plugins
+  - automated_security_helper.plugin_modules.ash_ferret_plugins
 external_reports_to_include: []
 global_settings:
   severity_threshold: MEDIUM
   suppressions:
+    - path: automated_security_helper/plugin_modules/ash_ferret_plugins/DEVELOPMENT.md
+      rule_id: SECRET-SECRET-KEYWORD
+      line_start: 501
+      line_end: 501
+      reason: Documentation example showing the SECRET-SECRET-KEYWORD detection pattern.
+    - path: automated_security_helper/plugin_modules/ash_ferret_plugins/ferret_scanner.py
+      rule_id: B404
+      line_start: 9
+      line_end: 9
+      reason: Subprocess module required — ferret-scan is an external CLI tool invoked via subprocess with list args (no shell=True).
+    - path: automated_security_helper/plugin_modules/ash_ferret_plugins/ferret_scanner.py
+      rule_id: B603
+      line_start: 410
+      line_end: 435
+      reason: Subprocess calls use list args (no shell=True) with validated inputs. ferret-scan binary path comes from shutil.which().
+    - path: automated_security_helper/plugin_modules/ash_ferret_plugins/ferret_scanner.py
+      rule_id: B607
+      line_start: 410
+      line_end: 435
+      reason: Partial executable path resolved via shutil.which() in validate_plugin_dependencies(). Standard ASH scanner pattern.
+    - path: scripts/generate_test_docx.py
+      rule_id: B311
+      line_start: 1
+      line_end: 203
+      reason: Standard random is intentional — generates synthetic test data with random.seed(42) for reproducibility, not used for security/crypto.
+    - path: tests/unit/plugin_modules/ash_ferret_plugins/conftest.py
+      rule_id: SECRET-SECRET-KEYWORD
+      line_start: 146
+      line_end: 146
+      reason: False positive — SETTING = "placeholder" uses a neutral variable name.
+    - path: scripts/generate_test_docx.py
+      rule_id: SECRET-HEX-HIGH-ENTROPY-STRING
+      line_start: 175
+      line_end: 177
+      reason: False positive — runtime-generated synthetic credit card numbers from seeded random for test data.
     - path: tests/integration/cli/test_mcp_file_tracking_integration.py
       rule_id: SECRET-SECRET-KEYWORD
       reason: False positive.
@@ -172,6 +208,20 @@ scanners:
     severity_threshold: "MEDIUM"
   syft:
     enabled: false
+  ferret-scan:
+    enabled: true
+    options:
+      confidence_levels: "high"
+      checks: "CREDIT_CARD,SECRETS,SSN,PASSPORT"
+      recursive: true
+      use_default_config: false
+      exclude_patterns:
+        - ".venv"
+        - "tests/test_data"
+        - ".ash/ash_output"
+        - ".git"
+        - "__pycache__"
+        - "*.pyc"
   trivy-repo:
     enabled: true
     options:

.github/workflows/ash-repo-scan-validation.yml

@@ -202,6 +202,14 @@ jobs:
             exit 1
           fi
 
+          # Install ferret-scan (cross-platform via pip)
+          echo "Installing ferret-scan..."
+          pip install ferret-scan
+
+          # Verify ferret-scan installation
+          ferret-scan --version
+          echo "ferret-scan installation completed!"
+
           echo "Community plugin tools installation completed successfully!"
 
       # Call the appropriate workflow based on matrix.method

README.md

@@ -91,15 +91,15 @@ ASH v3 integrates multiple open-source security tools as scanners. Tools like Ba
 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.1.13"
+alias ash="uvx git+https://github.com/awslabs/automated-security-helper.git@v3.2.0"
 ```
 
 ```powershell
 # 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.1.13 $args }
+function ash { uvx git+https://github.com/awslabs/automated-security-helper.git@v3.2.0 $args }
 ```
 
 ### Other Installation Methods
@@ -120,13 +120,13 @@ ash --help
 #### Using `pip`
 
 ```bash
-pip install git+https://github.com/awslabs/automated-security-helper.git@v3.1.13
+pip install git+https://github.com/awslabs/automated-security-helper.git@v3.2.0
 ```
 
 #### Clone the Repository
 
 ```bash
-git clone https://github.com/awslabs/automated-security-helper.git --branch v3.1.13
+git clone https://github.com/awslabs/automated-security-helper.git --branch v3.2.0
 cd automated-security-helper
 pip install .
 ```