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 5, 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 5, 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.0.tar.gz (33.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.0-py3-none-any.whl (33.7 MB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: ferret_scan-2.3.0.tar.gz
  • Upload date:
  • Size: 33.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.0.tar.gz
Algorithm Hash digest
SHA256 e7b730db9a8e75b20b2736d954535d3f99e1c4d3d3bfecd9f1ab1c5c8b41c030
MD5 56f317831d223819efd0df04abe27cc3
BLAKE2b-256 90b029ab4699b0f50b4492cbbc3d912d0937c564a84fc9633d23596a15d3fec3

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: ferret_scan-2.3.0-py3-none-any.whl
  • Upload date:
  • Size: 33.7 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.0-py3-none-any.whl
Algorithm Hash digest
SHA256 5a35d0b18bdc2ac8669b38a9e47dd337c630085bc7c521feaf6057cad55ced18
MD5 1eb07cc6e06f45e020af905e6774cd15
BLAKE2b-256 b87e628c434c6f6fba02d3d5e8238b969c24506093fbc952f1bd4759346ae685

See more details on using hashes here.

Provenance

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

2.3.1

2 files

This release

2.3.0 This release

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