GitHub Action: Statische Sicherheitstests für 42Crunch REST-APIs

Die Action für statische Sicherheitstests von REST-APIs ermittelt REST-API-Verträge, die der OpenAPI-Spezifikation (OAS, früher bekannt als Swagger) entsprechen, und führt gründliche Sicherheitsprüfungen an ihnen durch. Unterstützt werden sowohl OAS v2 als auch v3.0.x, jeweils im JSON- und YAML-Format.

Sie können diese Action in den folgenden Szenarien verwenden:

• Fügen Sie Ihren CI/CD-Workflows eine automatische statische API-Sicherheitstestaufgabe (SAST) hinzu.
• Führen Sie diese Prüfungen bei Pull-Request-Reviews und/oder Code-Merges durch.
• Melden Sie die gefundenen Probleme in den Sicherheits- / Code-Scanning-Alerts von GitHub.

Die Action wird von 42Crunch API Security Audit unterstützt. Security Audit führt eine statische Analyse der API-Definition durch, die mehr als 300 Prüfungen auf Best Practices und potenzielle Schwachstellen in Bezug auf Authentifizierung, Autorisierung sowie Dateneinschränkungen umfasst.

APIs in Ihren Repositorys entdecken

Standardmäßig führt diese Action Folgendes aus:

1. Durchsucht das Repository nach allen .json- und .yaml-Dateien.
2. Wählt die Dateien aus, die das OpenAPI-Schema verwenden.
3. Führt eine Sicherheitsprüfung der OpenAPI-Definitionen durch.

Auf diese Weise können Sie neue oder geänderte API-Verträge im Repository finden.

Sie können das Verhalten der Action fein abstimmen, indem Sie bestimmte Teile des Repositorys oder Dateinamenmasken angeben, die bei der Erkennung von APIs ein- oder ausgeschlossen werden sollen. Sie können die Erkennung sogar vollständig deaktivieren und stattdessen nur bestimmte zu prüfende API-Dateien auflisten und diese Ihren vorhandenen APIs in der 42Crunch API Security Platform zuordnen. Alle diese Einstellungen konfigurieren Sie in der Konfigurationsdatei 42c-conf.yaml. Erweiterte Beispiele finden Sie hier.

Alle entdeckten APIs werden in eine API-Collection in der 42Crunch-Plattform hochgeladen. Standardmäßig verwendet die Action die Umgebungsvariablen GITHUB_REPOSITORY und GITHUB_REF, um das Repository und den Branch-/Tag-/PR-Namen zu benennen, aus dem die API-Collection stammt. Sie können den Namen mit dem Parameter default-collection-name der Action überschreiben. Bei späteren Ausführungen werden die APIs in der Collection mit den Änderungen in Ihrem Repository synchron gehalten.

Mit dieser Action die Bereitstellung verwundbarer APIs blockieren

Fügen Sie diese Action Ihren CI/CD-Workflows in GitHub hinzu und lassen Sie sie bei API-Definitionen mit Sicherheitsproblemen fehlschlagen.

Security Audit vergibt für jeden API-Vertrag einen Audit-Score von 0 bis 100, der die Sicherheitsfläche Ihrer APIs widerspiegelt. Sie können den Parameter min-score der GitHub-Action verwenden, um den Schwellenwert für den Audit-Score festzulegen, bei dem die Action fehlschlägt (Standard ist 75, sofern kein anderer Wert angegeben ist). Dies hilft, API-Definitionen von schlechter Qualität zu erkennen und die Probleme bereits so früh wie möglich, nämlich zum Designzeitpunkt, zu beheben.

Erweiterte Fehlerbedingungen können in der Konfigurationsdatei 42c-conf.yaml festgelegt werden, z. B. Audit-Score nach Kategorie (Sicherheit oder Datenvalidierung), Schweregrad der Probleme oder sogar bestimmte Probleme, die über ihre Problem-ID angegeben werden. Erweiterte Beispiele finden Sie hier.

Darüber hinaus erzwingt das Plugin Security Quality Gates, die auf Plattformebene definiert sind (standardmäßige oder tag-gesteuerte). Security Quality Gates setzen die im Unternehmen definierten Anwendungssicherheitsanforderungen durch.

Detaillierte Berichte mit Handlungsempfehlungen lesen

Bei jeder Ausführung enthält die Action einen Link zu dem detaillierten, priorisierten Bericht mit Handlungsempfehlungen für jede Ihrer OpenAPI-Dateien:

Folgen Sie den Links, um den detaillierten Bericht in der 42Crunch-Plattform zu lesen:

42Crunch-Warnungen in GitHub Code Scanning hochladen

Sie können die von der 42Crunch-Prüfung gefundenen Probleme auch direkt in GitHub auf der Registerkarte Security unter Code scanning alerts verfolgen.

Aktivieren Sie dies, indem Sie einfach upload-to-code-scanning:true zu den Parametern der Action in Ihrem GitHub-Workflow hinzufügen.

Klicken Sie auf einen der Alerts, um die genaue Stelle in Ihrem Code zu sehen und Details zur Schwachstelle sowie die empfohlenen Abhilfemaßnahmen zu erhalten.

Erste Schritte

Diese Action nutzt den 42Crunch-API-Sicherheitsaudit-Dienst. Bevor Sie die Action verwenden, benötigen Sie ein Konto auf der 42Crunch-Plattform. Wenn Sie kein 42Crunch-Kunde sind, können Sie auf dieser Seite ein kostenloses Konto anfordern: https://42crunch.com/get-started/.

Befolgen Sie dann die in der Dokumentation beschriebenen Schritte, um ein API-Token für die Authentifizierung der Action bei der 42Crunch-Plattform zu erstellen und es als Secret in GitHub zu speichern.

Parameter der Action

api-token

Erforderlich Das API-Token, mit dem sich die GitHub-Action bei der 42Crunch-Plattform authentifiziert. Legen Sie Ihr API-Token nicht direkt in der Workflow-Datei ab! Erstellen Sie stattdessen ein GitHub-Secret in Ihren Repository-Einstellungen und referenzieren Sie es wie im folgenden Beispiel gezeigt.

min-score

Der Mindest-Audit-Score, den OpenAPI-Dateien erreichen müssen, andernfalls schlägt die Action fehl. Standard ist 75.

upload-to-code-scanning

Lädt die Prüfergebnisse in GitHub Code Scanning hoch. Standard ist false. Beachten Sie, dass der Workflow für diesen Schritt bestimmte Berechtigungen benötigt, damit er erfolgreich ist.

...
jobs:
  run_42c_audit:
    permissions:
      contents: read # for actions/checkout to fetch code
      security-events: write # for results upload to Github Code Scanning
...

ignore-failures

Wenn auf true gesetzt, erzwingt dies einen erfolgreichen Abschluss der Ausführung, auch wenn die von Ihnen festgelegten Fehlerbedingungen (wie min-score oder SQG-Kriterien) erfüllt sind. Standard ist false.

Dieser Parameter kann nützlich sein, wenn Sie SQG-Fehlerszenarien erkennen möchten, ohne sie durchzusetzen (d. h. Entwicklungsteams eine Schonfrist einräumen, bevor Builds zum Scheitern gebracht werden).

ignore-network-errors

Wenn auf true gesetzt, erzwingt dies einen erfolgreichen Abschluss der Ausführung, auch wenn ein Netzwerkfehler aufgetreten ist (z. B. eine fehlgeschlagene Verbindung zur 42Crunch-Plattform usw.). Standard ist false.

skip-local-checks

Wenn auf true gesetzt, deaktiviert dies alle in der Datei 42c-conf.yaml festgelegten Fehlerbedingungen (wie den Mindest-Score) und lässt die Ausführung nur fehlschlagen, wenn die in SQGs definierten Kriterien nicht erfüllt sind. Standard ist false.

platform-url

Die URL, unter der Sie auf die 42Crunch-Plattform zugreifen. Standard ist https://us.42crunch.cloud.

Wenn Sie Enterprise-Kunde sind, geben Sie die URL ein, die Sie für den Zugriff auf Ihre Produktionsplattform verwenden.

root-directory

Das Stammverzeichnis, das die Konfigurationsdatei 42c-conf.yaml enthält. Wenn nicht angegeben, wird stattdessen das aktuelle Arbeitsverzeichnis des Plugins verwendet, das normalerweise dem Stammverzeichnis des ausgecheckten Repositorys entspricht.

default-collection-name

Der Standard-Collection-Name, der beim Erstellen von Collections für entdeckte APIs verwendet wird. Wenn kein Name angegeben ist, wird ein Standardname aus den Repository- und Branch-/PR-Informationen erstellt.

log-level

Detaillierungsgrad der Protokolle, einer von: FATAL, ERROR, WARN, INFO, DEBUG. Standard ist INFO.

share-everyone

Teilt automatisch API-Collections, die von der CI/CD-Aufgabe erstellt wurden, mit allen in Ihrer Organisation auf der 42Crunch-Plattform. Akzeptierte Werte sind: OFF, READ_ONLY, READ_WRITE. Standard ist OFF. Beachten Sie, dass die Identität, unter der die Action ausgeführt wird (der Besitzer des API-Tokens), über die Berechtigung Share with Everyone verfügen muss, andernfalls schlägt die Aufgabe mit einem 403-Fehler fehl.

json-report

Schreibt einen Prüfungsausführungsbericht im JSON-Format in die angegebene Datei. Ein Ausführungsbericht enthält die Liste der APIs, die erstellt, aktualisiert und gelöscht wurden. Dies ist nützlich, wenn Sie die Ergebnisse der Prüfungsausführung automatisch in einem nachfolgenden Pipeline-Schritt verwenden möchten. Standardmäßig wird kein Bericht geschrieben.

api-tags

Die CI/CD-Aufgabe kann neu erstellten APIs automatisch Tags zuweisen. Tags werden im folgenden Format angegeben: category1:name1 category2:name2. Dieses Flag ist optional.

sarif-report

Konvertiert das rohe JSON-Format der Prüfung in SARIF und speichert die Ergebnisse in der angegebenen Datei. Standardmäßig wird kein Bericht geschrieben.

audit-timeout

Legt das maximale Zeitlimit (in Sekunden) für den Prüfungsbericht fest. Die Aufgabe schlägt fehl, wenn das Ergebnis innerhalb dieses Intervalls nicht bereit ist. Standard: 600

Voraussetzungen

Erstellen Sie ein API-Token auf der 42Crunch-Plattform und kopieren Sie dessen Wert in ein Repository-Secret mit dem Namen API_TOKEN.

Beispiele

Beispiel für einen einzelnen Schritt

Ein typischer neuer Schritt in einem vorhandenen Workflow würde wie folgt aussehen:

- name: 42crunch-static-api-testing
        uses: 42Crunch/api-security-audit-action@v4
        with:
          api-token: ${{ secrets.API_TOKEN }}
          default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
          log-level: info
          json-report: audit-action-report-${{ github.run_id }}
          sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF

Beispiel für einen vollständigen Workflow

Ein typischer Workflow, der den Inhalt des Repositorys überprüft, Security Audit für jede im Projekt gefundene OpenAPI-Datei ausführt und die Ausführungsdatei als Artefakt speichert, würde wie folgt aussehen:

name: "42crunch-audit-workflow"

# follow standard Code Scanning triggers
on:
  push:
    branches: [ "main" ]
  pull_request:
    # The branches below must be a subset of the branches above
    branches: [ "main" ]
  schedule:
    - cron: '19 9 * * 6'

env:
  PLATFORM_URL: https://us.42crunch.cloud

jobs:
  run_42c_audit:
    environment: QA
    permissions:
      contents: read # for actions/checkout to fetch code
      security-events: write # for results upload to Github Code Scanning
    runs-on: ubuntu-latest
    steps:
      - name: checkout repo
        uses: actions/checkout@v3
      - name: 42crunch-static-api-testing
        uses: 42Crunch/api-security-audit-action@v4
        with:
          api-token: ${{ secrets.API_TOKEN }}
          platform-url: ${{ env.PLATFORM_URL}}
          default-collection-name: GitHub-MyRepo-${{ github.ref_name }}
          # Upload results to Github code scanning
          upload-to-code-scanning: false
          log-level: info
          json-report: audit-action-report-${{ github.run_id }}
          sarif-report: 42Crunch_AuditReport_${{ github.run_id }}.SARIF
      - name: save-audit-report
        if: always()        
        uses: actions/upload-artifact@v3
        with:
          name: auditaction-report-${{ github.run_id }}
          path: audit-action-report-${{ github.run_id }}.json
          if-no-files-found: error

Support

Die Action wird vom 42Crunch-Ecosystems-Team gepflegt. Wenn Sie auf ein Problem stoßen oder eine Frage haben, die hier nicht beantwortet wird, können Sie ein Support-Ticket unter support.42crunch.com erstellen.

Wenn Sie ein Problem melden, geben Sie bitte Folgendes an:

• Die Version der GitHub-Action
• Relevante Protokolle und Fehlermeldungen
• Schritte zur Reproduktion des Problems