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.1

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.1
File	Size	Uploaded
ferret_scan-2.5.1.tar.gz	37.8 MB	Sep 22, 2026	Details

Built distribution (wheel)

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

Total release size: 75.7 MB

Release files / ferret_scan-2.5.1.tar.gz

Download URL	ferret_scan-2.5.1.tar.gz
Size	37.8 MB
Tags	Source
SHA-256 checksum How to use checksums	`63435d6cf5341aad82a4ab9970f2e908be22084e63ab333b65ccbfd871645942`
BLAKE2b-256 checksum How to use checksums	`b46db9f93e3eb159fe1eb83e22b9bd3697f694644ddee262f85375aa12d0f4f6`
Upload date	Sep 22, 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/2983781c1f086c045ffdf3b8605653135e59fdad

Workflow

Publishing configuration: github.com/awslabs/ferret-scan/blob/2983781c1f086c045ffdf3b8605653135e59fdad/.github/workflows/python-package.yml
Publishing logs: github.com/awslabs/ferret-scan/actions/runs/35786627838/attempts/1

Artifact

Subject: ferret_scan-2.5.1.tar.gz
SHA-256 checksum: 63435d6cf5341aad82a4ab9970f2e908be22084e63ab333b65ccbfd871645942 Verifying attestations

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

Download URL	ferret_scan-2.5.1-py3-none-any.whl
Size	37.9 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`324c83efe471a5182257715662272e615f8c707dd219c8eafbbad1ebe017654e`
BLAKE2b-256 checksum How to use checksums	`4aadc4bd5ed96948921c255c14db899fa34205b621011e8995eb3634cdffce00`
Upload date	Sep 22, 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/2983781c1f086c045ffdf3b8605653135e59fdad

Workflow

Publishing configuration: github.com/awslabs/ferret-scan/blob/2983781c1f086c045ffdf3b8605653135e59fdad/.github/workflows/python-package.yml
Publishing logs: github.com/awslabs/ferret-scan/actions/runs/35786627838/attempts/1

Artifact

Subject: ferret_scan-2.5.1-py3-none-any.whl
SHA-256 checksum: 324c83efe471a5182257715662272e615f8c707dd219c8eafbbad1ebe017654e Verifying attestations