trident-windows 0.9.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.
Files changed (48) hide show
  1. trident_windows-0.9.1/LICENSE +21 -0
  2. trident_windows-0.9.1/LICENSE-MODEL +21 -0
  3. trident_windows-0.9.1/PKG-INFO +320 -0
  4. trident_windows-0.9.1/README.md +285 -0
  5. trident_windows-0.9.1/pyproject.toml +63 -0
  6. trident_windows-0.9.1/setup.cfg +4 -0
  7. trident_windows-0.9.1/src/trident/__init__.py +2 -0
  8. trident_windows-0.9.1/src/trident/__main__.py +289 -0
  9. trident_windows-0.9.1/src/trident/_daemon.py +89 -0
  10. trident_windows-0.9.1/src/trident/action.py +213 -0
  11. trident_windows-0.9.1/src/trident/audit.py +48 -0
  12. trident_windows-0.9.1/src/trident/cascade.py +165 -0
  13. trident_windows-0.9.1/src/trident/cli.py +436 -0
  14. trident_windows-0.9.1/src/trident/config.py +114 -0
  15. trident_windows-0.9.1/src/trident/contracts.py +55 -0
  16. trident_windows-0.9.1/src/trident/data/icons/trident-danger-preview.png +0 -0
  17. trident_windows-0.9.1/src/trident/data/icons/trident-danger.ico +0 -0
  18. trident_windows-0.9.1/src/trident/data/icons/trident-monitor-preview.png +0 -0
  19. trident_windows-0.9.1/src/trident/data/icons/trident-monitor.ico +0 -0
  20. trident_windows-0.9.1/src/trident/data/icons/trident-safe-preview.png +0 -0
  21. trident_windows-0.9.1/src/trident/data/icons/trident-safe.ico +0 -0
  22. trident_windows-0.9.1/src/trident/data/icons/trident-trust-preview.png +0 -0
  23. trident_windows-0.9.1/src/trident/data/icons/trident-trust.ico +0 -0
  24. trident_windows-0.9.1/src/trident/data/strings.json +112 -0
  25. trident_windows-0.9.1/src/trident/data/trident.toml +56 -0
  26. trident_windows-0.9.1/src/trident/decision.py +299 -0
  27. trident_windows-0.9.1/src/trident/mode.py +64 -0
  28. trident_windows-0.9.1/src/trident/models.py +131 -0
  29. trident_windows-0.9.1/src/trident/paths.py +37 -0
  30. trident_windows-0.9.1/src/trident/report.py +212 -0
  31. trident_windows-0.9.1/src/trident/runtime.py +99 -0
  32. trident_windows-0.9.1/src/trident/setup/__init__.py +1 -0
  33. trident_windows-0.9.1/src/trident/setup/download_model.py +61 -0
  34. trident_windows-0.9.1/src/trident/system_defaults.py +79 -0
  35. trident_windows-0.9.1/src/trident/telemetry.py +192 -0
  36. trident_windows-0.9.1/src/trident/toast.py +125 -0
  37. trident_windows-0.9.1/src/trident/trust_store.py +105 -0
  38. trident_windows-0.9.1/src/trident/ui.py +145 -0
  39. trident_windows-0.9.1/src/trident/uri_handler.py +107 -0
  40. trident_windows-0.9.1/src/trident_windows.egg-info/PKG-INFO +320 -0
  41. trident_windows-0.9.1/src/trident_windows.egg-info/SOURCES.txt +46 -0
  42. trident_windows-0.9.1/src/trident_windows.egg-info/dependency_links.txt +1 -0
  43. trident_windows-0.9.1/src/trident_windows.egg-info/entry_points.txt +2 -0
  44. trident_windows-0.9.1/src/trident_windows.egg-info/requires.txt +8 -0
  45. trident_windows-0.9.1/src/trident_windows.egg-info/top_level.txt +1 -0
  46. trident_windows-0.9.1/tests/test_cascade.py +82 -0
  47. trident_windows-0.9.1/tests/test_contracts.py +62 -0
  48. trident_windows-0.9.1/tests/test_decision.py +84 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Aalok Singh, Pravinkumar Yadav
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.
@@ -0,0 +1,21 @@
1
+ The TRIDENT fine-tuned Laya model ("trident-laya-process-security-v1")
2
+ is a derivative work of the Laya multilingual checkpoint by ConvAI
3
+ Innovations (https://huggingface.co/convaiinnovations/laya-multilingual),
4
+ which is released under the Apache License, Version 2.0.
5
+
6
+ Accordingly, the TRIDENT fine-tuned model weights are distributed under
7
+ the Apache License, Version 2.0.
8
+
9
+ You may obtain a copy of the License at:
10
+
11
+ http://www.apache.org/licenses/LICENSE-2.0
12
+
13
+ Unless required by applicable law or agreed to in writing, software
14
+ distributed under the License is distributed on an "AS IS" BASIS,
15
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16
+ See the License for the specific language governing permissions and
17
+ limitations under the License.
18
+
19
+ The TRIDENT source code (all files under trident/, tests/, scripts/, and
20
+ the top-level Python files) is separately licensed under the MIT License.
21
+ See the LICENSE file in the repository root.
@@ -0,0 +1,320 @@
1
+ Metadata-Version: 2.4
2
+ Name: trident-windows
3
+ Version: 0.9.1
4
+ Summary: Local AI process security for Windows
5
+ Author: Aalok Singh, Pravinkumar Yadav
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/aalok101singh/trident
8
+ Project-URL: Model, https://huggingface.co/aalok101singh/trident-v1
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Environment :: Win32 (MS Windows)
11
+ Classifier: Intended Audience :: End Users/Desktop
12
+ Classifier: Operating System :: Microsoft :: Windows
13
+ Classifier: Operating System :: Microsoft :: Windows :: Windows 10
14
+ Classifier: Operating System :: Microsoft :: Windows :: Windows 11
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Topic :: Security
21
+ Classifier: Topic :: System :: Monitoring
22
+ Requires-Python: >=3.11
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ License-File: LICENSE-MODEL
26
+ Requires-Dist: psutil>=5.9
27
+ Requires-Dist: numpy>=1.26
28
+ Requires-Dist: onnxruntime>=1.31
29
+ Requires-Dist: transformers>=4.40
30
+ Requires-Dist: pydantic>=2.0
31
+ Requires-Dist: winotify>=1.1
32
+ Requires-Dist: huggingface_hub>=0.20
33
+ Requires-Dist: laya>=0.4.1
34
+ Dynamic: license-file
35
+
36
+ # TRIDENT
37
+
38
+ **The AI-powered immune layer for Windows.**
39
+
40
+ Watch. Judge. Act.
41
+
42
+ [![PyPI - Version](https://img.shields.io/pypi/v/trident-windows?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/trident-windows/)
43
+ [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/trident-windows?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/trident-windows/)
44
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
45
+ [![Platform: Windows](https://img.shields.io/badge/platform-Windows-0078D6?style=flat-square&logo=windows&logoColor=white)](https://github.com/aalok101singh/trident)
46
+ [![GitHub stars](https://img.shields.io/github/stars/aalok101singh/trident?style=social)](https://github.com/aalok101singh/trident/stargazers)
47
+
48
+ TRIDENT is a background security tool that watches every process starting on your Windows machine, scores it with a small AI model running locally on your CPU, and routes the decision through a three-tier confidence cascade before anything gets terminated.
49
+
50
+ **No cloud. No kernel driver. No signature database.** Just a fine-tuned transformer and a strict policy layer that refuses to let the model act alone.
51
+
52
+ ---
53
+
54
+ ## ๐Ÿค” What Is This, Really?
55
+
56
+ Every time you open an app, run a script, or something silently launches in the background, Windows creates a **new process**. TRIDENT sees that happen, asks a local AI model two questions โ€” *should we allow this or kill it?* and *how much should we trust it?* โ€” and then decides what to do.
57
+
58
+ Three possible outcomes:
59
+
60
+ 1. **Kill it silently** โ€” the model is very confident it's malicious, and the file isn't in a Windows system folder.
61
+ 2. **Watch it** โ€” the model is uncertain, so TRIDENT keeps an eye on it.
62
+ 3. **Ask you** โ€” the model is suspicious but not sure, so you get a native Windows notification asking what to do.
63
+
64
+ The AI is **never allowed to act alone**. Every kill decision passes through a safety cascade first. If the process is Windows' own `lsass.exe` or `powershell.exe`, the cascade refuses โ€” even if the model says kill. **That is the entire point of TRIDENT.**
65
+
66
+ ---
67
+
68
+ ## ๐Ÿš€ Install & Run
69
+
70
+ You need **Python 3.11 or newer** and **Windows 10 (1809+) or Windows 11**. That's it. No admin, no installer, no reboot.
71
+
72
+ Open PowerShell and run these three commands:
73
+
74
+ ```powershell
75
+ pip install trident-windows
76
+ trident models fetch
77
+ trident start
78
+ ```
79
+
80
+ | Command | What happens |
81
+ | :--- | :--- |
82
+ | `pip install trident-windows` | Installs TRIDENT and its dependencies. Takes ~2 minutes. |
83
+ | `trident models fetch` | Downloads the 280 MB AI model from Hugging Face to `%LOCALAPPDATA%\TRIDENT\models\`. Takes 2โ€“10 minutes depending on your connection. One-time. |
84
+ | `trident start` | Runs a first-time welcome message, registers TRIDENT to launch at logon, and starts the background daemon. |
85
+
86
+ **After `trident start` returns, you can close every terminal.** TRIDENT keeps running in the background. It survives closing the window, logging off, and rebooting.
87
+
88
+ ---
89
+
90
+ ## ๐Ÿ›ก๏ธ It Starts In Safe Mode
91
+
92
+ When you run `trident start` for the very first time, you'll see this:
93
+
94
+ ```
95
+ Welcome to TRIDENT.
96
+
97
+ TRIDENT watches every process on your machine and scores it
98
+ with a local AI model. In enforce mode, it can terminate
99
+ processes it thinks are malicious.
100
+
101
+ Kill mode is DISABLED by default. TRIDENT will run in dry-run
102
+ mode and record what it would have done. Review with:
103
+
104
+ trident logs --tail 50
105
+
106
+ Enable enforcement later with:
107
+
108
+ trident config --mode enforce
109
+
110
+ [Enter] to continue in dry-run mode
111
+ [q] to cancel
112
+ ```
113
+
114
+ **Press Enter.** TRIDENT starts in **dry-run mode**. It scores every process, writes every decision to a log file, but **kills nothing**. You can watch what it *would* have done for as long as you want.
115
+
116
+ When you're ready to let it actually enforce:
117
+
118
+ ```powershell
119
+ trident config --mode enforce
120
+ ```
121
+
122
+ The change takes effect immediately โ€” no restart needed.
123
+
124
+ ---
125
+
126
+ ## ๐Ÿง  How It Actually Works
127
+
128
+ ```text
129
+ New process starts on Windows
130
+ โ”‚
131
+ โ–ผ
132
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
133
+ โ”‚ Layer 1 โ€” Telemetry โ”‚
134
+ โ”‚ Polls every 500 ms. โ”‚
135
+ โ”‚ Two-pass: cheap scan of all โ”‚
136
+ โ”‚ PIDs, detailed scan only โ”‚
137
+ โ”‚ for genuinely new ones. โ”‚
138
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
139
+ โ”‚
140
+ โ–ผ
141
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
142
+ โ”‚ Layer 2 โ€” Decision Kernel โ”‚
143
+ โ”‚ Fine-tuned AI model. โ”‚
144
+ โ”‚ Runs on CPU. ~150 ms. โ”‚
145
+ โ”‚ Answers two questions per โ”‚
146
+ โ”‚ process: action + trust. โ”‚
147
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
148
+ โ”‚
149
+ โ–ผ
150
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
151
+ โ”‚ Layer 3 โ€” Cascade โ”‚
152
+ โ”‚ Refuses to let the model โ”‚
153
+ โ”‚ act alone. Three gates. โ”‚
154
+ โ”‚ Then: kill, monitor, or ask. โ”‚
155
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
156
+ ```
157
+
158
+ **The three safety gates:**
159
+
160
+ 1. **Confidence gate** โ€” the model must be at least 92% confident to auto-kill.
161
+ 2. **Critical path gate** โ€” anything inside `C:\Windows\System32`, `SysWOW64`, `WinSxS`, `Program Files\Windows Defender`, or `WindowsApps` is **never** auto-killed. It always goes to human review.
162
+ 3. **Trust gate** โ€” paths you have explicitly trusted are still scored, still logged, but never acted on.
163
+
164
+ If any gate says no, the decision becomes a Windows toast notification instead of a kill.
165
+
166
+ ---
167
+
168
+ ## ๐Ÿ“‹ Every Command
169
+
170
+ ```
171
+ trident start Start the background watcher
172
+ trident stop Stop it gracefully
173
+ trident stop --uninstall Also remove the logon registration
174
+ trident status Is it running? What mode?
175
+ trident logs --tail 50 Show the last 50 decisions
176
+ trident config View or change operating mode
177
+ trident models fetch Download the AI model from Hugging Face
178
+ trident models status Is the model downloaded?
179
+ trident trust <path> Add a path to the allowlist
180
+ trident report <pid> Open a decision report for a specific process
181
+ trident version Print version
182
+ ```
183
+
184
+ ---
185
+
186
+ ## ๐Ÿ”„ Three Modes
187
+
188
+ | Mode | Kills? | Sends Toasts? | Logs? | When to Use |
189
+ | :--- | :---: | :---: | :---: | :--- |
190
+ | `dry-run` | No | No | Yes | **Default for the first 24 hours** |
191
+ | `monitor` | No | Yes | Yes | After you've reviewed the log |
192
+ | `enforce` | Yes | Yes | Yes | When you trust the pipeline |
193
+
194
+ Switch modes at any time:
195
+
196
+ ```powershell
197
+ trident config --mode monitor
198
+ ```
199
+
200
+ The daemon picks up the change on its next polling tick. No restart.
201
+
202
+ ---
203
+
204
+ ## ๐Ÿ“Š Performance
205
+
206
+ Measured on a modern i7 dev machine:
207
+
208
+ | | Idle | Per New Process |
209
+ | :--- | :--- | :--- |
210
+ | **Memory** | ~495 MB | ~495 MB |
211
+ | **CPU** | 0.2% | ~8% (one core, ~150 ms) |
212
+
213
+ Expected on the reference target โ€” a 2-core i3-8100 with 4 GB RAM โ€” is the same memory footprint with 250โ€“400 ms per decision.
214
+
215
+ The 495 MB is 55% the AI model weights, memory-mapped from disk. Post-1.0 work includes int8 quantization, which should cut that down to roughly 70 MB.
216
+
217
+ ---
218
+
219
+ ## ๐Ÿงญ Where Everything Lives
220
+
221
+ All user data is scoped to one directory:
222
+
223
+ ```
224
+ %LOCALAPPDATA%\TRIDENT\
225
+ โ”œโ”€โ”€ config\ Your editable trident.toml + trusted_paths.json
226
+ โ”œโ”€โ”€ logs\ Daily decision logs (JSONL, one line per decision)
227
+ โ”œโ”€โ”€ models\ ONNX graph, weights, tokenizer
228
+ โ”œโ”€โ”€ cleanup-scripts\ Generated review-only PowerShell scripts
229
+ โ””โ”€โ”€ runtime\ daemon.pid, daemon.log, stop signal
230
+ ```
231
+
232
+ The audit log is append-only JSONL. Easy to grep, easy to `jq`, easy to feed into a future training pass.
233
+
234
+ ---
235
+
236
+ ## โŒ What It Does NOT Do
237
+
238
+ Honesty is important for a security tool. TRIDENT is **not**:
239
+
240
+ - **An antivirus.** It doesn't scan files on disk.
241
+ - **A firewall.** No network inspection, no outbound filtering.
242
+ - **A behavioral monitor.** It sees process *starts*, not what a running process does afterward. DLL injection, fileless attacks, and memory-resident malware are outside its scope.
243
+ - **A kernel-level defense.** User-mode only. A privileged attacker can bypass it. That's true of every user-mode security tool.
244
+
245
+ What it **does**: closes the gap between "no AI process layer" and "a small local model watching every process start." That's a real gap on a consumer Windows machine.
246
+
247
+ ---
248
+
249
+ ## ๐Ÿงน Uninstall Cleanly
250
+
251
+ ```powershell
252
+ trident stop --uninstall
253
+ pip uninstall trident-windows
254
+ Remove-Item "$env:LOCALAPPDATA\TRIDENT" -Recurse -Force
255
+ ```
256
+
257
+ The first command stops the daemon and removes the logon registration. The second uninstalls the Python package. The third deletes the user data (model, logs, config). No registry keys left behind except the `trident:` URI protocol โ€” remove it manually with `reg delete "HKCU\Software\Classes\trident" /f` if you want a truly clean slate.
258
+
259
+ ---
260
+
261
+ ## ๐Ÿ› ๏ธ For Developers
262
+
263
+ ```powershell
264
+ git clone https://github.com/aalok101singh/trident
265
+ cd trident
266
+ py -m venv .venv
267
+ .\.venv\Scripts\Activate.ps1
268
+ pip install -e .
269
+ trident models fetch
270
+ trident start
271
+ ```
272
+
273
+ Run the test suite:
274
+
275
+ ```powershell
276
+ pytest tests/
277
+ ```
278
+
279
+ Build a wheel:
280
+
281
+ ```powershell
282
+ pip install build
283
+ python -m build --wheel
284
+ ```
285
+
286
+ The wheel ends up in `dist\`. Install it in a fresh venv to verify.
287
+
288
+ ---
289
+
290
+ ## ๐Ÿงช Status
291
+
292
+ `v0.9.1` โ€” beta. Tested on Windows 10 and Windows 11 with Python 3.11 through 3.14.
293
+
294
+ Known limitations at this version:
295
+
296
+ - The model over-flags `powershell.exe` launches. Every one fires an escalation toast unless you trust the path.
297
+ - Unsigned executables in user-writable directories (Downloads, `%TEMP%`) are often flagged.
298
+ - Some developer tools (`python.exe`, `node.exe`, `cargo` binaries in user paths) get flagged at Tier 1 in enforce mode. A developer-path allowlist is planned for 0.10.
299
+ - Model confidence is not temperature-calibrated, so raw confidences are over-confident. The threat score uses the softmax margin to compensate.
300
+
301
+ Tracked at [github.com/aalok101singh/trident/issues](https://github.com/aalok101singh/trident/issues).
302
+
303
+ ---
304
+
305
+ ## ๐Ÿ“„ License
306
+
307
+ - **Code:** MIT โ€” see [LICENSE](LICENSE).
308
+ - **Model:** Apache 2.0 โ€” see [LICENSE-MODEL](LICENSE-MODEL).
309
+
310
+ ---
311
+
312
+ ## ๐Ÿ”— Links
313
+
314
+ - **GitHub:** [github.com/aalok101singh/trident](https://github.com/aalok101singh/trident)
315
+ - **PyPI:** [pypi.org/project/trident-windows](https://pypi.org/project/trident-windows/)
316
+ - **Model:** [huggingface.co/aalok101singh/trident-v1](https://huggingface.co/aalok101singh/trident-v1)
317
+
318
+ ---
319
+
320
+ *Watch. Judge. Act. Three prongs, one shaft. The shaft is the cascade.*
@@ -0,0 +1,285 @@
1
+ # TRIDENT
2
+
3
+ **The AI-powered immune layer for Windows.**
4
+
5
+ Watch. Judge. Act.
6
+
7
+ [![PyPI - Version](https://img.shields.io/pypi/v/trident-windows?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/trident-windows/)
8
+ [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/trident-windows?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/trident-windows/)
9
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
10
+ [![Platform: Windows](https://img.shields.io/badge/platform-Windows-0078D6?style=flat-square&logo=windows&logoColor=white)](https://github.com/aalok101singh/trident)
11
+ [![GitHub stars](https://img.shields.io/github/stars/aalok101singh/trident?style=social)](https://github.com/aalok101singh/trident/stargazers)
12
+
13
+ TRIDENT is a background security tool that watches every process starting on your Windows machine, scores it with a small AI model running locally on your CPU, and routes the decision through a three-tier confidence cascade before anything gets terminated.
14
+
15
+ **No cloud. No kernel driver. No signature database.** Just a fine-tuned transformer and a strict policy layer that refuses to let the model act alone.
16
+
17
+ ---
18
+
19
+ ## ๐Ÿค” What Is This, Really?
20
+
21
+ Every time you open an app, run a script, or something silently launches in the background, Windows creates a **new process**. TRIDENT sees that happen, asks a local AI model two questions โ€” *should we allow this or kill it?* and *how much should we trust it?* โ€” and then decides what to do.
22
+
23
+ Three possible outcomes:
24
+
25
+ 1. **Kill it silently** โ€” the model is very confident it's malicious, and the file isn't in a Windows system folder.
26
+ 2. **Watch it** โ€” the model is uncertain, so TRIDENT keeps an eye on it.
27
+ 3. **Ask you** โ€” the model is suspicious but not sure, so you get a native Windows notification asking what to do.
28
+
29
+ The AI is **never allowed to act alone**. Every kill decision passes through a safety cascade first. If the process is Windows' own `lsass.exe` or `powershell.exe`, the cascade refuses โ€” even if the model says kill. **That is the entire point of TRIDENT.**
30
+
31
+ ---
32
+
33
+ ## ๐Ÿš€ Install & Run
34
+
35
+ You need **Python 3.11 or newer** and **Windows 10 (1809+) or Windows 11**. That's it. No admin, no installer, no reboot.
36
+
37
+ Open PowerShell and run these three commands:
38
+
39
+ ```powershell
40
+ pip install trident-windows
41
+ trident models fetch
42
+ trident start
43
+ ```
44
+
45
+ | Command | What happens |
46
+ | :--- | :--- |
47
+ | `pip install trident-windows` | Installs TRIDENT and its dependencies. Takes ~2 minutes. |
48
+ | `trident models fetch` | Downloads the 280 MB AI model from Hugging Face to `%LOCALAPPDATA%\TRIDENT\models\`. Takes 2โ€“10 minutes depending on your connection. One-time. |
49
+ | `trident start` | Runs a first-time welcome message, registers TRIDENT to launch at logon, and starts the background daemon. |
50
+
51
+ **After `trident start` returns, you can close every terminal.** TRIDENT keeps running in the background. It survives closing the window, logging off, and rebooting.
52
+
53
+ ---
54
+
55
+ ## ๐Ÿ›ก๏ธ It Starts In Safe Mode
56
+
57
+ When you run `trident start` for the very first time, you'll see this:
58
+
59
+ ```
60
+ Welcome to TRIDENT.
61
+
62
+ TRIDENT watches every process on your machine and scores it
63
+ with a local AI model. In enforce mode, it can terminate
64
+ processes it thinks are malicious.
65
+
66
+ Kill mode is DISABLED by default. TRIDENT will run in dry-run
67
+ mode and record what it would have done. Review with:
68
+
69
+ trident logs --tail 50
70
+
71
+ Enable enforcement later with:
72
+
73
+ trident config --mode enforce
74
+
75
+ [Enter] to continue in dry-run mode
76
+ [q] to cancel
77
+ ```
78
+
79
+ **Press Enter.** TRIDENT starts in **dry-run mode**. It scores every process, writes every decision to a log file, but **kills nothing**. You can watch what it *would* have done for as long as you want.
80
+
81
+ When you're ready to let it actually enforce:
82
+
83
+ ```powershell
84
+ trident config --mode enforce
85
+ ```
86
+
87
+ The change takes effect immediately โ€” no restart needed.
88
+
89
+ ---
90
+
91
+ ## ๐Ÿง  How It Actually Works
92
+
93
+ ```text
94
+ New process starts on Windows
95
+ โ”‚
96
+ โ–ผ
97
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
98
+ โ”‚ Layer 1 โ€” Telemetry โ”‚
99
+ โ”‚ Polls every 500 ms. โ”‚
100
+ โ”‚ Two-pass: cheap scan of all โ”‚
101
+ โ”‚ PIDs, detailed scan only โ”‚
102
+ โ”‚ for genuinely new ones. โ”‚
103
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
104
+ โ”‚
105
+ โ–ผ
106
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
107
+ โ”‚ Layer 2 โ€” Decision Kernel โ”‚
108
+ โ”‚ Fine-tuned AI model. โ”‚
109
+ โ”‚ Runs on CPU. ~150 ms. โ”‚
110
+ โ”‚ Answers two questions per โ”‚
111
+ โ”‚ process: action + trust. โ”‚
112
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
113
+ โ”‚
114
+ โ–ผ
115
+ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
116
+ โ”‚ Layer 3 โ€” Cascade โ”‚
117
+ โ”‚ Refuses to let the model โ”‚
118
+ โ”‚ act alone. Three gates. โ”‚
119
+ โ”‚ Then: kill, monitor, or ask. โ”‚
120
+ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
121
+ ```
122
+
123
+ **The three safety gates:**
124
+
125
+ 1. **Confidence gate** โ€” the model must be at least 92% confident to auto-kill.
126
+ 2. **Critical path gate** โ€” anything inside `C:\Windows\System32`, `SysWOW64`, `WinSxS`, `Program Files\Windows Defender`, or `WindowsApps` is **never** auto-killed. It always goes to human review.
127
+ 3. **Trust gate** โ€” paths you have explicitly trusted are still scored, still logged, but never acted on.
128
+
129
+ If any gate says no, the decision becomes a Windows toast notification instead of a kill.
130
+
131
+ ---
132
+
133
+ ## ๐Ÿ“‹ Every Command
134
+
135
+ ```
136
+ trident start Start the background watcher
137
+ trident stop Stop it gracefully
138
+ trident stop --uninstall Also remove the logon registration
139
+ trident status Is it running? What mode?
140
+ trident logs --tail 50 Show the last 50 decisions
141
+ trident config View or change operating mode
142
+ trident models fetch Download the AI model from Hugging Face
143
+ trident models status Is the model downloaded?
144
+ trident trust <path> Add a path to the allowlist
145
+ trident report <pid> Open a decision report for a specific process
146
+ trident version Print version
147
+ ```
148
+
149
+ ---
150
+
151
+ ## ๐Ÿ”„ Three Modes
152
+
153
+ | Mode | Kills? | Sends Toasts? | Logs? | When to Use |
154
+ | :--- | :---: | :---: | :---: | :--- |
155
+ | `dry-run` | No | No | Yes | **Default for the first 24 hours** |
156
+ | `monitor` | No | Yes | Yes | After you've reviewed the log |
157
+ | `enforce` | Yes | Yes | Yes | When you trust the pipeline |
158
+
159
+ Switch modes at any time:
160
+
161
+ ```powershell
162
+ trident config --mode monitor
163
+ ```
164
+
165
+ The daemon picks up the change on its next polling tick. No restart.
166
+
167
+ ---
168
+
169
+ ## ๐Ÿ“Š Performance
170
+
171
+ Measured on a modern i7 dev machine:
172
+
173
+ | | Idle | Per New Process |
174
+ | :--- | :--- | :--- |
175
+ | **Memory** | ~495 MB | ~495 MB |
176
+ | **CPU** | 0.2% | ~8% (one core, ~150 ms) |
177
+
178
+ Expected on the reference target โ€” a 2-core i3-8100 with 4 GB RAM โ€” is the same memory footprint with 250โ€“400 ms per decision.
179
+
180
+ The 495 MB is 55% the AI model weights, memory-mapped from disk. Post-1.0 work includes int8 quantization, which should cut that down to roughly 70 MB.
181
+
182
+ ---
183
+
184
+ ## ๐Ÿงญ Where Everything Lives
185
+
186
+ All user data is scoped to one directory:
187
+
188
+ ```
189
+ %LOCALAPPDATA%\TRIDENT\
190
+ โ”œโ”€โ”€ config\ Your editable trident.toml + trusted_paths.json
191
+ โ”œโ”€โ”€ logs\ Daily decision logs (JSONL, one line per decision)
192
+ โ”œโ”€โ”€ models\ ONNX graph, weights, tokenizer
193
+ โ”œโ”€โ”€ cleanup-scripts\ Generated review-only PowerShell scripts
194
+ โ””โ”€โ”€ runtime\ daemon.pid, daemon.log, stop signal
195
+ ```
196
+
197
+ The audit log is append-only JSONL. Easy to grep, easy to `jq`, easy to feed into a future training pass.
198
+
199
+ ---
200
+
201
+ ## โŒ What It Does NOT Do
202
+
203
+ Honesty is important for a security tool. TRIDENT is **not**:
204
+
205
+ - **An antivirus.** It doesn't scan files on disk.
206
+ - **A firewall.** No network inspection, no outbound filtering.
207
+ - **A behavioral monitor.** It sees process *starts*, not what a running process does afterward. DLL injection, fileless attacks, and memory-resident malware are outside its scope.
208
+ - **A kernel-level defense.** User-mode only. A privileged attacker can bypass it. That's true of every user-mode security tool.
209
+
210
+ What it **does**: closes the gap between "no AI process layer" and "a small local model watching every process start." That's a real gap on a consumer Windows machine.
211
+
212
+ ---
213
+
214
+ ## ๐Ÿงน Uninstall Cleanly
215
+
216
+ ```powershell
217
+ trident stop --uninstall
218
+ pip uninstall trident-windows
219
+ Remove-Item "$env:LOCALAPPDATA\TRIDENT" -Recurse -Force
220
+ ```
221
+
222
+ The first command stops the daemon and removes the logon registration. The second uninstalls the Python package. The third deletes the user data (model, logs, config). No registry keys left behind except the `trident:` URI protocol โ€” remove it manually with `reg delete "HKCU\Software\Classes\trident" /f` if you want a truly clean slate.
223
+
224
+ ---
225
+
226
+ ## ๐Ÿ› ๏ธ For Developers
227
+
228
+ ```powershell
229
+ git clone https://github.com/aalok101singh/trident
230
+ cd trident
231
+ py -m venv .venv
232
+ .\.venv\Scripts\Activate.ps1
233
+ pip install -e .
234
+ trident models fetch
235
+ trident start
236
+ ```
237
+
238
+ Run the test suite:
239
+
240
+ ```powershell
241
+ pytest tests/
242
+ ```
243
+
244
+ Build a wheel:
245
+
246
+ ```powershell
247
+ pip install build
248
+ python -m build --wheel
249
+ ```
250
+
251
+ The wheel ends up in `dist\`. Install it in a fresh venv to verify.
252
+
253
+ ---
254
+
255
+ ## ๐Ÿงช Status
256
+
257
+ `v0.9.1` โ€” beta. Tested on Windows 10 and Windows 11 with Python 3.11 through 3.14.
258
+
259
+ Known limitations at this version:
260
+
261
+ - The model over-flags `powershell.exe` launches. Every one fires an escalation toast unless you trust the path.
262
+ - Unsigned executables in user-writable directories (Downloads, `%TEMP%`) are often flagged.
263
+ - Some developer tools (`python.exe`, `node.exe`, `cargo` binaries in user paths) get flagged at Tier 1 in enforce mode. A developer-path allowlist is planned for 0.10.
264
+ - Model confidence is not temperature-calibrated, so raw confidences are over-confident. The threat score uses the softmax margin to compensate.
265
+
266
+ Tracked at [github.com/aalok101singh/trident/issues](https://github.com/aalok101singh/trident/issues).
267
+
268
+ ---
269
+
270
+ ## ๐Ÿ“„ License
271
+
272
+ - **Code:** MIT โ€” see [LICENSE](LICENSE).
273
+ - **Model:** Apache 2.0 โ€” see [LICENSE-MODEL](LICENSE-MODEL).
274
+
275
+ ---
276
+
277
+ ## ๐Ÿ”— Links
278
+
279
+ - **GitHub:** [github.com/aalok101singh/trident](https://github.com/aalok101singh/trident)
280
+ - **PyPI:** [pypi.org/project/trident-windows](https://pypi.org/project/trident-windows/)
281
+ - **Model:** [huggingface.co/aalok101singh/trident-v1](https://huggingface.co/aalok101singh/trident-v1)
282
+
283
+ ---
284
+
285
+ *Watch. Judge. Act. Three prongs, one shaft. The shaft is the cascade.*