Ferret Scan Python Package

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:

Automatic Binary Download: Downloads the appropriate ferret-scan binary for your platform (Linux/macOS/Windows, x86_64/ARM64)
Transparent Execution: Passes all arguments directly to the native binary
Cross-Platform: Works on all platforms supported by ferret-scan
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.

Release files for ferret-scan 2.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ferret-scan 2.5.0
File	Size	Uploaded
ferret_scan-2.5.0.tar.gz	37.8 MB	Sep 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ferret-scan 2.5.0
File	Interpreter	ABI	Platform	Reset
ferret_scan-2.5.0-py3-none-any.whl 37.9 MB Sep 18, 2026	Python 3	none	any	Details

Total release size: 75.7 MB

Release files / ferret_scan-2.5.0.tar.gz

Download URL	ferret_scan-2.5.0.tar.gz
Size	37.8 MB
Tags	Source
SHA-256 checksum How to use checksums	`47c93a79df975c9bda755b5d3edef319a59332a0a881dcbac57d5bc718854bdf`
BLAKE2b-256 checksum How to use checksums	`c7b2819f62275ecc85a524c329324be455b38bd7c0c1daa67e07bd7c060cd64b`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/awslabs/ferret-scan
Publishing commit: github.com/awslabs/ferret-scan/tree/78e8e175b77bbabf72f55c05bdf5ac06a7bada0c

Workflow

Publishing configuration: github.com/awslabs/ferret-scan/blob/78e8e175b77bbabf72f55c05bdf5ac06a7bada0c/.github/workflows/python-package.yml
Publishing logs: github.com/awslabs/ferret-scan/actions/runs/35347370233/attempts/1

Artifact

Subject: ferret_scan-2.5.0.tar.gz
SHA-256 checksum: 47c93a79df975c9bda755b5d3edef319a59332a0a881dcbac57d5bc718854bdf Verifying attestations

Release files / ferret_scan-2.5.0-py3-none-any.whl

Download URL	ferret_scan-2.5.0-py3-none-any.whl
Size	37.9 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`7056cb10e8ad76c6a348fb3054a6790f1c1451c9ab9e5995450e611efef00122`
BLAKE2b-256 checksum How to use checksums	`9db69d02aad3f450752e4e91a1cd04a57030ae6a60050367ebcf3c666c6a4ce6`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/awslabs/ferret-scan
Publishing commit: github.com/awslabs/ferret-scan/tree/78e8e175b77bbabf72f55c05bdf5ac06a7bada0c

Workflow

Publishing configuration: github.com/awslabs/ferret-scan/blob/78e8e175b77bbabf72f55c05bdf5ac06a7bada0c/.github/workflows/python-package.yml
Publishing logs: github.com/awslabs/ferret-scan/actions/runs/35347370233/attempts/1

Artifact

Subject: ferret_scan-2.5.0-py3-none-any.whl
SHA-256 checksum: 7056cb10e8ad76c6a348fb3054a6790f1c1451c9ab9e5995450e611efef00122 Verifying attestations