doormat

Find the passwords people leave next to the label that says "Password".

People hide the spare key under the doormat. They hide passwords the same way: in the spreadsheet cell right next to Password:, in a cell that reads pwd = hunter2, or inside a database connection string. doormat reads .xlsx, .xls, .ods, .csv and .tsv files, models each sheet as a 2D grid, and pairs credential labels with the values around them.

• Spatial, not just regex. Scores every candidate value by its distance and direction from a credential label, its character mix and entropy, and nearby username or URL labels.
• Finds what grep misses. Credentials split across cells, built with CONCAT in formulas, or tucked into cell comments.
• Fast. Rust core with sheet-level parallelism: under 1 ms for a 5,000-cell sheet. Python bindings via PyO3, one FFI call per workbook.
• Measured on real data. Precision and recall are reported on the public Enron spreadsheet corpus, not just synthetic fixtures. See Accuracy.
• Offline and dependency-light. Two small runtime dependencies (openpyxl, and defusedxml to refuse malicious XML inside spreadsheet files). No network calls, no model downloads.

Documentation: https://dipan010.github.io/doormat/ (API reference, how detection works, threat model, evaluation).

Installation

pip install doormat

Optional readers for legacy formats:

pip install "doormat[xls]"   # Excel 97-2003 via xlrd
pip install "doormat[ods]"   # OpenDocument via odfpy
pip install "doormat[all]"   # both

Prebuilt wheels cover CPython 3.10 and newer on Linux (x86_64, aarch64), macOS (Intel, Apple Silicon) and Windows (x64). On other platforms pip builds from the source distribution, which needs a Rust toolchain. To work on doormat itself, see CONTRIBUTING.md.

Quickstart

import doormat

doc = doormat.load("it_handover.xlsx")
print(f"Scanned {doc.sheet_count} sheets, {doc.cell_count} cells")

for cred in doc.credentials(min_confidence=120):
    print(f"{cred.sheet}!{cred.coordinate}  {cred.key!r} -> {cred.value!r}  score={cred.confidence:.0f}")

Scanned 2 sheets, 7 cells
Servers!B3  'Password' -> 's3cRet!99'  score=210
Notes!A1  'VPN password' -> 'hunter2!'  score=250

Findings come back in reading order: sheet by sheet, then row and column. A finding's repr never includes the secret, so logging one is safe:

>>> doc.credentials(120)[0]
Relationship(key='Password', sheet='Servers', cell='B3', confidence=210)

API

What it detects

Supported formats

The reader is chosen by file extension, and binary formats are checked against their magic bytes before parsing. CSV and TSV files are treated as one sheet named after the file.

Accuracy

On 14 synthetic fixtures, one per detection pathway, doormat scores 100% precision and recall. Real spreadsheets are harder. On the public Enron spreadsheet corpus (15,929 files):

Precision for main is measured on files that played no part in tuning; recall is measured on files that did, so treat it as optimistic. Inline credentials are found with few false positives. Values beside a label are usually found, but a large share of those findings are still wrong pairings (usually a nearby label when the password cell is empty). The method, labelling rubric and caveats are in bench/corpus/README.md.

Performance

Rust core only, Apple Silicon, criterion.rs on synthetic workbooks:

On very large real workbooks, reading the file with openpyxl dominates: about 27 s to read a 170,000-cell workbook against 0.1 s of detection.

How it works

1. Extract. Python reads every cell, formula and comment in a single pass and sends the workbook to Rust in one call.
2. Featurize. Each cell is normalized once and tagged with bitmask flags (character classes, header keywords via Aho-Corasick) and Shannon entropy.
3. Select candidates. Cells with header keywords, high entropy, formulas, comments or inline patterns are kept and classified as headers or values.
4. Group. Adjacent candidates are clustered into regions with a breadth-first search over a 7x7 neighbourhood.
5. Pair and score. Each credential label is paired with its best-scoring neighbour using distance, character mix, entropy, region membership and nearby username or URL labels. Labels, prose and formulas are penalized.

Sheets are processed in parallel with Rayon. Scoring is heuristic; there is no trained model.

Limitations

• Hostile files are checked, not sandboxed. XML entity attacks are refused, and .xlsx/.xlsm/.ods files that would decompress beyond 512 MiB, or with a zip-bomb compression ratio, are rejected before parsing. Those checks trust the sizes declared inside the archive, which a determined attacker can forge; run doormat with a memory limit when scanning files from untrusted sources at scale.
• Password tables are not detected. A Password column with one credential per row is the most common pattern doormat misses today.
• Legacy .xls files expose no formulas or comments through xlrd, so those pathways only apply to .xlsx, .xlsm and .ods.
• Python only. Bindings for other languages are planned, as is a command-line tool.

Roadmap

• 0.2.0: first PyPI release
• 0.3.0: password-table detection, fewer false positives on empty form fields, faster extraction of large workbooks

All planned work is tracked in milestones; changes are listed in CHANGELOG.md.

Contributing

Bug reports and pull requests are welcome. Please follow the Code of Conduct. See CONTRIBUTING.md for building from source, running the tests and the benchmark harness, and adding a detection pathway.

Security

Please report vulnerabilities privately, as described in SECURITY.md. Never attach spreadsheets containing real credentials to issues; rebuild the layout with made-up values.

Acknowledgements

Real-world evaluation uses the Enron spreadsheet corpus by Felienne Hermans and Emerson Murphy-Hill ("Enron's Spreadsheets and Related Emails: A Dataset and Analysis", ICSE 2015), licensed CC BY 4.0. The corpus is not redistributed in this repository.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in doormat by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.