Skip to content

Workflow.md

Latest commit

 

History

History
350 lines (261 loc) · 9.75 KB

Workflow.md

File metadata and controls

350 lines (261 loc) · 9.75 KB
Raw

EDGP Workflow

Ten dokument opisuje praktyczny przeplyw end-to-end: od publicznych danych RPM lub ALBS, przez graf zaleznosci/provenance, po statyczny pakiet raportow mozliwy do otwarcia w przegladarce i sprawdzenia w CI.

Cel

EDGP ma zamienic rozproszone dane supply-chain w jeden sprawdzalny material dowodowy. W typowym scenariuszu nie chodzi tylko o zbudowanie grafu, ale o odpowiedz na pytania:

  • co jest w repozytorium lub buildzie;
  • co od czego zalezy;
  • co zmienilo sie miedzy dwoma punktami w czasie;
  • jaki jest blast radius wybranego pakietu;
  • czy istnieje advisory, license, solver lub provenance evidence;
  • czy caly zestaw raportow przechodzi jako status pass, warn, albo fail;
  • czy wynik da sie otworzyc i zweryfikowac bez bazy danych oraz bez serwera.

1. Bierzemy publiczne RPM repo albo publiczny ALBS build

Workflow zaczyna sie od publicznego zrodla danych.

Dla RPM repozytorium EDGP moze czytac:

  • lokalny primary.xml lub primary.xml.gz;
  • lokalny repomd.xml;
  • publiczny URL do repomd.xml;
  • base URL repozytorium, z ktorego da sie odnalezc metadane.

Przyklad:

edgp rpm-repo --source https://repo.almalinux.org/almalinux/10/BaseOS/x86_64/os/ --format json > rpm-graph.json

Dla ALBS EDGP moze czytac:

  • publiczny build ID;
  • lokalny JSON z metadanymi buildu;
  • publiczny URL API z metadanymi buildu.

Przyklad:

edgp albs-build --build-id 17812 --format json > albs-build-graph.json

W tym kroku projekt nie potrzebuje prywatnych zasobow. To jest celowo publiczny, AlmaLinux-compatible boundary, na ktorym mozna rozwijac i walidowac MVP bez dostepu do wewnetrznej infrastruktury.

2. EDGP buduje graf zaleznosci/provenance

Adapter zamienia wejscie na kanoniczny snapshot grafu: edgp.graph.snapshot.v1.

Dla RPM repozytorium graf zawiera miedzy innymi:

  • pakiety RPM jako wezly;
  • relacje requires rozstrzygniete do provider packages, kiedy provider jest widoczny w repozytorium;
  • jawne capability nodes dla nierozwiazanych wymagan;
  • metadata pakietow, takie jak name, version, release, arch, source RPM, license i vendor, jezeli sa dostepne.

Dla ALBS graf zawiera provenance:

  • source package;
  • repository;
  • commit;
  • build task;
  • build environment;
  • RPM artifacts;
  • sign/test/release records, jezeli sa obecne w publicznym payloadzie.

Technicznie EDGP przechowuje topologie grafu jako CSR, czyli Compressed Sparse Row. To jest wazne, bo pozniej traversal, impact i query nie musza chodzic po ciezkich obiektach Pythonowych. Runtime moze zostac zamrozony do NumPy int32 arrays, a nastepnie zapisany jako memory-mapped CSR artifact.

Przyklad artefaktu do wielokrotnego query:

edgp csr-artifact --snapshot rpm-graph.json --output-dir artifacts/rpm-csr --format text

Efekt: mamy graf jako sprawdzalny snapshot albo jako katalog .npy arrays z manifestem, digestami SHA-256 i opisem CSR/CSC-equivalent matrix views.

3. Robimy diff miedzy snapshotami albo focused diff-tree dla pakietu

Po zbudowaniu dwoch snapshotow mozna porownac caly graf:

edgp diff --left before.json --right after.json --format json > graph-diff.json

Ten raport pokazuje:

  • dodane i usuniete wezly;
  • dodane i usuniete krawedzie;
  • zmiany metadata;
  • klasyfikacje pakietowe, takie jak upgrade, downgrade, replacement, added, removed lub metadata-only.

Kiedy chcemy skupic sie na jednym pakiecie, uzywamy focused diff-tree:

edgp diff-tree \
  --left before.json \
  --right after.json \
  --node openssl \
  --direction dependents \
  --depth 4 \
  --format json > openssl-diff-tree.json

To odpowiada na pytanie: co zmienilo sie w dependency albo dependent cone wokol jednego pakietu. Dla review release/security jest to bardziej uzyteczne niz ogromny globalny diff, bo pokazuje zmiane w miejscu, ktore interesuje czlowieka.

4. Uruchamiamy impact, advisory, license i libsolv evidence

Nastepnie EDGP dokleja material dowodowy do grafu.

Impact:

edgp impact --source edgp-json --path rpm-graph.json --node openssl --format json > impact.json

Impact pokazuje:

  • bezposrednich dependentow;
  • wszystkich transitive affected dependents;
  • najkrotsze lancuchy zaleznosci prowadzace do wybranego komponentu.

Advisory:

edgp advisory \
  --source edgp-json \
  --path rpm-graph.json \
  --public-advisory-feed advisories.json \
  --ecosystem rpm \
  --format json > advisory.json

Advisory laczy feed OSV-like albo lokalny overlay z wezlem grafu i embeduje impact report dla trafionych komponentow.

License:

edgp license-report \
  --source edgp-json \
  --path rpm-graph.json \
  --deny-license GPL-3.0 \
  --format json > license-report.json

License report pozwala uzyc grafu jako wejscia do prostego compliance gate.

libsolv bridge:

edgp libsolv-bridge \
  --transaction solver-transaction.txt \
  --graph-snapshot rpm-graph.json \
  --format json > libsolv-bridge.json

EDGP nie probuje zastapic libsolv jako produkcyjnego RPM solvera. Bridge robi cos innego: bierze zapisany wynik transakcji solvera, normalizuje akcje RPM i mapuje je do wezlow grafu. Dzieki temu mozna pokazac, ktore solver actions maja najwiekszy wplyw w grafie zaleznosci.

5. Pakujemy wszystko w report-bundle

Kiedy mamy zestaw raportow, EDGP pakuje je w jeden statyczny katalog:

edgp report-bundle \
  --input rpm-graph.json \
  --input graph-diff.json \
  --input openssl-diff-tree.json \
  --input impact.json \
  --input advisory.json \
  --input license-report.json \
  --input libsolv-bridge.json \
  --output-dir reports/release-review \
  --triage-summary \
  --format text

report-bundle tworzy:

  • index.html;
  • osobne statyczne HTML dla kazdego raportu;
  • kopie zrodlowych JSON;
  • manifest.json;
  • opcjonalne triage-summary.json i triage-summary.html.

Manifest zapisuje:

  • liste raportow;
  • sciezki do JSON i HTML;
  • SHA-256 dla zrodel i renderow HTML;
  • top-level bundleSha256;
  • source kind i komendy generujace.

To jest wazne operacyjnie: bundle mozna przeslac, zarchiwizowac, otworzyc w przegladarce i pozniej sprawdzic, czy nie zostal zmieniony.

6. bundle-catalog robi jeden katalog wielu bundle'i

W realnym procesie nie ma jednego raportu. Sa bundle dla kilku repozytoriow, kilku buildow, kilku pakietow albo kilku eksperymentow.

bundle-catalog zbiera je w jeden index:

edgp bundle-catalog \
  --bundle reports/release-review \
  --bundle reports/rpm-repo-diff \
  --bundle reports/albs-build \
  --output-dir reports/catalog \
  --triage-summary \
  --format text

Catalog robi trzy rzeczy:

  • weryfikuje kazdy bundle;
  • zbiera per-bundle status, source kind, schema, failure codes i triage status;
  • agreguje metryki na poziomie calego batcha oraz source kind.

W katalogu widac miedzy innymi:

  • ile bundle'i przeszlo albo padlo;
  • ktory source kind generuje najwiecej problemow;
  • graph-diff i diff-tree policy failures;
  • real-data coverage/replacement-plan failures;
  • parallel-query node/path-query workload;
  • performance-report evidence;
  • verifier failure codes;
  • bundle fingerprints.

To jest odpowiednik executive/index view: zamiast otwierac 40 katalogow, otwieramy jeden katalog batcha.

7. triage-summary daje jeden status dla CI

triage-summary bierze raporty albo bundle/catalog i robi jeden status:

edgp triage-summary \
  --input reports/catalog/bundle-catalog.json \
  --format text \
  --fail-on-status fail

Status moze byc:

  • pass: brak istotnych problemow;
  • warn: cos wymaga uwagi, ale nie musi blokowac;
  • fail: problem powinien blokowac gate.

To jest warstwa CI. Zamiast pisac logike w pipeline dla kazdego typu raportu, pipeline moze zapytac o jeden rollup. Jednoczesnie pelny JSON/HTML zostaje zachowany, wiec reviewer moze otworzyc szczegoly.

8. Otwieramy statyczny HTML bez serwera i bez bazy

Na koncu mamy zwykle:

reports/catalog/
  index.html
  bundle-catalog.json
  triage-summary.json
  triage-summary.html
  manifest.json

Otwieramy:

open reports/catalog/index.html

albo przekazujemy katalog jako artefakt CI.

Nie jest potrzebny:

  • backend webowy;
  • baza danych;
  • kolejka;
  • konto cloud;
  • prywatna infrastruktura.

HTML jest statyczny, ale nie jest "martwy": wybrane raporty maja lokalne filtry, tabele, deep-link state w URL i panele wysokiego poziomu. To wystarcza do demo, review CI, handoffu do security/release engineering i przyszlego workbench/RAG ingestion.

Co W Tym Workflow Jest Produktem

Najwazniejszym produktem nie jest pojedynczy graf. Produktem jest zweryfikowany evidence chain:

public input
  -> EDGP graph snapshot
  -> diff / impact / advisory / license / libsolv evidence
  -> report bundle
  -> bundle catalog
  -> triage summary
  -> static HTML + manifest + digests

Ten chain daje trzy rzeczy:

  • decyzje: czy release/security gate przechodzi;
  • wyjasnienie: dlaczego status jest taki, a nie inny;
  • audyt: czy raporty i HTML nadal zgadzaja sie z manifestem.

Obecne Ograniczenia Workflow

  • Publiczne dane wystarczaja do walidacji MVP, ale nie zastapuja prywatnych CloudLinux/enterprise zrodel.
  • EDGP nie jest produkcyjnym RPM solverem; libsolv pozostaje authority dla SAT solving i transakcji.
  • Static HTML jest dobry do review i handoffu, ale nie zastapi jeszcze multi-user workbench z auth, RBAC, search indexem i baza.
  • Benchmarks i memory-mapped CSR pokazuja kierunek performance, ale nie sa jeszcze pelna gwarancja planetary-scale production.
  • Czesc fixture'ow pozostaje syntetyczna, szczegolnie tam, gdzie testuja invalid states albo parser edge cases.

Dlaczego To Ma Sens Jako Demo

Ten workflow pokazuje projekt od strony wartosci biznesowej: bierzemy realne publiczne wejscie, budujemy graf, wyjasniamy zmiane lub ryzyko, pakujemy dowody i dostajemy jeden status dla CI. To jest znacznie mocniejszy przekaz niz sam JSON, bo pokazuje cala sciezke decyzyjna od danych do audytowalnego artefaktu.