Was wm-audit genau tut – und wie Sie es aufrufen

Eine API-Spezifikation beschreibt, was eine Schnittstelle tun soll. Der Export des Gateways beschreibt, was sie tut: welche Policies zugeordnet sind, wohin geroutet wird, welche Protokolle erlaubt sind. wm-audit wertet diesen Export in einem Lauf aus:

• ›liest APIs, Policies, Policy-Aktionen und Aliase aus einem ZIP-Archiv oder einem entpackten Ordner,
• ›berücksichtigt nur Policy-Aktionen, die im Gateway einer Stage zugeordnet sind,
• ›prüft jede API gegen zehn Regeln und trennt belegte Befunde von Hinweisen,
• ›liest die Lastgrenzen der Traffic-Optimization-Policies aus,
• ›schreibt einen Bericht als Text, JSON, HTML oder JUnit-XML und setzt auf Wunsch einen Exit-Code für die Pipeline.

Was wm-audit nicht tut: Es stellt keine Verbindung her und sendet keine Anfrage an Ihre APIs. Es verändert den Export nicht und entpackt kein ZIP auf die Platte. Passwörter und Schlüssel (PassmanData, Keystore, Truststore, Kerberos) öffnet es nie. Ob eine Policy im Betrieb greift, zeigt erst ein Test gegen die laufende API – diese Fragen nennt der Bericht, statt sie zu bewerten.

Der Quelltext von wm-audit ist öffentlich: github.com/cehlert9999/sectestx-api-scanner ↗ (Apache-2.0). Im Ordner wm-audit-rs/ liegt das Programm in Rust: alle Prüfregeln, die Berichtsformate einschließlich JUnit und Lastrechner, die Sicherheitstests, das Prüfskript und die Startdateien. Unter wm-audit/tests/ liegen die 15 Prüffälle mit den erwarteten Ausgaben in allen vier Formaten. Daneben enthält das Repo oas-audit, die Prüfung hinter dem kostenlosen API-Check.

• ›Es ist derselbe Quelltext, aus dem die Programme für Windows, macOS und Linux gebaut werden; er liegt zusätzlich dem Lieferpaket bei.
• ›Bei jeder Änderung prüft GitHub Actions Formatierung, statische Analyse (clippy, Warnungen als Fehler) und alle Tests einschließlich der Prüffälle.
• ›pruefen.sh wiederholt die vollständige Prüfung in einem Lauf: Tests, Lizenzen, bekannte Schwachstellen, SBOM und Build ohne lokale Pfade. Es braucht cargo-deny, cargo-audit und cargo-cyclonedx.

Selbst bauen

git clone https://github.com/cehlert9999/sectestx-api-scanner
cd sectestx-api-scanner/wm-audit-rs
cargo build --release --locked   # Programm: target/release/wm-audit
cargo test --locked              # Prüffälle und Sicherheitstests
./pruefen.sh                     # alle Prüfungen in einem Lauf

Ohne Kommandozeile: Den Export auf die Startdatei ziehen oder sie doppelklicken und eine ZIP-Datei auswählen. Der HTML-Bericht wird unter Dokumente/wm-audit Berichte/ als Bericht_<Export>_<Datum>_<Uhrzeit>.html gespeichert und im Browser geöffnet.

Mit Kommandozeile:

wm-audit gateway-export.zip                              # Bericht als Text
wm-audit gateway-export.zip --html -o bericht.html       # Bericht mit Aufgabenliste
wm-audit gateway-export.zip --junit -o junit.xml --fail-on high   # für die Pipeline

Eine Installation oder Laufzeitumgebung ist nicht nötig; das Programm ist eine einzelne Datei.

Laut IBM-Dokumentation exportieren Sie APIs im API Gateway so:

• ›In der Titelleiste APIs öffnen.
• ›Eine API: das Export-Symbol neben der API anklicken. Mehrere APIs: die Kästchen der APIs markieren, das Zahnrad-Symbol anklicken und Export wählen.
• ›Optional „Include applications“ und weitere Optionen wählen, dann Export. Der Browser bietet das Archiv zum Speichern an.

Quelle: IBM: Exporting APIs ↗. Übergeben Sie wm-audit das Archiv unverändert oder den entpackten Ordner.

wm-audit EXPORT [--json | --html | --junit] [--output DATEI] [--fail-on SCHWERE]

Unter Windows heißt das Programm wm-audit.exe. Optionen dürfen vor oder nach dem Export stehen. Wird eine Option mehrfach angegeben, gilt der letzte Wert. Optionen werden nur ausgeschrieben erkannt, Abkürzungen wie --js sind ein Aufruffehler.

Regeln für Ausgabe und Formate

• ›--json, --html und --junit schließen sich gegenseitig aus. Ohne eine davon entsteht Text.
• ›Der Bericht ist immer UTF-8. Fehlermeldungen gehen auf die Fehlerausgabe, nie in den Bericht.
• ›Außer der Ausgabedatei schreibt wm-audit nichts: keine temporären Dateien, keine Logs, keine Konfiguration.

Keine Konfigurationsdatei, keine Umgebungsvariablen

wm-audit liest keine Konfigurationsdatei und keine Umgebungsvariablen. Das Verhalten hängt allein von den Argumenten und dem Export ab: gleicher Export, gleiche Optionen, byte-gleicher Bericht. Die Grenzen gegen manipulierte Exporte sind fest eingebaut:

Beispiele

# Bericht mit Aufgabenliste und Lastrechner
wm-audit gateway-export.zip --html -o bericht.html

# Entpackter Export, JSON in eine Datei
wm-audit ./export-ordner --json -o bericht.json

# Gate in der Pipeline: Exit 1 bei belegtem Befund ab "high"
wm-audit gateway-export.zip --fail-on high

# JUnit-XML für Jenkins, GitLab oder Azure DevOps
wm-audit gateway-export.zip --junit -o wm-audit-junit.xml --fail-on high

# Windows (PowerShell oder cmd)
wm-audit.exe C:\Exporte\gateway-export.zip --html -o bericht.html

Mit --junit schreibt wm-audit einen Testbericht, den Jenkins, GitLab, Azure DevOps und andere CI-Systeme anzeigen. Jede API ist eine Testsuite, jede Prüfregel ein Testfall: Für 100 APIs entstehen 1.000 Testfälle aus den Prüfregeln.

Wann ein Testfall fehlschlägt

• ›Ohne --fail-on: Jeder Befund, der die API trifft, ist ein Fehler – belegte Befunde wie Hinweise. Der Exit-Code bleibt 0.
• ›Mit --fail-on SCHWERE: Fehler sind genau die Befunde, die auch Exit-Code 1 auslösen: belegt und mindestens diese Schwere. Alle übrigen Befunde stehen im Testfall unter system-out; der Testfall gilt als bestanden.
• ›Zusammengefasste Befunde (eine Regel trifft mehr als die Hälfte der APIs) erscheinen bei jeder betroffenen API.
• ›Dieselbe API aus mehreren Umgebungen ergibt eine Testsuite; die Befunde beider Umgebungen stehen darin.

Aufbau

Das XML enthält keine Zeitstempel und keine Laufzeiten: Derselbe Export ergibt dieselbe Datei. Zeichen, die XML 1.0 nicht erlaubt, werden durch U+FFFD ersetzt; alles andere wird maskiert. Geprüft ist das Format gegen das JUnit-Schema des Jenkins-xUnit-Plugins (junit-10.xsd).

<?xml version="1.0" encoding="UTF-8"?>
<testsuites name="wm-audit" tests="109" failures="7" errors="0">
  <testsuite name="Export" tests="1" failures="0" errors="0" skipped="1">
    <properties>
      <property name="werkzeug" value="wm-audit 1.0.0"/>
      <property name="quelle" value="gateway-export.zip"/>
      <property name="sha256" value="2144f9b1…"/>
      <property name="fail_on" value="high"/>
      <property name="apis_gelesen" value="10"/>
      …
    </properties>
    <testcase classname="wm-audit.export" name="…/PolicyAction.c2-verwaist">
      <skipped message="nicht_zugeordnet"/>
    </testcase>
  </testsuite>
  <testsuite name="API: AnonymAPI 1.0" tests="10" failures="1" errors="0" skipped="0">
    <testcase classname="wm-audit.AnonymAPI 1_0" name="gw.no_identify_policy"/>
    <testcase classname="wm-audit.AnonymAPI 1_0" name="gw.anonymous_allowed">
      <failure type="critical" message="Identify-Policy erlaubt anonymen Zugriff">[CRITICAL, belegt] …
Empfehlung: allowAnonymous auf false setzen.
Fundstelle: fehler/assets/API/API.b2/API.b2 → Identify &amp; Authorize | allowAnonymous: true</failure>
    </testcase>
    <testcase classname="wm-audit.AnonymAPI 1_0" name="gw.application_identity_only">
      <system-out>Unterhalb der Schwelle --fail-on high: …</system-out>
    </testcase>
    …
  </testsuite>
  <testsuite name="Statisch nicht prüfbar" tests="8" failures="0" errors="0" skipped="8">
    <testcase classname="wm-audit.laufzeit" name="key_verification">
      <skipped message="Wird ein erfundener API-Key tatsächlich abgewiesen? …"/>
    </testcase>
    …
  </testsuite>
</testsuites>

Jenkins

Der erste Aufruf schreibt den HTML-Bericht und endet ohne --fail-on mit 0. Der zweite schlägt bei einem belegten Befund ab „high“ fehl; post { always } veröffentlicht den Testbericht und den HTML-Bericht trotzdem. Auf Windows-Agents bat statt sh und wm-audit.exe verwenden.

pipeline {
  agent any
  stages {
    stage('Gateway-Audit') {
      steps {
        sh 'wm-audit gateway-export.zip --html -o wm-audit-bericht.html'
        sh 'wm-audit gateway-export.zip --junit -o wm-audit-junit.xml --fail-on high'
      }
      post {
        always {
          junit 'wm-audit-junit.xml'
          archiveArtifacts artifacts: 'wm-audit-bericht.html'
        }
      }
    }
  }
}

GitLab CI

wm-audit:
  stage: test
  script:
    - wm-audit gateway-export.zip --html -o wm-audit-bericht.html
    - wm-audit gateway-export.zip --junit -o wm-audit-junit.xml --fail-on high
  artifacts:
    when: always
    paths:
      - wm-audit-bericht.html
    reports:
      junit: wm-audit-junit.xml

Azure DevOps

steps:
  - script: wm-audit gateway-export.zip --junit -o wm-audit-junit.xml --fail-on high
    displayName: wm-audit
  - task: PublishTestResults@2
    condition: always()
    inputs:
      testResultsFormat: JUnit
      testResultsFiles: wm-audit-junit.xml

Den Export liefert ein vorheriger Schritt, etwa ein Export aus der Testumgebung, den Sie im Repository oder als Artefakt ablegen. wm-audit selbst braucht keinen Zugriff auf das Gateway.

Text (Standard)

Kopfzeile mit Version, Name der Quelle und Art (zip oder verzeichnis), bei ZIP der SHA-256, dann die Zahl der gelesenen APIs, übersprungenen Dateien und nicht geöffneten gesperrten Einträge. Es folgen die Befunde (Schwere, Einstufung, Regel-ID, betroffene API, Titel), die Lastgrenzen je API, die übersprungenen Dateien mit Grund und die statisch nicht prüfbaren Fragen.

HTML

Eine einzelne Datei, die im Browser offline funktioniert: Eine Content-Security-Policy (default-src 'none') verbietet jede Verbindung, Werte aus dem Export werden nur als Text eingesetzt. Abschnitte: Ihre Aufgaben (sofort beheben, prüfen und entscheiden), Befunde mit Schritt-für-Schritt-Anleitung im API Gateway, Erfolgstest und Link zur IBM-Dokumentation, Lastgrenzen und Lastrechner, gelesene APIs, übersprungene Dateien, statisch nicht Prüfbares. Die Rohdaten stehen als JSON in der Datei.

JSON (wm-audit-bericht/1)

Schlüssel sortiert, zwei Leerzeichen Einzug, UTF-8 ohne ASCII-Escapes. Die wichtigsten Felder:

Gründe für übersprungene Dateien

Jede Datei, die wie ein Asset aussieht und nicht ausgewertet wurde, steht mit einem dieser Gründe im Bericht:

Belegt heißt: direkt aus der Konfiguration abgelesen; nur belegte Befunde lösen --fail-on aus. Hinweis heißt: starkes Anzeichen, das sich statisch nicht abschließend entscheiden lässt.

Zusammengefasste Befunde

Trifft eine Regel mehr als die Hälfte der APIs (gezählt nach Name und Version), meldet wm-audit sie einmal als „… (durchgängig)“ mit der Liste der betroffenen APIs. Ein belegter Befund behält dabei seine Schwere; ein Hinweis wird zur Information (info), weil er dann eine Gewohnheit beschreibt.

• ›APIs (API.<id>) mit Name, Version und nativeEndpoint.
• ›Policies (Policy.<id>) mit ihrer Zuordnung von Stages zu Policy-Aktionen (policyEnforcements). Eine Aktion zählt nur, wenn sie zugeordnet ist; eine verwaiste Datei verdeckt keine Lücke und erscheint als übersprungen.
• ›Policy-Aktionen (PolicyAction.<id>) – gehören zur innersten API im Verzeichnisbaum.
• ›Aliase vom Typ simple: Routing-Ziele wie ${Backend}/${sys:resource_path} werden aufgelöst; maßgeblich ist der nächstgelegene Alias-Ordner.
• ›Nie geöffnet werden PassmanData, Keystore, Truststore und Kerberos. Sie werden nur gezählt. Steht in einer Adresse ein Passwort, ersetzt der Bericht es durch ***.
• ›ZIP-Archive werden im Speicher gelesen, nicht entpackt. Doppelte Eintragsnamen führen zum Abbruch, symbolische Links werden nicht verfolgt.

Je Traffic-Optimization-Policy (throttle) liest wm-audit die Felder, die IBM in der offiziellen Postman-Collection verwendet: erlaubte Aufrufe (throttleRule mit requestCount und Operator GT), alertInterval, alertIntervalUnit (minutes, hours, days, weeks), consumerIds und alertMessage. Was nicht eindeutig lesbar ist, bleibt leer.

Der Lastrechner im HTML-Bericht spielt ein Lastprofil gegen eine Grenze durch und zeigt, was durchgeht, was mit 429 (Kontingent leer) und was mit 503 (Bulkhead) abgelehnt wird. Er stützt sich nur auf diese IBM-Aussagen:

• ›Token-Bucket-Verfahren: Ist das Kontingent leer, wird abgelehnt; nach Ablauf des Intervalls ist es wieder voll – Rate limit your APIs ↗
• ›Abgelehnt wird mit Status 429 und der Alert Message als Grund – Testing the API Rate Limit ↗
• ›Gezählt wird erst nach der Antwort des Backends; bei gleichzeitigen Aufrufen kann das Limit kurz überschritten werden – Traffic Optimization ↗
• ›Der Bulkhead begrenzt gleichzeitige Aufrufe je Gateway-Instanz und antwortet darüber mit 503 – Bulkhead ↗

Was nicht im Export steht – Zahl der Gateway-Knoten, Bulkhead-Wert, Antwortzeit des Backends, ob das Kontingent gemeinsam oder je Anwendung gilt – fragt der Rechner als Annahme ab. Die Überschreitung durch die späte Zählung schätzt er als Aufrufe pro Sekunde × Antwortzeit; das ist eine abgeleitete Größenordnung, keine Messung.

Diese Fragen beantwortet kein Export. Der Bericht nennt sie, bewertet sie aber nie:

• ?Wird ein erfundener API-Key tatsächlich abgewiesen?
• ?Wird die JWT-Signatur wirklich geprüft?
• ?Erreicht ein Aufrufer fremde Objekte (BOLA)?
• ?Wird die Rollenprüfung durchgesetzt?
• ?Lässt sich ein Trust-Header fälschen?
• ?Greift eine globale Threat-Protection?
• ?Werden Security-Header in Antworten gesetzt?
• ?Wie verhält sich CORS tatsächlich?

Bekannte Grenzen: Global Policies, Plans und Quotas sowie die Denial-of-Service-Regeln der Threat Protection stehen nicht im API-Export und werden nicht ausgewertet. Policies auf Teilbereichen einer API (Scopes) werden nicht unterschieden. Klartext-Routing wird für Straight-Through-Routing bewertet. Die Einheiten „Calendar Week“ und „Calendar Month“ der Traffic Optimization sind im Export nicht belegt und erscheinen unverändert. Getestet mit konstruierten Exporten und öffentlichen Software-AG-Beispielen im Format 10.x.

Die Laufzeitfragen beantwortet sectestx mit Tests gegen Ihre Testumgebung.

• ›Geschrieben in Rust, ohne unsafe-Code; Abbrüche über unwrap, expect und panic sind per Prüfregel ausgeschlossen.
• ›Keine Netzwerk- oder TLS-Bibliotheken – per Bann-Liste in der Lieferkettenprüfung ausgeschlossen.
• ›Nur Abhängigkeiten von crates.io unter MIT, Apache-2.0 oder Zlib; Stückliste (SBOM) als CycloneDX.
• ›Reproduzierbarer Build ohne lokale Pfade im Programm.
• ›Byte-gleiche Ergebnisse mit der Referenzimplementierung: 15 Golden-Fälle in allen vier Formaten und 10.000 zufällig erzeugte Exporte.

Das Lieferpaket enthält das Sicherheitsdatenblatt (SICHERHEIT.md, zu jeder Zusage der belegende Test), die SBOM, den Quelltext und pruefen.sh, das alle Prüfungen in einem Lauf wiederholt. Die Programme sind noch nicht mit einem Hersteller-Zertifikat signiert.