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 Sep 9, 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 Sep 9, 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.4.4.tar.gz (37.5 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.4.4-py3-none-any.whl (37.6 MB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: ferret_scan-2.4.4.tar.gz
  • Upload date:
  • Size: 37.5 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.4.4.tar.gz
Algorithm Hash digest
SHA256 7eb93cd5c7915754cdc0dcd27c27f8bd9a49ce562f7dd53e48813f22a2d8ff39
MD5 011543b4f66975091ca65f8d191ffd5e
BLAKE2b-256 046d30ec7656c9ad9709bae31e132841973e9122d2397d7196220f7946fadfc6

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferret_scan-2.4.4.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.4.4-py3-none-any.whl.

File metadata

  • Download URL: ferret_scan-2.4.4-py3-none-any.whl
  • Upload date:
  • Size: 37.6 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.4.4-py3-none-any.whl
Algorithm Hash digest
SHA256 e0fc9a6076201543bf6fe25d6fd145396e4c93d12ea2dc3d60c2a6ce11ae5e91
MD5 450d5c3e27181970a169641beb5b4a54
BLAKE2b-256 6b00c646d49302db88611442493af134ac915e5735ded111afeb7d75d91fd1b3

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferret_scan-2.4.4-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

This release

2.4.4 This release

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

2.3.1

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