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 26, 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 26, 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.0.tar.gz (35.6 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.0-py3-none-any.whl (35.7 MB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: ferret_scan-2.4.0.tar.gz
  • Upload date:
  • Size: 35.6 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.0.tar.gz
Algorithm Hash digest
SHA256 3fcf040fa28acb16c15c0f2207e3c357c8b8c163d78b8362d55fdde638fa5596
MD5 7283342b98745b457fa622bbb876b016
BLAKE2b-256 20ba8fdeaa9ecc655954a1e5297cae65e5d2b1bb550c75e7f9edf1d90949f4ac

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: ferret_scan-2.4.0-py3-none-any.whl
  • Upload date:
  • Size: 35.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.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 7dfb3f606386427286dce9a976715f913adc24d8276918fb5e30f3a458fb0deb
MD5 0de85d6bbed81fa1fefc1fbd47b54bc8
BLAKE2b-256 5d8e62d851368f739b0cea0c47898a7f15f0b6e90e50843b4ac1d33710c5610c

See more details on using hashes here.

Provenance

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

This release

2.4.0 This release

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