1. Abhängigkeiten der Dokumente darstellen

1.1. Das Abhängigkeitsnetz aus der Bibliographie und dem Quellcode automatisiert generieren

Ein weiterer Vorteil der Bibliographie und der Arbeitsweise mit AsciiDoc ist die Möglichkeit die Dateien automatisch zu parsen.

So kann man relativ einfach einen Abhängigkeitsbaum der erstellten und zitierten Dokumente generieren lassen. Neben einer einfachen Listen-Darstellung in HTML/PDF kann man den Abhängigkeitsbaum auch als Graphen visualisieren lassen. Hierzu bietet sich dann GraphViz an, das seit über 30 Jahren erfolgreich Graphen für große und kleine Projekte generiert und auch von PlantUML oder AsciiDoc genutzt wird.

Unsere Architektur-Dokumente spiegeln die Komplexität unserer Architekturen wieder. Dies zeigt sich in den vielfältigen Abhängigkeiten der Dokumente untereinander, z.B. die Anweisung zur Transportverschlüsselung. Diese hängt einerseits von der Dataport-weiten Krypto-Richtlinie und den entsprechenden Technischen Richtlinien des BSI ab, beeinflusst aber auch zahlreiche unserer Architekturkonzepte.

Eine häufige Frage ist z.B.: Welche unserer Architektur-Konzepte müssen wir aktualisieren, wenn z.B. die Technische Richtlinie zur Transportverschlüsselung des BSI aktualisiert wird? Dann muss zwangsweise unsere Anweisung Transportverschlüsselung aktualisiert werden, da diese die BSI TR zitiert. Damit ist aber noch nicht Schluss, der gesamte Abhängigkeitsbaum der Dokumente muss entsprechend aktualisiert werden, also alle Dokumente die wiederum auf unsere Anweisung Transportverschlüsselung verweisen.

Da ein Architekt - auch ein dedizierter »Wissens-Gärtner« a la Arc42 nicht den Gesamtüberblick über alle Architekturen, deren Konzepte und deren Abhängigkeiten behalten kann, kann der Abhängigkeitsbaum hier Abhilfe schaffen.

Dazu habe ich 2 kleine Perl-Skripte angepasst, die zuerst unseren AsciiDoc-Baum im Gitlab durchiterieren und das Ergebnis dann graphisch aufbereiten.

Das erste Skript iteriert durch unser Verzeichnis im Gitlab, sucht jede AsciiDoc-Datei und geht diese zeilenweise durch. In jeder Zeile wird geprüft, ob mittels cite-Befehl ein Bibliographie-Eintrag zitiert wird. Ist dem so, wird diese Beziehung (dieses AsciiDoc zitiert jenen Bib-Eintrag) in eine temporäre Datei geschrieben. Zusätzlich wird aus der Bibliographie neben dem BibKey auch der Titel und aus der AsciiDoc ggf. die Namem der Autoren extrahiert und in der temporären CSV gespeichert.

Diese Datei wird dann vom 2. Skript eingelesen und in 2 verschiedene Richtungen sortiert:

  1. Ein Dokumente zitiert n Bib-Einträge (Dependencies)

  2. Ein Bibeintrag wird von n Dokumenten (Reverse Dependenies) zitiert

Beide Relationen werden dann in Listenform für AsciiDoc/HTNL/PDF und in eine graphische Form mittels GraphViz aufbereitet.

Neben der sehr großen Gesamtübersicht gibt es auch noch eine Listendarstellung in der für die Abhängigkeiten nur für genau einen Bibkey dargestellt werden.

Zur einfachen Anzeige wird außerdem eine simple AsciiDoc/HTML-Übersicht generiert, die alle so erzeugten Graphen sortiert anzeigt.

Da die Graphen selber als SVG erzeugt werden, skalieren sie problemlos und können beliebig herein- und hinausgezoomt werden. Außerdem kann man die Knoten anklicken und landet dann direkt in der Bibliographie bzw. im jeweiligen Verzeichnis des Dokumentes im Gitlab.

Der Abhängigkeitsbaum zur Richtlinie für Open-Source-Quellen

dp px rl flossquellen

Anklicken zum vergrößern

Über den Graphen (oder Alternativ die Text-Darstellung) lässt sich leicht herausfinden welche Dokumenten alle von unserer Richtlinie für Open-Source-Quellen abhängen, z.B. die gesamten Sicherheitsbewertungen für Open-Source-Software oder die Richtlinie zur CI/CD-Sicherheit.