From 460a59bd8db1df1918700924c1a35497336661f7 Mon Sep 17 00:00:00 2001
From: Niroj33 <86530493+professor3333@users.noreply.github.com>
Date: Mon, 16 Nov 2026 02:09:21 +0545
Subject: [PATCH] Make the README concise and put the demo at the top
The README goes from 568 lines to 273. It now opens with the banner, a one-paragraph introduction and an animated demo of the review page, then gives a short quickstart, one headline results table, the architecture diagram, and compact data, deployment, status, limitations and documentation sections.
Nothing measured is dropped: the full results text moves to docs/results.md and the full command reference to docs/usage.md, verbatim apart from headings and link paths. docs/assets/demo.gif is recorded from the published Flask demo page by scripts/demo/record_gif.py (real model output and the page's own script); it replaces the older screenshot.
---
README.md | 693 +++++++++++--------------------------
docs/assets/app-review.png | Bin 243606 -> 0 bytes
docs/assets/demo.gif | Bin 0 -> 845938 bytes
docs/results.md | 167 +++++++++
docs/usage.md | 101 ++++++
scripts/demo/record_gif.py | 103 ++++++
6 files changed, 570 insertions(+), 494 deletions(-)
delete mode 100644 docs/assets/app-review.png
create mode 100644 docs/assets/demo.gif
create mode 100644 docs/results.md
create mode 100644 docs/usage.md
create mode 100644 scripts/demo/record_gif.py
diff --git a/README.md b/README.md
index 57ccdab..46ac5a5 100644
--- a/README.md
+++ b/README.md
@@ -5,564 +5,269 @@
[](https://github.com/professor3333/TriggerMap/actions/workflows/ci.yml)
+[-8b5cf6)](https://github.com/professor3333/TriggerMap/releases/tag/v0.2.0)
+[](https://professor3333.github.io/TriggerMap/)

-[](LICENSE)
+[](LICENSE)
[](annotations/README.md)
-
-
-
-
-**Read the advisory. Get the conditions. Check them against your deployment.**
-
-[Architecture](#architecture) ·
-[Why](#why-triggermap) ·
-[What it extracts](#what-it-extracts) ·
-[See it](#see-it) ·
-[Principles](#design-principles) ·
-[Status](#project-status) ·
-[Quickstart](#quickstart) ·
-[Data](#data-and-licensing)
----
+**TriggerMap reads a security advisory for a Python package and tells you under what conditions
+the vulnerability is reachable.** A dependency scanner such as
+[OSV-Scanner](https://github.com/google/osv-scanner) says *which* package is affected. TriggerMap
+extracts the conditions stated in the advisory text (a setting, a feature in use, the attacker's
+access, a platform), with their role and logic. Every item links to the exact words that state
+it, so a developer can check it against their deployment and export the record.
-## Architecture
-
-```mermaid
-flowchart LR
- subgraph Data["Dataset pipeline"]
- A[Pinned advisory
snapshot] --> B[Validate · normalise
preserve offsets]
- B --> C[Annotation and
adjudication]
- C --> D[Versioned dataset
and frozen splits]
- end
- subgraph Models["Modelling"]
- D --> E[Rules · CRF ·
DistilBERT · DeBERTa]
- E --> F[Evaluation and
calibration]
- F --> G[Versioned
model bundle]
- end
- subgraph Serving["Review application"]
- H[GHSA / CVE id, text,
or OSV-Scanner result] --> I[FastAPI]
- I --> J[Shared
preprocessing]
- J --> K[Inference and
structured decoding]
- G --> K
- K --> L[Evidence-linked
review UI]
- L --> M[Review storage
and export]
- M --> N[Curated
correction queue]
- end
- N -. human adjudication .-> C
+
-🟩 built · 🟨 in progress · ⬜ planned. Training and serving share one preprocessing module, so offsets mean the same thing everywhere.
+Try the live demo → Real output of the released model on a Flask advisory, mistakes included: it finds two of the five listed conditions and marks one background phrase as required. One illustrative advisory, not an accuracy claim.
-## Why TriggerMap
+| Category | Role | Group |
|---|---|---|
|
+> When **using aiohttp as a web server** and **enabling static resource resolution** with
+> **`follow_symlinks` set to True**, it can lead to this vulnerability.
-`CONFIGURATION` option or flag values -`USAGE` features, functions, modes used -`ACCESS` what the attacker must have -`PLATFORM` OS, runtime, infrastructure +| Span | Category | Role | Group | +|---|---|---|---| +| using aiohttp as a web server | `USAGE` | `REQUIRED` | `ALL` | +| enabling static resource resolution | `USAGE` | `REQUIRED` | `ALL` | +| follow_symlinks set to True | `CONFIGURATION` | `REQUIRED` | `ALL` | - |
+The three spans form one `ALL` group: every one of them must hold. The full label set:
-`REQUIRED` must hold (incl. required *absences*) -`EXCEPTION` if it holds, you are not exposed -`NOT_REQUIRED` the text says it is unnecessary -`UNCERTAIN` the text does not settle it - - |
+| | Labels |
+|---|---|
+| **Category** | `CONFIGURATION` · `USAGE` · `ACCESS` · `PLATFORM` |
+| **Role** | `REQUIRED` (includes required *absences*) · `EXCEPTION` · `NOT_REQUIRED` · `UNCERTAIN` |
+| **Group** | `ALL` · `ANY` · `UNRESOLVED` |
-`ALL` every member must hold -`ANY` one member suffices -`UNRESOLVED` connected, logic unclear +Three rules shape everything else: - |
-tw9K&$ynr=GqK{o!o3-HA=XO}LkoV6#~Y8o@|9c_L*xY2}D12Vli>d4Lu@
z){o5h)=-)d?BFN25L$qMaF=f|nYM=Q#9zMHx`=UDzUmIr9$H^tO*i{Leg@@=L@uuf
zJTZGZfE08DsFVwTYjL`A&Er;;|H1F^;4=+8d{5$S3FmKd?K^yYJB;eWpby=njkH{;
zcJuXU8BJpUJbjkY)?m
z(nZ# gyvuaGwsQ-YG?KzYsFMY4CjP^48ythSk3U194b?dqX$IsUr~>%p6Z|%2n`RJ*G37()gpGziXuWwHFKr6GMzJ5uQ{bUr-9H
zASkPCv*oB7WYtARcT{M0>|RoYV<=@~{^j207H6$KD2D!F0U9-ihoFHex=doyBK{6*
zTD}{uI+eK4P^r1Wd$omcEDIA8brvbH&X)o)gzNuG;fxW@DmKA~?k_iqe^8sgAM*Xu
z{Yk``sTCq(2Pf*y8wCO_CyOl=B#!7weC=*~@MlSAM+>VM_Mk<+PPeaL<
UQmBEc5<6%M4*RY>!3P9eX!+d
zSXouywr|+ybaVH%2ez|%_$*MUAtd4CNA<6-M7H^AxP5c;K5d+0g4Rfa{rL39sw$!u
zL*e3VwE2GN0lRrVC~wIO1xa0j-=}l^fBxifIdb#t9$aCG*)dl$t;zPx#-bJ0dPv|1
zd)}I%j-i9kMC6!X2+rHu%|^~iH7_jAuPy+I%kM}Nk>Xk`*_MTd5)z7lK@|InKruOq
zGLejS_Oy-AUD(ZYGQPnuTGE#