ai-secret-scout 2.3.0

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.
Files changed (5) hide show
  1. package/README.fr.md +514 -0
  2. package/README.md +519 -0
  3. package/ai_secret_scout.py +2376 -0
  4. package/bin/aiscout.js +31 -0
  5. package/package.json +40 -0
package/README.md ADDED
@@ -0,0 +1,519 @@
1
+ <div align="center">
2
+ <pre>
3
+ █████╗ ██╗ ███████╗ ██████╗ ██████╗ ██╗ ██╗████████╗
4
+ ██╔══██╗██║ ██╔════╝██╔════╝██╔═══██╗██║ ██║╚══██╔══╝
5
+ ███████║██║ ███████╗██║ ██║ ██║██║ ██║ ██║
6
+ ██╔══██║██║ ╚════██║██║ ██║ ██║██║ ██║ ██║
7
+ ██║ ██║██║ ███████║╚██████╗╚██████╔╝╚██████╔╝ ██║
8
+ ╚═╝ ╚═╝╚═╝ ╚══════╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚═╝
9
+ ◈ A I S E C R E T S C O U T ◈
10
+ </pre>
11
+
12
+ <h2>AI Secret Scout (<code>aiscout</code>) — v2.3.0</h2>
13
+
14
+ <p align="center">
15
+ <!-- Row 1: tech & platform badges -->
16
+ <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&amp;logoColor=white" alt="Python 3.10+">
17
+ <img src="https://img.shields.io/badge/Interface-Full--Screen%20TUI-06B6D4?logo=gnometerminal&amp;logoColor=white" alt="Full-Screen TUI">
18
+ <img src="https://img.shields.io/badge/Dependencies-Zero%20External-22c55e?logo=python&amp;logoColor=white" alt="Zero Dependencies">
19
+ <img src="https://img.shields.io/badge/Watchdog-Real--Time%20%26%20Desktop%20Alerts-F59E0B?logo=airplayaudio&amp;logoColor=white" alt="Real-Time Watchdog">
20
+ <img src="https://img.shields.io/badge/Safe%20Restore-Backup%20Manager-7C3AED?logo=securityscorecard&amp;logoColor=white" alt="Safe Restore">
21
+ <img src="https://img.shields.io/badge/Platform-Linux%20%7C%20WSL%20(only)-E95420?logo=linux&amp;logoColor=white" alt="Linux | WSL (only)">
22
+ </p>
23
+
24
+ <p align="center">
25
+ <!-- Row 2: audited AI ecosystems -->
26
+ <img src="https://img.shields.io/badge/Claude%20Code-Audited-D97706?logo=anthropic&amp;logoColor=white" alt="Claude Code">
27
+ <img src="https://img.shields.io/badge/Antigravity-Audited-4285F4?logo=google&amp;logoColor=white" alt="Antigravity">
28
+ <img src="https://img.shields.io/badge/OpenAI%20Codex-Audited-10A37F?logo=openai&amp;logoColor=white" alt="Codex">
29
+ <img src="https://img.shields.io/badge/GitHub%20Copilot-Audited-000000?logo=githubcopilot&amp;logoColor=white" alt="GitHub Copilot">
30
+ <img src="https://img.shields.io/badge/Cursor%20%26%20Aider-Audited-8B5CF6" alt="Cursor &amp; Aider">
31
+ </p>
32
+
33
+ <p align="center">
34
+ <i>Audit, real-time background monitoring (Watchdog), desktop notifications, heuristic secret detection, and safe redaction for AI coding assistant histories.</i>
35
+ </p>
36
+
37
+ <p align="center">
38
+ <b>🇬🇧 English documentation</b> | <b><a href="./README.fr.md">🇫🇷 Documentation en français</a></b>
39
+ </p>
40
+ </div>
41
+
42
+ ---
43
+
44
+ ## 📑 Table of Contents
45
+ 1. [Why this project?](#-why-this-project)
46
+ 2. [Key Highlights of v2.3.0](#-key-highlights-of-v230)
47
+ 3. [Quickstart](#-quickstart)
48
+ 4. [TUI Interface & Navigation](#-tui-interface--navigation)
49
+ 5. [Real-Time Watchdog & Desktop Notifications](#-real-time-watchdog--desktop-notifications)
50
+ 6. [Backup & Restore Manager (`Safe Restore`)](#-backup--restore-manager-safe-restore)
51
+ 7. [Audited AI Ecosystems](#-audited-ai-ecosystems)
52
+ 8. [Detection Engine & Signatures (18 built-in + Custom)](#-detection-engine--signatures-18-built-in--custom)
53
+ 9. [Custom Rules Configuration (`rules.json`)](#-custom-rules-configuration-rulesjson)
54
+ 10. [Anti-False-Positive Heuristics](#-anti-false-positive-heuristics)
55
+ 11. [Safe Sanitization & Redaction (`Safe Redact`)](#-safe-sanitization--redaction-safe-redact)
56
+ 12. [Keyboard Shortcuts & Controls](#-keyboard-shortcuts--controls)
57
+ 13. [Scripting / CLI Mode & Automation](#-scripting--cli-mode--automation)
58
+ 14. [Technical Architecture](#-technical-architecture)
59
+
60
+ ---
61
+
62
+ ## 🔍 Why this project?
63
+
64
+ When using autonomous coding assistants (**Claude Code**, **Google Antigravity / Gemini CLI**, **OpenAI Codex**, **GitHub Copilot CLI**, **Cursor**, **Aider**), language models persist complete conversation transcripts and execution logs in your local user directory (`~/.claude`, `~/.gemini`, etc.).
65
+
66
+ ### The Problem
67
+ 1. **Passive secret leakage**: When an agent runs a terminal command (e.g., `infisical secrets`, `ssh`, `curl`, or a script loading `.env`), raw terminal outputs and environment dumps are stored in plain text in local log files.
68
+ 2. **Active prompt leakage**: When a developer pastes an API key, personal access token, or password directly into an AI chat session, that credential remains written to disk forever.
69
+ 3. **Lack of native cleanup**: Even when an AI assistant warns you about a leaked secret in conversation, it **never** retroactively purges or redacts that value from disk history.
70
+ 4. **Invisible persistence**: Stored secrets remain silently exposed to local malware, accidental cloud backups, dotfile synchronizations, or repository sharing.
71
+
72
+ **AI Secret Scout (`aiscout`)** solves this critical security gap: it scans and monitors all AI assistant histories across your system, attributes every detected secret to its **originating project**, identifies its **exact usage context**, and allows surgical **safe redaction** with automated backups and instant rollback capabilities.
73
+
74
+ ---
75
+
76
+ ## 🌟 Key Highlights of v2.3.0
77
+
78
+ * **📡 Real-Time Continuous Monitoring (Watchdog Mode)**:
79
+ * Watches AI session files for additions or modifications with near-zero CPU usage.
80
+ * Sends immediate **native desktop notifications** (`notify-send`) on Linux (KDE Plasma Wayland / GNOME).
81
+ * Live visual heartbeat `🟢 [WATCHDOG ACTIVE]` with a rolling real-time event log.
82
+ * Available via TUI menu `[8]` or direct CLI command: `aiscout --watch`.
83
+
84
+ * **↩️ Backup & Restore Manager (`Safe Restore`)**:
85
+ * Dedicated interactive TUI table to inspect all `.bak` backup files created during redactions.
86
+ * Individual surgical restoration (`[R]`), batch rollback of all originals (`[A]`), or definitive backup purge (`[P]`).
87
+ * Dedicated CLI commands: `aiscout --restore` and `aiscout --clean-backups`.
88
+
89
+ * **🔍 Interactive Live Search (`/`) & Dynamic Sorting (`S`/`D`/`O`) in TUI**:
90
+ * `/` key: Instant inline search bar (filters live across category, tool, project, path, or secret value).
91
+ * Dynamic sorting shortcuts:
92
+ * `S`: Sort by descending severity (`🔴 CRITICAL` > `🟡 HIGH` > `🔵 MEDIUM`).
93
+ * `D`: Sort by session timestamp / freshness (most recent first).
94
+ * `O`: Sort alphabetically by AI tool.
95
+ * Fast reset via `Backspace` or `Esc`.
96
+
97
+ * **⚙️ Custom Rules Engine & 4 New Built-in Signatures**:
98
+ * Automatically loads user-defined regex rules from `~/.config/aiscout/rules.json`.
99
+ * 4 new enterprise signatures included out of the box:
100
+ * **GitLab Personal Access Token** (`glpat-[0-9a-zA-Z_\-]{20,}`)
101
+ * **HuggingFace Access Token** (`hf_[a-zA-Z0-9]{34,}`)
102
+ * **Resend API Key** (`re_[a-zA-Z0-9_\-]{24,}`)
103
+ * **Supabase / JWT Secret** (`eyJ...`)
104
+ * CLI inspection command: `aiscout --list-rules` showcasing all 18 built-in patterns plus custom rules.
105
+
106
+ ---
107
+
108
+ ## 🚀 Quickstart
109
+
110
+ > [!IMPORTANT]
111
+ > **Platform Support**: `aiscout` currently supports **Linux** (Wayland & X11) and **WSL / WSL2** (Windows Subsystem for Linux). Native Windows and macOS are not supported at this stage.
112
+
113
+ `aiscout` can be executed instantly without installation or installed globally:
114
+
115
+ ```bash
116
+ # ⚡ Instant execution without prior installation
117
+ npx ai-secret-scout
118
+ # or using bun
119
+ bunx ai-secret-scout
120
+
121
+ # 📦 Permanent global installation (recommended)
122
+ npm install -g ai-secret-scout
123
+ # or using bun
124
+ bun add -g ai-secret-scout
125
+
126
+ # Once installed, both aiscout and ai-secret-scout commands are available globally:
127
+ aiscout
128
+
129
+ # Launch real-time background watchdog with desktop notifications
130
+ aiscout --watch
131
+
132
+ # Restore all original files from .bak backups
133
+ aiscout --restore
134
+
135
+ # Permanently purge all .bak backup files
136
+ aiscout --clean-backups
137
+
138
+ # List all active detection rules (built-in + custom)
139
+ aiscout --list-rules
140
+ ```
141
+
142
+ The application automatically switches your terminal to an alternate screen buffer (`\033[?1049h`). Upon exit (`Q`), your original terminal prompt and history are seamlessly restored without visual leftovers.
143
+
144
+ ---
145
+
146
+ ## 🎨 TUI Interface & Navigation
147
+
148
+ `aiscout` features a standalone, dependency-free terminal user interface (built with standard Python library modules) that dynamically adjusts to your terminal geometry without truncation or phantom scrolling.
149
+
150
+ ### 1. Central Hub & Dashboard
151
+
152
+ ```text
153
+ ◈ AISCOUT v2.3.0 │ User : dev_redious │ Host : linux-workstation 12/09/2026 22:30
154
+
155
+ █████╗ ██╗ ███████╗ ██████╗ ██████╗ ██╗ ██╗████████╗
156
+ ██╔══██╗██║ ██╔════╝██╔════╝██╔═══██╗██║ ██║╚══██╔══╝
157
+ ███████║██║ ███████╗██║ ██║ ██║██║ ██║ ██║
158
+ ██╔══██║██║ ╚════██║██║ ██║ ██║██║ ██║ ██║
159
+ ██║ ██║██║ ███████║╚██████╗╚██████╔╝╚██████╔╝ ██║
160
+ ╚═╝ ╚═╝╚═╝ ╚══════╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚═╝
161
+
162
+ ◈ A I S E C R E T S A U D I T & R E D A C T I O N ◈
163
+ Claude Code • Antigravity / Gemini • Codex • GitHub Copilot • Cursor
164
+
165
+ [ 🔴 19 CRITICAL │ 🟡 1 HIGH │ 🔵 1 MEDIUM ] ◈ TOTAL : 21 EXPOSED SECRETS
166
+
167
+ ║ ▶ [1] 🔍 RUN FULL AUDIT ACROSS ALL AI SESSIONS ║
168
+ │ [2] 📋 SECRET EXPLORER (INTERACTIVE TUI TABLE) │
169
+ │ [3] 👁️ REVEAL MODE (TOGGLE PLAIN-TEXT VALUES) │
170
+ │ [4] 🏷️ FILTER BY AI TOOL OR PROJECT │
171
+ │ [5] 💾 EXPORT AUDIT REPORT (MARKDOWN / JSON) │
172
+ │ [6] 🛡️ SAFE SANITIZATION & REDACTION │
173
+ │ [7] ↩️ BACKUPS & RESTORE MANAGER (.BAK) │
174
+ │ [8] 📡 REAL-TIME WATCHDOG (LIVE ALERTS) │
175
+ │ [9] 🚪 EXIT APPLICATION │
176
+
177
+ ╭─ SELECTED ACTION ───────────────────────────────────────────────────────────╮
178
+ │ 💡 Browse through detected credentials with keyboard controls and inspect │
179
+ ╰─────────────────────────────────────────────────────────────────────────────╯
180
+
181
+ [↑/↓] Navigate │ [Enter] Confirm │ [1-9] Direct Jump │ [Q] Quit
182
+ ```
183
+
184
+ ### 2. Secret Explorer (Interactive Table, Dynamic Sorting & Search)
185
+
186
+ The interactive table allows fluid inspection of all detected secrets with multi-criteria sorting and instantaneous full-text filtering:
187
+
188
+ ```text
189
+ ◈ AISCOUT v2.3.0 │ User : dev_redious │ Host : linux-workstation 12/09/2026 22:30
190
+
191
+ 📋 SECRET EXPLORER (1/21) — Mode : MASKED 🛡️ │ Sort : Severity (🔴 > 🟡 > 🔵)
192
+
193
+ # │ SEVERITY │ CATEGORY │ AI TOOL │ PROJECT │ SECRET VALUE
194
+ ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
195
+ 1 │ 🔴 CRITICAL │ Private Key (SSH/RSA/ECC) │ Claude Code │ ~ │ ----****************...
196
+ 2 │ 🔴 CRITICAL │ Private Key (SSH/RSA/ECC) │ Claude Code │ ~ │ ----****************...
197
+ 3 │ 🔴 CRITICAL │ GitHub Token (PAT/Fine-Gr) │ Claude Code │ ~/Documents/Dev/App... │ ghp_****************...
198
+ 4 │ 🔴 CRITICAL │ Infisical / Coolify Token │ Claude Code │ ~/Documents/Dev/App... │ st.4****************...
199
+ 5 │ 🟡 HIGH │ Discord Bot Token │ Claude Code │ ~/Documents/Dev/App... │ MTE2****************...
200
+ 6 │ 🔵 MEDIUM │ Password passed via CLI │ Claude Code │ ~/Documents/Dev/App... │ pass****************...
201
+ ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
202
+
203
+ [↑/↓] Navigate │ [Enter] Card │ [/] Search │ [S/D/O] Sort │ [R] Reveal │ [C] Redact │ [Q] Back
204
+ ```
205
+
206
+ #### Interactive Full-Text Search (`/`)
207
+ Pressing `/` opens an inline prompt directly in the status bar. The table updates dynamically with every keystroke:
208
+
209
+ ```text
210
+ ◈ AISCOUT v2.3.0 │ User : dev_redious │ Host : linux-workstation 12/09/2026 22:30
211
+
212
+ 📋 SECRET EXPLORER (1/3) — Mode : MASKED 🛡️ │ Sort : Severity (🔴 > 🟡 > 🔵)
213
+ 🔍 Active filter: "github" (3 matching secrets) │ [Backspace/Esc] Clear
214
+
215
+ # │ SEVERITY │ CATEGORY │ AI TOOL │ PROJECT │ SECRET VALUE
216
+ ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
217
+ 1 │ 🔴 CRITICAL │ GitHub Token (PAT/Fine-Gr) │ Claude Code │ ~/Documents/Dev/App... │ ghp_****************...
218
+ 2 │ 🔴 CRITICAL │ GitHub Token (PAT/Fine-Gr) │ Claude Code │ ~/Documents/Dev/App... │ ghp_****************...
219
+ 3 │ 🔴 CRITICAL │ GitHub Token (PAT/Fine-Gr) │ Antigravity (Gemi) │ Antigravity Session │ ghp_****************...
220
+ ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
221
+
222
+ [↑/↓] Navigate │ [Enter] Card │ [/] Search │ [S/D/O] Sort │ [R] Reveal │ [C] Redact │ [Q] Back
223
+ ```
224
+
225
+ ### 3. Detailed Audit Card (Modal Card)
226
+
227
+ Pressing `Enter` on any row displays a full diagnostic modal card highlighting the source file, context, and remediation recommendations:
228
+
229
+ ```text
230
+ ◈ AISCOUT v2.3.0 │ User : dev_redious │ Host : linux-workstation 12/09/2026 22:30
231
+
232
+ ╭──────────────────────────────────────────────────────────────────────────────────╮
233
+ │ AUDIT CARD FOR DETECTED SECRET │
234
+ ├──────────────────────────────────────────────────────────────────────────────────┤
235
+ │ Category : Private Key (SSH / RSA / ECC) │
236
+ │ Severity : CRITICAL │
237
+ │ AI Tool : Claude Code │
238
+ │ Origin Project : ~ │
239
+ │ Session Date : 2026-08-20 14:06 │
240
+ │ Location : 20b45f26-98f1-4273-a834-32243f11d067.jsonl:23 │
241
+ │ Context : Tool output execution (bash command, .env, or infisical output)│
242
+ ├──────────────────────────────────────────────────────────────────────────────────┤
243
+ │ PLAIN VALUE : -----BEGIN OPENSSH PRIVATE KEY----- │
244
+ ├──────────────────────────────────────────────────────────────────────────────────┤
245
+ │ Log Excerpt : │ SECRET NAME │ SECRET VALUE │
246
+ ├──────────────────────────────────────────────────────────────────────────────────┤
247
+ │ Recommended : 1. Rotate the compromised key or token immediately. │
248
+ │ Action : 2. Redact this log entry with [C] to erase residual traces. │
249
+ ╰──────────────────────────────────────────────────────────────────────────────────╯
250
+
251
+ [C] Redact this secret │ [Esc] or [Q] Return to list
252
+ ```
253
+
254
+ ### 4. Real-Time Scan Spinner & Progress Gauge
255
+
256
+ During scans, redactions, or reports generation, an animated 100ms spinner displays current scan phase and progress percentage:
257
+
258
+ ```text
259
+ ◈ AISCOUT v2.3.0 │ User : dev_redious │ Host : linux-workstation 12/09/2026 22:30
260
+
261
+ █████╗ ██╗ ███████╗ ██████╗ ██████╗ ██╗ ██╗████████╗
262
+ ██╔══██╗██║ ██╔════╝██╔════╝██╔═══██╗██║ ██║╚══██╔══╝
263
+ ███████║██║ ███████╗██║ ██║ ██║██║ ██║ ██║
264
+ ██╔══██║██║ ╚════██║██║ ██║ ██║██║ ██║ ██║
265
+ ██║ ██║██║ ███████║╚██████╗╚██████╔╝╚██████╔╝ ██║
266
+ ╚═╝ ╚═╝╚═╝ ╚══════╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚═╝
267
+
268
+ ⚡ SECURITY SCAN IN PROGRESS...
269
+
270
+ ╭──────────────────────────────────────────────────────────────────╮
271
+ │ ⠹ [▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▱▱▱▱▱▱▱▱▱▱▱] 58% │
272
+ │ Scanning : Infisical / Coolify Token │
273
+ ╰──────────────────────────────────────────────────────────────────╯
274
+
275
+ Please wait while inspecting session histories...
276
+ ```
277
+
278
+ ### 🌟 TUI Engine Strengths
279
+ * **Robust Arrow Key Decoder**: Non-blocking input decoder with 100ms lookahead absorbing all ANSI escape variants (`\x1b[A`, `\x1b[B`, `\x1bOA`, `\x1bOB`, Linux console, Shift/Ctrl modifiers).
280
+ * **Auto-Adaptive Layout**:
281
+ * Fixed top bar at **line 1**.
282
+ * Fixed bottom status bar at **last terminal line**.
283
+ * Height ≥ 42: Double-bordered full-width menu cards (`╔══════╗`).
284
+ * Height 27–41: Compact highlighted bar buttons with contextual explanation box.
285
+ * Height < 27: Ultra-dense header ensuring all actions remain accessible.
286
+ * **Unicode Width Precision**: Incorporates character width metrics (`unicodedata.east_asian_width`) to guarantee pixel-perfect vertical border alignment with multi-byte emojis.
287
+
288
+ ---
289
+
290
+ ## 📡 Real-Time Watchdog & Desktop Notifications
291
+
292
+ The **Watchdog** mode turns `aiscout` into a background sentinel:
293
+
294
+ ```text
295
+ ◈ AISCOUT v2.3.0 │ User : dev_redious │ Host : linux-workstation 12/09/2026 22:21
296
+
297
+ 📡 REAL-TIME MONITORING (WATCHDOG) │ 🟢 [ACTIVE SENTINEL]
298
+ Detects active AI sessions writing to disk and sends instant desktop alerts
299
+
300
+ ╭──────────────────────────────────────────────────────────────────────────────╮
301
+ │ Monitored Files : 5498 │ Live Scans : 14 │ Alerts Triggered : 0 │
302
+ ╰──────────────────────────────────────────────────────────────────────────────╯
303
+
304
+ ╭─ 📜 ROLLING EVENT LOG (14 events) ───────────────────────────────────────────╮
305
+ │ [22:20:10] 🚀 Sentinel started — 5498 AI history files monitored │
306
+ │ [22:20:45] ℹ️ Verified clean modification: history.jsonl │
307
+ │ [22:21:02] ⚠️ ALERT : GitHub Token (CRITICAL) in Claude Code (~/AppProject) │
308
+ ╰──────────────────────────────────────────────────────────────────────────────╯
309
+
310
+ [Q] or [Esc] Stop monitoring and return to main menu
311
+ ```
312
+
313
+ ### How it Works
314
+ 1. **Lightweight Polling**: Inspects filesystem modification timestamps (`mtime`) across AI log directories without expensive full disk scans.
315
+ 2. **Targeted Scan**: Upon detecting a modified or newly created file, only that specific file is scanned on the fly via `scan_single_file()`.
316
+ 3. **Native Desktop Alerts**: Triggers `notify-send` with `critical` urgency on Linux desktop environments (KDE Plasma Wayland, GNOME).
317
+ 4. **Audible Alert**: Fires terminal bell sound (`\a`) on critical secret detections.
318
+
319
+ ---
320
+
321
+ ## ↩️ Backup & Restore Manager (`Safe Restore`)
322
+
323
+ TUI Menu `[7]` provides complete control over backup files created prior to sanitization:
324
+
325
+ ```text
326
+ ◈ AISCOUT v2.3.0 │ User : dev_redious │ Host : linux-workstation 12/09/2026 22:22
327
+
328
+ ↩️ SAFE RESTORE & BACKUP MANAGER (.BAK)
329
+ Restore original files before redaction or purge stale backup copies.
330
+
331
+ # │ SOURCE FILE │ AI TOOL │ SIZE │ BACKUP DATE
332
+ ──────────────────────────────────────────────────────────────────────────────────────────
333
+ 1 │ 20b45f26-98f1-4273-a834...jsonl │ Claude Code │ 412.3 KB │ 12/09/2026 22:15
334
+ 2 │ history.jsonl │ Antigravity (Gemini) │ 84.1 KB │ 12/09/2026 21:50
335
+ ──────────────────────────────────────────────────────────────────────────────────────────
336
+
337
+ [↑/↓] Navigate │ [R] Restore selected │ [A] Restore all │ [P] Purge (.bak) │ [Esc] Back
338
+ ```
339
+
340
+ * **`[R]` Restore selected file**: Replaces the sanitized file with its pre-redaction copy and deletes the `.bak`.
341
+ * **`[A]` Restore all**: Restores all detected backups across all projects in a single confirmed action.
342
+ * **`[P]` Purge backups**: Permanently deletes all `.bak` files to finalize sanitization and free disk space.
343
+
344
+ ---
345
+
346
+ ## 📁 Audited AI Ecosystems
347
+
348
+ `aiscout` automatically scans history paths across your workstation:
349
+
350
+ | AI Coding Assistant | Monitored Paths | File Types |
351
+ | :--- | :--- | :--- |
352
+ | **Claude Code** | `~/.claude/projects/`, `~/.claude/history.jsonl`, `~/.claude/handoff/` | `JSONL`, `JSON` |
353
+ | **Google Antigravity / Gemini CLI** | `~/.gemini/antigravity-cli/brain/`, `~/.gemini/antigravity-cli/history.jsonl`, `conversations/` | `JSONL`, `JSON` |
354
+ | **OpenAI Codex CLI** | `~/.codex/sessions/`, `~/.codex/history.jsonl` | `JSONL`, `JSON` |
355
+ | **GitHub Copilot CLI** | `~/.copilot/session-state/` | `JSON`, `LOG` |
356
+ | **Cursor & Aider** | `~/.cursor/projects/`, `~/.cursor/plans/`, `.aider.chat.history.md` | `JSON`, `MD` |
357
+
358
+ ---
359
+
360
+ ## 🛡️ Detection Engine & Signatures (18 built-in + Custom)
361
+
362
+ | Category | Severity | Detection Pattern Signature |
363
+ | :--- | :---: | :--- |
364
+ | **GitHub Token (PAT / Fine-Grained)** | 🔴 **CRITICAL** | `ghp_[A-Za-z0-9]{36}`, `github_pat_[A-Za-z0-9_]{82}` |
365
+ | **GitLab Personal Access Token** *(New)* | 🔴 **CRITICAL** | `glpat-[0-9a-zA-Z_\-]{20,}` |
366
+ | **HuggingFace Token** *(New)* | 🔴 **CRITICAL** | `hf_[a-zA-Z0-9]{34,}` |
367
+ | **Private Key (SSH / RSA / ECC / PEM)** | 🔴 **CRITICAL** | `-----BEGIN (?:OPENSSH|RSA|EC) PRIVATE KEY-----` |
368
+ | **Stripe Secret Key** | 🔴 **CRITICAL** | `sk_live_[0-9a-zA-Z]{24,}`, `rk_live_[0-9a-zA-Z]{24,}` |
369
+ | **Database URI (with Credentials)** | 🔴 **CRITICAL** | `postgres://user:password@host`, `mysql://...`, `mongodb://...` |
370
+ | **Infisical / Coolify Token** | 🔴 **CRITICAL** | `st.[a-f0-9]{24}.[a-f0-9]{64}`, `inf_sec_...`, `inf_tok_...` |
371
+ | **Resend API Key** *(New)* | 🟡 **HIGH** | `re_[a-zA-Z0-9_\-]{24,}` |
372
+ | **Supabase / JWT Secret** *(New)* | 🟡 **HIGH** | `eyJ[a-zA-Z0-9_-]{10,}\.eyJ...` |
373
+ | **Anthropic API Key** | 🟡 **HIGH** | `sk-ant-api03-[A-Za-z0-9_-]{30,}` |
374
+ | **OpenAI API Key** | 🟡 **HIGH** | `sk-proj-[A-Za-z0-9_-]{32,}` |
375
+ | **AWS Access Key** | 🟡 **HIGH** | `AKIA[0-9A-Z]{16}`, `ASIA[0-9A-Z]{16}` |
376
+ | **Discord Bot Token** | 🟡 **HIGH** | `[MN][A-Za-z\d]{23,25}\.[a-zA-Z0-9_-]{6}\.[a-zA-Z0-9_-]{27,39}` |
377
+ | **Slack Token** | 🟡 **HIGH** | `xox[baprs]-[0-9a-zA-Z]{10,48}` |
378
+ | **Tailscale Auth Key** | 🟡 **HIGH** | `tskey-auth-[a-zA-Z0-9_-]{20,}` |
379
+ | **Sensitive Environment Variable** | 🟡 **HIGH** | `PGPASSWORD=...`, `MYSQL_PWD=...`, `API_KEY=...` |
380
+ | **Password in Chat Prompt** | 🟡 **HIGH** | `"my password is ..."`, `"pwd: ..."` |
381
+ | **Password passed via CLI Command** | 🔵 **MEDIUM** | `sshpass -p ...`, `mysql -p...`, `--password ...` |
382
+
383
+ ---
384
+
385
+ ## ⚙️ Custom Rules Configuration (`rules.json`)
386
+
387
+ You can define custom, organization-specific secret patterns in:
388
+ `~/.config/aiscout/rules.json`
389
+
390
+ ```json
391
+ {
392
+ "_comment": "Add your custom detection rules here. Format: Rule Name: {regex, severity, description}",
393
+ "Internal Corporate Token": {
394
+ "regex": "\\bcorp_sec_[a-zA-Z0-9]{24,}\\b",
395
+ "severity": "CRITICAL",
396
+ "description": "Internal secret token granting access to corporate services."
397
+ },
398
+ "Partner API Key": {
399
+ "regex": "\\bpartner_live_[a-z0-9]{32}\\b",
400
+ "severity": "HIGH",
401
+ "description": "B2B partner API authentication key."
402
+ }
403
+ }
404
+ ```
405
+
406
+ All custom rules are automatically tagged with a `[CUSTOM]` badge and incorporated into scans, the watchdog, and the interactive TUI table.
407
+
408
+ ---
409
+
410
+ ## 🧠 Anti-False-Positive Heuristics
411
+
412
+ To avoid noisy alerts and false positives, `aiscout` runs 5 mathematical filters:
413
+
414
+ 1. **Shannon Entropy Calculation ($H$)**:
415
+ $$H(X) = -\sum_{i=1}^n P(x_i) \log_2 P(x_i)$$
416
+ Strings with low entropy (< 3.2 bits/symbol) are automatically discarded.
417
+ 2. **Character Class Diversity**:
418
+ Random tokens must combine at least 3 distinct character classes (lowercase, uppercase, digits, symbols).
419
+ 3. **Contextual Placeholder Blacklist**:
420
+ Explicit exclusion of documentation examples: `your_token`, `dummy`, `example`, `change_me`, `sk-ant-xxx`, etc.
421
+ 4. **Cryptographic Block Verification for Private Keys**:
422
+ Isolated string mentions are ignored; only complete key blocks containing headers, body, and footers (`-----END ...`) are reported.
423
+ 5. **Mirror Anti-Self-Detection Shield**:
424
+ `aiscout` ignores its own regex signatures, binary scripts, and previously redacted tags (`[REDACTED_BY_AISCOUT]`).
425
+
426
+ ---
427
+
428
+ ## 🛡️ Safe Sanitization & Redaction (`Safe Redact`)
429
+
430
+ * **Targeted Surgical Redaction (`[C]`)**: In-place replacement of a single compromised secret with `[REDACTED_BY_AISCOUT]`.
431
+ * **Global Redaction (`[6]`)**: One-click sanitization of all detected compromised sessions.
432
+ * **Guaranteed `.bak` Backups**: An exact copy is saved prior to any file modification.
433
+ * **Safe Restore Integration**: Every redaction can be undone on demand from the `[7]` backup screen.
434
+
435
+ ---
436
+
437
+ ## 🕹️ Keyboard Shortcuts & Controls
438
+
439
+ ### Main Dashboard Hub
440
+ | Key | Action |
441
+ | :--- | :--- |
442
+ | `↑` / `↓` or `k` / `j` | Move selection cursor |
443
+ | `Enter` / `Space` / `→` | Execute highlighted action |
444
+ | `1` to `9` | Direct numeric menu jump |
445
+ | `Q` or `Ctrl+C` | Clean exit |
446
+
447
+ ### Secret Explorer (TUI Table)
448
+ | Key | Action |
449
+ | :--- | :--- |
450
+ | `↑` / `↓` or `k` / `j` | Navigate row by row |
451
+ | `PageUp` / `PageDown` | Scroll by full page |
452
+ | `Enter` | Open **detailed audit card** |
453
+ | `/` | **Interactive live search** (category, tool, project, path, value) |
454
+ | `S` | **Sort by severity** (`🔴 CRITICAL` > `🟡 HIGH` > `🔵 MEDIUM`) |
455
+ | `D` | **Sort by date** (most recent sessions first) |
456
+ | `O` | **Sort by AI tool** (alphabetical) |
457
+ | `Backspace` / `Esc` | Clear active search query |
458
+ | `R` | Toggle **Masked** (`ghp_****...`) vs **Plain-Text** |
459
+ | `C` | Surgically redact the highlighted secret |
460
+ | `Q` or `Esc` | Return to main dashboard |
461
+
462
+ ### Backup Manager (`Safe Restore`) & Watchdog
463
+ | Key | Action |
464
+ | :--- | :--- |
465
+ | `R` *(Backups)* | Restore selected `.bak` file |
466
+ | `A` *(Backups)* | Restore all original backup files |
467
+ | `P` *(Backups)* | Permanently purge all `.bak` copies |
468
+ | `Q` or `Esc` | Exit screen and return to dashboard |
469
+
470
+ ---
471
+
472
+ ## ⚙️ Scripting / CLI Mode & Automation
473
+
474
+ ```bash
475
+ # Run headless terminal scan
476
+ aiscout --scan
477
+
478
+ # Launch real-time background watchdog with desktop notifications
479
+ aiscout --watch
480
+
481
+ # Restore all original files from .bak backups
482
+ aiscout --restore
483
+
484
+ # Permanently purge all backup files
485
+ aiscout --clean-backups
486
+
487
+ # List all 18 active rules plus user custom rules
488
+ aiscout --list-rules
489
+
490
+ # Print plain-text unmasked secrets
491
+ aiscout --reveal
492
+
493
+ # Output raw JSON stream for automated CI/CD pipelines
494
+ aiscout --json | jq '.[] | select(.severity == "CRITICAL")'
495
+
496
+ # Export report directly to Markdown or JSON file
497
+ aiscout --export ~/Documents/audit_secrets.md
498
+ aiscout --export ~/Documents/audit_secrets.json
499
+
500
+ # Scan a custom user home directory
501
+ aiscout --home-dir /home/other_user
502
+ ```
503
+
504
+ ---
505
+
506
+ ## 🏗️ Technical Architecture
507
+
508
+ * **Core Engine**: Pure Python 3.10+ standard library (`os`, `sys`, `re`, `json`, `termios`, `tty`, `select`, `unicodedata`, `shutil`, `argparse`, `subprocess`).
509
+ * **Zero External Dependencies**: Zero `pip` dependencies required.
510
+ * **Supported Platforms**: **Linux** (native Wayland / X11) and **WSL / WSL2** on Windows (macOS and native Windows not supported).
511
+ * **Notification System**: Auto-detects `notify-send` for native desktop banners on Wayland & X11.
512
+ * **Configuration Path**: `~/.config/aiscout/rules.json`
513
+ * **Zero Telemetry**: 100% local execution, zero outbound network traffic, complete privacy guarantee.
514
+
515
+ ---
516
+
517
+ <div align="center">
518
+ <sub>Built with care for the autonomous AI coding era • Released under the MIT License</sub>
519
+ </div>