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 Jul 23, 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 Jul 23, 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.1.2.tar.gz (33.1 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.1.2-py3-none-any.whl (33.1 MB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for ferret_scan-2.1.2.tar.gz
Algorithm Hash digest
SHA256 c2a877fc7820fbd774c1771d88af35982f715220ece1a5125c40eb1cd3fd3f2d
MD5 7af7fe7d75638243dc92a4357f367dd6
BLAKE2b-256 bdd7f5869e436e5bd56b5025c1c18f42abd0d13558a97db4cc45262c5c3687ac

See more details on using hashes here.

Provenance

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

File metadata

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

File hashes

Hashes for ferret_scan-2.1.2-py3-none-any.whl
Algorithm Hash digest
SHA256 0a013a15fed974472b0e5f54d156c1fc6e8f9b19e715400435e4acf84d6278f2
MD5 ed9368de12ba4865e8fc3487c60450ff
BLAKE2b-256 930e045740cc173bed0a3b63db222c437b2a4d5416185d2e2eed8581995b8ce9

See more details on using hashes here.

Provenance

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

2.3.0

2 files

2.2.1

2 files

2.2.0

2 files

2.1.3

2 files

This release

2.1.2 This release

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