filegrail helps determine where a file came from, what it records about itself, what it contains, and what happened to it locally.

It draws from three areas:

1. Origin - what the machine recorded - browser history, OS origin metadata, shell history, archives, torrents, recent-file records, sync folders and trash. These traces can reveal where a file came from, how it arrived, when it appeared and where it was stored.
2. Metadata - what the file records about itself - EXIF, XMP, IPTC, C2PA, document properties, media tags, email headers and other embedded data. This can reveal devices, software, authors, timestamps, GPS coordinates and document history.
3. Content - what the file says inside - with --content, readable text from supported documents is scanned for URLs, domains, email addresses, IP addresses, coordinates and MD5/SHA-1/SHA-256 values. The text itself is not printed or stored - only extracted identifiers and their locations.

Where evidence was found and what that evidence means are kept separate:

Every record also states how it was matched to the file - by exact path, file attribute, name and size, container membership, filename or the file's own bytes.

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

Give filegrail a file or directory and it checks the provenance traces and embedded metadata that apply. Every result keeps its source visible.

When independent sources disagree, both values are preserved and the conflict is reported rather than resolved automatically.

Evidence sources

Origin and activity traces

These sources exist outside the analyzed file. They are records left by browsers, operating systems, shells and applications as files are downloaded, opened, extracted, synchronized or deleted.

They can reveal URLs, referrers, timestamps, previous paths and container membership. Availability depends on what evidence still exists on the system.

Check what is available on the current machine or profile:

filegrail doctor

For another user profile or mounted copy:

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

Supported formats

Embedded metadata

Metadata stored inside the file can reveal devices, GPS coordinates, timestamps, authors, editors, software, document properties, media tags and authenticity data.

Original field names are preserved in the report.

Cross-format metadata

XMP, XMP history and IPTC can occur across multiple formats and are extracted wherever supported.

Email

Saved email messages can expose their delivery path through Received: headers. With --content, readable text/plain and text/html message bodies are also inspected.

Archives

filegrail can inspect supported files inside archives without unpacking the archive into the scanned directory.

Archive membership can also link an extracted file back to an entry by name and uncompressed size and, when available, inherit provenance from the archive itself.

Torrents and sidecars

Torrent membership is matched when both file name and exact size agree with an entry.

A matching <name>.info.json can recover provenance for media downloaded with yt-dlp.

Document content

--content also scans the text stored inside supported documents.

The text itself is not added to the report. Only supported identifiers and their locations are retained.

Content scanning is limited to 1 MB of text per file and 64 members of a packaged document.

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

Identifier types

The same identifier detection is applied to metadata and, with --content, document text. Filters remove common false positives.

Every value keeps its file, source and exact field or document location.

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

Analysis

Correlation and conflicts

When multiple sources describe the same file, filegrail compares them rather than choosing one automatically.

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

How a record was matched to a file

Every evidence record includes the basis of its association with the file. An exact recorded path and a filename-only match are therefore never presented as equivalent.

These values appear in the report's match column and under match.method in JSON.

filegrail does not assign evidence confidence scores. Instead it reports the category, source and match basis directly.

Extracting investigation pivots from metadata and content

filegrail ./case --identify      # out of metadata
filegrail ./case --content       # out of metadata and document text

--identify extracts supported identifier types from metadata and provenance records.

--content extends the same extraction to supported document bodies and automatically enables identifier detection.

Results are grouped by type and retain the file, source and exact field or location. Values found across independent sources are highlighted separately.

Clusters

filegrail ./photos --cluster

Groups files by shared identifying values and reports the field behind each grouping:

• camera serial - EXIF · BodySerialNumber: identifies the same physical camera.
• camera model - EXIF · Make + Model: identifies the same model, not the same device.
• author - OOXML · creator or equivalent: a recorded author value.

Timeline

filegrail ./case --timeline

Combines available origin, metadata and activity timestamps into one chronological view.

File relationships

XMP identifiers such as:

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

can link files even after renaming or export. Relationships can include derived-from, source-of, same-document and 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 without starting a scan.

Commands

filegrail PATH is the normal scan form. filegrail scan PATH is its explicit equivalent.

Scan options

A normal scan checks embedded metadata and available local provenance traces. Content inspection, hashing and clustering run only when requested.

--home uses another user profile, copied profile or mounted image as the source of local evidence.

Clean options

Use --out DIR to write cleaned copies. Use --check to inspect what would be removed without writing anything.

The output directory cannot be inside the directory being cleaned.

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 read the text inside supported documents
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, each copy is scanned again. Any supported metadata that remains is reported.

Metadata removal is not anonymization. Pixels, sensor patterns, codec fingerprints and document content may still identify a source.

JSON and automation

Use --json with scripts, jq, notebooks, pipelines or other tools. All main commands support machine-readable output with command-specific schemas and exit codes.

Schemas are versioned independently, so unrelated command changes do not force consumers to update.

Exit codes:

A scan document contains root, home, summary, files, and when requested, identifiers, shared_attributes and unsearched.

Each file includes path, size, mtime, btime, sha256, links and evidence. Evidence records contain their category, source, match and decoded fields. Correlation results are stored under correlation.

Privacy

filegrail runs locally and makes no network requests. The main privacy risk is the report itself.

Reports may contain:

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

Redact sensitive values before sharing output:

filegrail ./case --redact

or:

filegrail ./case --redact --json

Always review a redacted report before publishing it.

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.