Output Format

[davidkopp]

Ich würde hiermit gerne klären, ob noch Anpassungen am Output-Format vorgenommen werden sollten und wenn ja, welche. Aktuell bin ich ja an der Integration in GMT dran, so dass sich gewisse Inhalte darauf auswirken können.

Das aktuelle Output-Format vom dependency_resolver sieht so aus:

{
  "_container-info": {
    "name": "nginx-container",
    "image": "nginx:latest",
    "hash": "sha256:2cd1d97f893f..."
  },
  "dpkg": {
    "scope": "system",
    "dependencies": {
      "package-name": {
        "version": "1.2.3 amd64",
        "hash": "abc123..."
      }
    }
  },
  "pip": {
    "scope": "project",
    "location": "/path/to/venv/lib/python3.12/site-packages",
    "hash": "def456...",
    "dependencies": {
      "package-name": {
        "version": "1.2.3"
      }
    }
  }
}

Unzufrieden bin ich insbesondere mit dem Key _container-info. Hier als reinen Output vom dependency_resolver finde ich das noch passend, aber innerhalb von GMT sieht das seltsam aus.

Ich habe mir mal das JSON-Format von Syft etwas angeschaut und mich etwas inspirieren lassen.

• Schema: https://raw.githubusercontent.com/anchore/syft/main/schema/json/schema-16.0.36.json
• Beispiel-Output: https://github.com/green-coding-solutions/dependency-resolver/blob/tool-comparison/docs/tool-comparison/gmt-gunicorn/syft-json_formatted.json

Der folgende Output entspricht nicht exakt dem Syft-Schema, hat aber einiges davon übernommen:

{
  "source": {
    "type": "docker",
    "name": "nginx-container",
    "image": "nginx:latest",
    "hash": "sha256:2cd1d97f893f...",
    "metadata": {
      "imageSize": 505664711,
      "architecture": "amd64",
      "os": "linux"
    }
  },
  "distro": {
      "name": "Ubuntu 24.04.3 LTS",
      "id": "Ubuntu",
      "versionID": "24.04",
      "versionCodename": "noble"
  },
  "packages": [ // artifacts
    {
      "name": "package-name-1",
      "type": "deb",
      "version": "1.2.3",
      "architecture": "amd64",
      "hash": "abc123...",
      "found-by": "dpkg_detector",
      "location": "/usr/bin/apt"
    },
    {
      "name": "package-name-2",
      "type": "python",
      "version": "0.7.0",
      "hash": "def456...",
      "found-by": "pip_detector",
      "location": "/var/www/startup/venv/lib/python3.12/site-packages/annotated_types-0.7.0.dist-info"
    }
  ],
  "descriptor": {
    "name": "dependency_resolver",
    "version": "0.0.1",
    "configuration": {
      "skip-system-scope": false,
      "only-container-info": false,
      "pretty-print": true,
      "detectors": {
        "used": [
          "dpkg_detector",
          "pip_detector"
        ]
      }
    }
  }
}

Die größte Veränderung ist, dass alle Pakete in einer Liste sind und mit dem Key type dann spezifiziert wird, was es für ein Paket ist.
Außerdem wurde _container-info mit source ersetzt und die Keys distro und descriptor hinzugefügt.

Das soll vor allem als Diskussionsgrundlage dienen. Ich erwarte nicht, dass das genau so umgesetzt werden sollte.
Gibt es hier etwas, was euch gefällt und ich übernehmen soll?

@ArneTR @ribalba

[ribalba]

• Ich finde das source besser als "_container-info":

Zur Zeit verwendest du ja das packagin system als key was dazu fuehren wird, dass wir das beachten muessen in weiterfuerhrenden code. Wenn wir eine Liste mit packages haben in der einfach ein type gesetzt ist koennen wir den code system unabhaengig schreiben.

Es waere sogar zu ueberlegen ob wir nicht einfach das Syft Format erweitern und somit enventuell tools aus dem space verwenden koennen.

[davidkopp]

Die 2 genannten Änderungen

• _container-info -> source
• eine Liste an Paketen mit type anstatt eines Dictionaries mit Package-Manager als Key

würde ich auf jeden Fall umsetzen.

Wollen wir das Syft-JSON-Format erweitern?

Ich habe mir mal angeschaut, wie ein Minimal Output mit 3 Paketen aussehen könnte, welches alle verpflichtenden Felder vom Syft JSON-Schema 16.0.39 beinhaltet.

Darin enthalten sind Properties wie licenses, die in dem Schema verpflichtend sind, für unsere Zwecke jedoch keinen Mehrwert bringen. Um vollständig compliant zu sein, müsste das gemacht werden.

Denkbar wäre für mich auch gegen die required-Regeln zu verstoßen, sich ansonsten jedoch an die Struktur vom Schema zu halten.

Wollen wir uns dem Syft-JSON-Format annähern oder einen komplett eigenen Weg gehen?

Die SBOM-Formate cyclonedx und spdx sind übrigens total ungeeignet für uns. Das github-json-Format (Format für GitHub's dependency snapshot) ist ziemlich leichtgewichtig (siehe Beispiel hier), so dass es grundsätzlich denkbar wäre, darauf aufzubauen. Jedoch sehe ich aktuell keinen Vorteil darin, sich zwanghaft diesem Format anzunähern. Da finde ich eine Annäherung an das Syft JSON-Format schon erstrebenswerter.

Minimal Sample Output using Syft JSON Format

{
  "artifacts": [
    {
      "id": "dpkg-libc6",
      "name": "libc6",
      "version": "2.36-9+deb12u4",
      "type": "deb",
      "foundBy": "dpkg_detector",
      "locations": [
        {
          "path": "/var/lib/dpkg/status",
          "accessPath": "/var/lib/dpkg/status"
        }
      ],
      "licenses": [
        {
          "value": "LGPL-2.1",
          "spdxExpression": "LGPL-2.1-only",
          "type": "declared",
          "urls": [],
          "locations": [
            {
              "path": "/usr/share/doc/libc6/copyright",
              "accessPath": "/usr/share/doc/libc6/copyright"
            }
          ]
        }
      ],
      "language": "",
      "cpes": [
        {
          "cpe": "cpe:2.3:a:gnu:glibc:2.36:*:*:*:*:*:*:*"
        }
      ],
      "purl": "pkg:deb/debian/libc6@2.36-9+deb12u4?arch=amd64"
    },
    {
      "id": "pip-flask",
      "name": "flask",
      "version": "2.3.3",
      "type": "python",
      "foundBy": "pip_detector",
      "locations": [
        {
          "path": "/app/venv/lib/python3.12/site-packages",
          "accessPath": "/app/venv/lib/python3.12/site-packages"
        }
      ],
      "licenses": [
        {
          "value": "BSD-3-Clause",
          "spdxExpression": "BSD-3-Clause",
          "type": "declared",
          "urls": [],
          "locations": [
            {
              "path": "/app/venv/lib/python3.12/site-packages/flask-2.3.3.dist-info/LICENSE",
              "accessPath": "/app/venv/lib/python3.12/site-packages/flask-2.3.3.dist-info/LICENSE"
            }
          ]
        }
      ],
      "language": "python",
      "cpes": [
        {
          "cpe": "cpe:2.3:a:palletsprojects:flask:2.3.3:*:*:*:*:python:*:*"
        }
      ],
      "purl": "pkg:pypi/flask@2.3.3"
    },
    {
      "id": "pip-requests",
      "name": "requests",
      "version": "2.31.0",
      "type": "python",
      "foundBy": "pip_detector",
      "locations": [
        {
          "path": "/app/venv/lib/python3.12/site-packages",
          "accessPath": "/app/venv/lib/python3.12/site-packages"
        }
      ],
      "licenses": [
        {
          "value": "Apache-2.0",
          "spdxExpression": "Apache-2.0",
          "type": "declared",
          "urls": [],
          "locations": [
            {
              "path": "/app/venv/lib/python3.12/site-packages/requests-2.31.0.dist-info/LICENSE",
              "accessPath": "/app/venv/lib/python3.12/site-packages/requests-2.31.0.dist-info/LICENSE"
            }
          ]
        }
      ],
      "language": "python",
      "cpes": [
        {
          "cpe": "cpe:2.3:a:python-requests:requests:2.31.0:*:*:*:*:python:*:*"
        }
      ],
      "purl": "pkg:pypi/requests@2.31.0"
    }
  ],
  "artifactRelationships": [
    {
      "parent": "pip-flask",
      "child": "pip-requests",
      "type": "dependency-of"
    }
  ],
  "source": {
    "id": "web-app-container",
    "name": "web-app",
    "version": "latest",
    "type": "image",
    "metadata": {
      "name": "web-app",
      "image": "python:3.12-slim",
      "hash": "sha256:a1b2c3d4e5f6..."
    }
  },
  "distro": {
    "name": "Debian GNU/Linux",
    "version": "12",
    "id": "debian"
  },
  "descriptor": {
    "name": "dependency-resolver",
    "version": "1.0.0"
  },
  "schema": {
    "version": "16.0.39",
    "url": "https://raw.githubusercontent.com/anchore/syft/main/schema/json/schema-16.0.39.json"
  }
}

Edit: Analyse und Sample-Dateien lassen sich hier einsehen:
https://github.com/green-coding-solutions/dependency-resolver/tree/adopt-syft-json-schema/docs/technical/analyses/syft-json-schema-adoption

[davidkopp]

Falls wir uns dem Syft-JSON-Format annähern wollen, jedoch auf für uns unnötige Attribute verzichten wollen, hier ein neuer Entwurf für ein "eigenes" Format:

{
  "source": {
    "type": "docker",
    "name": "nginx-container",
    "image": "nginx:latest",
    "hash": "sha256:2cd1d97f893f...",
    "metadata": {
      "imageSize": 505664711,
      "architecture": "amd64",
      "os": "linux"
    }
  },
  "distro": {
      "name": "Ubuntu 24.04.3 LTS",
      "id": "Ubuntu",
      "versionID": "24.04",
      "versionCodename": "noble"
  },
  "artifacts": [ // put all package manager dependencies and arbitrary artificats into this list (Syft does this as well and distinguish them by 'type' and 'metadataType')
    {
      "id": "cd0a6d87e2b9c130", // hash-value generated out of some (not all) properties
      "name": "apt",
      "version": "2.6.1",
      "type": "deb",
      "found-by": "dpkg_detector",
      "location": "/usr/bin/apt", // or locations with multiple paths
      "scope": "system", // does not exist in Syft (I would like it to be able to differentiate project and system packages without parsing the location path)
      "metadataType": "dpkg-db-entry",
      "metadata": {
        "architecture": "amd64",
        "hash": "abc123...",
        "installedSize": 686,
        "files": [ // do we want to collect related files for a package?
          {
              "path": "/etc/apt/apt.conf.d/01autoremove",
              "digest": {
                  "algorithm": "md5",
                  "value": "879455db9b938ce287b23383629aedce"
              },
              "isConfigFile": true
          },
          {
              "path": "/lib/systemd/system/apt-daily.timer",
              "digest": {
                  "algorithm": "md5",
                  "value": "57b964b4d70e49baf77ca7c971358acf"
              },
              "isConfigFile": false
          },
          // ...
        ]
      }
    },
    // ...
  ],
  "runtime-configuration": { // invented by me -> first draft, has to be improved!
    "environment-variables": [
      {
        "name": "JAVA_OPTS",
        "value": "-Xmx4g -XX:+UseG1GC"
      },
      {
        "name": "LOG_LEVEL",
        "value": "ERROR"
      }
    ],
    "configuration-files": [
      {
        "path": "/app/application.yml",
        "parsed-settings": [
          {
            "key": "server.tomcat.max-threads",
            "value": "200"
          },
          {
            "key": "spring.datasource.hikari.maximum-pool-size",
            "value": "20"
          }
        ]
      },
      {
        "path": "/etc/resolv.conf",
        "parsed-settings": [
          {
            "key": "dns-timeout",
            "value": "2s"
          },
          {
            "key": "dns-attempts",
            "value": "3"
          }
        ]
      }
    ],
    "container-runtime": {
      "memory-limit": "6Gi",
      "cpu-limit": "2000m"
    }
  },
  "descriptor": {
    "name": "dependency_resolver",
    "version": "0.0.1",
    "configuration": {
      "skip-system-scope": false,
      "only-container-info": false, // may be renamed to "only-source-info"
      "pretty-print": true,
      "detectors": {
        "used": [
          "dpkg_detector",
          "pip_detector"
        ]
      }
    }
  },
  "schema": {
    "version": "0.0.1" // do we want to have our own schema with versioning?
  }
}

[ArneTR]

Ich sehe aktuell keine Notwendigkeit hier irgend eine Formatspezifikation zu implementieren.

Das kann jederzeit einfach geändert werden. Zur Not zieht man einen Transformer / Exporter ein.

Bitte nutz einfach das Format mit dem du am einfachsten entwicklen kannst. Ich sehe kein Risiko das wir eingehen, wenn wir hier ein völlig wildes Format wählen und es dann in 3 Monaten ändern wollen. Der Aufwand sollte überschaubar sein.

Dazu kommt das die Dateien so absurd groß werden, dass die sowieso nicht mehr von Menschen gelesen werden können. Daher sind IMHO lesbarkeits-features zweitrangig.

Ein Plug&Play mit Swyft wäre natürlich nett. Ich lese aber raus, dass dies so nicht möglich ist, da wir manche Features wie License gar nicht implementieren wollen. Damit wäre es auch nicht relevant IMHO

[davidkopp]

Das Output Format hat sich seit dem letzten Update leicht verändert. Das aktuelle Format ist auf folgender Seite beschrieben:
https://github.com/green-coding-solutions/energy-dependency-inspector/blob/main/docs/usage/output-format.md

Was gestern dazu gekommen ist, sind "Mixed-Scope Packages (Multi-Location Detection)". Das hatte ich im ursprünglichen Design nicht vorgesehen gehabt, was nun dazu führt, dass je nach Scope es entweder direkt die dependencies Liste unterhalb vom Paket-Manager gibt (alleiniger Scope ist project oder system). oder es dazwischen noch eine locationsListe gibt (Scopemixed).
Aktuell ist es also so, dass zunächst der Scope überprüft werden muss, before die dependencies abgefragt werden können. Etwas unschön.

3 Möglichkeiten stehen diesbezüglich für mich zur Debatte:

1. so lassen wie es jetzt ist
2. den locations Key für alle Paket-Manager einführen, so dass es immer die Hierarchie <package_manager>.locations.dependencies gibt.
3. Umstellung auf eine flache Struktur wie es Syft macht (es gibt nur eine dependencies / packages / artifacts Liste -> Meta-Informationen wie Paket-Manager, Location, Location-Hash, etc. müssten bei jedem einzelnen Paket mit angegeben werden (viele duplizierte Informationen im Output)