From 2b7ec544dacb9b9b6a014c3a68c8bfd50ba38d24 Mon Sep 17 00:00:00 2001
From: Sebas <claude.these371@passmail.net>
Date: Thu, 25 Jun 2026 07:30:05 +0000
Subject: [PATCH] docs: Tools-Tabelle komplett (9 Tools) + Suppression-Write +
 VULNERABILITY_ANALYSIS

---
 README.md | 44 ++++++++++++++++++++++++++++++++++++--------
 1 file changed, 36 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index de9db2f..405c8a9 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,8 @@
 # dependencyTrack-MCP
 
 MCP-Server fuer [OWASP Dependency-Track](https://dependencytrack.org/), in Rust.
-Read-only Zugriff auf Projekte, Findings und Metriken.
+Ueberwiegend lesender Zugriff (Projekte, Findings, Metriken, VEX/SBOM u.a.) plus
+eine geschuetzte Schreib-Operation: Finding-Suppression/Analyse.
 
 Zwei Frontends, eine gemeinsame Tool-Logik:
 
@@ -19,7 +20,7 @@ Zwei Frontends, eine gemeinsame Tool-Logik:
 ```
 crates/dtrack-config   Config (TOML laden/speichern, Secret-Masking, Persistenz)
 crates/dtrack-perms    RBAC-Policy (Rollen/Clients, Deny-overrides-Allow)
-crates/dtrack-core     DT-REST-Client (reqwest+rustls, read-only)
+crates/dtrack-core     DT-REST-Client (reqwest+rustls)
 crates/dtrack-tools    rmcp-Server (die Tools) -- transport-unabhaengig, geteilt
 crates/dtrack-stdio    Bin: stdio-Frontend
 crates/dtrack-http     Bin: HTTP-Frontend (axum + StreamableHTTP + Admin-UI)
@@ -27,18 +28,38 @@ crates/dtrack-http     Bin: HTTP-Frontend (axum + StreamableHTTP + Admin-UI)
 
 ## Tools
 
+Lesend:
+
 | Tool | Argument | DT-Endpoint |
 |---|---|---|
 | `list_projects` | -- | `GET /project` |
+| `lookup_project` | `name`, `version?` | `GET /project/lookup` |
+| `project_components` | `uuid` | `GET /component/project/{uuid}` |
 | `project_findings` | `uuid` | `GET /finding/project/{uuid}` |
 | `project_metrics` | `uuid` | `GET /metrics/project/{uuid}/current` |
+| `project_violations` | `uuid` | `GET /violation/project/{uuid}` (braucht `VIEW_POLICY_VIOLATION`) |
+| `project_vex` | `uuid` | `GET /vex/cyclonedx/project/{uuid}` |
+| `project_bom` | `uuid` | `GET /bom/cyclonedx/project/{uuid}` |
+
+Schreibend (braucht das DT-Recht `VULNERABILITY_ANALYSIS`):
+
+| Tool | Argument | DT-Endpoint |
+|---|---|---|
+| `suppress_finding` | `project`, `component`, `vulnerability`, `suppressed?`, `state?`, `justification?`, `comment?` | `PUT /analysis` |
+
+> `suppress_finding` ist die einzige schreibende Operation. Die drei UUIDs
+> (project/component/vulnerability) stammen aus der `project_findings`-Antwort.
+> `suppressed` ist standardmaessig `true` (`false` hebt die Unterdrueckung auf).
+> Wer nur lesen soll, bekommt einen Key **ohne** `VULNERABILITY_ANALYSIS` --
+> dann scheitert der Write serverseitig mit HTTP 403. Im HTTP-Modus zusaetzlich
+> per RBAC eingrenzbar (eigene Rolle / `deny`).
 
 ## Konfiguration (Umgebungsvariablen)
 
 | Var | Pflicht | Bedeutung |
 |---|---|---|
 | `DTRACK_URL` | ja* | Basis-URL der DT-Instanz (ohne `/api/v1`, wird angehaengt) |
-| `DTRACK_API_KEY` | ja* | API-Key eines **read-only** Teams (`VIEW_PORTFOLIO`, `VIEW_VULNERABILITY`) |
+| `DTRACK_API_KEY` | ja* | API-Key eines Teams. Lesen: `VIEW_PORTFOLIO` + `VIEW_VULNERABILITY` (Policy-Verstoesse: `VIEW_POLICY_VIOLATION`); fuer `suppress_finding`: `VULNERABILITY_ANALYSIS` |
 | `DTRACK_INSECURE` | nein | `1`/`true` -> TLS-Pruefung aus (Notbehelf bei internem CA-Cert) |
 | `DTRACK_CONFIG` | nein | Pfad zu einer TOML-Config; einmal aus env gebootstrappt, danach massgeblich |
 | `DTRACK_PERMISSIONS` | nein | (nur HTTP) Pfad zur RBAC-Policy; gesetzt -> RBAC statt flacher Token-Liste |
@@ -114,7 +135,8 @@ volumes:
 `docker compose up -d` (apiserver braucht ~4 GB RAM + ein paar Minuten beim
 Erststart). Dann `http://localhost:8082` (Login `admin`/`admin`), unter
 **Administration -> Access Management -> Teams** einen API-Key mit
-`VIEW_PORTFOLIO` + `VIEW_VULNERABILITY` erzeugen und ein Projekt anlegen.
+`VIEW_PORTFOLIO` + `VIEW_VULNERABILITY` erzeugen (fuer den Suppression-Test
+zusaetzlich `VULNERABILITY_ANALYSIS`) und ein Projekt anlegen.
 Aus dem MCP-Container ist die DT unter `http://host.docker.internal:8081`
 erreichbar (nicht `localhost`).
 
@@ -241,17 +263,23 @@ leer = offen). Fuer feinere Rechte `permissions.toml.example` nach
 
 Modell: benannte Rollen mit `allow`/`deny` (`"*"` = alle Tools, **deny schlaegt
 allow**), Clients ordnen einen Bearer-Token einer Rolle zu. Ein nicht erlaubter
-`tools/call` wird mit **403** abgewiesen.
+`tools/call` wird mit **403** abgewiesen. Tipp: das schreibende `suppress_finding`
+gezielt nur Auditor-Rollen erlauben (oder breit per `deny` ausschliessen).
 
 ```toml
 [[roles]]
-name  = "metrics-only"
-allow = ["list_projects", "project_metrics"]
+name  = "read-only"
+allow = ["*"]
+deny  = ["suppress_finding"]
+
+[[roles]]
+name  = "auditor"
+allow = ["*"]
 
 [[clients]]
 name  = "dashboard-bot"
 token = "GEHEIM"
-role  = "metrics-only"
+role  = "read-only"
 ```
 
 ## Admin-UI