questio 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
questio-0.1.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nomada Software LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
questio-0.1.1/PKG-INFO ADDED
@@ -0,0 +1,308 @@
1
+ Metadata-Version: 2.4
2
+ Name: questio
3
+ Version: 0.1.1
4
+ Summary: Forensic PDF auditor CLI for detecting edited, forged, or tampered PDFs. Local-first, no cloud, no uploads.
5
+ Author: Nomada Software LLC
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/nomada-labs/questio
8
+ Project-URL: Repository, https://github.com/nomada-labs/questio
9
+ Project-URL: Issues, https://github.com/nomada-labs/questio/issues
10
+ Keywords: pdf,forensics,document-forensics,pdf-forensics,pdf-tampering-detection,fraud-detection,digital-forensics,cli,local-first
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Information Technology
14
+ Classifier: Intended Audience :: Legal Industry
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Topic :: Security
22
+ Classifier: Topic :: Utilities
23
+ Requires-Python: >=3.10
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Provides-Extra: dev
27
+ Requires-Dist: pytest>=7; extra == "dev"
28
+ Requires-Dist: pytest-cov; extra == "dev"
29
+ Requires-Dist: reportlab; extra == "dev"
30
+ Dynamic: license-file
31
+
32
+ # questio: Forensic PDF Auditor for Detecting Tampered Documents
33
+
34
+ > Someone edited this PDF after it was signed. questio can tell you where.
35
+
36
+ Edit a PDF in Word, LibreOffice, Acrobat, Preview, Sejda, Foxit, or anything else, and you leave traces behind. Producer strings that shouldn't be there. Font tags reset mid-document. End-of-file markers stacked on top of each other. questio reads all of it and scores the document 0 to 100.
37
+
38
+ It runs on your laptop. Nothing uploads, ever. Generic mode works on any PDF with zero setup. Train it once on a genuine bank statement, invoice, or contract you already hold, and questio gets surgical: it flags the exact object in the next forgery that does not match.
39
+
40
+ No cloud. No shared registry. No vendor asking you to trust them. That includes us.
41
+
42
+ ---
43
+
44
+ > A freelancer receives a signed contract back from a client. The PDF looks identical: same fonts, same layout, same signature block. questio scores it 34/100 and flags an Acrobat edit signature on page 2 plus a font tag drift that does not match the rest of the document. The payment terms paragraph had been rewritten after signing. The diff is now sitting in her terminal.
45
+
46
+ ---
47
+
48
+ ## How it works
49
+
50
+ ### 1. Editor and producer detection
51
+
52
+ Every PDF carries metadata saying what tool made it. Microsoft Word, LibreOffice, Canva, Apple Pages, and Google Docs are uncommon for official documents from banks, utilities, HMRC, or enterprise software. questio flags them on sight. Adobe Acrobat, Foxit, PDF-XChange, Sejda, and Nitro are editors, not generators. If one shows up in the metadata of a bank statement, somebody opened the file and saved it again.
53
+
54
+ **Translation:** if your landlord sends a "bank statement" whose producer field says LibreOffice, that is the tool noticing.
55
+
56
+ ### 2. Font session tracking
57
+
58
+ Every time a PDF is saved, embedded fonts get a random 6-character tag (for example `ABCDEF+Helvetica`). A clean single-session document has one set of tags. A document edited and re-saved has two. Three save passes leave three sets. This trace survives flattening and is the most reliable signal questio has.
59
+
60
+ **Translation:** if someone added a fake line to an invoice, the fake line often carries a different font tag than the rest. questio catches this even when the eye cannot.
61
+
62
+ ### 3. Revision history mapping
63
+
64
+ PDFs can be saved incrementally, leaving a literal history of every change stacked inside the file. questio counts the end-of-file markers and, when it finds more than one, tells you which revision modified which page and which objects.
65
+
66
+ **Translation:** three end-of-file markers means three save passes. A clean original has exactly one.
67
+
68
+ ### 4. Acrobat edit signature
69
+
70
+ Adobe Acrobat's Edit Text tool leaves a particular kind of font object behind (CIDFont). Microsoft Word, Adobe InDesign, Google Chrome, LibreOffice, and most other generators never write these. If one appears in a document that claims to come from a generator that does not use them, Acrobat touched the file.
71
+
72
+ **Translation:** this is the surgical catch. When it fires, the forger almost certainly used Acrobat's Edit Text tool.
73
+
74
+ ### 5. Content stream fingerprinting
75
+
76
+ Every generator has a drawing handwriting: coordinate precision, operator style, font reference patterns. questio learns these dimensions as a fingerprint and compares them against a stored issuer profile.
77
+
78
+ **Translation:** if a document claims to come from InDesign but draws text the way Acrobat does, it was edited.
79
+
80
+ ---
81
+
82
+ ## What questio refuses to do
83
+
84
+ - **No cloud.** There is no hosted version, no "questio pro", no API key. Your documents never leave your machine.
85
+ - **No shared fingerprint registry.** Fingerprints stay on your laptop. A public registry would be a honeypot for forgers: upload a bad fingerprint, make real documents look fake, or vice versa.
86
+ - **No court admissibility claims.** questio produces evidence and a score. It does not produce verdicts. Admissibility is your lawyer's job.
87
+ - **No GUI.** A GUI invites verdict-seeking users. questio's whole point is that you do the thinking.
88
+ - **No telemetry.** Nothing is logged, uploaded, or phoned home. Verify with the source if you do not trust the binary.
89
+
90
+ ---
91
+
92
+ ## Local-first: why questio never uploads your PDFs
93
+
94
+ Most PDF-checking tools ask you to upload the file. That creates two problems questio refuses to inherit:
95
+
96
+ 1. **Your sensitive documents reach a third party.** Bank statements, legal contracts, payslips, medical records. Even if the service promises to delete them, you have no way to verify.
97
+ 2. **A central fingerprint database is a liability.** Anyone who contributes a fingerprint can poison the registry. A malicious actor could upload a fingerprint that makes forged documents score as genuine, or the reverse.
98
+
99
+ questio sidesteps both by running entirely on your laptop. Your fingerprints live in `~/.questio/fingerprints/` and never leave. You decide which documents are genuine by training the tool on files you verified yourself. The trust chain starts and ends with you.
100
+
101
+ ---
102
+
103
+ ## Installation
104
+
105
+ ```bash
106
+ pipx install questio # or: pip install questio
107
+ ```
108
+
109
+ **Requires**: Python 3.10+, [exiftool](https://exiftool.org/)
110
+
111
+ ```bash
112
+ brew install exiftool # macOS
113
+ apt install libimage-exiftool-perl # Debian/Ubuntu
114
+ ```
115
+
116
+ ---
117
+
118
+ ## Usage
119
+
120
+ ### Audit a PDF (default)
121
+
122
+ ```bash
123
+ questio invoice.pdf
124
+ ```
125
+
126
+ **Exit codes**
127
+
128
+ | Code | Meaning |
129
+ |------|---------|
130
+ | `0` | Authentic: trust score >= 80 |
131
+ | `1` | Suspicious: trust score 50 to 79 |
132
+ | `2` | Likely tampered: trust score < 50 |
133
+ | `3` | Error (file not found, exiftool missing, etc.) |
134
+
135
+ **Options**
136
+
137
+ ```
138
+ --json Machine-readable JSON output
139
+ --verbose, -v Full structural dump (font details, content stream fingerprint)
140
+ --issuer NAME Verify against a stored issuer fingerprint
141
+ ```
142
+
143
+ ### Learn an issuer fingerprint
144
+
145
+ ```bash
146
+ questio learn --issuer three-uk genuine-bill.pdf
147
+ ```
148
+
149
+ Run on several known-good samples from the same issuer to build a reliable fingerprint. Each `learn` call adds to the existing profile rather than replacing it.
150
+
151
+ ### Verify against a known issuer
152
+
153
+ ```bash
154
+ questio verify --issuer three-uk suspect-bill.pdf
155
+ ```
156
+
157
+ Compares the suspect document's structural dimensions against the stored fingerprint and reports per-dimension confidence scores and any deviations.
158
+
159
+ ### Compare two PDFs directly
160
+
161
+ ```bash
162
+ questio compare reference.pdf suspect.pdf
163
+ ```
164
+
165
+ Side-by-side structural diff: font prefixes, content stream fingerprint, object counts, metadata fields. Useful when you have a confirmed genuine copy to compare against.
166
+
167
+ ---
168
+
169
+ ## Output example
170
+
171
+ ```
172
+ $ questio invoice.pdf
173
+
174
+ ================================================================
175
+ PDF AUDIT -- invoice.pdf
176
+ ================================================================
177
+
178
+ Trust Score: 83/100 ████████████████████████████████░░░░░░░░
179
+ Verdict: LIKELY AUTHENTIC
180
+
181
+ Creator: Adobe InDesign 19.0
182
+ Producer: Adobe PDF Library 15.0
183
+ Created: 2024-03-15T14:22:31+00:00
184
+ Modified: 2024-03-15T14:22:35+00:00
185
+ Pages: 1
186
+ Revisions: 1 (%%EOF markers)
187
+ Objects: 47
188
+ Size: 84 KB
189
+
190
+ Revision Map
191
+ ----------------------------------------------------------------
192
+ Rev 1: 84.2 KB, 47 objects [original]
193
+
194
+ Findings
195
+ ----------------------------------------------------------------
196
+ v Producer Adobe PDF Library 15.0 (trusted)
197
+ v Font subsets 3 subsets, consistent prefix ABCDEF
198
+ v Revisions Single revision -- no incremental updates
199
+ ! Timestamp gap 4s create->modify (low confidence -- sub-minute)
200
+ v Content stream Matches Adobe InDesign profile
201
+ v Font types TrueType only -- consistent with declared tool
202
+ v Object count 47 objects -- within expected range
203
+ v File structure Cross-reference table valid
204
+ v Version PDF 1.6 -- consistent with producer
205
+ v Coord precision 3 decimal places -- matches Adobe profile
206
+ ```
207
+
208
+ ---
209
+
210
+ ## Fingerprint format
211
+
212
+ Fingerprints are stored as JSON at `~/.questio/fingerprints/<issuer>.json`. Each file records the issuer name, number of training samples, and arrays of observed values plus min/max ranges for structural dimensions: font subset prefixes, content stream operator distributions, coordinate precision, font reference style, object counts, and producer strings.
213
+
214
+ Override the storage directory with the `QUESTIO_HOME` environment variable:
215
+
216
+ ```bash
217
+ QUESTIO_HOME=/team/shared/fingerprints questio verify --issuer acme suspect.pdf
218
+ ```
219
+
220
+ Fingerprints are automatically migrated from the legacy `~/.pdf-audit/fingerprints/` path on first run.
221
+
222
+ Do not import fingerprints from untrusted sources. A fingerprint tells questio what to treat as normal. A poisoned fingerprint from a bad actor could make tampered documents score as genuine.
223
+
224
+ See [docs/FINGERPRINT_FORMAT.md](docs/FINGERPRINT_FORMAT.md) for the complete field reference and hand-authoring guide.
225
+
226
+ ---
227
+
228
+ ## How to check if a PDF has been edited
229
+
230
+ 1. Install questio: `pipx install questio` (or `pip install questio`)
231
+ 2. Install exiftool (the only external dependency): `brew install exiftool` on macOS, `apt install libimage-exiftool-perl` on Debian/Ubuntu.
232
+ 3. Run: `questio suspect.pdf`
233
+ 4. Read the trust score and findings list. Scores above 80 are typically authentic, 50 to 79 are suspicious, below 50 are likely tampered.
234
+ 5. For surgical verification of a specific issuer, train questio on a genuine document from that issuer first: `questio learn --issuer three-uk real_bill.pdf`. Then verify future documents against the trained fingerprint: `questio verify --issuer three-uk suspect_bill.pdf`.
235
+
236
+ ---
237
+
238
+ ## Who uses questio
239
+
240
+ - **Journalists** checking the authenticity of leaked documents from sources
241
+ - **Fraud investigators** verifying invoices, expense receipts, and supplier documents
242
+ - **Paralegals** running initial integrity reviews on client-submitted exhibits
243
+ - **Accountants** flagging suspect bank statements, payslips, or tax forms
244
+ - **Landlords and property managers** checking proof-of-income submissions
245
+ - **Small-business owners** verifying supplier invoices and contractor credentials
246
+ - **KYC and compliance teams** adding a pre-manual-review filter to document workflows
247
+
248
+ ---
249
+
250
+ ## Limitations
251
+
252
+ questio is a heuristic tool. It makes educated guesses based on structural evidence. It cannot:
253
+
254
+ - Read the visual content of a PDF (it does not OCR text or compare images)
255
+ - Detect a forgery that was recreated from scratch in the same tool the original used
256
+ - Catch a tampering that happened before the PDF was generated (e.g. a doctored spreadsheet exported to PDF)
257
+ - Prove a document is fake. It can only prove that structural evidence is inconsistent with the document's claim.
258
+ - Replace human judgment. Always verify findings manually before acting.
259
+
260
+ ---
261
+
262
+ ## Troubleshooting
263
+
264
+ **exiftool not found**
265
+ ```bash
266
+ brew install exiftool # macOS
267
+ apt install libimage-exiftool-perl # Debian/Ubuntu
268
+ ```
269
+
270
+ **False positive on a legitimate PDF**
271
+ Run `questio learn` on several known-good samples from the same issuer before using `questio verify`. A fingerprint built from a single sample is too narrow and will flag minor generator variation as suspicious. Three or more samples is the practical minimum.
272
+
273
+ **Fingerprint not loading**
274
+ Check that `~/.questio/fingerprints/<issuer>.json` exists. If you were using an older version, fingerprints at `~/.pdf-audit/fingerprints/` are migrated automatically on first run. You can also set `QUESTIO_HOME` to point at an existing directory.
275
+
276
+ **`questio` command not found after install**
277
+ Ensure your Python `bin` directory is on `PATH`. With pipx: `pipx install questio`.
278
+
279
+ ---
280
+
281
+ ## FAQ
282
+
283
+ **Q: How do I check if a PDF has been edited after it was created?**
284
+ A: Run `questio document.pdf`. It scores the PDF 0 to 100 and flags ten kinds of tampering traces: producer metadata that should not be there, font tags stacked from multiple editing sessions, Acrobat-specific font signatures, extra end-of-file markers, timestamp gaps, and content stream patterns inconsistent with the declared generator.
285
+
286
+ **Q: Can questio detect a forged bank statement?**
287
+ A: Yes. questio catches edits from any common tool: Microsoft Word, LibreOffice, Apple Pages, Canva, Google Docs, Adobe Acrobat, Foxit, PDF-XChange, Sejda. Typically multiple traces fire at once: producer metadata, font session tags, and timestamp drift. Acrobat's edit tool fires an extra signature on top of the rest.
288
+
289
+ **Q: Does questio send my PDFs to a cloud service?**
290
+ A: No. questio runs entirely on your machine. It never uploads, phones home, or requires an API key.
291
+
292
+ **Q: What PDF tampering does questio catch that I cannot see by eye?**
293
+ A: Font tag drift across editing sessions, Acrobat-specific font object signatures, incremental save history, mismatched producer metadata, permission-lock abuse, and byte-level drawing instructions inconsistent with the declared PDF generator.
294
+
295
+ **Q: Is questio free and open source?**
296
+ A: Yes. MIT-licensed Python CLI. Install with pip, run against any PDF, no account required.
297
+
298
+ ---
299
+
300
+ ## License
301
+
302
+ MIT (c) 2026 Nomada Software LLC
303
+
304
+ ---
305
+
306
+ ## Disclaimer
307
+
308
+ questio is a heuristic forensic tool. Its output is not legal evidence and is not court-admissible. It produces a score and a list of structural anomalies. It does not produce verdicts. Always verify findings manually before making any accusations or decisions. The authors accept no liability for incorrect results.
@@ -0,0 +1,277 @@
1
+ # questio: Forensic PDF Auditor for Detecting Tampered Documents
2
+
3
+ > Someone edited this PDF after it was signed. questio can tell you where.
4
+
5
+ Edit a PDF in Word, LibreOffice, Acrobat, Preview, Sejda, Foxit, or anything else, and you leave traces behind. Producer strings that shouldn't be there. Font tags reset mid-document. End-of-file markers stacked on top of each other. questio reads all of it and scores the document 0 to 100.
6
+
7
+ It runs on your laptop. Nothing uploads, ever. Generic mode works on any PDF with zero setup. Train it once on a genuine bank statement, invoice, or contract you already hold, and questio gets surgical: it flags the exact object in the next forgery that does not match.
8
+
9
+ No cloud. No shared registry. No vendor asking you to trust them. That includes us.
10
+
11
+ ---
12
+
13
+ > A freelancer receives a signed contract back from a client. The PDF looks identical: same fonts, same layout, same signature block. questio scores it 34/100 and flags an Acrobat edit signature on page 2 plus a font tag drift that does not match the rest of the document. The payment terms paragraph had been rewritten after signing. The diff is now sitting in her terminal.
14
+
15
+ ---
16
+
17
+ ## How it works
18
+
19
+ ### 1. Editor and producer detection
20
+
21
+ Every PDF carries metadata saying what tool made it. Microsoft Word, LibreOffice, Canva, Apple Pages, and Google Docs are uncommon for official documents from banks, utilities, HMRC, or enterprise software. questio flags them on sight. Adobe Acrobat, Foxit, PDF-XChange, Sejda, and Nitro are editors, not generators. If one shows up in the metadata of a bank statement, somebody opened the file and saved it again.
22
+
23
+ **Translation:** if your landlord sends a "bank statement" whose producer field says LibreOffice, that is the tool noticing.
24
+
25
+ ### 2. Font session tracking
26
+
27
+ Every time a PDF is saved, embedded fonts get a random 6-character tag (for example `ABCDEF+Helvetica`). A clean single-session document has one set of tags. A document edited and re-saved has two. Three save passes leave three sets. This trace survives flattening and is the most reliable signal questio has.
28
+
29
+ **Translation:** if someone added a fake line to an invoice, the fake line often carries a different font tag than the rest. questio catches this even when the eye cannot.
30
+
31
+ ### 3. Revision history mapping
32
+
33
+ PDFs can be saved incrementally, leaving a literal history of every change stacked inside the file. questio counts the end-of-file markers and, when it finds more than one, tells you which revision modified which page and which objects.
34
+
35
+ **Translation:** three end-of-file markers means three save passes. A clean original has exactly one.
36
+
37
+ ### 4. Acrobat edit signature
38
+
39
+ Adobe Acrobat's Edit Text tool leaves a particular kind of font object behind (CIDFont). Microsoft Word, Adobe InDesign, Google Chrome, LibreOffice, and most other generators never write these. If one appears in a document that claims to come from a generator that does not use them, Acrobat touched the file.
40
+
41
+ **Translation:** this is the surgical catch. When it fires, the forger almost certainly used Acrobat's Edit Text tool.
42
+
43
+ ### 5. Content stream fingerprinting
44
+
45
+ Every generator has a drawing handwriting: coordinate precision, operator style, font reference patterns. questio learns these dimensions as a fingerprint and compares them against a stored issuer profile.
46
+
47
+ **Translation:** if a document claims to come from InDesign but draws text the way Acrobat does, it was edited.
48
+
49
+ ---
50
+
51
+ ## What questio refuses to do
52
+
53
+ - **No cloud.** There is no hosted version, no "questio pro", no API key. Your documents never leave your machine.
54
+ - **No shared fingerprint registry.** Fingerprints stay on your laptop. A public registry would be a honeypot for forgers: upload a bad fingerprint, make real documents look fake, or vice versa.
55
+ - **No court admissibility claims.** questio produces evidence and a score. It does not produce verdicts. Admissibility is your lawyer's job.
56
+ - **No GUI.** A GUI invites verdict-seeking users. questio's whole point is that you do the thinking.
57
+ - **No telemetry.** Nothing is logged, uploaded, or phoned home. Verify with the source if you do not trust the binary.
58
+
59
+ ---
60
+
61
+ ## Local-first: why questio never uploads your PDFs
62
+
63
+ Most PDF-checking tools ask you to upload the file. That creates two problems questio refuses to inherit:
64
+
65
+ 1. **Your sensitive documents reach a third party.** Bank statements, legal contracts, payslips, medical records. Even if the service promises to delete them, you have no way to verify.
66
+ 2. **A central fingerprint database is a liability.** Anyone who contributes a fingerprint can poison the registry. A malicious actor could upload a fingerprint that makes forged documents score as genuine, or the reverse.
67
+
68
+ questio sidesteps both by running entirely on your laptop. Your fingerprints live in `~/.questio/fingerprints/` and never leave. You decide which documents are genuine by training the tool on files you verified yourself. The trust chain starts and ends with you.
69
+
70
+ ---
71
+
72
+ ## Installation
73
+
74
+ ```bash
75
+ pipx install questio # or: pip install questio
76
+ ```
77
+
78
+ **Requires**: Python 3.10+, [exiftool](https://exiftool.org/)
79
+
80
+ ```bash
81
+ brew install exiftool # macOS
82
+ apt install libimage-exiftool-perl # Debian/Ubuntu
83
+ ```
84
+
85
+ ---
86
+
87
+ ## Usage
88
+
89
+ ### Audit a PDF (default)
90
+
91
+ ```bash
92
+ questio invoice.pdf
93
+ ```
94
+
95
+ **Exit codes**
96
+
97
+ | Code | Meaning |
98
+ |------|---------|
99
+ | `0` | Authentic: trust score >= 80 |
100
+ | `1` | Suspicious: trust score 50 to 79 |
101
+ | `2` | Likely tampered: trust score < 50 |
102
+ | `3` | Error (file not found, exiftool missing, etc.) |
103
+
104
+ **Options**
105
+
106
+ ```
107
+ --json Machine-readable JSON output
108
+ --verbose, -v Full structural dump (font details, content stream fingerprint)
109
+ --issuer NAME Verify against a stored issuer fingerprint
110
+ ```
111
+
112
+ ### Learn an issuer fingerprint
113
+
114
+ ```bash
115
+ questio learn --issuer three-uk genuine-bill.pdf
116
+ ```
117
+
118
+ Run on several known-good samples from the same issuer to build a reliable fingerprint. Each `learn` call adds to the existing profile rather than replacing it.
119
+
120
+ ### Verify against a known issuer
121
+
122
+ ```bash
123
+ questio verify --issuer three-uk suspect-bill.pdf
124
+ ```
125
+
126
+ Compares the suspect document's structural dimensions against the stored fingerprint and reports per-dimension confidence scores and any deviations.
127
+
128
+ ### Compare two PDFs directly
129
+
130
+ ```bash
131
+ questio compare reference.pdf suspect.pdf
132
+ ```
133
+
134
+ Side-by-side structural diff: font prefixes, content stream fingerprint, object counts, metadata fields. Useful when you have a confirmed genuine copy to compare against.
135
+
136
+ ---
137
+
138
+ ## Output example
139
+
140
+ ```
141
+ $ questio invoice.pdf
142
+
143
+ ================================================================
144
+ PDF AUDIT -- invoice.pdf
145
+ ================================================================
146
+
147
+ Trust Score: 83/100 ████████████████████████████████░░░░░░░░
148
+ Verdict: LIKELY AUTHENTIC
149
+
150
+ Creator: Adobe InDesign 19.0
151
+ Producer: Adobe PDF Library 15.0
152
+ Created: 2024-03-15T14:22:31+00:00
153
+ Modified: 2024-03-15T14:22:35+00:00
154
+ Pages: 1
155
+ Revisions: 1 (%%EOF markers)
156
+ Objects: 47
157
+ Size: 84 KB
158
+
159
+ Revision Map
160
+ ----------------------------------------------------------------
161
+ Rev 1: 84.2 KB, 47 objects [original]
162
+
163
+ Findings
164
+ ----------------------------------------------------------------
165
+ v Producer Adobe PDF Library 15.0 (trusted)
166
+ v Font subsets 3 subsets, consistent prefix ABCDEF
167
+ v Revisions Single revision -- no incremental updates
168
+ ! Timestamp gap 4s create->modify (low confidence -- sub-minute)
169
+ v Content stream Matches Adobe InDesign profile
170
+ v Font types TrueType only -- consistent with declared tool
171
+ v Object count 47 objects -- within expected range
172
+ v File structure Cross-reference table valid
173
+ v Version PDF 1.6 -- consistent with producer
174
+ v Coord precision 3 decimal places -- matches Adobe profile
175
+ ```
176
+
177
+ ---
178
+
179
+ ## Fingerprint format
180
+
181
+ Fingerprints are stored as JSON at `~/.questio/fingerprints/<issuer>.json`. Each file records the issuer name, number of training samples, and arrays of observed values plus min/max ranges for structural dimensions: font subset prefixes, content stream operator distributions, coordinate precision, font reference style, object counts, and producer strings.
182
+
183
+ Override the storage directory with the `QUESTIO_HOME` environment variable:
184
+
185
+ ```bash
186
+ QUESTIO_HOME=/team/shared/fingerprints questio verify --issuer acme suspect.pdf
187
+ ```
188
+
189
+ Fingerprints are automatically migrated from the legacy `~/.pdf-audit/fingerprints/` path on first run.
190
+
191
+ Do not import fingerprints from untrusted sources. A fingerprint tells questio what to treat as normal. A poisoned fingerprint from a bad actor could make tampered documents score as genuine.
192
+
193
+ See [docs/FINGERPRINT_FORMAT.md](docs/FINGERPRINT_FORMAT.md) for the complete field reference and hand-authoring guide.
194
+
195
+ ---
196
+
197
+ ## How to check if a PDF has been edited
198
+
199
+ 1. Install questio: `pipx install questio` (or `pip install questio`)
200
+ 2. Install exiftool (the only external dependency): `brew install exiftool` on macOS, `apt install libimage-exiftool-perl` on Debian/Ubuntu.
201
+ 3. Run: `questio suspect.pdf`
202
+ 4. Read the trust score and findings list. Scores above 80 are typically authentic, 50 to 79 are suspicious, below 50 are likely tampered.
203
+ 5. For surgical verification of a specific issuer, train questio on a genuine document from that issuer first: `questio learn --issuer three-uk real_bill.pdf`. Then verify future documents against the trained fingerprint: `questio verify --issuer three-uk suspect_bill.pdf`.
204
+
205
+ ---
206
+
207
+ ## Who uses questio
208
+
209
+ - **Journalists** checking the authenticity of leaked documents from sources
210
+ - **Fraud investigators** verifying invoices, expense receipts, and supplier documents
211
+ - **Paralegals** running initial integrity reviews on client-submitted exhibits
212
+ - **Accountants** flagging suspect bank statements, payslips, or tax forms
213
+ - **Landlords and property managers** checking proof-of-income submissions
214
+ - **Small-business owners** verifying supplier invoices and contractor credentials
215
+ - **KYC and compliance teams** adding a pre-manual-review filter to document workflows
216
+
217
+ ---
218
+
219
+ ## Limitations
220
+
221
+ questio is a heuristic tool. It makes educated guesses based on structural evidence. It cannot:
222
+
223
+ - Read the visual content of a PDF (it does not OCR text or compare images)
224
+ - Detect a forgery that was recreated from scratch in the same tool the original used
225
+ - Catch a tampering that happened before the PDF was generated (e.g. a doctored spreadsheet exported to PDF)
226
+ - Prove a document is fake. It can only prove that structural evidence is inconsistent with the document's claim.
227
+ - Replace human judgment. Always verify findings manually before acting.
228
+
229
+ ---
230
+
231
+ ## Troubleshooting
232
+
233
+ **exiftool not found**
234
+ ```bash
235
+ brew install exiftool # macOS
236
+ apt install libimage-exiftool-perl # Debian/Ubuntu
237
+ ```
238
+
239
+ **False positive on a legitimate PDF**
240
+ Run `questio learn` on several known-good samples from the same issuer before using `questio verify`. A fingerprint built from a single sample is too narrow and will flag minor generator variation as suspicious. Three or more samples is the practical minimum.
241
+
242
+ **Fingerprint not loading**
243
+ Check that `~/.questio/fingerprints/<issuer>.json` exists. If you were using an older version, fingerprints at `~/.pdf-audit/fingerprints/` are migrated automatically on first run. You can also set `QUESTIO_HOME` to point at an existing directory.
244
+
245
+ **`questio` command not found after install**
246
+ Ensure your Python `bin` directory is on `PATH`. With pipx: `pipx install questio`.
247
+
248
+ ---
249
+
250
+ ## FAQ
251
+
252
+ **Q: How do I check if a PDF has been edited after it was created?**
253
+ A: Run `questio document.pdf`. It scores the PDF 0 to 100 and flags ten kinds of tampering traces: producer metadata that should not be there, font tags stacked from multiple editing sessions, Acrobat-specific font signatures, extra end-of-file markers, timestamp gaps, and content stream patterns inconsistent with the declared generator.
254
+
255
+ **Q: Can questio detect a forged bank statement?**
256
+ A: Yes. questio catches edits from any common tool: Microsoft Word, LibreOffice, Apple Pages, Canva, Google Docs, Adobe Acrobat, Foxit, PDF-XChange, Sejda. Typically multiple traces fire at once: producer metadata, font session tags, and timestamp drift. Acrobat's edit tool fires an extra signature on top of the rest.
257
+
258
+ **Q: Does questio send my PDFs to a cloud service?**
259
+ A: No. questio runs entirely on your machine. It never uploads, phones home, or requires an API key.
260
+
261
+ **Q: What PDF tampering does questio catch that I cannot see by eye?**
262
+ A: Font tag drift across editing sessions, Acrobat-specific font object signatures, incremental save history, mismatched producer metadata, permission-lock abuse, and byte-level drawing instructions inconsistent with the declared PDF generator.
263
+
264
+ **Q: Is questio free and open source?**
265
+ A: Yes. MIT-licensed Python CLI. Install with pip, run against any PDF, no account required.
266
+
267
+ ---
268
+
269
+ ## License
270
+
271
+ MIT (c) 2026 Nomada Software LLC
272
+
273
+ ---
274
+
275
+ ## Disclaimer
276
+
277
+ questio is a heuristic forensic tool. Its output is not legal evidence and is not court-admissible. It produces a score and a list of structural anomalies. It does not produce verdicts. Always verify findings manually before making any accusations or decisions. The authors accept no liability for incorrect results.
@@ -0,0 +1,51 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "questio"
7
+ version = "0.1.1"
8
+ description = "Forensic PDF auditor CLI for detecting edited, forged, or tampered PDFs. Local-first, no cloud, no uploads."
9
+ readme = "README.md"
10
+ license = { text = "MIT" }
11
+ requires-python = ">=3.10"
12
+ authors = [{ name = "Nomada Software LLC" }]
13
+ keywords = [
14
+ "pdf",
15
+ "forensics",
16
+ "document-forensics",
17
+ "pdf-forensics",
18
+ "pdf-tampering-detection",
19
+ "fraud-detection",
20
+ "digital-forensics",
21
+ "cli",
22
+ "local-first",
23
+ ]
24
+ classifiers = [
25
+ "Development Status :: 4 - Beta",
26
+ "Environment :: Console",
27
+ "Intended Audience :: Information Technology",
28
+ "Intended Audience :: Legal Industry",
29
+ "License :: OSI Approved :: MIT License",
30
+ "Operating System :: OS Independent",
31
+ "Programming Language :: Python :: 3",
32
+ "Programming Language :: Python :: 3.10",
33
+ "Programming Language :: Python :: 3.11",
34
+ "Programming Language :: Python :: 3.12",
35
+ "Topic :: Security",
36
+ "Topic :: Utilities",
37
+ ]
38
+
39
+ [project.urls]
40
+ Homepage = "https://github.com/nomada-labs/questio"
41
+ Repository = "https://github.com/nomada-labs/questio"
42
+ Issues = "https://github.com/nomada-labs/questio/issues"
43
+
44
+ [project.scripts]
45
+ questio = "questio.questio:main"
46
+
47
+ [project.optional-dependencies]
48
+ dev = ["pytest>=7", "pytest-cov", "reportlab"]
49
+
50
+ [tool.setuptools.packages.find]
51
+ where = ["."]
@@ -0,0 +1 @@
1
+ __version__ = '0.1.0'