SEDATED

Zweck

Angesichts der Vielzahl von Codeänderungen, die in der heutigen CICD-Umgebung erforderlich sind, pushen Entwickler ständig Code, der unbeabsichtigt vertrauliche Informationen enthalten könnte. Diese potenzielle Offenlegung sensibler Daten stellt ein enormes Risiko für Organisationen dar (2017 OWASP Top Ten #3 – Sensitive Data Exposure). SEDATED® behebt dieses Problem, indem es alle eingehenden Codeänderungen automatisch überprüft und dem Entwickler sofort Rückmeldung gibt. Wenn sensible Daten erkannt werden, wird verhindert, dass der oder die Commits an den Git-Server gepusht werden.

**HINWEIS: NUR Zeilen, die in Commit-Pushes hinzugefügt oder geändert werden (beginnend mit + in der Patch-Datei), werden von SEDATED® gescannt. Zeilen, die in Commit-Pushes entfernt werden (beginnend mit - in der Patch-Datei), werden NICHT von SEDATED® gescannt.

Einrichtung

1. SEDATED® klonen

git clone https://github.com/OWASP/SEDATED.git

cd SEDATED/

2. .example-Dateien aktualisieren

cp /config/whitelists/commit_whitelist.txt.example /config/whitelists/commit_whitelist.txt

cp /config/whitelists/repo_whitelist.txt.example /config/whitelists/repo_whitelist.txt

cp /config/enforced_repos_list.txt.example /config/enforced_repos_list.txt

3. Variablen und Funktionen in /config/custom_configs.sh anpassen (nach Wunsch)

4. SEDATED® mit organisationsspezifischer Implementierung pushen

Schieben Sie die organisationsspezifische Implementierung von SEDATED® in das gewünschte Git-Repository der Organisation (GitHub, GitLab, Git usw.)

5. Pre-Receive-Hook auf SEDATED®'s pre-receive.sh verweisen

Anleitungen dazu für eine GitHub Enterprise-Instanz finden Sie in GitHub_Enterprise_Setup.md.

Lokales Testen

• GitHub Docker Setup – Allgemeine Anleitung zum Einrichten eines GitHub-Docker-Containers als Git-Server mit aktiviertem Pre-Receive-Hook für lokale Tests.
  • Es müssen einige Anpassungen vorgenommen werden, damit SEDATED® wie vorgesehen funktioniert.
    • always_reject.sh muss durch das SEDATED®-Skript pre-receive.sh ersetzt werden.
    • Die zugehörigen Dateien/Ordnerstruktur von SEDATED® müssen im selben Verzeichnis liegen bzw. für das Skript pre-receive.sh zugänglich sein.
    • Möglicherweise sind auch einige zusätzliche Anpassungen erforderlich. Die oben verlinkte Anleitung ist jedoch ein guter Ausgangspunkt für lokale Tests.

Dateibeschreibungen

pre-receive.sh

• Herz und Seele von SEDATED®.
• Das SEDATED®-Pre-Receive-Git-Hook-Skript arbeitet mit den Regexes von SEDATED® (config/regexes.json) zusammen, um hinzugefügte oder geänderte Codezeilen zu identifizieren, die in eine Git-Instanz gepusht werden und hartcodierte Anmeldeinformationen/sensible Daten enthalten (wie in config/regexes.json definiert). Es verhindert den Push, WENN Zeilen mit hartcodierten Anmeldeinformationen/sensiblen Daten gefunden werden.

/config/custom_configs.sh

• Die benutzerdefinierte Konfigurationsdatei von SEDATED®, die zusammen mit pre-receive.sh verwendet wird. Sie ermöglicht Organisationen, ihre SEDATED®-Implementierung anzupassen, ohne den Quellcode in SEDATED®'s pre-receive.sh ändern zu müssen, indem sie integrierte anpassbare Variablen und Funktionen bereitstellt, die von pre-receive.sh eingebunden werden.

/config/enforced_repos_list.txt

• Wird verwendet, wenn das use_enforced_repo_check_custom-Flag von SEDATED® (Pre-Receive-Hook) in config/custom_configs.sh auf „True“ gesetzt ist.
• Ermöglicht es, SEDATED® global im Unternehmen zu „aktivieren“, aber selektiv nur für Repositorys zu „erzwingen“, die in dieser Datei aufgeführt sind.
• Die Erzwingung für alle Repositorys unter einer bestimmten Organisation oder einem bestimmten Benutzernamen kann durch Anhängen von /* an die Organisation oder den Benutzernamen erreicht werden, bei dem die Erzwingung gewünscht wird.
• Wenn SEDATED® global in einer Organisation aktiviert ist und nicht in der Datei /config/enforced_repos_list.txt erscheint, sieht der Pusher (wenn er von der Kommandozeile pusht) eine anpassbare Nachricht (anpassbar über die Datei /config/custom_configs.sh) und SEDATED® scannt keinen der im Push enthaltenen Codes.
• Das Flag zum Aktivieren/Deaktivieren dieser Funktionalität befindet sich in /config/custom_configs.sh und kann auf „True“ oder „False“ gesetzt werden.
  • „False“ – Jedes Repository mit aktiviertem SEDATED® hat auch die SEDATED®-Erzwingung aktiviert.
  • „True“ – Nur Repositorys mit aktiviertem SEDATED®, die auch in der Datei /config/enforced_repos_list.txt aufgeführt sind, haben die SEDATED®-Erzwingung aktiviert. Alle anderen Repositorys mit aktiviertem SEDATED®, die jedoch nicht in der Datei /config/enforced_repos_list.txt aufgeführt sind, sehen nur eine benutzerdefinierte Nachricht; es wird kein Code für Pusher aus diesen Repositorys gescannt.
• Diese Datei kann leer sein, muss aber existieren, wenn das Flag use_enforced_repo_check_custom in config/custom_configs.sh auf „True“ gesetzt ist.

/config/regexes.json

• Enthält die regulären Ausdrücke (Regexes), die verwendet werden, um sensible Daten/hartcodierte Anmeldeinformationen zu kennzeichnen.
• Diese Regexes werden von GNU grep (in pre-receive.sh) mit dem Flag -P verwendet, was sie zu Perl-kompatiblen regulären Ausdrücken (PCREs) macht.
• Regexes können nach Bedarf zu dieser Datei hinzugefügt oder daraus entfernt werden. Wenn jedoch das Skript /testing/regex_testing/regex_test_script.sh verwendet wird, muss die Datei /testing/regex_testing/test_cases.txt aktualisiert werden, indem die Testfälle für die aktualisierten Regexes hinzugefügt oder entfernt werden, damit die Ergebnisse des /testing/regex_testing/regex_test_script.sh korrekt sind.
• Wenn Regexes in dieser Datei hinzugefügt/geändert werden, können je nach gewünschten Regexes zusätzliche Escape-Zeichen \ erforderlich sein, da diese Datei im JSON-Format vorliegt.

/config/whitelists/commit_whitelist.txt

• Wird bei einem falsch positiven Ergebnis verwendet: Ein oder mehrere Commits können vom Scanvorgang ausgeschlossen werden, wenn ihre Commit-IDs in dieser Datei enthalten sind.
• Die Commit-IDs müssen in dieser Datei durch Zeilenumbrüche getrennt sein, wie in der Beispiel-Datei /config/whitelists/commit_whitelist.txt.example gezeigt.
• Diese Datei kann leer sein, muss aber existieren.

Optional: Bitten Sie Entwickler, Pull-Requests an diese Datei (commit_whitelist.txt) zu senden, wenn sie auf falsch positive Ergebnisse stoßen, damit diese überprüft werden können.

/config/whitelists/repo_whitelist.txt

• (Organisation/Benutzername)/Repositorys, die in dieser Datei enthalten sind, werden vollständig vom Scannen auf sensible Daten/hartcodierte Anmeldeinformationen ausgeschlossen, bis sie aus dieser Liste entfernt werden.
• Wird im Falle eines massiven Pushs (z. B. Repository-Migration) verwendet, bei dem SEDATED® den neuen/geänderten Code im Push nicht innerhalb des 5-Sekunden-Fensters scannen kann (das 5-Sekunden-Fenster ist GitHub-spezifisch und kann bei anderen Git-Instanzen anders sein).
• (Organisation/Benutzername)/Repository-Namen müssen in dieser Datei durch Zeilenumbrüche getrennt sein, wie in der Beispiel-Datei /config/whitelists/repo_whitelist.txt.example gezeigt.
• Diese Datei kann leer sein, muss aber existieren.

/testing/regex_testing/regex_test_script.sh

• Das SEDATED®-Regex-Testskript, das zusammen mit testing/regex_testing/test_cases.txt verwendet wird, ist eine einfache, schnelle, Offline-Methode, um zu testen/validieren, ob die regulären Ausdrücke in config/regexes.json gültig sind und die gewünschten Muster erkennen sowie gewünschte Ausschlüsse/Nicht-Übereinstimmungen korrekt handhaben.
  • Testet Regexes gegen eine Liste von Testfällen (/testing/regex_testing/test_cases.txt), um zu überprüfen, ob die Regexes wie erwartet funktionieren.
  • Beinhaltet Tests für sowohl positive als auch negative Testfälle (/testing/regex_testing/test_cases.txt).
  • MUSS GNU grep verwenden, wenn das Skript ausgeführt wird, da sonst das Skript fehlschlägt (BSD grep hat nicht das -P-Flag).
  • Die für dieses Skript verwendeten Testfälle stammen aus /testing/regex_testing/test_cases.txt.

/testing/regex_testing/test_cases.txt

• Liste der Testfälle, die an /testing/regex_testing/regex_test_script.sh zur Verarbeitung übergeben werden.
• Jeder Testfall hat >>pass oder >>fail angehängt. Diese teilen dem Skript /testing/regex_testing/regex_test_script.sh mit, welche Erwartung für die Regexes besteht.
  • >>pass bedeutet, dass ein Push mit dem vorangestellten String von SEDATED® akzeptiert wird (d. h. die Regexes markieren den vorangestellten String NICHT).
  • >>fail bedeutet, dass ein Push mit dem vorangestellten String von SEDATED® abgelehnt wird (d. h. die Regexes markieren den vorangestellten String).

Anpassung

Benutzerdefinierte Variablen und Funktionen sind so konzipiert, dass Organisationen ihre eigene spezifische Implementierung von SEDATED® einfach anpassen können, ohne die Haupt-Pre-Receive-Hook-Datei zu ändern, die die Hauptarbeit erledigt. Alle benutzerdefinierten Variablen und Funktionen finden Sie in /config/custom_configs.sh. Die Erklärungen der in dieser Datei enthaltenen Variablen sind unten aufgeführt.

Benutzerdefinierte Variablen

• show_SEDATED_link_custom – „True“, um einen Link zum OWASP/SEDATED GitHub-Repository anzuzeigen (Groß-/Kleinschreibung beachten), andernfalls auf „False“ setzen.
• documentation_link_custom – Fügen Sie einen Link zur organisationsspezifischen Dokumentation hinzu, wie die Organisation möchte, dass Entwickler mit abgelehnten Pushes umgehen, und/oder allgemeine organisationsspezifische Informationen zu SEDATED®.
  • Wird dem Entwickler angezeigt, wenn ein Push abgelehnt wird.
  • Wird dem Entwickler angezeigt, wenn die erzwungene Repository-Überprüfung auf „True“ gesetzt ist und das Repository nicht in der Datei enforced_repos_list.txt enthalten ist.
• use_enforced_repo_check_custom – „True“ oder „False“ (Groß-/Kleinschreibung beachten).
  • Weitere Details zur Bedeutung dieses Flags finden Sie in der Dateibeschreibung oben für /config/enforced_repos_list.txt.
• enforced_repo_check_true_message_custom mit benutzerdefinierter Nachricht (nur erforderlich, wenn use_enforced_repo_check_custom auf „True“ gesetzt ist).
• obfuscate_output_custom – „True“ oder „False“ (Groß-/Kleinschreibung beachten). Mit dieser Option können sensible Daten, die in der Ausgabe von SEDATED® angezeigt werden, maskiert werden.

Benutzerdefinierte Funktionen

• SET_USER_REPO_NAME_CUSTOM
  • Setzt Benutzer-/Organisations-/Gruppen- und Repository-Namen.
  • Setzt Benutzer-/Organisations-/Gruppen- und Repository-Namen mithilfe der Variable GITHUB_REPO_NAME, wenn GitHub verwendet wird.
  • Wenn nicht GitHub verwendet wird, können benutzerdefinierte Variablen gesetzt werden, um diese Namen zu erhalten.
  • Die bereitgestellten Nicht-GitHub-Namen sind für das reine Abrufen der Namen in Vanilla-Git eingerichtet, müssen jedoch möglicherweise basierend auf unterschiedlichen Implementierungen (Git SCMs) angepasst werden.
• PRINT_ERROR_MESSAGE_CUSTOM
  • Ermöglicht das Drucken einer benutzerdefinierten Fehlermeldung, wenn Fehler auftreten.
• EXIT_SEDATED_CUSTOM
  • Führen Sie beim Beenden von SEDATED® eine zusätzliche benutzerdefinierte Aktion aus (z. B. protokollieren, Metriken senden usw.).
  • Standardmäßig : („nichts tun“) als zusätzliche Aktion; muss nicht geändert werden.
• UNABLE_TO_ACCESS_REPO_WHITELIST_CUSTOM
  • Führen Sie eine zusätzliche benutzerdefinierte Aktion aus, wenn SEDATED® nicht auf die Repository-Whitelist-Datei zugreifen kann (z. B. Fehlermeldung ausgeben, protokollieren, Metrik senden usw.).
  • Standardmäßig : („nichts tun“) als zusätzliche Aktion; muss nicht geändert werden.
• PUSH_ACCEPTED_CUSTOM
  • Führen Sie eine zusätzliche benutzerdefinierte Aktion aus, wenn ein Push akzeptiert wird (z. B. protokollieren, Metriken senden usw.).
  • Standardmäßig : („nichts tun“) als zusätzliche Aktion; muss nicht geändert werden.
• UNABLE_TO_ACCESS_REGEXES_CUSTOM
  • Führen Sie eine zusätzliche benutzerdefinierte Aktion aus, wenn SEDATED® nicht auf die Datei regexes.json zugreifen kann.
  • Standardmäßig : („nichts tun“) als zusätzliche Aktion; muss nicht geändert werden.
  • SEDATED® wird exit 1 ausführen und eine Fehlermeldung ausgeben, wenn nicht auf die Regexes zugegriffen werden kann. Es kann jedoch in diesen Fällen eine zusätzliche benutzerdefinierte Aktion durchgeführt werden, falls gewünscht (z. B. zusätzliche Fehlermeldung ausgeben, protokollieren, Metrik senden usw.).
• PUSH_REJECTED_WITH_VIOLATIONS_CUSTOM
  • Führen Sie eine zusätzliche benutzerdefinierte Aktion aus, wenn Pushes aufgrund von Verstößen abgelehnt werden (z. B. protokollieren, Metriken senden usw.).
  • Standardmäßig : („nichts tun“) als zusätzliche Aktion; muss nicht geändert werden.
• UNABLE_TO_ACCESS_COMMIT_WHITELIST_CUSTOM
  • Führen Sie eine zusätzliche benutzerdefinierte Aktion aus, wenn SEDATED® nicht auf die Commit-Whitelist-Datei zugreifen kann (z. B. protokollieren, Metriken senden usw.).
  • Standardmäßig : („nichts tun“) als zusätzliche Aktion; muss nicht geändert werden.

Kompatibilität

Nur kompatibel mit SCM-Tools, die das Git-Versionskontrollsystem verwenden.

• GitHub
  • Vollständig getestet (Enterprise v2.15.3).
  • SEDATED® GitHub Enterprise Setup.
• GitLab
  • Vorläufig getestet.
  • Änderungen an SET_USER_REPO_NAME_CUSTOM sind erforderlich, um Benutzer/Org und Repo-Namen zu setzen.
• Git
  • Vorläufig getestet.
  • Alle SEDATED®-Dateien/-Ordner müssen in das Verzeichnis .git/hooks/ gelegt werden (außer dem Dokumentationsordner/-dateien).
  • Entfernen Sie .sample aus pre-receive.sample und kopieren Sie den Code aus SEDATED®'s pre-receive.sh in die Datei pre-receive, die wir gerade aus der .sample-Datei erstellt haben.
  • Abhängig von der Implementierung möchten Sie möglicherweise git-template oder etwas Ähnliches verwenden.
• Jedes andere Git-SCM-Tool
  • Nicht getestet.
  • Änderungen an SET_USER_REPO_NAME_CUSTOM werden wahrscheinlich erforderlich sein, um Benutzer/Org und Repo-Namen zu setzen.
  • Möglicherweise sind zusätzliche Anpassungen erforderlich, damit es funktioniert.

Mitwirken

Beiträge zu diesem Projekt sind willkommen!

Sie können auf folgende Weise beitragen:

• Reichen Sie Ihre Verbesserungsideen bei uns ein (oder bei jedem in der Community, der die Herausforderung annehmen möchte, Ihre Idee in **SEDATED®**s Codebasis Wirklichkeit werden zu lassen), indem Sie bitte ein Issue erstellen mit einer guten Erklärung, was Ihrer Meinung nach SEDATED® verbessern könnte und wie dies Ihrer Meinung nach praktisch in der Codebasis umgesetzt werden könnte.
• Reichen Sie einen Pull-Request mit Ihren Codeänderungen ein, um SEDATED® besser zu machen. Wir werden sie überprüfen, testen und zusammenführen. :)

Autoren

• Dennis Kennedy
• Simeon Cloutier

Lizenz

SEDATED® ist lizenziert unter der BSD 3-Clause "New" or "Revised" License.

**SEDATED® garantiert nicht, dass jede Instanz von hartcodierten Anmeldeinformationen, Schlüsseln, Geheimnissen usw. markiert wird. Es verwendet Regex-Musterabgleich, und obwohl es ziemlich gut darin geworden ist, die meisten Instanzen zu erkennen, ist es nicht perfekt. Wir sind jedoch immer offen für Ideen und/oder Pull-Requests, um SEDATED® noch besser zu machen.