42crunch/api-security-audit-actionAutomatizza il controllo statico della sicurezza delle API sui contratti OpenAPI in CI/CD, eseguendo oltre 300 controlli per autenticazione, autorizzazione e vincoli sui dati, con soglie di punteggio minimo e output SARIF.
L'azione REST API Static Security Testing individua i contratti API REST che seguono la specifica OpenAPI (OAS, in precedenza nota come Swagger) ed esegue controlli di sicurezza approfonditi su di essi. Sono supportate sia la OAS v2 che la v3.0.x, in formato JSON e YAML.
Puoi utilizzare questa azione nei seguenti scenari:
L'azione è basata su 42Crunch API Security Audit. Security Audit esegue un'analisi statica della definizione API che include più di 300 controlli su best practice e potenziali vulnerabilità relative ad autenticazione, autorizzazione e vincoli sui dati.
Per impostazione predefinita, questa azione:
.json e .yaml nel repository.In questo modo puoi individuare eventuali nuovi contratti API o contratti modificati nel repository.
Puoi ottimizzare il comportamento dell'azione specificando parti specifiche del repository o maschere per i nomi dei file da includere o escludere nell'individuazione delle API. Puoi anche disabilitare completamente l'individuazione e, invece, elencare solo file API specifici da controllare e mapparli alle API esistenti nella piattaforma API Security di 42Crunch. Puoi configurare tutte queste impostazioni nel file di configurazione 42c-conf.yaml. Per esempi avanzati, vedi qui.
Tutte le API individuate vengono caricate in una raccolta API nella piattaforma 42Crunch. Per impostazione predefinita, l'azione utilizza le variabili d'ambiente GITHUB_REPOSITORY e GITHUB_REF per denominare il repository e il branch/tag/PR da cui ha origine la raccolta API. Puoi sovrascrivere il nome utilizzando il parametro default-collection-name dell'azione. Durante le esecuzioni successive, le API nella raccolta vengono mantenute sincronizzate con le modifiche del tuo repository.
Aggiungi questa azione ai tuoi workflow CI/CD in GitHub e falla fallire in presenza di definizioni API che contengono problemi di sicurezza.
Security Audit assegna a ogni contratto API un punteggio di audit da 0 a 100 che riflette la superficie di sicurezza delle tue API. Puoi utilizzare il parametro min-score dell'azione GitHub per impostare la soglia del punteggio di audit oltre la quale l'azione fallisce (il valore predefinito è 75, se non viene specificato un altro valore). Questo aiuta a individuare definizioni API di bassa qualità e a risolvere i problemi già in fase di progettazione.
Condizioni di errore più avanzate possono essere impostate nel file di configurazione 42c-conf.yaml, come il punteggio di audit per categoria (sicurezza o validazione dei dati), il livello di gravità dei problemi, o persino problemi specifici, indicati tramite il loro ID. Per esempi avanzati, vedi qui.
Inoltre, il plugin applica i security quality gates definiti a livello di piattaforma (quelli predefiniti o basati su tag). I security quality gates impongono i requisiti di sicurezza delle applicazioni definiti all'interno dell'azienda.
Ogni volta che l'azione viene eseguita, include un collegamento al report dettagliato, prioritizzato e utilizzabile per ciascuno dei tuoi file OpenAPI:
Segui i collegamenti per leggere il report dettagliato nella piattaforma 42Crunch:
Puoi anche tenere traccia dei problemi trovati dall'audit di 42Crunch direttamente in GitHub, nella scheda Security, sotto Code scanning alerts.
Per abilitarlo, basta includere upload-to-code-scanning:true nei parametri dell'azione nel tuo workflow GitHub.
Fai clic su uno qualsiasi degli avvisi per vedere la sua posizione esatta nel codice e ottenere i dettagli della vulnerabilità e i passaggi di remediation consigliati.
Questa azione utilizza il servizio 42Crunch API Security Audit. Prima di utilizzare l'azione, dovrai avere un account sulla piattaforma 42Crunch. Se non sei un cliente 42Crunch, puoi richiedere un account gratuito da questa pagina: https://42crunch.com/get-started/.
Quindi, segui i passaggi descritti nella documentazione per creare un token API che consenta all'azione di autenticarsi sulla piattaforma 42Crunch e salvalo come secret in GitHub.
api-tokenObbligatorio Il token API che l'azione GitHub utilizza per autenticarsi sulla piattaforma 42Crunch. Non inserire il token API direttamente nel file del workflow! Crea invece un secret GitHub nelle impostazioni del repository e fai riferimento ad esso come mostrato nell'esempio seguente.
min-scoreIl punteggio di audit minimo che i file OpenAPI devono raggiungere, altrimenti l'azione fallisce. Il valore predefinito è 75.
upload-to-code-scanningCarica i risultati dell'audit su Github Code Scanning. Il valore predefinito è false. Nota che il workflow deve avere permessi specifici affinché questo passaggio abbia successo.
...
jobs:
run_42c_audit:
permissions:
contents: read # for actions/checkout to fetch code
security-events: write # for results upload to Github Code Scanning
...
ignore-failuresSe impostato su true, forza il completamento dell'esecuzione con successo anche se le condizioni di errore impostate (come min-score o i criteri SQG) vengono soddisfatte. Il valore predefinito è false.
Questo parametro può essere utile se vuoi rilevare scenari di errore SQG senza applicarli (ad esempio, concedere un periodo di grazia ai team di sviluppo prima di iniziare a rompere le build).
ignore-network-errorsSe impostato su true, forza il completamento dell'esecuzione con successo anche se si è verificato un errore di rete (come un errore di connessione alla piattaforma 42Crunch, ecc.). Il valore predefinito è false.
skip-local-checksSe impostato su true, disabilita tutte le condizioni di errore (come il punteggio minimo) impostate nel file 42c-conf.yaml e fa fallire l'esecuzione solo se i criteri definiti negli SQG non vengono soddisfatti. Il valore predefinito è false.
platform-urlL'URL con cui accedi alla piattaforma 42Crunch. Il valore predefinito è https://us.42crunch.cloud.
Se sei un cliente enterprise, inserisci l'URL che usi per accedere alla tua piattaforma di produzione.
root-directoryLa directory root che contiene il file di configurazione 42c-conf.yaml. Se non specificata, viene utilizzata la directory di lavoro corrente del plugin, che normalmente corrisponde alla root del repository estratto.
default-collection-nameIl nome predefinito della raccolta utilizzato quando si creano raccolte per le API individuate. Se non viene fornito alcun nome, viene creato un nome predefinito dalle informazioni su repository e branch/PR.
log-levelLivello di dettaglio nei log, uno tra: FATAL, ERROR, WARN, INFO, DEBUG. Il valore predefinito è INFO.
share-everyoneCondivide automaticamente le raccolte API create dall'attività CI/CD con tutti nella tua organizzazione sulla piattaforma 42Crunch. I valori accettati sono: OFF, READ_ONLY, READ_WRITE. Il valore predefinito è OFF. Nota che l'identità con cui viene eseguita l'azione (il proprietario del token API) deve avere il permesso Share with Everyone, altrimenti l'attività fallirà con un errore 403.
json-reportScrive un report di esecuzione dell'audit in formato JSON nel file specificato. Un report di esecuzione descrive in dettaglio l'elenco delle API create, aggiornate ed eliminate. Utile se vuoi consumare automaticamente i risultati dell'esecuzione dell'audit in un passaggio successivo della pipeline. Per impostazione predefinita, non viene scritto alcun report.
api-tagsL'attività CI/CD può assegnare automaticamente tag alle API di nuova creazione. I tag sono specificati nel formato seguente: category1:name1 category2:name2. Questo flag è opzionale.
sarif-reportConverte il formato JSON grezzo dell'audit in SARIF e salva i risultati nel file specificato. Per impostazione predefinita, non viene scritto alcun report.
audit-timeoutImposta il timeout massimo (in secondi) per il report di audit. L'attività fallirà se il risultato non è pronto entro tale intervallo. Predefinito: 600
Crea un token API sulla piattaforma 42Crunch e copiane il valore in un secret del repository chiamato API_TOKEN.
Un tipico nuovo passaggio in un workflow esistente sarebbe simile a questo:
- 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
Un workflow tipico che controlla il contenuto del repository, esegue Security Audit su ciascuno dei file OpenAPI trovati nel progetto e salva il file di esecuzione come artefatto sarebbe simile a questo:
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
L'azione è mantenuta dal team 42Crunch Ecosystems. Se incontri un problema o hai una domanda a cui non è stata data risposta qui, puoi creare un ticket di supporto su support.42crunch.com.
Quando segnali un problema, includi: