Ferret Scan Python Package

Ferret Scan Logo

A Python wrapper for Ferret Scan, a sensitive data detection tool. This package provides easy installation and seamless pre-commit hook integration.

Installation

pip install ferret-scan

Usage

Command Line

After installation, use ferret-scan exactly like the native binary:

# Basic scan
ferret-scan --file document.txt

# JSON output
ferret-scan --file document.txt --format json

# Quiet mode for scripts
ferret-scan --file document.txt --quiet

# Pre-commit mode with optimizations
ferret-scan --pre-commit-mode --confidence high,medium --checks all

Pre-commit Hook

Ferret Scan provides multiple pre-commit hook configurations for different security requirements. Add to your .pre-commit-config.yaml:

Default Configuration (Recommended)

repos:
  - repo: https://github.com/awslabs/ferret-scan
    rev: v1.0.0
    hooks:
      - id: ferret-scan

Strict Security (Blocks on high confidence findings)

repos:
  - repo: https://github.com/awslabs/ferret-scan
    rev: v1.0.0
    hooks:
      - id: ferret-scan-strict

Advisory Mode (Shows findings but never blocks)

repos:
  - repo: https://github.com/awslabs/ferret-scan
    rev: v1.0.0
    hooks:
      - id: ferret-scan-advisory

Secrets Only (Focus on API keys and tokens)

repos:
  - repo: https://github.com/awslabs/ferret-scan
    rev: v1.0.0
    hooks:
      - id: ferret-scan-secrets

Financial Data (Credit cards and financial info)

repos:
  - repo: https://github.com/awslabs/ferret-scan
    rev: v1.0.0
    hooks:
      - id: ferret-scan-financial

PII Detection (SSN, passport, email)

repos:
  - repo: https://github.com/awslabs/ferret-scan
    rev: v1.0.0
    hooks:
      - id: ferret-scan-pii

Metadata Check (Document metadata scanning)

repos:
  - repo: https://github.com/awslabs/ferret-scan
    rev: v1.0.0
    hooks:
      - id: ferret-scan-metadata

CI/CD Optimized (Structured output for pipelines)

repos:
  - repo: https://github.com/awslabs/ferret-scan
    rev: v1.0.0
    hooks:
      - id: ferret-scan-ci

Custom Configuration

You can also customize any hook with additional arguments:

repos:
  - repo: https://github.com/awslabs/ferret-scan
    rev: v1.0.0
    hooks:
      - id: ferret-scan
        args: ['--confidence', 'high', '--checks', 'CREDIT_CARD,SECRETS', '--verbose']

Local Installation

For local installations, use the ferret-scan command directly:

repos:
  - repo: local
    hooks:
      - id: ferret-scan
        name: Ferret Scan - Sensitive Data Detection
        entry: ferret-scan
        language: system
        files: '\.(txt|py|js|ts|go|java|json|yaml|yml|md|csv|log|conf|config|ini|env)$'
        args: ['--pre-commit-mode', '--confidence', 'high,medium']

How It Works

This Python package:

  1. Automatic Binary Download: Downloads the appropriate ferret-scan binary for your platform (Linux/macOS/Windows, x86_64/ARM64)
  2. Transparent Execution: Passes all arguments directly to the native binary
  3. Cross-Platform: Works on all platforms supported by ferret-scan
  4. Pre-commit Ready: Integrates seamlessly with pre-commit hooks with automatic optimizations

Supported Platforms

  • Linux: x86_64, ARM64
  • macOS: x86_64 (Intel), ARM64 (Apple Silicon)
  • Windows: x86_64, ARM64

Features

All features of the native ferret-scan binary are available:

  • Sensitive Data Detection: Credit cards, passports, SSNs, API keys, etc.
  • Multiple Formats: Text, JSON, CSV, YAML, JUnit, GitLab SAST output
  • Document Processing: PDF, Office documents, images
  • Pre-commit Optimizations: Automatic quiet mode, no colors, appropriate exit codes
  • Suppression Rules: Manage false positives
  • Configuration: YAML config files and profiles
  • Redaction: Remove sensitive data from documents

Command Line Options

The Python package supports all command-line options of the native binary:

  • --file: Input file, directory, or glob pattern. Use - to read from standard input.
  • --stdin: Read content from standard input (treated as plain text)
  • --stdin-name: Synthetic label for findings when scanning stdin (default: <stdin>)
  • --format: Output format (text, json, csv, yaml, junit, gitlab-sast)
  • --confidence: Confidence levels (high, medium, low, combinations)
  • --checks: Specific checks to run (CREDIT_CARD, SECRETS, SSN, etc.)
  • --pre-commit-mode: Enable pre-commit optimizations
  • --verbose: Detailed information for findings
  • --quiet: Suppress progress output
  • --no-color: Disable colored output
  • --recursive: Recursively scan directories
  • --enable-preprocessors: Enable document text extraction
  • --config: Configuration file path
  • --profile: Configuration profile name

Requirements

  • Python 3.7+
  • Internet connection (for initial binary download)

License

Apache License 2.0 - see the LICENSE file for details.

Contributing

See the main Ferret Scan repository for contribution guidelines.

Project links

Data verified by PyPI on Aug 14, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.4.5)

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for rustic_aws from gravatar.com rustic_aws Avatar for sectoramen from gravatar.com sectoramen

Credits

Author: AWS

GitHub Statistics

Data verified by PyPI on Aug 14, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.7

Provides Extra

test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ferret_scan-2.3.1.tar.gz (34.7 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

ferret_scan-2.3.1-py3-none-any.whl (34.8 MB view details)

Uploaded Python 3

File details

Details for the file ferret_scan-2.3.1.tar.gz.

File metadata

  • Download URL: ferret_scan-2.3.1.tar.gz
  • Upload date:
  • Size: 34.7 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ferret_scan-2.3.1.tar.gz
Algorithm Hash digest
SHA256 a957eb575e3e3705c548dce7273d4096091c8550f615ecbf48ea32ba25b493f9
MD5 5f69295ac73ae09a628603bf325a0ff9
BLAKE2b-256 8dafccd1d4c3487d6bce3feec627f9851e4d737a44e53114be225e33bf7d3737

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferret_scan-2.3.1.tar.gz:

Publisher: python-package.yml on awslabs/ferret-scan

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ferret_scan-2.3.1-py3-none-any.whl.

File metadata

  • Download URL: ferret_scan-2.3.1-py3-none-any.whl
  • Upload date:
  • Size: 34.8 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ferret_scan-2.3.1-py3-none-any.whl
Algorithm Hash digest
SHA256 d48fe77d0c94090d864e8857c2afaf1f53a93dfa4cd0cd57185ade80e813c6e5
MD5 f162c5d013bd43ffdcb3e2958efdac66
BLAKE2b-256 2a6d17952fb89595dc3035c3e50bd89c856253e74b15cd0ab6ac2d5169c4b0ed

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferret_scan-2.3.1-py3-none-any.whl:

Publisher: python-package.yml on awslabs/ferret-scan

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

2.4.5

2 files

2.4.4

2 files

2.4.3

2 files

2.4.2

2 files

2.4.1

2 files

2.4.0

2 files

2.3.4

2 files

2.3.3

2 files

2.3.2

2 files

This release

2.3.1 This release

2 files

2.3.0

2 files

2.2.1

2 files

2.2.0

2 files

2.1.3

2 files

2.1.2

2 files

2.1.1

2 files

2.1.0

2 files

2.0.2

2 files

2.0.1

2 files

2.0.0

2 files

1.10.0

2 files

1.9.0

2 files

1.8.4

2 files

1.8.3

2 files

1.8.2

2 files

1.8.1

2 files

1.8.0

2 files

1.7.1

2 files

1.7.0

2 files

1.6.1

2 files

1.6.0

2 files

1.5.3

2 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.0

2 files

1.3.35

2 files

1.3.34

2 files

1.3.33

2 files

1.3.32

2 files

1.3.31

2 files

1.3.30

2 files

1.3.29

2 files

1.3.28

2 files

1.3.27

2 files

1.3.26

2 files

1.3.25

2 files

1.3.24

2 files

1.3.23

2 files

1.3.22

2 files

1.3.21

2 files

1.3.20

2 files

1.3.19

2 files

1.3.18

2 files

1.2.11

2 files

1.2.7

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page