filegrail analyzes files and directories using two kinds of information:

1. Traces already stored on the machine - browser downloads, OS origin metadata, shell history, archives, torrents, recent files, sync folders and trash records.
2. Data stored inside the files - EXIF, XMP, IPTC, C2PA, document properties, media metadata, email headers and other embedded metadata.

It keeps three questions separate:

Scanning is local, read-only and makes no network requests. filegrail clean is the only command that writes files, and it writes cleaned copies to a separate directory.

What it does

Evidence sources

Acquisition and interaction traces

Use:

filegrail doctor

to see which of these sources are actually available on the current machine or profile.

For another user profile or a mounted copy:

filegrail doctor --home /mnt/profile
filegrail /mnt/evidence --home /mnt/profile

Supported formats

Embedded metadata

Cross-format metadata

These blocks are detected wherever they are embedded, not only by extension.

Email

Archives

Files inside supported archives are analyzed without unpacking the archive to disk.

Torrents and sidecars

For the complete format reference and edge cases, see docs/FORMATS.md.

Content extraction

--content reads supported document text in addition to metadata and runs identifier extraction over it.

filegrail ./case --content

--content implies --identify.

PDF metadata is supported, but PDF body text is not extracted by --content.

Analysis

Correlation and conflicts

filegrail compares independent evidence instead of collapsing everything into one origin field.

It can report:

• multiple sources supporting the same origin
• conflicting origin URLs
• file-size mismatches
• filename-only matches
• creation/modification dates in impossible order
• XMP editing steps out of sequence
• EXIF vs XMP differences
• PDF Info vs XMP differences
• XMP derivation relationships between files
• C2PA hard-binding mismatches

Confidence values rank competing claims. They are not probability scores or forensic verdicts.

Investigation pivots

filegrail ./case --identify

Extracts:

• URLs
• domains
• email addresses
• IPv4 addresses
• coordinates
• MD5, SHA-1 and SHA-256 values found in metadata/content

Each value keeps the file, source and field/location it came from.

Shared sources

filegrail ./photos --cluster

Groups files by:

• camera body/serial
• camera model
• author

Timeline

filegrail ./case --timeline

Places recorded acquisition, creation, editing and interaction events in chronological order.

File relationships

XMP identifiers such as:

• xmpMM:DocumentID
• xmpMM:InstanceID
• xmpMM:OriginalDocumentID
• xmpMM:DerivedFrom

can link renamed or exported files and show relationships such as derived-from, source-of, same-document or common-ancestor.

Installation

Requires Python 3.10+.

pipx install filegrail

or:

uv tool install filegrail

From the repository:

git clone https://github.com/osint-shifu/filegrail.git
cd filegrail
PYTHONPATH=src python -m filegrail.cli /path/to/files

Runtime dependencies: 0.

Usage

filegrail <path> [options]
filegrail <command> [options]

Analyze one file:

filegrail suspicious.pdf

Analyze a directory recursively:

filegrail ./evidence

Analyze the current directory:

filegrail .

Running filegrail with no arguments displays the command overview and does not start a scan.

Commands

Scan options

Clean options

Examples

# Full analysis of one file
filegrail photo.jpg

# Scan a case and show only the index
filegrail ./case --brief

# Extract investigation pivots
filegrail ./case --identify

# Also search supported document content
filegrail ./case --content

# Build a timeline
filegrail ./case --timeline

# Find files sharing cameras or authors
filegrail ./case --cluster

# Explain exactly why a finding was produced
filegrail explain document.pdf

# Compare two files
filegrail compare original.docx edited.docx

# Analyze another user profile
filegrail /mnt/evidence --home /mnt/profile

# JSON report
filegrail ./case --json > report.json

# JSON report with credentials redacted
filegrail ./case --redact --json > report.json

Metadata removal

filegrail clean removes supported metadata from copies. Originals are never modified.

Cleanable formats

Clean one file:

filegrail clean photo.jpg --out ./clean

Check without writing:

filegrail clean ./publish --check

After cleaning, the output is read again by the same metadata readers. Anything still detected is reported.

Metadata removal is not anonymization. Image pixels, sensor patterns, codec fingerprints and document content can still identify a source.

JSON and automation

--json is available on all main commands.

Schemas include:

• filegrail.scan/1
• filegrail.explain/1
• filegrail.compare/1
• filegrail.doctor/1
• filegrail.clean/1

JSON output preserves:

• files and paths
• acquisition/intrinsic/interaction claims
• decoded metadata
• evidence sources
• confidence values
• findings and conflicts
• extracted identifiers
• shared-source clusters
• file relationships

Privacy

filegrail makes no network requests.

Reports can contain sensitive local data such as:

• private URLs
• credentials or tokens embedded in URLs/commands
• file-system paths
• email addresses
• IP addresses
• GPS coordinates

Use:

filegrail ./case --redact

or:

filegrail ./case --redact --json

before sharing output.

Always review redacted reports manually before publishing them.

Limits

• filegrail can only use evidence that still exists.
• Cleared browser history, removed extended attributes or missing shell history cannot be reconstructed.
• A supported sync folder can show account/folder context, but not who uploaded a file.
• WhatsApp/Telegram filename patterns do not identify a sender or conversation.
• C2PA hard binding is checked, but the certificate chain/signature trust is not verified.
• PDF metadata is read; PDF body text is not extracted by --content.
• Unsupported file formats can still participate in provenance analysis when external/local evidence about them exists.
• filegrail is not a monitoring agent, chain-of-custody system or full disk-forensics suite.

Documentation

• Complete format reference
• Security
• Changelog

License

Apache-2.0.